Feat: 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;
@@ -19,6 +20,8 @@ trait CallsTools
      * @param  Tool[]  $tools
      * @param  ToolCall[]  $toolCalls
      * @return ToolResult[]
+     *
+     * @throws PrismException|JsonException
      */
     protected function callTools(array $tools, array $toolCalls): array
     {
@@ -53,12 +56,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/Enums/StreamEventType.php

@@ -21,4 +21,6 @@ enum StreamEventType: string
     case Artifact = 'artifact';
     case Error = 'error';
     case StreamEnd = 'stream_end';
+    case StepStart = 'step_start';
+    case StepFinish = 'step_finish';
 }

src/Events/Broadcasting/StepFinishBroadcast.php

@@ -0,0 +1,7 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Prism\Prism\Events\Broadcasting;
+
+class StepFinishBroadcast extends StreamEventBroadcast {}

src/Events/Broadcasting/StepStartBroadcast.php

@@ -0,0 +1,7 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Prism\Prism\Events\Broadcasting;
+
+class StepStartBroadcast extends StreamEventBroadcast {}

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

@@ -18,6 +18,8 @@
 use Prism\Prism\Streaming\Events\CitationEvent;
 use Prism\Prism\Streaming\Events\ErrorEvent;
 use Prism\Prism\Streaming\Events\ProviderToolEvent;
+use Prism\Prism\Streaming\Events\StepFinishEvent;
+use Prism\Prism\Streaming\Events\StepStartEvent;
 use Prism\Prism\Streaming\Events\StreamEndEvent;
 use Prism\Prism\Streaming\Events\StreamEvent;
 use Prism\Prism\Streaming\Events\StreamStartEvent;
@@ -79,18 +81,28 @@ protected function processStream(Response $response, Request $request, int $dept
             $streamEvent = $this->processEvent($event);
 
             if ($streamEvent instanceof Generator) {
-                yield from $streamEvent;
+                foreach ($streamEvent as $event) {
+                    yield $event;
+                }
             } elseif ($streamEvent instanceof StreamEvent) {
                 yield $streamEvent;
             }
         }
 
         if ($this->state->hasToolCalls()) {
-            yield from $this->handleToolCalls($request, $depth);
+            foreach ($this->handleToolCalls($request, $depth) as $item) {
+                yield $item;
+            }
 
             return;
         }
 
+        $this->state->markStepFinished();
+        yield new StepFinishEvent(
+            id: EventID::generate(),
+            timestamp: time()
+        );
+
         yield $this->emitStreamEndEvent();
     }
 
@@ -115,8 +127,9 @@ protected function processEvent(array $event): StreamEvent|Generator|null
 
     /**
      * @param  array<string, mixed>  $event
+     * @return Generator<StreamEvent>
      */
-    protected function handleMessageStart(array $event): ?StreamStartEvent
+    protected function handleMessageStart(array $event): Generator
     {
         $message = $event['message'] ?? [];
         $this->state->withMessageId($message['id'] ?? EventID::generate());
@@ -132,18 +145,25 @@ protected function handleMessageStart(array $event): ?StreamStartEvent
         }
 
         // Only emit StreamStartEvent once per streaming session
-        if (! $this->state->shouldEmitStreamStart()) {
-            return null;
+        if ($this->state->shouldEmitStreamStart()) {
+            $this->state->markStreamStarted();
+
+            yield new StreamStartEvent(
+                id: EventID::generate(),
+                timestamp: time(),
+                model: $message['model'] ?? 'unknown',
+                provider: 'anthropic'
+            );
         }
 
-        $this->state->markStreamStarted();
+        if ($this->state->shouldEmitStepStart()) {
+            $this->state->markStepStarted();
 
-        return new StreamStartEvent(
-            id: EventID::generate(),
-            timestamp: time(),
-            model: $message['model'] ?? 'unknown',
-            provider: 'anthropic'
-        );
+            yield new StepStartEvent(
+                id: EventID::generate(),
+                timestamp: time()
+            );
+        }
     }
 
     /**
@@ -475,9 +495,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;
+                }
+
                 $output = call_user_func_array($tool->handle(...), $toolCall->arguments());
 
                 if (is_string($output)) {
@@ -531,6 +560,23 @@ protected function handleToolCalls(Request $request, int $depth): Generator
             }
         }
 
+        // skip calling llm if there are pending deferred tools
+        if ($hasDeferred) {
+            $this->state->markStepFinished();
+            yield new StepFinishEvent(
+                id: EventID::generate(),
+                timestamp: time()
+            );
+
+            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(
@@ -544,6 +590,13 @@ protected function handleToolCalls(Request $request, int $depth): Generator
 
             $request->addMessage(new ToolResultMessage($toolResults));
 
+            // Emit step finish after tool calls
+            $this->state->markStepFinished();
+            yield new StepFinishEvent(
+                id: EventID::generate(),
+                timestamp: time()
+            );
+
             // Continue streaming if within step limit
             $depth++;
             if ($depth < $request->maxSteps()) {

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

@@ -21,6 +21,8 @@
 use Prism\Prism\Providers\DeepSeek\Maps\ToolMap;
 use Prism\Prism\Streaming\EventID;
 use Prism\Prism\Streaming\Events\ArtifactEvent;
+use Prism\Prism\Streaming\Events\StepFinishEvent;
+use Prism\Prism\Streaming\Events\StepStartEvent;
 use Prism\Prism\Streaming\Events\StreamEndEvent;
 use Prism\Prism\Streaming\Events\StreamEvent;
 use Prism\Prism\Streaming\Events\StreamStartEvent;
@@ -96,6 +98,15 @@ protected function processStream(Response $response, Request $request, int $dept
                 );
             }
 
+            if ($this->state->shouldEmitStepStart()) {
+                $this->state->markStepStarted();
+
+                yield new StepStartEvent(
+                    id: EventID::generate(),
+                    timestamp: time()
+                );
+            }
+
             if ($this->hasToolCalls($data)) {
                 $toolCalls = $this->extractToolCalls($data, $toolCalls);
 
@@ -214,6 +225,12 @@ protected function processStream(Response $response, Request $request, int $dept
             return;
         }
 
+        $this->state->markStepFinished();
+        yield new StepFinishEvent(
+            id: EventID::generate(),
+            timestamp: time()
+        );
+
         yield new StreamEndEvent(
             id: EventID::generate(),
             timestamp: time(),
@@ -378,9 +395,32 @@ protected function handleToolCalls(Request $request, string $text, array $toolCa
             }
         }
 
+        // skip calling llm if there are pending deferred tools
+        if ($this->hasDeferredTools($request->tools(), $mappedToolCalls)) {
+            $this->state->markStepFinished();
+            yield new StepFinishEvent(
+                id: EventID::generate(),
+                timestamp: time()
+            );
+
+            yield new StreamEndEvent(
+                id: EventID::generate(),
+                timestamp: time(),
+                finishReason: FinishReason::ToolCalls
+            );
+
+            return;
+        }
+
         $request->addMessage(new AssistantMessage($text, $mappedToolCalls));
         $request->addMessage(new ToolResultMessage($toolResults));
 
+        $this->state->markStepFinished();
+        yield new StepFinishEvent(
+            id: EventID::generate(),
+            timestamp: time()
+        );
+
         $this->state->resetTextState();
         $this->state->withMessageId(EventID::generate());
 

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);
         }