feat(streaming|anthropic): implement Anthropic provider tool call handling in streaming responses (#712)

Author: roymckenzie

src/Providers/Anthropic/Handlers/Stream.php

@@ -16,6 +16,7 @@
 use Prism\Prism\Streaming\EventID;
 use Prism\Prism\Streaming\Events\CitationEvent;
 use Prism\Prism\Streaming\Events\ErrorEvent;
+use Prism\Prism\Streaming\Events\ProviderToolEvent;
 use Prism\Prism\Streaming\Events\StreamEndEvent;
 use Prism\Prism\Streaming\Events\StreamEvent;
 use Prism\Prism\Streaming\Events\StreamStartEvent;
@@ -152,6 +153,7 @@ protected function handleContentBlockStart(array $event): ?StreamEvent
             ),
             'thinking' => $this->handleThinkingStart(),
             'tool_use' => $this->handleToolUseStart($contentBlock),
+            'server_tool_use' => $this->handleProviderToolUseStart($contentBlock),
             default => null,
         };
     }
@@ -170,6 +172,7 @@ protected function handleContentBlockDelta(array $event): ?StreamEvent
             ['thinking', 'thinking_delta'] => $this->handleThinkingDelta($delta),
             ['thinking', 'signature_delta'] => $this->handleSignatureDelta($delta),
             ['tool_use', 'input_json_delta'] => $this->handleToolInputDelta($delta),
+            ['server_tool_use', 'input_json_delta'] => $this->handleProviderToolInputDelta($delta),
             default => null,
         };
     }
@@ -191,6 +194,7 @@ protected function handleContentBlockStop(array $event): ?StreamEvent
                 reasoningId: $this->state->reasoningId()
             ),
             'tool_use' => $this->handleToolUseComplete(),
+            'server_tool_use' => $this->handleProviderToolUseComplete(),
             default => null,
         };
 
@@ -493,6 +497,72 @@ protected function handleToolCalls(Request $request, int $depth): Generator
         }
     }
 
+    /**
+     * @param  array<string, mixed>  $contentBlock
+     */
+    protected function handleProviderToolUseStart(array $contentBlock): ProviderToolEvent
+    {
+        if ($this->state->currentBlockIndex() !== null) {
+            $this->state->addProviderToolCall($this->state->currentBlockIndex(), [
+                'id' => $contentBlock['id'] ?? EventID::generate(),
+                'name' => $contentBlock['name'] ?? 'unknown',
+                'input' => '',
+            ]);
+        }
+
+        return new ProviderToolEvent(
+            id: EventID::generate(),
+            timestamp: time(),
+            toolType: $contentBlock['name'] ?? 'unknown',
+            status: 'started',
+            itemId: $contentBlock['id'],
+            data: $contentBlock['input'] ?? '',
+        );
+    }
+
+    /**
+     * @param  array<string, mixed>  $delta
+     */
+    protected function handleProviderToolInputDelta(array $delta): null
+    {
+        $partialJson = $delta['partial_json'] ?? '';
+
+        if ($this->state->currentBlockIndex() !== null && isset($this->state->providerToolCalls()[$this->state->currentBlockIndex()])) {
+            $this->state->appendProviderToolCallInput($this->state->currentBlockIndex(), $partialJson);
+        }
+
+        return null;
+    }
+
+    protected function handleProviderToolUseComplete(): ?ProviderToolEvent
+    {
+        if ($this->state->currentBlockIndex() === null || ! isset($this->state->providerToolCalls()[$this->state->currentBlockIndex()])) {
+            return null;
+        }
+
+        $providerToolCall = $this->state->providerToolCalls()[$this->state->currentBlockIndex()];
+
+        // Parse the JSON input
+        $input = $providerToolCall['input'];
+        if (is_string($input) && json_validate($input)) {
+            $input = json_decode($input, true);
+        } elseif (is_string($input) && $input !== '') {
+            // If it's not valid JSON but not empty, wrap in array
+            $input = ['input' => $input];
+        } else {
+            $input = [];
+        }
+
+        return new ProviderToolEvent(
+            id: EventID::generate(),
+            timestamp: time(),
+            toolType: $providerToolCall['name'],
+            status: 'completed',
+            itemId: $providerToolCall['id'],
+            data: $input,
+        );
+    }
+
     /**
      * @return array<string, mixed>|null
      */

src/Providers/Anthropic/ValueObjects/AnthropicStreamState.php

