feature #709 [Agent] Dispatch more tool call events (franzwilding)

This PR was squashed before being merged into the main branch.

Discussion
----------

[Agent] Dispatch more tool call events

| Q             | A
| ------------- | ---
| Bug fix?      | no
| New feature?  | no
| Docs?         | no
| Issues        | Fix #680
| License       | MIT

This PR dispatches three new events around tool calling.

Commits
-------

36079d2 [Agent] Dispatch more tool call events

Author: OskarStark

src/agent/doc/index.rst

@@ -331,6 +331,24 @@ to skip the next LLM call by setting a result yourself::
         }
     });
 
+Tool Call Lifecycle Events
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you need to react more granularly to the lifecycle of individual tool calls, you can listen to the
+``ToolCallArgumentsResolved``, ``ToolCallSucceeded`` and ``ToolCallFailed`` events. These are dispatched at different stages::
+
+    $eventDispatcher->addListener(ToolCallArgumentsResolved::class, function (ToolCallArgumentsResolved $event): void {
+        // Let the client know, that the tool $event->toolCall->name was executed
+    });
+
+    $eventDispatcher->addListener(ToolCallSucceeded::class, function (ToolCallSucceeded $event): void {
+        // Let the client know, that the tool $event->toolCall->name successfully returned the result $event->result
+    });
+
+    $eventDispatcher->addListener(ToolCallFailed::class, function (ToolCallFailed $event): void {
+        // Let the client know, that the tool $event->toolCall->name failed with the exception: $event->exception
+    });
+
 Keeping Tool Messages
 ~~~~~~~~~~~~~~~~~~~~~
 

src/agent/src/Toolbox/Event/ToolCallFailed.php

@@ -0,0 +1,31 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\AI\Agent\Toolbox\Event;
+
+use Symfony\AI\Platform\Tool\Tool;
+
+/**
+ * Dispatched after successfully invoking a tool.
+ */
+final readonly class ToolCallFailed
+{
+    /**
+     * @param array<string, mixed> $arguments
+     */
+    public function __construct(
+        public object $tool,
+        public Tool $metadata,
+        public array $arguments,
+        public \Throwable $exception,
+    ) {
+    }
+}

src/agent/src/Toolbox/Event/ToolCallSucceeded.php

@@ -0,0 +1,31 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\AI\Agent\Toolbox\Event;
+
+use Symfony\AI\Platform\Tool\Tool;
+
+/**
+ * Dispatched after successfully invoking a tool.
+ */
+final readonly class ToolCallSucceeded
+{
+    /**
+     * @param array<string, mixed> $arguments
+     */
+    public function __construct(
+        public object $tool,
+        public Tool $metadata,
+        public array $arguments,
+        public mixed $result,
+    ) {
+    }
+}

src/agent/src/Toolbox/Toolbox.php

@@ -14,6 +14,8 @@
 use Psr\Log\LoggerInterface;
 use Psr\Log\NullLogger;
 use Symfony\AI\Agent\Toolbox\Event\ToolCallArgumentsResolved;
+use Symfony\AI\Agent\Toolbox\Event\ToolCallFailed;
+use Symfony\AI\Agent\Toolbox\Event\ToolCallSucceeded;
 use Symfony\AI\Agent\Toolbox\Exception\ToolExecutionException;
 use Symfony\AI\Agent\Toolbox\Exception\ToolExecutionExceptionInterface;
 use Symfony\AI\Agent\Toolbox\Exception\ToolNotFoundException;
@@ -80,12 +82,14 @@ public function execute(ToolCall $toolCall): mixed
 
             $arguments = $this->argumentResolver->resolveArguments($metadata, $toolCall);
             $this->eventDispatcher?->dispatch(new ToolCallArgumentsResolved($tool, $metadata, $arguments));
-
             $result = $tool->{$metadata->reference->method}(...$arguments);
+            $this->eventDispatcher?->dispatch(new ToolCallSucceeded($tool, $metadata, $arguments, $result));
         } catch (ToolExecutionExceptionInterface $e) {
+            $this->eventDispatcher?->dispatch(new ToolCallFailed($tool, $metadata, $arguments ?? [], $e));
             throw $e;
         } catch (\Throwable $e) {
             $this->logger->warning(\sprintf('Failed to execute tool "%s".', $toolCall->name), ['exception' => $e]);
+            $this->eventDispatcher?->dispatch(new ToolCallFailed($tool, $metadata, $arguments ?? [], $e));
             throw ToolExecutionException::executionFailed($toolCall, $e);
         }
 

src/agent/tests/Toolbox/ToolboxEventDispatcherTest.php

@@ -0,0 +1,95 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\AI\Agent\Tests\Toolbox;
+
+use PHPUnit\Framework\MockObject\Exception;
+use PHPUnit\Framework\TestCase;
+use Symfony\AI\Agent\Toolbox\Event\ToolCallArgumentsResolved;
+use Symfony\AI\Agent\Toolbox\Event\ToolCallFailed;
+use Symfony\AI\Agent\Toolbox\Event\ToolCallSucceeded;
+use Symfony\AI\Agent\Toolbox\Toolbox;
+use Symfony\AI\Fixtures\Tool\ToolCustomException;
+use Symfony\AI\Fixtures\Tool\ToolException;
+use Symfony\AI\Fixtures\Tool\ToolNoParams;
+use Symfony\AI\Platform\Result\ToolCall;
+use Symfony\Component\EventDispatcher\EventDispatcherInterface;
+
+final class ToolboxEventDispatcherTest extends TestCase
+{
+    private Toolbox $toolbox;
+    private array $dispatchedEvents = [];
+
+    /**
+     * @throws Exception
+     */
+    protected function setUp(): void
+    {
+        $dispatcher = $this->createMock(EventDispatcherInterface::class);
+        $dispatcher
+            ->method('dispatch')
+            ->willReturnCallback(function (object $event, ?string $eventName = null) {
+                $this->dispatchedEvents[] = $eventName ?? $event::class;
+
+                return $event;
+            });
+        $this->toolbox = new Toolbox([
+            new ToolNoParams(),
+            new ToolException(),
+            new ToolCustomException(),
+        ], eventDispatcher: $dispatcher);
+    }
+
+    public function testExecuteWithUnknownTool()
+    {
+        try {
+            $this->toolbox->execute(new ToolCall('call_1234', 'foo_bar_baz'));
+        } catch (\Throwable) {
+        }
+        $this->assertEmpty($this->dispatchedEvents);
+    }
+
+    public function testExecuteWithToolExecutionException()
+    {
+        try {
+            $this->toolbox->execute(new ToolCall('call_1234', 'tool_exception'));
+        } catch (\Throwable) {
+        }
+        $this->assertEquals([
+            ToolCallArgumentsResolved::class,
+            ToolCallFailed::class,
+        ], $this->dispatchedEvents);
+    }
+
+    public function testExecuteWithCustomExecutionException()
+    {
+        try {
+            $this->toolbox->execute(new ToolCall('call_1234', 'tool_custom_exception'));
+        } catch (\Throwable) {
+        }
+        $this->assertEquals([
+            ToolCallArgumentsResolved::class,
+            ToolCallFailed::class,
+        ], $this->dispatchedEvents);
+    }
+
+    public function testExecuteSuccess()
+    {
+        try {
+            $this->toolbox->execute(new ToolCall('call_1234', 'tool_no_params'));
+        } catch (\Throwable) {
+        }
+        $this->assertEquals([
+            ToolCallArgumentsResolved::class,
+            ToolCallSucceeded::class,
+        ], $this->dispatchedEvents);
+    }
+}