refactor: simplify agent driver tool runtime contract

Author: Dariusz Debowczyk

packages/agents/src/AgentLoop.php

@@ -8,6 +8,7 @@
 use Cognesy\Agents\Continuation\StopReason;
 use Cognesy\Agents\Continuation\StopSignal;
 use Cognesy\Agents\Data\AgentState;
+use Cognesy\Agents\Drivers\CanAcceptToolRuntime;
 use Cognesy\Agents\Drivers\CanUseTools;
 use Cognesy\Agents\Enums\ExecutionStatus;
 use Cognesy\Agents\Drivers\ToolCalling\ToolCallingDriver;
@@ -92,13 +93,14 @@ public function execute(AgentState $state): AgentState {
 
     #[\Override]
     public function iterate(AgentState $state): iterable {
+        $driver = $this->bindToolRuntime($this->driver);
         $state = $this->onBeforeExecution($state);
         while (true) {
             $stepStarted = false;
             try {
                 $state = $this->onBeforeStep($state);
                 $stepStarted = true;
-                $state = $this->handleToolUse($state);
+                $state = $this->handleToolUse($state, $driver);
             } catch (AgentStopException $stop) {
                 $state = $this->handleStopException($state, $stop);
             } catch (Throwable $error) {
@@ -170,9 +172,9 @@ protected function onError(AgentState $state, Throwable $error): AgentState {
 
     // INTERNAL ///////////////////////////////////////////
 
-    private function handleToolUse(AgentState $state) : AgentState {
+    private function handleToolUse(AgentState $state, CanUseTools $driver) : AgentState {
         try {
-            $state = $this->useTools($state);
+            $state = $this->useTools($state, $driver);
         } catch (ToolExecutionBlockedException $block) {
             $state = $this->handleToolBlockException($state, $block);
         }
@@ -206,15 +208,21 @@ protected function shouldStop(AgentState $state): bool {
         return $shouldStop;
     }
 
-    private function useTools(AgentState $state): AgentState {
-        $state = $this->driver->useTools(
-            state: $state,
-            tools: $this->tools,
-            executor: $this->toolExecutor
-        );
+    private function useTools(AgentState $state, CanUseTools $driver): AgentState {
+        $state = $driver->useTools(state: $state);
         return $state;
     }
 
+    private function bindToolRuntime(CanUseTools $driver): CanUseTools {
+        return match (true) {
+            $driver instanceof CanAcceptToolRuntime => $driver->withToolRuntime(
+                tools: $this->tools,
+                executor: $this->toolExecutor,
+            ),
+            default => $driver,
+        };
+    }
+
     // EVENT DELEGATION ///////////////////////////////////
 
     public function wiretap(callable $listener): self {

packages/agents/src/Builder/AgentConfigurator.php

@@ -10,6 +10,7 @@
 use Cognesy\Agents\Context\CanAcceptMessageCompiler;
 use Cognesy\Agents\Context\CanCompileMessages;
 use Cognesy\Agents\Context\Compilers\ConversationWithCurrentToolTrace;
+use Cognesy\Agents\Drivers\CanAcceptToolRuntime;
 use Cognesy\Agents\Drivers\CanUseTools;
 use Cognesy\Agents\Drivers\ToolCalling\ToolCallingDriver;
 use Cognesy\Agents\Hook\Collections\RegisteredHooks;
@@ -62,7 +63,7 @@ public function install(CanProvideAgentCapability $capability): self {
     }
 
     public function toAgentLoop(): AgentLoop {
-        $driver = $this->resolveDriver();
+        $driver = $this->normalizeDriver($this->toolUseDriver, $this->contextCompiler);
         $tools = $this->resolveTools($driver);
         $interceptor = $this->resolveInterceptor();
 
@@ -72,6 +73,7 @@ public function toAgentLoop(): AgentLoop {
             interceptor: $interceptor,
             throwOnToolFailure: false,
         );
+        $driver = $this->bindToolRuntime($driver, $tools, $executor);
 
         return new AgentLoop(
             tools: $tools,
@@ -169,17 +171,24 @@ private function with(
         );
     }
 
-    private function resolveDriver(): CanUseTools {
-        return $this->normalizeDriver($this->toolUseDriver, $this->contextCompiler);
-    }
-
     private function normalizeDriver(CanUseTools $driver, CanCompileMessages $compiler): CanUseTools {
         return match (true) {
             $driver instanceof CanAcceptMessageCompiler => $driver->withMessageCompiler($compiler),
             default => $driver,
         };
     }
 
+    private function bindToolRuntime(
+        CanUseTools $driver,
+        Tools $tools,
+        ToolExecutor $executor,
+    ) : CanUseTools {
+        return match (true) {
+            $driver instanceof CanAcceptToolRuntime => $driver->withToolRuntime($tools, $executor),
+            default => $driver,
+        };
+    }
+
     private function resolveTools(CanUseTools $driver): Tools {
         return $this->deferredTools->resolve($this->tools, $driver, $this->events);
     }

packages/agents/src/Drivers/CanAcceptToolRuntime.php

@@ -0,0 +1,11 @@
+<?php declare(strict_types=1);
+
+namespace Cognesy\Agents\Drivers;
+
+use Cognesy\Agents\Collections\Tools;
+use Cognesy\Agents\Tool\Contracts\CanExecuteToolCalls;
+
+interface CanAcceptToolRuntime
+{
+    public function withToolRuntime(Tools $tools, CanExecuteToolCalls $executor): static;
+}

packages/agents/src/Drivers/CanUseTools.php

@@ -2,11 +2,9 @@
 
 namespace Cognesy\Agents\Drivers;
 
-use Cognesy\Agents\Collections\Tools;
 use Cognesy\Agents\Data\AgentState;
-use Cognesy\Agents\Tool\Contracts\CanExecuteToolCalls;
 
 interface CanUseTools
 {
-    public function useTools(AgentState $state, Tools $tools, CanExecuteToolCalls $executor): AgentState;
+    public function useTools(AgentState $state): AgentState;
 }

packages/agents/src/Drivers/ReAct/ReActDriver.php

@@ -10,6 +10,7 @@
 use Cognesy\Agents\Data\AgentState;
 use Cognesy\Agents\Data\AgentStep;
 use Cognesy\Agents\Data\ToolExecution;
+use Cognesy\Agents\Drivers\CanAcceptToolRuntime;
 use Cognesy\Agents\Drivers\CanUseTools;
 use Cognesy\Agents\Drivers\ReAct\Actions\MakeReActPrompt;
 use Cognesy\Agents\Drivers\ReAct\Actions\MakeToolCalls;
@@ -22,6 +23,8 @@
 use Cognesy\Agents\Events\InferenceResponseReceived;
 use Cognesy\Agents\Events\ValidationFailed;
 use Cognesy\Agents\Exceptions\AgentException;
+use Cognesy\Agents\Interception\PassThroughInterceptor;
+use Cognesy\Agents\Tool\ToolExecutor;
 use Cognesy\Agents\Tool\Contracts\CanExecuteToolCalls;
 use Cognesy\Events\Contracts\CanHandleEvents;
 use Cognesy\Events\EventBusResolver;
@@ -51,7 +54,7 @@
 use Cognesy\Utils\Result\Result;
 use DateTimeImmutable;
 
-final class ReActDriver implements CanUseTools, CanAcceptLLMConfig, CanAcceptMessageCompiler
+final class ReActDriver implements CanUseTools, CanAcceptToolRuntime, CanAcceptLLMConfig, CanAcceptMessageCompiler
 {
     private LLMProvider $llm;
     private ?HttpClient $httpClient = null;
@@ -66,6 +69,8 @@ final class ReActDriver implements CanUseTools, CanAcceptLLMConfig, CanAcceptMes
     private CanHandleEvents $events;
     private CanCreateInference $inference;
     private CanCreateStructuredOutput $structuredOutput;
+    private Tools $tools;
+    private CanExecuteToolCalls $executor;
 
     public function __construct(
         CanCreateInference $inference,
@@ -81,6 +86,8 @@ public function __construct(
         OutputMode $mode = OutputMode::Json,
         ?CanCompileMessages $messageCompiler = null,
         ?CanHandleEvents $events = null,
+        ?Tools $tools = null,
+        ?CanExecuteToolCalls $executor = null,
     ) {
         $this->inference = $inference;
         $this->structuredOutput = $structuredOutput;
@@ -95,13 +102,19 @@ public function __construct(
         $this->mode = $mode;
         $this->messageCompiler = $messageCompiler ?? new ConversationWithCurrentToolTrace();
         $this->events = EventBusResolver::using($events);
+        $this->tools = $tools ?? new Tools();
+        $this->executor = $executor ?? new ToolExecutor(
+            tools: $this->tools,
+            events: $this->events,
+            interceptor: new PassThroughInterceptor(),
+        );
     }
 
     #[\Override]
-    public function useTools(AgentState $state, Tools $tools, CanExecuteToolCalls $executor): AgentState {
+    public function useTools(AgentState $state): AgentState {
         $state = $this->ensureStateLLMConfig($state);
         $messages = $this->messageCompiler->compile($state);
-        $system = $this->buildSystemPrompt($tools);
+        $system = $this->buildSystemPrompt($this->tools);
         $cachedContext = $this->structuredCachedContext($state);
 
         $requestStartedAt = new DateTimeImmutable();
@@ -131,7 +144,7 @@ public function useTools(AgentState $state, Tools $tools, CanExecuteToolCalls $e
         $this->emitInferenceResponseReceived($state, $inferenceResponse, $requestStartedAt);
 
         $validator = new ReActValidator();
-        $validation = $validator->validateBasicDecision($decision, $tools->names());
+        $validation = $validator->validateBasicDecision($decision, $this->tools->names());
         if ($validation->isInvalid()) {
             $this->emitValidationFailed(
                 state: $state,
@@ -142,7 +155,7 @@ public function useTools(AgentState $state, Tools $tools, CanExecuteToolCalls $e
             return $state->withCurrentStep($step)->withFailure(new AgentException($validation->getErrorMessage()));
         }
 
-        $toolCalls = (new MakeToolCalls($tools, $validator))($decision);
+        $toolCalls = (new MakeToolCalls($this->tools, $validator))($decision);
 
         $usage = $inferenceResponse->usage();
 
@@ -157,7 +170,7 @@ public function useTools(AgentState $state, Tools $tools, CanExecuteToolCalls $e
             return $state->withCurrentStep($step);
         }
 
-        $executions = $executor->executeTools($toolCalls, $state);
+        $executions = $this->executor->executeTools($toolCalls, $state);
 
         $outputMessages = $this->makeFollowUps($decision, $executions);
         $responseWithCalls = $this->withToolCalls($inferenceResponse, $toolCalls);
@@ -209,6 +222,11 @@ public function withMessageCompiler(CanCompileMessages $compiler): static {
         return $this->with(messageCompiler: $compiler);
     }
 
+    #[\Override]
+    public function withToolRuntime(Tools $tools, CanExecuteToolCalls $executor): static {
+        return $this->with(tools: $tools, executor: $executor);
+    }
+
     // INTERNAL ////////////////////////////////////////////////////////////////
 
     private function with(
@@ -224,6 +242,8 @@ private function with(
         ?CanCompileMessages $messageCompiler = null,
         ?CanCreateInference $inference = null,
         ?CanCreateStructuredOutput $structuredOutput = null,
+        ?Tools $tools = null,
+        ?CanExecuteToolCalls $executor = null,
     ): self {
         return new self(
             inference: $inference ?? $this->inference,
@@ -239,6 +259,8 @@ private function with(
             mode: $mode ?? $this->mode,
             messageCompiler: $messageCompiler ?? $this->messageCompiler,
             events: $this->events,
+            tools: $tools ?? $this->tools,
+            executor: $executor ?? $this->executor,
         );
     }