feature #764 [Agent] Enable tools to add sources (chr-hertel)

This PR was merged into the main branch.

Discussion
----------

[Agent] Enable tools to add sources

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

<img width="1920" height="1004" alt="image" src="https://github.com/user-attachments/assets/84215766-e6d9-4308-9701-acff53ed1502" />

- [x] tests
- [x] provide way without keep messages

Commits
-------

2222db7 Enable tools to add sources

Author: OskarStark

docs/components/agent.rst

@@ -314,6 +314,52 @@ If you want to expose the underlying error to the LLM, you can throw a custom ex
         }
     }
 
+Tool Sources
+~~~~~~~~~~~~
+
+Some tools bring in data to the agent from external sources, like search engines or APIs. Those sources can be exposed
+by enabling `keepToolSources` as argument of the :class:`Symfony\\AI\\Agent\\Toolbox\\AgentProcessor`::
+
+    use Symfony\AI\Agent\Toolbox\AgentProcessor;
+    use Symfony\AI\Agent\Toolbox\Toolbox;
+
+    $toolbox = new Toolbox([new MyTool()]);
+    $toolProcessor = new AgentProcessor($toolbox, keepToolSources: true);
+
+In the tool implementation sources can be added by implementing the
+:class:`Symfony\\AI\\Agent\\Toolbox\\Source\\HasSourcesInterface` in combination with the trait
+:class:`Symfony\\AI\\Agent\\Toolbox\\Source\\HasSourcesTrait`::
+
+    use Symfony\AI\Agent\Toolbox\Source\HasSourcesInterface;
+    use Symfony\AI\Agent\Toolbox\Source\HasSourcesTrait;
+
+    #[AsTool('my_tool', 'Example tool with sources.')]
+    final class MyTool implements HasSourcesInterface
+    {
+        use HasSourcesTrait;
+
+        public function __invoke(string $query): string
+        {
+            // Add sources relevant for the result
+
+            $this->addSource(
+                new Source('Example Source 1', 'https://example.com/source1', 'Relevant content from source 1'),
+            );
+
+            // return result
+        }
+    }
+
+The sources can be fetched from the metadata of the result after the agent execution::
+
+    $result = $agent->call($messages);
+
+    foreach ($result->getMetadata()->get('sources', []) as $source) {
+        echo sprintf(' - %s (%s): %s', $source->getName(), $source->getReference(), $source->getContent());
+    }
+
+See `Anthropic Toolbox Example`_ for a complete example using sources with Wikipedia tool.
+
 Tool Filtering
 ~~~~~~~~~~~~~~
 
@@ -765,6 +811,7 @@ Code Examples
 
 
 .. _`Platform Component`: https://github.com/symfony/ai-platform
+.. _`Anthropic Toolbox Example`: https://github.com/symfony/ai/blob/main/examples/anthropic/toolcall.php
 .. _`Brave Tool`: https://github.com/symfony/ai/blob/main/examples/toolbox/brave.php
 .. _`Clock Tool`: https://github.com/symfony/ai/blob/main/examples/toolbox/clock.php
 .. _`Crawler Tool`: https://github.com/symfony/ai/blob/main/examples/toolbox/brave.php

examples/anthropic/toolcall.php

@@ -11,6 +11,7 @@
 
 use Symfony\AI\Agent\Agent;
 use Symfony\AI\Agent\Toolbox\AgentProcessor;
+use Symfony\AI\Agent\Toolbox\Source\Source;
 use Symfony\AI\Agent\Toolbox\Tool\Wikipedia;
 use Symfony\AI\Agent\Toolbox\Toolbox;
 use Symfony\AI\Platform\Bridge\Anthropic\PlatformFactory;
@@ -23,10 +24,16 @@
 
 $wikipedia = new Wikipedia(http_client());
 $toolbox = new Toolbox([$wikipedia], logger: logger());
-$processor = new AgentProcessor($toolbox);
+$processor = new AgentProcessor($toolbox, keepToolSources: true);
 $agent = new Agent($platform, 'claude-3-5-sonnet-20241022', [$processor], [$processor]);
 
 $messages = new MessageBag(Message::ofUser('Who is the current chancellor of Germany?'));
 $result = $agent->call($messages);
 
