feature #771 [AI Bundle][Demo] Add config options for keeping tool call messages and sources + expose metadata in profiler (chr-hertel)

This PR was merged into the main branch.

Discussion
----------

[AI Bundle][Demo] Add config options for keeping tool call messages and sources + expose metadata in profiler

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

<img width="1346" height="602" alt="image" src="https://github.com/user-attachments/assets/e68b4ace-321e-484a-9d39-63bbc672d2f7" />

<img width="1346" height="602" alt="image" src="https://github.com/user-attachments/assets/d09819a1-5081-428e-abf9-57d02bf7fe28" />

Commits
-------

cbf0629 Add config options for keeping tool call messages and sources + expose metadata in profiler

Author: chr-hertel

.github/workflows/code-quality.yaml

@@ -29,7 +29,7 @@ jobs:
             - name: Configure environment
               run: |
                   echo COLUMNS=120 >> $GITHUB_ENV
-                  echo COMPOSER_UP='composer update --no-progress --no-interaction --ansi --ignore-platform-req=ext-mongodb' >> $GITHUB_ENV
+                  echo COMPOSER_UP='composer update --no-progress --no-interaction --no-scripts --ansi --ignore-platform-req=ext-mongodb' >> $GITHUB_ENV
                   echo PHPSTAN='vendor/bin/phpstan' >> $GITHUB_ENV
 
                   PACKAGES=$(find src/ -mindepth 2 -type f -name composer.json -not -path "*/vendor/*" -printf '%h\n' | sed 's/^src\///' | grep -Ev "examples" | sort |  tr '\n' ' ')

demo/config/packages/ai.yaml

@@ -25,10 +25,11 @@ ai:
                 options:
                     temperature: 0.5
             prompt:
-                text: 'Please answer the users question based on Wikipedia and provide a link to the article.'
+                text: 'Please answer the users question based on Wikipedia, only use information provided in the messages.'
                 include_tools: true
             tools:
                 - 'Symfony\AI\Agent\Toolbox\Tool\Wikipedia'
+            include_sources: true
         audio:
             model: 'gpt-4o-mini?temperature=1.0'
             prompt: 'You are a friendly chatbot that likes to have a conversation with users and asks them some questions.'
@@ -89,7 +90,7 @@ services:
 
     Symfony\AI\Store\Document\Loader\RssFeedLoader: ~
     Symfony\AI\Store\Document\Transformer\TextTrimTransformer: ~
-    
+
     app.filter.week_of_symfony:
         class: 'Symfony\AI\Store\Document\Filter\TextContainsFilter'
         arguments:

demo/src/Wikipedia/Chat.php

@@ -43,7 +43,9 @@ public function submitMessage(string $message): void
 
         \assert($result instanceof TextResult);
 
-        $messages->add(Message::ofAssistant($result->getContent()));
+        $response = Message::ofAssistant($result->getContent());
+        $response->getMetadata()->add('sources', $result->getMetadata()->get('sources', []));
+        $messages->add($response);
 
         $this->saveMessages($messages);
     }

demo/templates/components/wikipedia.html.twig

@@ -1,4 +1,4 @@
-{% import "_message.html.twig" as message %}
+{% import "_message.html.twig" as msg %}
 
 <div class="card mx-auto shadow-lg" {{ attributes.defaults(stimulus_controller('wikipedia')) }}>
     <div class="card-header p-2">
@@ -9,6 +9,16 @@
     <div id="chat-body" class="card-body p-4 overflow-auto">
         {% for message in this.messages %}
             {% include '_message.html.twig' with { message, latest: loop.last } %}
+            {% if message.metadata.has('sources') %}
+                <div class="ms-5">
+                    <h6>Sources:</h6>
+                    <ol>
+                        {% for source in message.metadata.get('sources') %}
+                            <li><a class="text-black-50" href="{{ source.reference }}" target="_blank" rel="noopener">{{ source.name }}</a></li>
+                        {% endfor %}
+                    </ol>
+                </div>
+            {% endif %}
         {% else %}
             <div id="welcome" class="text-center mt-5 py-5 bg-white rounded-5 shadow-sm w-75 mx-auto">
                 {{ ux_icon('mdi:wikipedia', { height: '200px', width: '200px' }) }}
@@ -17,8 +27,8 @@
             </div>
         {% endfor %}
         <div id="loading-message" class="d-none">
-            {{ message.user([{text:''}]) }}
-            {{ message.bot('The Wikipedia Bot is doing some research ...', true) }}
+            {{ msg.user([{text:''}]) }}
+            {{ msg.bot('The Wikipedia Bot is doing some research ...', true) }}
         </div>
     </div>
     <div class="card-footer p-2">

