improv: Better default, preserve tool msgs

Author: aszenz

docs/components/agent.rst

@@ -405,12 +405,12 @@ If you need to react more granularly to the lifecycle of individual tool calls,
         // Let the client know, that the tool $event->toolCall->name failed with the exception: $event->exception
     });
 
-Keeping Tool Messages
-~~~~~~~~~~~~~~~~~~~~~
+Excluding Tool Messages from :class:`Symfony\\AI\\Platform\\Message\\MessageBag`
+~~~~~~~~~~~~~~~~~~~~------------------------------------------------------------
 
-Sometimes you might wish to keep the tool messages (:class:`Symfony\\AI\\Platform\\Message\\AssistantMessage` containing the ``toolCalls`` and :class:`Symfony\\AI\\Platform\\Message\\ToolCallMessage`
-containing the result) in the context. Enable the ``keepToolMessages`` flag of the toolbox' :class:`Symfony\\AI\\Agent\\Toolbox\\AgentProcessor`
-to ensure those messages will be added to your :class:`Symfony\\AI\\Platform\\Message\\MessageBag`::
+Sometimes you might wish to exclude the tool messages (:class:`Symfony\\AI\\Platform\\Message\\AssistantMessage` containing the ``toolCalls`` and :class:`Symfony\\AI\\Platform\\Message\\ToolCallMessage`
+containing the result) in the context. Enable the ``excludeToolMessages`` flag of the toolbox' :class:`Symfony\\AI\\Agent\\Toolbox\\AgentProcessor`
+to ensure those messages will be removed from your :class:`Symfony\\AI\\Platform\\Message\\MessageBag`::
 
     use Symfony\AI\Agent\Toolbox\AgentProcessor;
     use Symfony\AI\Agent\Toolbox\Toolbox;
@@ -428,11 +428,11 @@ to ensure those messages will be added to your :class:`Symfony\\AI\\Platform\\Me
     $tool = new MyTool();
 
     $toolbox = new Toolbox([$tool]);
-    $toolProcessor = new AgentProcessor($toolbox, keepToolMessages: true);
+    $toolProcessor = new AgentProcessor($toolbox, excludeToolMessages: true);
 
     $agent = new Agent($platform, $model, inputProcessor: [$toolProcessor], outputProcessor: [$toolProcessor]);
     $result = $agent->call($messages);
-    // $messages will now include the tool messages
+    // $messages will now exclude the tool messages
 
 Code Examples (with built-in tools)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

src/agent/CHANGELOG.md

@@ -6,6 +6,7 @@ CHANGELOG
 
  * [BC BREAK] Rename `Symfony\AI\Agent\Toolbox\Tool\Agent` to `Symfony\AI\Agent\Toolbox\Tool\Subagent`
  * Add `MetaDataAwareTrait` to `MockResponse`, the metadata will also be set on the returned `TextResult` when calling the `toResult` function
+ * [BC Break] Refactor Agent Processor `keepToolMessages` to `excludeToolMessages` and change default behaviour to preserve tool messages.
 
 0.3
 ---

src/agent/src/Toolbox/AgentProcessor.php

@@ -50,7 +50,7 @@ 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 $excludeToolMessages = false,
         private readonly bool $includeSources = false,
         private readonly ?int $maxToolCalls = null,
     ) {
@@ -104,7 +104,7 @@ private function isFlatStringArray(array $tools): bool
     private function handleToolCallsCallback(Output $output, ToolCallResult $result, ?AssistantMessage $streamedAssistantResponse = null): ResultInterface
     {
         ++$this->nestingLevel;
-        $messages = $this->keepToolMessages ? $output->getMessageBag() : clone $output->getMessageBag();
+        $messages = $this->excludeToolMessages ? clone $output->getMessageBag() : $output->getMessageBag();
 
         if (null !== $streamedAssistantResponse && '' !== $streamedAssistantResponse->getContent()) {
             $messages->add($streamedAssistantResponse);

src/agent/tests/Toolbox/AgentProcessorTest.php

@@ -97,7 +97,7 @@ public function testProcessOutputWithToolCallResponseKeepingMessages()
 
         $agent = $this->createStub(AgentInterface::class);
 
-        $processor = new AgentProcessor($toolbox, keepToolMessages: true);
+        $processor = new AgentProcessor($toolbox, excludeToolMessages: false);
         $processor->setAgent($agent);
 
         $output = new Output('gpt-4', $result, $messageBag);
@@ -123,7 +123,7 @@ public function testProcessOutputWithToolCallResponseForgettingMessages()
 
         $agent = $this->createStub(AgentInterface::class);
 
-        $processor = new AgentProcessor($toolbox, keepToolMessages: false);
+        $processor = new AgentProcessor($toolbox, excludeToolMessages: true);
         $processor->setAgent($agent);
 
         $output = new Output('gpt-4', $result, $messageBag);