feature #58 feat: Denormalize tool arguments (valtzu)

This PR was merged into the main branch.

Discussion
----------

feat: Denormalize tool arguments

| Q             | A
| ------------- | ---
| Bug fix?      | no
| New feature?  | yes
| Docs?         |
| Issues        |
| License       | MIT

Cherry picking php-llm/llm-chain#359

Commits
-------

1491da8 feat: Denormalize tool arguments (#359)

Author: chr-hertel

fixtures/Tool/ToolDate.php

@@ -0,0 +1,26 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\AI\Fixtures\Tool;
+
+use Symfony\AI\Agent\Toolbox\Attribute\AsTool;
+
+#[AsTool('tool_date', 'A tool with date parameter')]
+final class ToolDate
+{
+    /**
+     * @param \DateTimeImmutable $date The date
+     */
+    public function __invoke(\DateTimeImmutable $date): string
+    {
+        return \sprintf('Weekday: %s', $date->format('l'));
+    }
+}

src/agent/src/Toolbox/Event/ToolCallArgumentsResolved.php

@@ -0,0 +1,32 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <[email protected]>
+ *
+ * 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 the arguments are denormalized, just before invoking the tool.
+ *
+ * @author Valtteri R <[email protected]>
+ */
+final readonly class ToolCallArgumentsResolved
+{
+    /**
+     * @param array<string, mixed> $arguments
+     */
+    public function __construct(
+        public object $tool,
+        public Tool $metadata,
+        public array $arguments,
+    ) {
+    }
+}

src/agent/src/Toolbox/ToolCallArgumentResolver.php

@@ -0,0 +1,45 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\AI\Agent\Toolbox;
+
+use Symfony\AI\Platform\Response\ToolCall;
+use Symfony\AI\Platform\Tool\Tool;
+use Symfony\Component\Serializer\Normalizer\DateTimeNormalizer;
+use Symfony\Component\Serializer\Normalizer\DenormalizerInterface;
+use Symfony\Component\Serializer\Normalizer\ObjectNormalizer;
+use Symfony\Component\Serializer\Serializer;
+
+/**
+ * @author Valtteri R <[email protected]>
+ */
+final readonly class ToolCallArgumentResolver implements ToolCallArgumentResolverInterface
+{
+    public function __construct(
+        private DenormalizerInterface $denormalizer = new Serializer([new DateTimeNormalizer(), new ObjectNormalizer()]),
+    ) {
+    }
+
+    public function resolveArguments(object $tool, Tool $metadata, ToolCall $toolCall): array
+    {
+        $method = new \ReflectionMethod($metadata->reference->class, $metadata->reference->method);
+
+        /** @var array<string, \ReflectionProperty> $parameters */
+        $parameters = array_column($method->getParameters(), null, 'name');
+        $arguments = [];
+
+        foreach ($toolCall->arguments as $name => $value) {
+            $arguments[$name] = $this->denormalizer->denormalize($value, (string) $parameters[$name]->getType());
+        }
+
+        return $arguments;
+    }
+}

src/agent/src/Toolbox/ToolCallArgumentResolverInterface.php

@@ -0,0 +1,26 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\AI\Agent\Toolbox;
+
+use Symfony\AI\Platform\Response\ToolCall;
+use Symfony\AI\Platform\Tool\Tool;
+
+/**
+ * @author Valtteri R <[email protected]>
+ */
+interface ToolCallArgumentResolverInterface
+{
+    /**
+     * @return array<string, mixed>
+     */
+    public function resolveArguments(object $tool, Tool $metadata, ToolCall $toolCall): array;
+}

src/agent/src/Toolbox/Toolbox.php

@@ -13,11 +13,13 @@
 
 use Psr\Log\LoggerInterface;
 use Psr\Log\NullLogger;
+use Symfony\AI\Agent\Toolbox\Event\ToolCallArgumentsResolved;
 use Symfony\AI\Agent\Toolbox\Exception\ToolExecutionException;
 use Symfony\AI\Agent\Toolbox\Exception\ToolNotFoundException;
 use Symfony\AI\Agent\Toolbox\ToolFactory\ReflectionToolFactory;
 use Symfony\AI\Platform\Response\ToolCall;
 use Symfony\AI\Platform\Tool\Tool;
+use Symfony\Contracts\EventDispatcher\EventDispatcherInterface;
 
 /**
  * @author Christopher Hertel <[email protected]>
@@ -45,6 +47,8 @@ public function __construct(
         private readonly ToolFactoryInterface $toolFactory,
         iterable $tools,
         private readonly LoggerInterface $logger = new NullLogger(),
+        private readonly ToolCallArgumentResolverInterface $argumentResolver = new ToolCallArgumentResolver(),
+        private readonly ?EventDispatcherInterface $eventDispatcher = null,
     ) {
         $this->tools = $tools instanceof \Traversable ? iterator_to_array($tools) : $tools;
     }
@@ -77,7 +81,11 @@ public function execute(ToolCall $toolCall): mixed
 
         try {
             $this->logger->debug(\sprintf('Executing tool "%s".', $toolCall->name), $toolCall->arguments);
-            $result = $tool->{$metadata->reference->method}(...$toolCall->arguments);
+
+            $arguments = $this->argumentResolver->resolveArguments($tool, $metadata, $toolCall);
+            $this->eventDispatcher?->dispatch(new ToolCallArgumentsResolved($tool, $metadata, $arguments));
+
+            $result = $tool->{$metadata->reference->method}(...$arguments);
         } catch (\Throwable $e) {
             $this->logger->warning(\sprintf('Failed to execute tool "%s".', $toolCall->name), ['exception' => $e]);
             throw ToolExecutionException::executionFailed($toolCall, $e);

src/agent/tests/Toolbox/ToolCallArgumentResolverTest.php

@@ -0,0 +1,41 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <[email protected]>
+ *
+ * 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\Attributes\CoversClass;
+use PHPUnit\Framework\Attributes\Test;
+use PHPUnit\Framework\Attributes\UsesClass;
+use PHPUnit\Framework\TestCase;
+use Symfony\AI\Agent\Toolbox\ToolCallArgumentResolver;
+use Symfony\AI\Fixtures\Tool\ToolDate;
+use Symfony\AI\Platform\Response\ToolCall;
+use Symfony\AI\Platform\Tool\ExecutionReference;
+use Symfony\AI\Platform\Tool\Tool;
+
+#[CoversClass(ToolCallArgumentResolver::class)]
+#[UsesClass(Tool::class)]
+#[UsesClass(ExecutionReference::class)]
+#[UsesClass(ToolCall::class)]
+class ToolCallArgumentResolverTest extends TestCase
+{
+    #[Test]
+    public function resolveArguments(): void
+    {
+        $resolver = new ToolCallArgumentResolver();
+
+        $tool = new ToolDate();
+        $metadata = new Tool(new ExecutionReference(ToolDate::class, '__invoke'), 'tool_date', 'test');
+        $toolCall = new ToolCall('invocation', 'tool_date', ['date' => '2025-06-29']);
+
+        self::assertEquals(['date' => new \DateTimeImmutable('2025-06-29')], $resolver->resolveArguments($tool, $metadata, $toolCall));
+    }
+}

src/agent/tests/Toolbox/ToolboxTest.php

@@ -24,6 +24,7 @@
 use Symfony\AI\Agent\Toolbox\ToolFactory\ChainFactory;
 use Symfony\AI\Agent\Toolbox\ToolFactory\MemoryToolFactory;
 use Symfony\AI\Agent\Toolbox\ToolFactory\ReflectionToolFactory;
+use Symfony\AI\Fixtures\Tool\ToolDate;
 use Symfony\AI\Fixtures\Tool\ToolException;
 use Symfony\AI\Fixtures\Tool\ToolMisconfigured;
 use Symfony\AI\Fixtures\Tool\ToolNoAttribute1;
@@ -60,6 +61,7 @@ protected function setUp(): void
             new ToolOptionalParam(),
             new ToolNoParams(),
             new ToolException(),
+            new ToolDate(),
         ]);
     }
 
@@ -122,11 +124,30 @@ public function getTools(): void
             'This tool is broken',
         );
 
+        $toolDate = new Tool(
+            new ExecutionReference(ToolDate::class, '__invoke'),
+            'tool_date',
+            'A tool with date parameter',
+            [
+                'type' => 'object',
+                'properties' => [
+                    'date' => [
+                        'type' => 'string',
+                        'format' => 'date-time',
+                        'description' => 'The date',
+                    ],
+                ],
+                'required' => ['date'],
+                'additionalProperties' => false,
+            ],
+        );
+
         $expected = [
             $toolRequiredParams,
             $toolOptionalParam,
             $toolNoParams,
             $toolException,
+            $toolDate,
         ];
 
         self::assertEquals($expected, $actual);
@@ -181,6 +202,12 @@ public static function executeProvider(): iterable
             'tool_required_params',
             ['text' => 'Hello', 'number' => 3],
         ];
+
+        yield 'tool_date' => [
+            'Weekday: Sunday',
+            'tool_date',
+            ['date' => '2025-06-29'],
+        ];
     }
 
     #[Test]