Enable tools to add sources

Author: chr-hertel

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,19 @@
 
 $wikipedia = new Wikipedia(http_client());
 $toolbox = new Toolbox([$wikipedia], logger: logger());
-$processor = new AgentProcessor($toolbox);
+$processor = new AgentProcessor($toolbox, keepToolMessages: 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 ($messages->getToolCallMessages() as $message) {
+ /** @var Source $source */
+ foreach ($message->getMetadata()->get('tool_sources') as $source) {
+ echo sprintf(' - %s (%s)', $source->getName(), $source->getReference()).\PHP_EOL;
+ }
+}
+echo \PHP_EOL;

src/agent/src/Toolbox/AgentProcessor.php

@@ -100,13 +100,15 @@ private function handleToolCallsCallback(Output $output): \Closure
  $results = [];
  foreach ($toolCalls as $toolCall) {
  $results[] = $toolResult = $this->toolbox->execute($toolCall);
- $messages->add(Message::ofToolCall($toolCall, $this->resultConverter->convert($toolResult)));
+ $message = Message::ofToolCall($toolCall, $this->resultConverter->convert($toolResult));
+ $message->getMetadata()->add('tool_sources', $toolResult->getSources());
+ $messages->add($message);
  }
 
  $event = new ToolCallsExecuted(...$results);
  $this->eventDispatcher?->dispatch($event);
 
- $result = $event->hasResponse() ? $event->getResult() : $this->agent->call($messages, $output->getOptions());
+ $result = $event->hasResult() ? $event->getResult() : $this->agent->call($messages, $output->getOptions());
  } while ($result instanceof ToolCallResult);
 
  return $result;

src/agent/src/Toolbox/Event/ToolCallsExecuted.php

@@ -30,7 +30,7 @@ public function __construct(ToolResult ...$toolResults)
  $this->toolResults = $toolResults;
  }
 
- public function hasResponse(): bool
+ public function hasResult(): bool
  {
  return isset($this->result);
  }

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/Source/UsesSourcesInterface.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 UsesSourcesInterface
+{
+ public function setSourceMap(SourceMap $sourceMap): void;
+}

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

@@ -0,0 +1,27 @@
+<?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 UsesSourcesTrait
+{
+ private SourceMap $sourceMap;
+
+ public function setSourceMap(SourceMap $sourceMap): void
+ {
+ $this->sourceMap = $sourceMap;
+ }
+
+ private function addSource(Source $source): void
+ {
+ $this->sourceMap->addSource($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\Source;
+use Symfony\AI\Agent\Toolbox\Source\UsesSourcesInterface;
+use Symfony\AI\Agent\Toolbox\Source\UsesSourcesTrait;
 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 UsesSourcesInterface
 {
+ use UsesSourcesTrait;
+
  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;
+ }
 }

src/agent/src/Toolbox/Toolbox.php

@@ -19,6 +19,8 @@
 use Symfony\AI\Agent\Toolbox\Exception\ToolExecutionException;
 use Symfony\AI\Agent\Toolbox\Exception\ToolExecutionExceptionInterface;
 use Symfony\AI\Agent\Toolbox\Exception\ToolNotFoundException;
+use Symfony\AI\Agent\Toolbox\Source\SourceMap;
+use Symfony\AI\Agent\Toolbox\Source\UsesSourcesInterface;
 use Symfony\AI\Agent\Toolbox\ToolFactory\ReflectionToolFactory;
 use Symfony\AI\Platform\Result\ToolCall;
 use Symfony\AI\Platform\Tool\Tool;
@@ -82,7 +84,17 @@ public function execute(ToolCall $toolCall): ToolResult
 
  $arguments = $this->argumentResolver->resolveArguments($metadata, $toolCall);
  $this->eventDispatcher?->dispatch(new ToolCallArgumentsResolved($tool, $metadata, $arguments));
- $result = new ToolResult($toolCall, $tool->{$metadata->getReference()->getMethod()}(...$arguments));
+
+ if ($tool instanceof UsesSourcesInterface) {
+ $tool->setSourceMap($sourceMap = new SourceMap());
+ }
+
+ $result = new ToolResult(
+ $toolCall,
+ $tool->{$metadata->getReference()->getMethod()}(...$arguments),
+ $sourceMap->getSources(),
+ );
+
  $this->eventDispatcher?->dispatch(new ToolCallSucceeded($tool, $metadata, $arguments, $result));
  } catch (ToolExecutionExceptionInterface $e) {
  $this->eventDispatcher?->dispatch(new ToolCallFailed($tool, $metadata, $arguments ?? [], $e));