[Agent] Enable tools to add sources

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;
+ }
 }