feat: client executed tools

Author: vinitkadam03

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

@@ -388,6 +388,75 @@ 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.
+
+### Explicit Declaration (Recommended)
+
+Use the `clientExecuted()` method to explicitly mark a tool as client-executed:
+
+```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')
+    ->clientExecuted();
+```
+
+This makes your intent clear and self-documenting.
+
+### Implicit Declaration
+
+You can also create a client-executed tool by simply omitting 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');
+    // No using() call - tool is implicitly client-executed
+```
+
+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

@@ -8,10 +8,15 @@
 use Illuminate\Support\Facades\Concurrency;
 use Illuminate\Support\ItemNotFoundException;
 use Illuminate\Support\MultipleItemsFoundException;
+use JsonException;
+use Prism\Prism\Enums\FinishReason;
 use Prism\Prism\Exceptions\PrismException;
 use Prism\Prism\Streaming\EventID;
 use Prism\Prism\Streaming\Events\ArtifactEvent;
+use Prism\Prism\Streaming\Events\StepFinishEvent;
+use Prism\Prism\Streaming\Events\StreamEndEvent;
 use Prism\Prism\Streaming\Events\ToolResultEvent;
+use Prism\Prism\Streaming\StreamState;
 use Prism\Prism\Tool;
 use Prism\Prism\ValueObjects\ToolCall;
 use Prism\Prism\ValueObjects\ToolOutput;
@@ -25,13 +30,15 @@ trait CallsTools
      * @param  Tool[]  $tools
      * @param  ToolCall[]  $toolCalls
      * @return ToolResult[]
+     *
+     * @throws PrismException|JsonException
      */
-    protected function callTools(array $tools, array $toolCalls): array
+    protected function callTools(array $tools, array $toolCalls, bool &$hasPendingToolCalls): array
     {
         $toolResults = [];
 
         // Consume generator to execute all tools and collect results
-        foreach ($this->callToolsAndYieldEvents($tools, $toolCalls, EventID::generate(), $toolResults) as $event) {
+        foreach ($this->callToolsAndYieldEvents($tools, $toolCalls, EventID::generate(), $toolResults, $hasPendingToolCalls) as $event) {
             // Events are discarded for non-streaming handlers
         }
 
@@ -46,13 +53,15 @@ protected function callTools(array $tools, array $toolCalls): array
      * @param  ToolResult[]  $toolResults  Results are collected into this array by reference
      * @return Generator<ToolResultEvent|ArtifactEvent>
      */
-    protected function callToolsAndYieldEvents(array $tools, array $toolCalls, string $messageId, array &$toolResults): Generator
+    protected function callToolsAndYieldEvents(array $tools, array $toolCalls, string $messageId, array &$toolResults, bool &$hasPendingToolCalls): Generator
     {
-        $groupedToolCalls = $this->groupToolCallsByConcurrency($tools, $toolCalls);
+        $serverToolCalls = $this->filterServerExecutedToolCalls($tools, $toolCalls, $hasPendingToolCalls);
+
+        $groupedToolCalls = $this->groupToolCallsByConcurrency($tools, $serverToolCalls);
 
         $executionResults = $this->executeToolsWithConcurrency($tools, $groupedToolCalls, $messageId);
 
-        foreach (array_keys($toolCalls) as $index) {
+        foreach (collect($executionResults)->keys()->sort() as $index) {
             $result = $executionResults[$index];
 
             $toolResults[] = $result['toolResult'];
@@ -64,8 +73,39 @@ protected function callToolsAndYieldEvents(array $tools, array $toolCalls, strin
     }
 
     /**
+     * Filter out client-executed tool calls, setting the pending flag if any are found.
+     *
      * @param  Tool[]  $tools
      * @param  ToolCall[]  $toolCalls
+     * @return array<int, ToolCall> Server-executed tool calls with original indices preserved
+     */
+    protected function filterServerExecutedToolCalls(array $tools, array $toolCalls, bool &$hasPendingToolCalls): array
+    {
+        $serverToolCalls = [];
+
+        foreach ($toolCalls as $index => $toolCall) {
+            try {
+                $tool = $this->resolveTool($toolCall->name, $tools);
+
+                if ($tool->isClientExecuted()) {
+                    $hasPendingToolCalls = true;
+
+                    continue;
+                }
+
+                $serverToolCalls[$index] = $toolCall;
+            } catch (PrismException) {
+                // Unknown tool - keep it so error handling works in executeToolCall
+                $serverToolCalls[$index] = $toolCall;
+            }
+        }
+
+        return $serverToolCalls;
+    }
+
+    /**
+     * @param  Tool[]  $tools
+     * @param  array<int, ToolCall>  $toolCalls
      * @return array{concurrent: array<int, ToolCall>, sequential: array<int, ToolCall>}
      */
     protected function groupToolCallsByConcurrency(array $tools, array $toolCalls): array
@@ -197,8 +237,31 @@ protected function executeToolCall(array $tools, ToolCall $toolCall, string $mes
         }
     }
 
+    /**
+     * Yield stream completion events when client-executed tools are pending.
+     *
+     * @return Generator<StepFinishEvent|StreamEndEvent>
+     */
+    protected function yieldToolCallsFinishEvents(StreamState $state): Generator
+    {
+        yield new StepFinishEvent(
+            id: EventID::generate(),
+            timestamp: time()
+        );
+
+        yield new StreamEndEvent(
+            id: EventID::generate(),
+            timestamp: time(),
+            finishReason: FinishReason::ToolCalls,
+            usage: $state->usage(),
+            citations: $state->citations(),
+        );
+    }
+
     /**
      * @param  Tool[]  $tools
+     *
+     * @throws PrismException
      */
     protected function resolveTool(string $name, array $tools): Tool
     {

src/Exceptions/PrismException.php

@@ -94,4 +94,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

@@ -499,7 +499,15 @@ protected function handleToolCalls(Request $request, int $depth): Generator
 
         // Execute tools and emit results
         $toolResults = [];
-        yield from $this->callToolsAndYieldEvents($request->tools(), $toolCalls, $this->state->messageId(), $toolResults);
+        $hasPendingToolCalls = false;
+        yield from $this->callToolsAndYieldEvents($request->tools(), $toolCalls, $this->state->messageId(), $toolResults, $hasPendingToolCalls);
+
+        if ($hasPendingToolCalls) {
+            $this->state->markStepFinished();
+            yield from $this->yieldToolCallsFinishEvents($this->state);
+
+            return;
+        }
 
         // Add messages to request for next turn
         if ($toolResults !== []) {

src/Providers/Anthropic/Handlers/Structured.php

@@ -150,7 +150,8 @@ protected function handleToolCalls(array $toolCalls, Response $tempResponse): Re
     protected function executeCustomToolsAndFinalize(array $toolCalls, Response $tempResponse): Response
     {
         $customToolCalls = $this->filterCustomToolCalls($toolCalls);
-        $toolResults = $this->callTools($this->request->tools(), $customToolCalls);
+        $hasPendingToolCalls = false;
+        $toolResults = $this->callTools($this->request->tools(), $customToolCalls, $hasPendingToolCalls);
         $this->addStep($toolCalls, $tempResponse, $toolResults);
 
         return $this->responseBuilder->toResponse();
@@ -162,7 +163,8 @@ protected function executeCustomToolsAndFinalize(array $toolCalls, Response $tem
     protected function executeCustomToolsAndContinue(array $toolCalls, Response $tempResponse): Response
     {
         $customToolCalls = $this->filterCustomToolCalls($toolCalls);
-        $toolResults = $this->callTools($this->request->tools(), $customToolCalls);
+        $hasPendingToolCalls = false;
+        $toolResults = $this->callTools($this->request->tools(), $customToolCalls, $hasPendingToolCalls);
 
         $message = new ToolResultMessage($toolResults);
         if ($toolResultCacheType = $this->request->providerOptions('tool_result_cache_type')) {
@@ -173,7 +175,7 @@ protected function executeCustomToolsAndContinue(array $toolCalls, Response $tem
         $this->request->resetToolChoice();
         $this->addStep($toolCalls, $tempResponse, $toolResults);
 
-        if ($this->canContinue()) {
+        if (! $hasPendingToolCalls && $this->canContinue()) {
             return $this->handle();
         }
 

src/Providers/Anthropic/Handlers/Text.php

@@ -93,7 +93,8 @@ public static function buildHttpRequestPayload(PrismRequest $request): array
 
     protected function handleToolCalls(): Response
     {
-        $toolResults = $this->callTools($this->request->tools(), $this->tempResponse->toolCalls);
+        $hasPendingToolCalls = false;
+        $toolResults = $this->callTools($this->request->tools(), $this->tempResponse->toolCalls, $hasPendingToolCalls);
 
         $this->addStep($toolResults);
 
@@ -113,7 +114,7 @@ protected function handleToolCalls(): Response
         $this->request->addMessage($toolResultMessage);
         $this->request->resetToolChoice();
 
-        if ($this->responseBuilder->steps->count() < $this->request->maxSteps()) {
+        if (! $hasPendingToolCalls && $this->responseBuilder->steps->count() < $this->request->maxSteps()) {
             return $this->handle();
         }
 

src/Providers/DeepSeek/Handlers/Stream.php

@@ -381,7 +381,15 @@ protected function handleToolCalls(Request $request, string $text, array $toolCa
         }
 
         $toolResults = [];
-        yield from $this->callToolsAndYieldEvents($request->tools(), $mappedToolCalls, $this->state->messageId(), $toolResults);
+        $hasPendingToolCalls = false;
+        yield from $this->callToolsAndYieldEvents($request->tools(), $mappedToolCalls, $this->state->messageId(), $toolResults, $hasPendingToolCalls);
+
+        if ($hasPendingToolCalls) {
+            $this->state->markStepFinished();
+            yield from $this->yieldToolCallsFinishEvents($this->state);
+
+            return;
+        }
 
         $this->state->markStepFinished();
         yield new StepFinishEvent(

src/Providers/DeepSeek/Handlers/Text.php

@@ -59,7 +59,12 @@ protected function handleToolCalls(array $data, Request $request): TextResponse
     {
         $toolCalls = ToolCallMap::map(data_get($data, 'choices.0.message.tool_calls', []));
 
-        $toolResults = $this->callTools($request->tools(), $toolCalls);
+        $hasPendingToolCalls = false;
+        $toolResults = $this->callTools(
+            $request->tools(),
+            $toolCalls,
+            $hasPendingToolCalls,
+        );
 
         $this->addStep($data, $request, $toolResults);
 
@@ -71,7 +76,7 @@ protected function handleToolCalls(array $data, Request $request): TextResponse
         $request = $request->addMessage(new ToolResultMessage($toolResults));
         $request->resetToolChoice();
 
-        if ($this->shouldContinue($request)) {
+        if (! $hasPendingToolCalls && $this->shouldContinue($request)) {
             return $this->handle($request);
         }
 

src/Providers/Gemini/Handlers/Stream.php

@@ -326,6 +326,7 @@ protected function handleToolCalls(
         array $data = []
     ): Generator {
         $mappedToolCalls = [];
+        $hasPendingToolCalls = false;
 
         // Convert tool calls to ToolCall objects
         foreach ($this->state->toolCalls() as $toolCallData) {
@@ -334,8 +335,16 @@ protected function handleToolCalls(
 
         // Execute tools and emit results
         $toolResults = [];
-        yield from $this->callToolsAndYieldEvents($request->tools(), $mappedToolCalls, $this->state->messageId(), $toolResults);
+        yield from $this->callToolsAndYieldEvents($request->tools(), $mappedToolCalls, $this->state->messageId(), $toolResults, $hasPendingToolCalls);
 
+        if ($hasPendingToolCalls) {
+            $this->state->markStepFinished();
+            yield from $this->yieldToolCallsFinishEvents($this->state);
+
+            return;
+        }
+
+        // Add messages for next turn and continue streaming
         if ($toolResults !== []) {
             // Emit step finish after tool calls
             $this->state->markStepFinished();

src/Providers/Gemini/Handlers/Structured.php

@@ -202,17 +202,19 @@ protected function handleStop(array $data, Request $request, FinishReason $finis
      */
     protected function handleToolCalls(array $data, Request $request): StructuredResponse
     {
+        $hasPendingToolCalls = false;
         $toolResults = $this->callTools(
             $request->tools(),
-            ToolCallMap::map(data_get($data, 'candidates.0.content.parts', []))
+            ToolCallMap::map(data_get($data, 'candidates.0.content.parts', [])),
+            $hasPendingToolCalls,
         );
 
         $request->addMessage(new ToolResultMessage($toolResults));
         $request->resetToolChoice();
 
         $this->addStep($data, $request, FinishReason::ToolCalls, $toolResults);
 
-        if ($this->shouldContinue($request)) {
+        if (! $hasPendingToolCalls && $this->shouldContinue($request)) {
             return $this->handle($request);
         }