Feat: Add support for client-executed tools

docs/core-concepts/tools-function-calling.md

@@ -305,6 +305,56 @@ use Prism\Prism\Facades\Tool;
 $tool = Tool::make(CurrentWeatherTool::class);
 ```
 
+## Client-Executed Tools
+
+Sometimes you need tools that are executed by the client (e.g., frontend application) rather than on the server. Client-executed tools are defined without a handler function - simply omit the `using()` call:
+
+```php
+use Prism\Prism\Facades\Tool;
+
+$clientTool = Tool::as('browser_action')
+    ->for('Perform an action in the user\'s browser')
+    ->withStringParameter('action', 'The action to perform');
+    // Note: No using() call - this tool will be executed by the client
+```
+
+When the AI calls a client-executed tool, Prism will:
+1. Stop execution and return control to your application
+2. Set the response's `finishReason` to `FinishReason::ToolCalls`
+3. Include the tool calls in the response for your client to execute
+
+### Handling Client-Executed Tools
+
+```php
+use Prism\Prism\Facades\Prism;
+use Prism\Prism\Enums\FinishReason;
+
+$response = Prism::text()
+    ->using('anthropic', 'claude-3-5-sonnet-latest')
+    ->withTools([$clientTool])
+    ->withMaxSteps(3)
+    ->withPrompt('Click the submit button')
+    ->asText();
+
+```
+
+### Streaming with Client-Executed Tools
+
+When streaming, client-executed tools emit a `ToolCallEvent` but no `ToolResultEvent`:
+
+```php
+
+$response = Prism::text()
+    ->using('anthropic', 'claude-3-5-sonnet-latest')
+    ->withTools([$clientTool])
+    ->withMaxSteps(3)
+    ->withPrompt('Click the submit button')
+    ->asStream();
+```
+
+> [!NOTE]
+> Client-executed tools are useful for scenarios like browser automation, UI interactions, or any operation that must run on the user's device rather than the server.
+
 ## Tool Choice Options
 
 You can control how the AI uses tools with the `withToolChoice` method:

src/Concerns/CallsTools.php

@@ -6,6 +6,7 @@
 
 use Illuminate\Support\ItemNotFoundException;
 use Illuminate\Support\MultipleItemsFoundException;
+use JsonException;
 use Prism\Prism\Exceptions\PrismException;
 use Prism\Prism\Tool;
 use Prism\Prism\ValueObjects\ToolCall;
@@ -18,6 +19,8 @@ trait CallsTools
      * @param  Tool[]  $tools
      * @param  ToolCall[]  $toolCalls
      * @return ToolResult[]
+     *
+     * @throws PrismException|JsonException
      */
     protected function callTools(array $tools, array $toolCalls): array
     {
@@ -47,12 +50,25 @@ function (ToolCall $toolCall) use ($tools): ToolResult {
                 }
 
             },
-            $toolCalls
+            array_filter($toolCalls, fn (ToolCall $toolCall): bool => ! $this->resolveTool($toolCall->name, $tools)->isClientExecuted())
         );
     }
 
     /**
      * @param  Tool[]  $tools
+     * @param  ToolCall[]  $toolCalls
+     *
+     * @throws PrismException
+     */
+    protected function hasDeferredTools(array $tools, array $toolCalls): bool
+    {
+        return array_any($toolCalls, fn (ToolCall $toolCall): bool => $this->resolveTool($toolCall->name, $tools)->isClientExecuted());
+    }
+
+    /**
+     * @param  Tool[]  $tools
+     *
+     * @throws PrismException
      */
     protected function resolveTool(string $name, array $tools): Tool
     {

src/Exceptions/PrismException.php

@@ -76,4 +76,11 @@ public static function unsupportedProviderAction(string $method, string $provide
             $provider,
         ));
     }
+
+    public static function toolHandlerNotDefined(string $toolName): self
+    {
+        return new self(
+            sprintf('Tool (%s) has no handler defined', $toolName)
+        );
+    }
 }

src/Providers/Anthropic/Handlers/Stream.php

@@ -443,9 +443,18 @@ protected function handleToolCalls(Request $request, int $depth): Generator
 
         // Execute tools and emit results
         $toolResults = [];
+        $hasDeferred = false;
         foreach ($toolCalls as $toolCall) {
             try {
                 $tool = $this->resolveTool($toolCall->name, $request->tools());
+
+                // Skip deferred tools - frontend will provide results
+                if ($tool->isClientExecuted()) {
+                    $hasDeferred = true;
+
+                    continue;
+                }
+
                 $result = call_user_func_array($tool->handle(...), $toolCall->arguments());
 
                 $toolResult = new ToolResult(
@@ -483,6 +492,17 @@ protected function handleToolCalls(Request $request, int $depth): Generator
             }
         }
 
+        // skip calling llm if there are pending deferred tools
+        if ($hasDeferred) {
+            yield new StreamEndEvent(
+                id: EventID::generate(),
+                timestamp: time(),
+                finishReason: FinishReason::ToolCalls
+            );
+
+            return;
+        }
+
         // Add messages to request for next turn
         if ($toolResults !== []) {
             $request->addMessage(new AssistantMessage(

src/Providers/Anthropic/Handlers/Structured.php

@@ -172,7 +172,7 @@ protected function executeCustomToolsAndContinue(array $toolCalls, Response $tem
         $this->request->addMessage($message);
         $this->addStep($toolCalls, $tempResponse, $toolResults);
 
-        if ($this->canContinue()) {
+        if (! $this->hasDeferredTools($this->request->tools(), $toolCalls) && $this->canContinue()) {
             return $this->handle();
         }
 

src/Providers/Anthropic/Handlers/Text.php

@@ -113,7 +113,7 @@ protected function handleToolCalls(): Response
 
         $this->addStep($toolResults);
 
-        if ($this->responseBuilder->steps->count() < $this->request->maxSteps()) {
+        if (! $this->hasDeferredTools($this->request->tools(), $this->tempResponse->toolCalls) && $this->responseBuilder->steps->count() < $this->request->maxSteps()) {
             return $this->handle();
         }
 

src/Providers/DeepSeek/Handlers/Stream.php

@@ -359,6 +359,17 @@ protected function handleToolCalls(Request $request, string $text, array $toolCa
             );
         }
 
+        // skip calling llm if there are pending deferred tools
+        if ($this->hasDeferredTools($request->tools(), $mappedToolCalls)) {
+            yield new StreamEndEvent(
+                id: EventID::generate(),
+                timestamp: time(),
+                finishReason: FinishReason::ToolCalls
+            );
+
+            return;
+        }
+
         $request->addMessage(new AssistantMessage($text, $mappedToolCalls));
         $request->addMessage(new ToolResultMessage($toolResults));
 

src/Providers/DeepSeek/Handlers/Text.php

@@ -73,7 +73,10 @@ protected function handleToolCalls(array $data, Request $request): TextResponse
 
         $this->addStep($data, $request, $toolResults);
 
-        if ($this->shouldContinue($request)) {
+        if (! $this->hasDeferredTools($request->tools(), ToolCallMap::map(data_get($data, 'choices.0.message.tool_calls', [])))
+            &&
+            $this->shouldContinue($request)
+        ) {
             return $this->handle($request);
         }
 

src/Providers/Gemini/Handlers/Stream.php

@@ -283,6 +283,7 @@ protected function handleToolCalls(
         array $data = []
     ): Generator {
         $mappedToolCalls = [];
+        $hasDeferred = false;
 
         // Convert tool calls to ToolCall objects
         foreach ($this->state->toolCalls() as $toolCallData) {
@@ -294,6 +295,14 @@ protected function handleToolCalls(
         foreach ($mappedToolCalls as $toolCall) {
             try {
                 $tool = $this->resolveTool($toolCall->name, $request->tools());
+
+                // Skip deferred tools - frontend will provide results
+                if ($tool->isClientExecuted()) {
+                    $hasDeferred = true;
+
+                    continue;
+                }
+
                 $result = call_user_func_array($tool->handle(...), $toolCall->arguments());
 
                 $toolResult = new ToolResult(
@@ -333,6 +342,17 @@ protected function handleToolCalls(
             }
         }
 
+        // skip calling llm if there are pending deferred tools
+        if ($hasDeferred) {
+            yield new StreamEndEvent(
+                id: EventID::generate(),
+                timestamp: time(),
+                finishReason: FinishReason::ToolCalls
+            );
+
+            return;
+        }
+
         // Add messages for next turn and continue streaming
         if ($toolResults !== []) {
             $request->addMessage(new AssistantMessage($this->state->currentText(), $mappedToolCalls));

src/Providers/Gemini/Handlers/Structured.php

@@ -209,7 +209,7 @@ protected function handleToolCalls(array $data, Request $request): StructuredRes
 
         $this->addStep($data, $request, FinishReason::ToolCalls, $toolResults);
 
-        if ($this->shouldContinue($request)) {
+        if (! $this->hasDeferredTools($request->tools(), ToolCallMap::map(data_get($data, 'candidates.0.content.parts', []))) && $this->shouldContinue($request)) {
             return $this->handle($request);
         }
 

src/Providers/Gemini/Handlers/Text.php

@@ -156,7 +156,7 @@ protected function handleToolCalls(array $data, Request $request): TextResponse
 
         $this->addStep($data, $request, FinishReason::ToolCalls, $toolResults);
 
-        if ($this->shouldContinue($request)) {
+        if (! $this->hasDeferredTools($request->tools(), ToolCallMap::map(data_get($data, 'candidates.0.content.parts', []))) && $this->shouldContinue($request)) {
             return $this->handle($request);
         }
 

src/Providers/Groq/Handlers/Stream.php

@@ -257,6 +257,17 @@ protected function handleToolCalls(
             );
         }
 
+        // skip calling llm if there are pending deferred tools
+        if ($this->hasDeferredTools($request->tools(), $mappedToolCalls)) {
+            yield new StreamEndEvent(
+                id: EventID::generate(),
+                timestamp: time(),
+                finishReason: FinishReason::ToolCalls
+            );
+
+            return;
+        }
+
         $request->addMessage(new AssistantMessage($text, $mappedToolCalls));
         $request->addMessage(new ToolResultMessage($toolResults));
 

src/Providers/Groq/Handlers/Text.php

@@ -95,7 +95,7 @@ protected function handleToolCalls(array $data, Request $request, ClientResponse
 
         $this->addStep($data, $request, $clientResponse, FinishReason::ToolCalls, $toolResults);
 
-        if ($this->shouldContinue($request)) {
+        if (! $this->hasDeferredTools($request->tools(), $this->mapToolCalls(data_get($data, 'choices.0.message.tool_calls', []) ?? [])) && $this->shouldContinue($request)) {
             return $this->handle($request);
         }
 

src/Providers/Mistral/Handlers/Stream.php

@@ -251,6 +251,17 @@ protected function handleToolCalls(
             );
         }
 
+        // skip calling llm if there are pending deferred tools
+        if ($this->hasDeferredTools($request->tools(), $mappedToolCalls)) {
+            yield new StreamEndEvent(
+                id: EventID::generate(),
+                timestamp: time(),
+                finishReason: FinishReason::ToolCalls
+            );
+
+            return;
+        }
+
         $request->addMessage(new AssistantMessage($text, $mappedToolCalls));
         $request->addMessage(new ToolResultMessage($toolResults));
 

src/Providers/Mistral/Handlers/Text.php

@@ -81,7 +81,7 @@ protected function handleToolCalls(array $data, Request $request, ClientResponse
 
         $this->addStep($data, $request, $clientResponse, $toolResults);
 
-        if ($this->shouldContinue($request)) {
+        if (! $this->hasDeferredTools($request->tools(), $this->mapToolCalls(data_get($data, 'choices.0.message.tool_calls', []))) && $this->shouldContinue($request)) {
             return $this->handle($request);
         }
 

src/Providers/Ollama/Handlers/Stream.php

@@ -273,6 +273,17 @@ protected function handleToolCalls(
             );
         }
 
+        // skip calling llm if there are pending deferred tools
+        if ($this->hasDeferredTools($request->tools(), $mappedToolCalls)) {
+            yield new StreamEndEvent(
+                id: EventID::generate(),
+                timestamp: time(),
+                finishReason: FinishReason::ToolCalls
+            );
+
+            return;
+        }
+
         // Add messages for next turn
         $request->addMessage(new AssistantMessage($text, $mappedToolCalls));
         $request->addMessage(new ToolResultMessage($toolResults));

src/Providers/Ollama/Handlers/Text.php

@@ -105,7 +105,7 @@ protected function handleToolCalls(array $data, Request $request): Response
 
         $this->addStep($data, $request, $toolResults);
 
-        if ($this->shouldContinue($request)) {
+        if (! $this->hasDeferredTools($request->tools(), $this->mapToolCalls(data_get($data, 'message.tool_calls', []))) && $this->shouldContinue($request)) {
             return $this->handle($request);
         }
 
@@ -133,10 +133,18 @@ protected function shouldContinue(Request $request): bool
      */
     protected function addStep(array $data, Request $request, array $toolResults = []): void
     {
+        $toolCalls = $this->mapToolCalls(data_get($data, 'message.tool_calls', []) ?? []);
+
+        // Ollama sends done_reason: "stop" even when there are tool calls
+        // Override finish reason to ToolCalls when tool calls are present
+        $finishReason = $toolCalls === []
+            ? $this->mapFinishReason($data)
+            : FinishReason::ToolCalls;
+
         $this->responseBuilder->addStep(new Step(
             text: data_get($data, 'message.content') ?? '',
-            finishReason: $this->mapFinishReason($data),
-            toolCalls: $this->mapToolCalls(data_get($data, 'message.tool_calls', []) ?? []),
+            finishReason: $finishReason,
+            toolCalls: $toolCalls,
             toolResults: $toolResults,
             providerToolCalls: [],
             usage: new Usage(

src/Providers/OpenAI/Handlers/Stream.php

@@ -352,6 +352,17 @@ protected function handleToolCalls(Request $request, int $depth): Generator
             );
         }
 
+        // skip calling llm if there are pending deferred tools
+        if ($this->hasDeferredTools($request->tools(), $mappedToolCalls)) {
+            yield new StreamEndEvent(
+                id: EventID::generate(),
+                timestamp: time(),
+                finishReason: FinishReason::ToolCalls
+            );
+
+            return;
+        }
+
         $request->addMessage(new AssistantMessage($this->state->currentText(), $mappedToolCalls));
         $request->addMessage(new ToolResultMessage($toolResults));
 

src/Providers/OpenAI/Handlers/Structured.php

@@ -100,7 +100,7 @@ protected function handleToolCalls(array $data, Request $request, ClientResponse
 
         $this->addStep($data, $request, $clientResponse, $toolResults);
 
-        if ($this->shouldContinue($request)) {
+        if (! $this->hasDeferredTools($request->tools(), ToolCallMap::map($this->extractFunctionCalls($data))) && $this->shouldContinue($request)) {
             return $this->handle($request);
         }
 

src/Providers/OpenAI/Handlers/Text.php

@@ -100,7 +100,10 @@ protected function handleToolCalls(array $data, Request $request, ClientResponse
 
         $this->addStep($data, $request, $clientResponse, $toolResults);
 
-        if ($this->shouldContinue($request)) {
+        if (! $this->hasDeferredTools($request->tools(), ToolCallMap::map(array_filter(data_get($data, 'output', []), fn (array $output): bool => $output['type'] === 'function_call')))
+            &&
+            $this->shouldContinue($request)
+        ) {
             return $this->handle($request);
         }