-echo $result->getContent().\PHP_EOL;
+echo $result->getContent().\PHP_EOL.\PHP_EOL;
+
+echo 'Used sources:'.\PHP_EOL;
+foreach ($result->getMetadata()->get('sources', []) as $source) {
+    echo sprintf(' - %s (%s)', $source->getName(), $source->getReference()).\PHP_EOL;
+}
+echo \PHP_EOL;

fixtures/Tool/ToolSources.php

@@ -0,0 +1,37 @@
+<?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\Fixtures\Tool;
+
+use Symfony\AI\Agent\Toolbox\Attribute\AsTool;
+use Symfony\AI\Agent\Toolbox\Source\HasSourcesInterface;
+use Symfony\AI\Agent\Toolbox\Source\HasSourcesTrait;
+use Symfony\AI\Agent\Toolbox\Source\Source;
+
+#[AsTool('tool_sources', 'Tool that records some sources')]
+final class ToolSources implements HasSourcesInterface
+{
+    use HasSourcesTrait;
+
+    /**
+     * @param string $query Search query
+     */
+    public function __invoke(string $query): string
+    {
+        $foundContent = 'Content of that relevant article.';
+
+        $this->addSource(
+            new Source('Relevant Article', 'https://example.com/relevant-article', $foundContent),
+        );
+
+        return $foundContent;
+    }
+}

src/agent/src/Toolbox/AgentProcessor.php

@@ -18,6 +18,7 @@
 use Symfony\AI\Agent\Output;
 use Symfony\AI\Agent\OutputProcessorInterface;
 use Symfony\AI\Agent\Toolbox\Event\ToolCallsExecuted;
+use Symfony\AI\Agent\Toolbox\Source\Source;
 use Symfony\AI\Agent\Toolbox\StreamResult as ToolboxStreamResponse;
 use Symfony\AI\Platform\Message\AssistantMessage;
 use Symfony\AI\Platform\Message\Message;