@@ -10,6 +10,9 @@ class AnthropicStreamState extends StreamState
 {
     protected string $currentThinkingSignature = '';
 
+    /** @var array<int, array<string, mixed>> */
+    protected array $providerToolCalls = [];
+
     public function appendThinkingSignature(string $signature): self
     {
         $this->currentThinkingSignature .= $signature;
@@ -22,10 +25,40 @@ public function currentThinkingSignature(): string
         return $this->currentThinkingSignature;
     }
 
+    /**
+     * @param  array<string, mixed>  $providerToolCall
+     */
+    public function addProviderToolCall(int $index, array $providerToolCall): self
+    {
+        $this->providerToolCalls[$index] = $providerToolCall;
+
+        return $this;
+    }
+
+    /**
+     * @return array<int, array<string, mixed>>
+     */
+    public function providerToolCalls(): array
+    {
+        return $this->providerToolCalls;
+    }
+
+    public function appendProviderToolCallInput(int $index, string $input): self
+    {
+        if (! isset($this->providerToolCalls[$index])) {
+            $this->providerToolCalls[$index] = ['input' => ''];
+        }
+
+        $this->providerToolCalls[$index]['input'] .= $input;
+
+        return $this;
+    }
+
     public function reset(): self
     {
         parent::reset();
         $this->currentThinkingSignature = '';
+        $this->providerToolCalls = [];
 
         return $this;
     }
@@ -34,6 +67,7 @@ public function resetTextState(): self
     {
         parent::resetTextState();
         $this->currentThinkingSignature = '';
+        $this->providerToolCalls = [];
 
         return $this;
     }

tests/Providers/Anthropic/StreamTest.php

@@ -16,6 +16,7 @@
 use Prism\Prism\Facades\Prism;
 use Prism\Prism\Facades\Tool;
 use Prism\Prism\Streaming\Events\CitationEvent;
+use Prism\Prism\Streaming\Events\ProviderToolEvent;
 use Prism\Prism\Streaming\Events\StreamEndEvent;
 use Prism\Prism\Streaming\Events\StreamEvent;
 use Prism\Prism\Streaming\Events\TextDeltaEvent;
@@ -454,6 +455,45 @@
     });
 });
 