docs/components/agent.rst

@@ -318,13 +318,13 @@ 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`::
+by enabling `includeSources` 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);
+    $toolProcessor = new AgentProcessor($toolbox, includeSources: true);
 
 In the tool implementation sources can be added by implementing the
 :class:`Symfony\\AI\\Agent\\Toolbox\\Source\\HasSourcesInterface` in combination with the trait

examples/anthropic/toolcall.php

@@ -24,7 +24,7 @@
 
 $wikipedia = new Wikipedia(http_client());
 $toolbox = new Toolbox([$wikipedia], logger: logger());
-$processor = new AgentProcessor($toolbox, keepToolSources: true);
+$processor = new AgentProcessor($toolbox, includeSources: true);
 $agent = new Agent($platform, 'claude-3-5-sonnet-20241022', [$processor], [$processor]);
 
 $messages = new MessageBag(Message::ofUser('Who is the current chancellor of Germany?'));

src/agent/src/Toolbox/AgentProcessor.php

@@ -53,7 +53,7 @@ public function __construct(
         private readonly ToolResultConverter $resultConverter = new ToolResultConverter(),
         private readonly ?EventDispatcherInterface $eventDispatcher = null,
         private readonly bool $keepToolMessages = false,
-        private readonly bool $keepToolSources = false,
+        private readonly bool $includeSources = false,
     ) {
     }
 
@@ -127,7 +127,7 @@ private function handleToolCallsCallback(Output $output): \Closure
             } while ($result instanceof ToolCallResult);
 
             --$this->nestingLevel;
-            if ($this->keepToolSources && 0 === $this->nestingLevel) {
+            if ($this->includeSources && 0 === $this->nestingLevel) {
                 $result->getMetadata()->add('sources', $this->sources);
                 $this->sources = [];
             }

src/agent/tests/Toolbox/AgentProcessorTest.php

@@ -148,7 +148,7 @@ public function testSourcesEndUpInResultMetadataWithSettingOn()
             ->method('call')
             ->willReturn(new TextResult('Final response based on the two articles.'));
 
-        $processor = new AgentProcessor($toolbox, keepToolSources: true);
+        $processor = new AgentProcessor($toolbox, includeSources: true);
         $processor->setAgent($agent);
 
         $output = new Output('gpt-4', $result, $messageBag);
@@ -181,7 +181,7 @@ public function testSourcesDoNotEndUpInResultMetadataWithSettingOff()
             ->method('call')
             ->willReturn(new TextResult('Final response based on the two articles.'));
 
-        $processor = new AgentProcessor($toolbox, keepToolSources: false);
+        $processor = new AgentProcessor($toolbox, includeSources: false);
         $processor->setAgent($agent);
 
         $output = new Output('gpt-4', $result, $messageBag);
@@ -220,7 +220,7 @@ public function testSourcesGetCollectedAcrossConsecutiveToolCalls()
                 new DeferredResult(new PlainConverter(new TextResult('Final response based on both articles.')), new InMemoryRawResult())
             );
 
-        $processor = new AgentProcessor($toolbox, keepToolSources: true);
+        $processor = new AgentProcessor($toolbox, includeSources: true);
         $agent = new Agent($platform, 'foo-bar', [$processor], [$processor]);
         $processor->setAgent($agent);
 

src/ai-bundle/config/options.php

@@ -409,7 +409,18 @@
                                 ->end()
                             ->end()
                         ->end()
-                        ->booleanNode('fault_tolerant_toolbox')->defaultTrue()->end()
+                        ->booleanNode('keep_tool_messages')
+                            ->info('Keep tool messages in the conversation history')
+                            ->defaultFalse()
+                        ->end()
+                        ->booleanNode('include_sources')
+                            ->info('Include sources exposed by tools as part of the tool result metadata')
+                            ->defaultFalse()
+                        ->end()
+                        ->booleanNode('fault_tolerant_toolbox')
+                            ->info('Continue the agent run even if a tool call fails')
+                            ->defaultTrue()
+                        ->end()
                     ->end()
                 ->end()
             ->end()

src/ai-bundle/config/services.php

@@ -157,6 +157,7 @@
                 service('ai.tool_result_converter'),
                 service('event_dispatcher')->nullOnInvalid(),
                 false,
+                false,
             ])
         ->set('ai.security.is_granted_attribute_listener', IsGrantedToolAttributeListener::class)
             ->args([