Fixes in OpenResponses impl + refactoring of agents

Author: ddebowczyk

examples/A02_Advanced/ContextCachingOAIResponses/run.php

@@ -9,10 +9,6 @@
 so you can focus on your business logic while still being able to take advantage of lower
 latency and costs.
 
-> **Note:** With the Responses API you can also chain server-side context
-> using `previous_response_id`. Prompt caching and token counters still depend
-> on model eligibility and prompt size.
-
 
 ## Example
 
@@ -60,6 +56,7 @@ class Project {
 ```php
 <?php
 $content = file_get_contents(__DIR__ . '/../../../README.md');
+$cacheKey = 'context_cache_structured_oai_responses_readme_v1';
 
 $cached = (new StructuredOutput)->using('openai-responses')->withCachedContext(
     system: 'Your goal is to respond questions about the project described in the README.md file'
@@ -75,11 +72,20 @@ class Project {
 
 ```php
 <?php
+/** @var array<string, mixed> $optionsBase */
+$optionsBase = [
+    'max_output_tokens' => 4096,
+    // Improve cache routing for identical prefixes between requests.
+    'prompt_cache_key' => $cacheKey,
+    'prompt_cache_retention' => 'in_memory',
+];
+
 // get StructuredOutputResponse object to get access to usage and other metadata
 $response1 = $cached->with(
     messages: 'Describe the project in a way compelling to my audience: P&C insurance CIOs.',
     responseModel: Project::class,
-    options: ['max_output_tokens' => 4096],
+    model: 'gpt-4.1',
+    options: $optionsBase,
     mode: OutputMode::JsonSchema,
 )->create();
 
@@ -98,7 +104,7 @@ class Project {
 
 // get usage information from response() method which returns raw InferenceResponse object
 $usage1 = $response1->response()->usage();
-echo "Usage: {$usage1->inputTokens} prompt tokens, {$usage1->cacheWriteTokens} cache write tokens\n";
+echo "Usage #1: {$usage1->inputTokens} prompt tokens, {$usage1->cacheWriteTokens} cache write tokens\n";
 ?>
 ```
 Now we can use the same context to ask the user to describe the project for a different
@@ -110,14 +116,15 @@ class Project {
 ```php
 <?php
 // get StructuredOutputResponse object to get access to usage and other metadata
-$options2 = ['max_output_tokens' => 4096];
+$options2 = $optionsBase;
 if ($previousResponseId !== '') {
     $options2['previous_response_id'] = $previousResponseId;
 }
 
 $response2 = $cached->with(
     messages: "Describe the project in a way compelling to my audience: boutique CMS consulting company owner.",
     responseModel: Project::class,
+    model: 'gpt-4.1',
     options: $options2,
     mode: OutputMode::JsonSchema,
 )->create();
@@ -130,9 +137,7 @@ class Project {
 
 // get usage information from response() method which returns raw InferenceResponse object
 $usage2 = $response2->response()->usage();
-echo "Usage: {$usage2->inputTokens} prompt tokens, {$usage2->cacheReadTokens} cache read tokens\n";
-if ($usage2->cacheReadTokens === 0) {
-    echo "Note: cacheReadTokens is 0. Prompt caching applies only to eligible models and prompt sizes.\n";
-}
+echo "Usage #2: {$usage2->inputTokens} prompt tokens, {$usage2->cacheReadTokens} cache read tokens\n";
+assert($usage2->cacheReadTokens > 0, 'Expected prompt cache read tokens > 0');
 ?>
 ```

examples/A05_Extras/OpenAIResponsesStreamingStructuredOutput/run.php

@@ -43,6 +43,7 @@ class PersonProfile
 
 $profile = (new StructuredOutput)
     ->using('openai-responses')
+    // ->withHttpDebugPreset('on') // enable HTTP stack debug output if needed
     ->withOutputMode(OutputMode::JsonSchema)
     ->withResponseClass(PersonProfile::class)
     ->withMessages($text)

examples/B03_LLMTroubleshooting/HttpDebug/run.php

@@ -5,10 +5,13 @@
 
 ## Overview
 
-Instructor PHP provides a way to debug HTTP calls made to LLM APIs via `withDebug()` method call
-on `Inference` object.
+Instructor PHP provides a way to debug HTTP calls made to LLM APIs via
+`withHttpDebugPreset()` (or the legacy `withDebugPreset()`) on the `Inference`
+object.
 
-When debug mode is turned on all HTTP requests and responses are dumped to the console.
+When HTTP debug mode is enabled, the HTTP middleware stack prints request and
+response details (including streaming data) to the console and dispatches HTTP
+debug events.
 
 ## Example
 
@@ -19,7 +22,7 @@
 use Cognesy\Polyglot\Inference\Inference;
 
 $response = (new Inference)
-    ->withDebugPreset('on') // Enable debug mode
+    ->withHttpDebugPreset('on') // Enable HTTP debug middleware
     ->with(
         messages: [['role' => 'user', 'content' => 'What is the capital of Brasil']],
         options: ['max_tokens' => 128]

packages/agents/src/Agent/Agent.php

@@ -2,30 +2,22 @@
 
 namespace Cognesy\Agents\Agent;
 
-use Cognesy\Agents\Agent\StateProcessing\CanApplyProcessors;
-use Cognesy\Agents\Agent\StateProcessing\CanProcessAgentState;
-use Cognesy\Agents\Agent\StateProcessing\StateProcessors;
 use Cognesy\Agents\Core\Collections\Tools;
-use Cognesy\Agents\Core\Tools\ToolExecutor;
 use Cognesy\Agents\Core\Continuation\ContinuationCriteria;
-use Cognesy\Agents\Core\Continuation\Contracts\CanEvaluateContinuation;
 use Cognesy\Agents\Core\Continuation\Enums\StopReason;
 use Cognesy\Agents\Core\Contracts\CanControlAgentLoop;
+use Cognesy\Agents\Core\Contracts\CanEmitAgentEvents;
 use Cognesy\Agents\Core\Contracts\CanExecuteToolCalls;
 use Cognesy\Agents\Core\Contracts\CanHandleAgentErrors;
 use Cognesy\Agents\Core\Contracts\CanUseTools;
-use Cognesy\Agents\Core\Contracts\ToolInterface;
 use Cognesy\Agents\Core\Data\AgentState;
 use Cognesy\Agents\Core\Data\AgentStep;
 use Cognesy\Agents\Core\Data\CurrentExecution;
 use Cognesy\Agents\Core\Data\StepExecution;
 use Cognesy\Agents\Core\Enums\AgentStatus;
-use Cognesy\Agents\Core\ErrorHandling\AgentErrorHandler;
-use Cognesy\Agents\Core\ErrorHandling\ErrorPolicy;
-use Cognesy\Agents\Core\Events\AgentEventEmitter;
 use Cognesy\Agents\Core\Exceptions\AgentException;
 use Cognesy\Agents\Core\Lifecycle\CanObserveAgentLifecycle;
-use Cognesy\Events\Contracts\CanHandleEvents;
+use Cognesy\Agents\Core\Tools\ToolExecutor;
 use DateTimeImmutable;
 use Throwable;
 
@@ -37,23 +29,15 @@
  */
 class Agent implements CanControlAgentLoop
 {
-    private readonly AgentEventEmitter $eventEmitter;
-
     public function __construct(
         private readonly Tools $tools,
         private readonly CanExecuteToolCalls $toolExecutor,
         private readonly CanHandleAgentErrors $errorHandler,
-        private readonly ?CanApplyProcessors $processors,
         private readonly ContinuationCriteria $continuationCriteria,
         private readonly CanUseTools $driver,
-        AgentEventEmitter $eventEmitter,
-        ?CanHandleEvents $events = null,
+        private readonly CanEmitAgentEvents $eventEmitter,
         private readonly ?CanObserveAgentLifecycle $observer = null,
-    ) {
-        $this->eventEmitter = $events !== null
-            ? $eventEmitter->withEventHandler($events)
-            : $eventEmitter;
-    }
+    ) {}
 
     // PUBLIC API //////////////////////////////////
 
@@ -102,7 +86,7 @@ protected function onBeforeExecution(AgentState $state): AgentState {
         $this->eventEmitter->executionStarted($state, count($this->tools->names()));
 
         if ($this->observer !== null) {
-            $state = $this->observer->executionStarting($state);
+            $state = $this->observer->beforeExecution($state);
         }
 
         return $state;
@@ -112,7 +96,7 @@ protected function onBeforeStep(AgentState $state): AgentState {
         $this->eventEmitter->stepStarted($state);
 
         if ($this->observer !== null) {
-            $state = $this->observer->stepStarting($state);
+            $state = $this->observer->beforeStep($state);
         }
 
         return $state;
@@ -145,7 +129,7 @@ private function onAfterToolUse(AgentState $state, AgentStep $rawStep) : AgentSt
 
     protected function onAfterStep(AgentState $state): AgentState {
         if ($this->observer !== null) {
-            $state = $this->observer->stepEnding($state);
+            $state = $this->observer->afterStep($state);
         }
 
         $this->eventEmitter->stepCompleted($state);
@@ -161,7 +145,7 @@ protected function onAfterExecution(AgentState $state): AgentState {
         $finalState = $state->withStatus($status);
 
         if ($this->observer !== null) {
-            $finalState = $this->observer->executionEnding($finalState);
+            $finalState = $this->observer->afterExecution($finalState);
         }
 
         $this->eventEmitter->executionFinished($finalState);
@@ -199,7 +183,7 @@ protected function onError(Throwable $error, AgentState $state): AgentState {
                 $agentException = $handling->exception instanceof AgentException
                     ? $handling->exception
                     : AgentException::fromThrowable($handling->exception);
-                $nextState = $this->observer->executionFailed($nextState, $agentException);
+                $nextState = $this->observer->onError($nextState, $agentException);
             }
         }
 
@@ -225,7 +209,7 @@ protected function shouldContinue(AgentState $state): bool {
         // We're about to stop - let the observer intervene if registered
         if ($this->observer !== null) {
             $stopReason = $state->stopReason() ?? StopReason::Completed;
-            $decision = $this->observer->stopping($state, $stopReason);
+            $decision = $this->observer->beforeStopDecision($state, $stopReason);
             if ($decision->isPrevented()) {
                 return true; // Observer prevented stopping, continue execution
             }
@@ -235,10 +219,7 @@ protected function shouldContinue(AgentState $state): bool {
     }
 
     private function performStep(AgentState $state): AgentState {
-        return match(true) {
-            ($this->processors === null) => $this->useTools($state),
-            default => $this->processors->apply($state, fn($s) => $this->useTools($s)),
-        };
+        return $this->useTools($state);
     }
 
     private function useTools(AgentState $state): AgentState {
@@ -306,32 +287,27 @@ public function driver(): CanUseTools {
         return $this->driver;
     }
 
-    public function eventEmitter(): AgentEventEmitter {
+    public function eventEmitter(): CanEmitAgentEvents {
         return $this->eventEmitter;
     }
 
+    public function observer(): ?CanObserveAgentLifecycle {
+        return $this->observer;
+    }
+
     // MUTATORS /////////////////////////////////////////////
 
     public function with(
         ?Tools $tools = null,
         ?CanExecuteToolCalls $toolExecutor = null,
         ?CanHandleAgentErrors $errorHandler = null,
-        ?CanApplyProcessors $processors = null,
         ?ContinuationCriteria $continuationCriteria = null,
         ?CanUseTools $driver = null,
-        ?AgentEventEmitter $eventEmitter = null,
-        ?CanHandleEvents $events = null,
+        ?CanEmitAgentEvents $eventEmitter = null,
         ?CanObserveAgentLifecycle $observer = null,
     ): self {
         $resolvedTools = $tools ?? $this->tools;
 
-        // Resolve emitter: prefer explicit, then create new if events changed
-        $resolvedEmitter = $eventEmitter ?? (
-            $events !== null
-                ? $this->eventEmitter->withEventHandler($events)
-                : $this->eventEmitter
-        );
-
         // If tools changed but no executor provided, create new executor
         $resolvedExecutor = $toolExecutor ?? (
             $tools !== null
@@ -343,52 +319,10 @@ public function with(
             tools: $resolvedTools,
             toolExecutor: $resolvedExecutor,
             errorHandler: $errorHandler ?? $this->errorHandler,
-            processors: $processors ?? $this->processors,
             continuationCriteria: $continuationCriteria ?? $this->continuationCriteria,
             driver: $driver ?? $this->driver,
-            eventEmitter: $resolvedEmitter,
+            eventEmitter: $eventEmitter ?? $this->eventEmitter,
             observer: $observer ?? $this->observer,
         );
     }
-
-    public function withProcessors(CanProcessAgentState ...$processors): self {
-        return $this->with(processors: new StateProcessors(...$processors));
-    }
-
-    public function withDriver(CanUseTools $driver): self {
-        return $this->with(driver: $driver);
-    }
-
-    public function withContinuationCriteria(CanEvaluateContinuation ...$criteria): self {
-        return $this->with(continuationCriteria: new ContinuationCriteria(...$criteria));
-    }
-
-    public function withTools(array|ToolInterface|Tools $tools): self {
-        return $this->with(tools: match (true) {
-            is_array($tools) => new Tools(...$tools),
-            $tools instanceof ToolInterface => new Tools($tools),
-            $tools instanceof Tools => $tools,
-            default => new Tools(),
-        });
-    }
-
-    public function withToolExecutor(CanExecuteToolCalls $toolExecutor): self {
-        return $this->with(toolExecutor: $toolExecutor);
-    }
-
-    public function withErrorHandler(CanHandleAgentErrors $errorHandler): self {
-        return $this->with(errorHandler: $errorHandler);
-    }
-
-    public function withErrorPolicy(ErrorPolicy $policy): self {
-        return $this->with(errorHandler: AgentErrorHandler::withPolicy($policy));
-    }
-
-    public function withObserver(?CanObserveAgentLifecycle $observer): self {
-        return $this->with(observer: $observer);
-    }
-
-    public function observer(): ?CanObserveAgentLifecycle {
-        return $this->observer;
-    }
 }