bug #177 [Agent][AIBundle] Improve tool argument denormalization (valtzu)

This PR was merged into the main branch.

Discussion
----------

[Agent][AIBundle] Improve tool argument denormalization

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

Address some issues regarding argument value denormalization:

1. Arrays of objects did not work, even with `serializer` that had `ArrayDenormalizer` in it
1. We did not check for mandatory parameters before
1. Extra arguments from the platform caused an exception – now they are ignored
    * If we still want to throw, that's fine, but it should be a more managed exception instead of `Trying to call getType() on null`
1. Use `symfony/type-info` instead of trying to resolve the type ourselves from reflection (which completely ignores phpdoc)
    * Arrays/collections still need some special handling since `ArrayDenormalizer` does not support `array<key, value>` syntax

Commits
-------

c174b64 [Agent][AIBundle] Improve tool argument resolving

Author: chr-hertel

fixtures/SomeStructure.php

@@ -13,5 +13,12 @@
 
 final class SomeStructure
 {
+    public function __construct(?string $some = null)
+    {
+        if (null !== $some) {
+            $this->some = $some;
+        }
+    }
+
     public string $some;
 }

fixtures/Tool/ToolArrayMultidimensional.php

@@ -0,0 +1,29 @@
+<?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;
+use Symfony\AI\Fixtures\SomeStructure;
+
+#[AsTool('tool_array_multidimensional', 'A tool with multidimensional array parameters')]
+final class ToolArrayMultidimensional
+{
+    /**
+     * @param float[][]                $vectors
+     * @param array<string, list<int>> $sequences
+     * @param SomeStructure[][]        $objects
+     */
+    public function __invoke(array $vectors, array $sequences, array $objects): string
+    {
+        return 'Hello world!';
+    }
+}

src/agent/src/Toolbox/ToolCallArgumentResolver.php

@@ -11,21 +11,29 @@
 
 namespace Symfony\AI\Agent\Toolbox;
 
+use Symfony\AI\Agent\Toolbox\Exception\ToolException;
 use Symfony\AI\Platform\Result\ToolCall;
 use Symfony\AI\Platform\Tool\Tool;
+use Symfony\Component\Serializer\Normalizer\ArrayDenormalizer;
 use Symfony\Component\Serializer\Normalizer\DateTimeNormalizer;
 use Symfony\Component\Serializer\Normalizer\DenormalizerInterface;
 use Symfony\Component\Serializer\Normalizer\ObjectNormalizer;
 use Symfony\Component\Serializer\Serializer;