@@ -34,11 +35,25 @@ final class AgentProcessor implements InputProcessorInterface, OutputProcessorIn
 {
     use AgentAwareTrait;
 
+    /**
+     * Sources get collected during tool calls on class level to be able to handle consecutive tool calls.
+     * They get added to the result metadata and reset when the outermost agent call is finished via nesting level.
+     *
+     * @var Source[]
+     */
+    private array $sources = [];
+
+    /**
+     * Tracks the nesting level of agent calls.
+     */
+    private int $nestingLevel = 0;
+
     public function __construct(
         private readonly ToolboxInterface $toolbox,
         private readonly ToolResultConverter $resultConverter = new ToolResultConverter(),
         private readonly ?EventDispatcherInterface $eventDispatcher = null,
         private readonly bool $keepToolMessages = false,
+        private readonly bool $keepToolSources = false,
     ) {
     }
 
@@ -87,6 +102,7 @@ private function isFlatStringArray(array $tools): bool
     private function handleToolCallsCallback(Output $output): \Closure
     {
         return function (ToolCallResult $result, ?AssistantMessage $streamedAssistantResponse = null) use ($output): ResultInterface {
+            ++$this->nestingLevel;
             $messages = $this->keepToolMessages ? $output->getMessageBag() : clone $output->getMessageBag();
 
             if (null !== $streamedAssistantResponse && '' !== $streamedAssistantResponse->getContent()) {
@@ -101,6 +117,7 @@ private function handleToolCallsCallback(Output $output): \Closure
                 foreach ($toolCalls as $toolCall) {
                     $results[] = $toolResult = $this->toolbox->execute($toolCall);
                     $messages->add(Message::ofToolCall($toolCall, $this->resultConverter->convert($toolResult)));
+                    array_push($this->sources, ...$toolResult->getSources());
                 }
 
                 $event = new ToolCallsExecuted(...$results);
@@ -109,6 +126,12 @@ private function handleToolCallsCallback(Output $output): \Closure
                 $result = $event->hasResult() ? $event->getResult() : $this->agent->call($messages, $output->getOptions());
             } while ($result instanceof ToolCallResult);
 
+            --$this->nestingLevel;
+            if ($this->keepToolSources && 0 === $this->nestingLevel) {
+                $result->getMetadata()->add('sources', $this->sources);
+                $this->sources = [];
+            }
+
             return $result;
         };
     }

src/agent/src/Toolbox/Source/HasSourcesInterface.php

@@ -0,0 +1,17 @@
+<?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\Source;
+
+interface HasSourcesInterface
+{
+    public function setSourceMap(SourceMap $sourceMap): void;
+}

src/agent/src/Toolbox/Source/HasSourcesTrait.php

@@ -0,0 +1,32 @@
+<?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\Source;
+
+trait HasSourcesTrait
+{
+    private SourceMap $sourceMap;
+
+    public function setSourceMap(SourceMap $sourceMap): void
+    {
+        $this->sourceMap = $sourceMap;
+    }
+
+    public function getSourceMap(): SourceMap
+    {
+        return $this->sourceMap ??= new SourceMap();
+    }
+
+    private function addSource(Source $source): void
+    {
+        $this->getSourceMap()->addSource($source);
+    }
+}

src/agent/src/Toolbox/Source/Source.php

@@ -0,0 +1,37 @@
+<?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\Source;
+
+readonly class Source
+{
+    public function __construct(
+        private string $name,
+        private string $reference,
+        private string $content,
+    ) {
+    }
+
+    public function getName(): string
+    {
+        return $this->name;
+    }
+
+    public function getReference(): string
+    {
+        return $this->reference;
+    }
+
+    public function getContent(): string
+    {
+        return $this->content;
+    }
+}

src/agent/src/Toolbox/Source/SourceMap.php

@@ -0,0 +1,33 @@
+<?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\Source;
+
+class SourceMap
+{
+    /**
+     * @var Source[]
+     */
+    private array $sources = [];
+
+    /**
+     * @return Source[]
+     */
+    public function getSources(): array
+    {
+        return $this->sources;
+    }
+
+    public function addSource(Source $source): void
+    {
+        $this->sources[] = $source;
+    }
+}

src/agent/src/Toolbox/Tool/Wikipedia.php

@@ -12,15 +12,20 @@
 namespace Symfony\AI\Agent\Toolbox\Tool;
 
 use Symfony\AI\Agent\Toolbox\Attribute\AsTool;
+use Symfony\AI\Agent\Toolbox\Source\HasSourcesInterface;
+use Symfony\AI\Agent\Toolbox\Source\HasSourcesTrait;
+use Symfony\AI\Agent\Toolbox\Source\Source;
 use Symfony\Contracts\HttpClient\HttpClientInterface;
 
 /**
  * @author Christopher Hertel <mail@christopher-hertel.de>
  */
 #[AsTool('wikipedia_search', description: 'Searches Wikipedia for a given query', method: 'search')]
 #[AsTool('wikipedia_article', description: 'Retrieves a Wikipedia article by its title', method: 'article')]
-final readonly class Wikipedia
+final class Wikipedia implements HasSourcesInterface
 {
+    use HasSourcesTrait;
+
     public function __construct(
         private HttpClientInterface $httpClient,
         private string $locale = 'en',
@@ -81,6 +86,10 @@ public function article(string $title): string
             $result .= \PHP_EOL;
         }
 
+        $this->addSource(
+            new Source($article['title'], $this->getUrl($article['title']), $article['extract'])
+        );
+
         return $result.'This is the content of article "'.$article['title'].'":'.\PHP_EOL.$article['extract'];
     }
 
@@ -96,4 +105,9 @@ private function execute(array $query, ?string $locale = null): array
 
         return $response->toArray();
     }
+
+    private function getUrl(string $title): string
+    {
+        return \sprintf('https://%s.wikipedia.org/wiki/%s', $this->locale, str_replace(' ', '_', $title));
+    }
 }

src/agent/src/Toolbox/ToolResult.php

@@ -11,16 +11,21 @@
 
 namespace Symfony\AI\Agent\Toolbox;
 
+use Symfony\AI\Agent\Toolbox\Source\Source;
 use Symfony\AI\Platform\Result\ToolCall;
 
 /**
  * @author Christopher Hertel <mail@christopher-hertel.de>
  */
 final readonly class ToolResult
 {
+    /**
+     * @param Source[] $sources
+     */
     public function __construct(
         private ToolCall $toolCall,
         private mixed $result,
+        private array $sources = [],
     ) {
     }
 
@@ -33,4 +38,12 @@ public function getResult(): mixed
     {
         return $this->result;
     }
+
+    /**
+     * @return Source[]
+     */
+    public function getSources(): array
+    {
+        return $this->sources;
+    }
 }