+describe('provider tool calls', function (): void {
+    it('can handle provider tool calls in streaming responses', function (): void {
+        FixtureResponse::fakeStreamResponses('v1/messages', 'anthropic/stream-with-web-search-citations');
+
+        $response = Prism::text()
+            ->using(Provider::Anthropic, 'claude-3-7-sonnet-20250219')
+            ->withPrompt('What is the weather like in London UK today?')
+            ->withProviderTools([new ProviderTool(type: 'web_search_20250305', name: 'web_search')])
+            ->asStream();
+
+        $providerToolEvents = [];
+
+        foreach ($response as $event) {
+            if ($event instanceof ProviderToolEvent) {
+                $providerToolEvents[] = $event;
+            }
+        }
+
+        // Verify that provider tool call events were emitted
+        expect($providerToolEvents)->not->toBeEmpty();
+
+        // Verify the structure of the first provider tool call event
+        $firstEvent = $providerToolEvents[0];
+        expect($firstEvent)->toBeInstanceOf(ProviderToolEvent::class);
+        expect($firstEvent->toolType)->toBe('web_search');
+        expect($firstEvent->status)->toBe('started');
+        expect($firstEvent->itemId)->not->toBeEmpty();
+        expect($firstEvent->data)->toBeArray();
+
+        // Verify the structure of the second provider tool call event
+        $secondEvent = $providerToolEvents[1];
+        expect($secondEvent)->toBeInstanceOf(ProviderToolEvent::class);
+        expect($secondEvent->toolType)->toBe('web_search');
+        expect($secondEvent->status)->toBe('completed');
+        expect($secondEvent->itemId)->not->toBeEmpty();
+        expect($secondEvent->data)->toBeArray();
+    });
+});
+
 describe('exception handling', function (): void {
     it('throws a PrismRateLimitedException with a 429 response code', function (): void {
         Http::fake([

tests/Unit/Providers/Anthropic/AnthropicStreamStateTest.php

@@ -113,11 +113,13 @@
     $state->appendThinkingSignature('sig-1');
     $state->appendText('Hello');
     $state->appendThinkingSignature('-sig-2');
+    $state->addProviderToolCall(0, ['id' => 'tool-123']);
     $state->markStreamStarted();
 
     expect($state->messageId())->toBe('msg-456')
         ->and($state->model())->toBe('claude-3-5-sonnet')
         ->and($state->currentThinkingSignature())->toBe('sig-1-sig-2')
+        ->and($state->providerToolCalls())->toBe([0 => ['id' => 'tool-123']])
         ->and($state->currentText())->toBe('Hello')
         ->and($state->hasStreamStarted())->toBeTrue();
 });
@@ -140,6 +142,8 @@
     $state->appendThinkingSignature('signature-value');
     $state->withBlockContext(2, 'text');
     $state->addToolCall(0, ['id' => 'tool-1', 'name' => 'search']);
+    $state->addProviderToolCall(0, ['id' => 'tool-1']);
+    $state->addProviderToolCall(1, ['id' => 'tool-2']);
     $state->addCitation($citation);
     $state->withUsage($usage);
     $state->withFinishReason(FinishReason::Stop);
@@ -155,6 +159,7 @@
         ->and($state->currentText())->toBe('response text')
         ->and($state->currentThinking())->toBe('thought process')
         ->and($state->currentThinkingSignature())->toBe('signature-value')
+        ->and($state->providerToolCalls())->toBe([0 => ['id' => 'tool-1'], 1 => ['id' => 'tool-2']])
         ->and($state->currentBlockIndex())->toBe(2)
         ->and($state->currentBlockType())->toBe('text')
         ->and($state->toolCalls())->toBe([0 => ['id' => 'tool-1', 'name' => 'search']])
@@ -287,3 +292,84 @@
 
     expect($state->currentThinkingSignature())->toBe($expected);
 });
+
+it('constructs with empty provider tool calls', function (): void {
+    $state = new AnthropicStreamState;
+
+    expect($state->providerToolCalls())->toBe([]);
+});
+
+it('reset clears provider tool calls', function (): void {
+    $state = new AnthropicStreamState;
+    $state->addProviderToolCall(0, ['id' => 'tool-1']);
+    $state->addProviderToolCall(1, ['id' => 'tool-2']);
+
+    $state->reset();
+
+    expect($state->providerToolCalls())->toBe([]);
+});
+
+it('addProviderToolCall adds tool call at specified block index', function (): void {
+    $state = new AnthropicStreamState;
+
+    $state->addProviderToolCall(0, ['id' => 'tool-1']);
+    $state->addProviderToolCall(2, ['id' => 'tool-3']);
+
+    expect($state->providerToolCalls())->toBe([
+        0 => ['id' => 'tool-1'],
+        2 => ['id' => 'tool-3'],
+    ]);
+});
+
+it('addProviderToolCall returns self for fluent chaining', function (): void {
+    $state = new AnthropicStreamState;
+
+    $result = $state->addProviderToolCall(0, ['id' => 'tool-1']);
+
+    expect($result)->toBe($state);
+});
+
+it('appendProviderToolCallInput appends input to existing tool call', function (): void {
+    $state = new AnthropicStreamState;
+
+    $state->addProviderToolCall(0, ['input' => 'initial-']);
+    $state->appendProviderToolCallInput(0, 'more-');
+    $state->appendProviderToolCallInput(0, 'data');
+
+    expect($state->providerToolCalls())->toBe([
+        0 => ['input' => 'initial-more-data'],
+    ]);
+});
+
+it('appendProviderToolCallInput initializes tool call if not present', function (): void {
+    $state = new AnthropicStreamState;
+
+    $state->appendProviderToolCallInput(1, 'input-data');
+
+    expect($state->providerToolCalls())->toBe([
+        1 => ['input' => 'input-data'],
+    ]);
+});
+
+it('appendProviderToolCallInput returns self for fluent chaining', function (): void {
+    $state = new AnthropicStreamState;
+
+    $result = $state->appendProviderToolCallInput(0, 'data');
+
+    expect($result)->toBe($state);
+});
+
+it('handles multiple provider tool calls correctly', function (): void {
+    $state = new AnthropicStreamState;
+
+    $state->addProviderToolCall(0, ['id' => 'tool-1', 'input' => 'start-']);
+    $state->appendProviderToolCallInput(0, 'middle-');
+    $state->appendProviderToolCallInput(0, 'end');
+
+    $state->addProviderToolCall(2, ['id' => 'tool-3', 'input' => 'only-input']);
+
+    expect($state->providerToolCalls())->toBe([
+        0 => ['id' => 'tool-1', 'input' => 'start-middle-end'],
+        2 => ['id' => 'tool-3', 'input' => 'only-input'],
+    ]);
+});