+use Symfony\Component\TypeInfo\Type\CollectionType;
+use Symfony\Component\TypeInfo\TypeResolver\TypeResolver;
 
 /**
  * @author Valtteri R <[email protected]>
  */
 final readonly class ToolCallArgumentResolver
 {
+    private TypeResolver $typeResolver;
+
     public function __construct(
-        private DenormalizerInterface $denormalizer = new Serializer([new DateTimeNormalizer(), new ObjectNormalizer()]),
+        private DenormalizerInterface $denormalizer = new Serializer([new DateTimeNormalizer(), new ObjectNormalizer(), new ArrayDenormalizer()]),
+        ?TypeResolver $typeResolver = null,
     ) {
+        $this->typeResolver = $typeResolver ?? TypeResolver::create();
     }
 
     /**
@@ -35,13 +43,33 @@ public function resolveArguments(Tool $metadata, ToolCall $toolCall): array
     {
         $method = new \ReflectionMethod($metadata->reference->class, $metadata->reference->method);
 
-        /** @var array<string, \ReflectionProperty> $parameters */
+        /** @var array<string, \ReflectionParameter> $parameters */
         $parameters = array_column($method->getParameters(), null, 'name');
         $arguments = [];
 
-        foreach ($toolCall->arguments as $name => $value) {
-            $parameterType = (string) $parameters[$name]->getType();
-            $arguments[$name] = 'array' === $parameterType ? $value : $this->denormalizer->denormalize($value, $parameterType);
+        foreach ($parameters as $name => $reflectionParameter) {
+            if (!\array_key_exists($name, $toolCall->arguments)) {
+                if (!$reflectionParameter->isOptional()) {
+                    throw new ToolException(\sprintf('Parameter "%s" is mandatory for tool "%s".', $name, $toolCall->name));
+                }
+                continue;
+            }
+
+            $value = $toolCall->arguments[$name];
+            $parameterType = $this->typeResolver->resolve($reflectionParameter);
+            $dimensions = '';
+            while ($parameterType instanceof CollectionType) {
+                $dimensions .= '[]';
+                $parameterType = $parameterType->getCollectionValueType();
+            }
+
+            $parameterType .= $dimensions;
+
+            if ($this->denormalizer->supportsDenormalization($value, $parameterType)) {
+                $value = $this->denormalizer->denormalize($value, $parameterType);
+            }
+
+            $arguments[$name] = $value;
         }
 
         return $arguments;

src/agent/tests/Toolbox/ToolCallArgumentResolverTest.php

@@ -16,8 +16,11 @@
 use PHPUnit\Framework\Attributes\UsesClass;
 use PHPUnit\Framework\TestCase;
 use Symfony\AI\Agent\Toolbox\ToolCallArgumentResolver;
+use Symfony\AI\Fixtures\SomeStructure;
 use Symfony\AI\Fixtures\Tool\ToolArray;
+use Symfony\AI\Fixtures\Tool\ToolArrayMultidimensional;
 use Symfony\AI\Fixtures\Tool\ToolDate;
+use Symfony\AI\Fixtures\Tool\ToolNoParams;
 use Symfony\AI\Platform\Result\ToolCall;
 use Symfony\AI\Platform\Tool\ExecutionReference;
 use Symfony\AI\Platform\Tool\Tool;
@@ -57,4 +60,40 @@ public function resolveScalarArrayArguments(): void
 
         self::assertSame($expected, $resolver->resolveArguments($metadata, $toolCall));
     }
+
+    #[Test]
+    public function resolveMultidimensionalArrayArguments(): void
+    {
+        $resolver = new ToolCallArgumentResolver();
+
+        $metadata = new Tool(new ExecutionReference(ToolArrayMultidimensional::class, '__invoke'), 'tool_array_multidimensional', 'A tool with multidimensional array parameters');
+        $toolCall = new ToolCall('tool_id_1234', 'tool_array_multidimensional', [
+            'vectors' => [[1.2, 3.4], [4.5, 5.6]],
+            'sequences' => ['first' => [1, 2, 3], 'second' => [4, 5, 6]],
+            'objects' => [[['some' => 'a'], ['some' => 'b']]],
+        ]);
+
+        $expected = [
+            'vectors' => [[1.2, 3.4], [4.5, 5.6]],
+            'sequences' => ['first' => [1, 2, 3], 'second' => [4, 5, 6]],
+            'objects' => [[new SomeStructure('a'), new SomeStructure('b')]],
+        ];
+
+        self::assertEquals($expected, $resolver->resolveArguments($metadata, $toolCall));
+    }
+
+    #[Test]
+    public function ignoreExtraArguments(): void
+    {
+        $resolver = new ToolCallArgumentResolver();
+
+        $metadata = new Tool(new ExecutionReference(ToolNoParams::class, '__invoke'), 'tool_no_params', 'A tool without params');
+        $toolCall = new ToolCall('tool_id_1234', 'tool_no_params', [
+            'foo' => 1,
+            'bar' => 2,
+            'baz' => 3,
+        ]);
+
+        self::assertSame([], $resolver->resolveArguments($metadata, $toolCall));
+    }
 }

src/ai-bundle/config/services.php

@@ -92,6 +92,7 @@
         ->set('ai.tool_call_argument_resolver', ToolCallArgumentResolver::class)
             ->args([
                 service('serializer'),
+                service('type_info.resolver')->nullOnInvalid(),
             ])
         ->set('ai.tool.agent_processor.abstract', ToolProcessor::class)
             ->abstract()