[AI Bundle][Agent] Add #[AsInputProcessor] and #[AsOutputProcessor]

VincentLanglet · chr-hertel · commit 1d77c9788994 · 2025-09-02T22:35:06.000+02:00
diff --git a/src/agent/src/Attribute/AsInputProcessor.php b/src/agent/src/Attribute/AsInputProcessor.php
@@ -0,0 +1,26 @@
+<?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\Attribute;
+
+#[\Attribute(\Attribute::TARGET_CLASS | \Attribute::IS_REPEATABLE)]
+final readonly class AsInputProcessor
+{
+    /**
+     * @param string|null $agent the service id of the agent which will use this processor,
+     *                           null to register this processor for all existing agents
+     */
+    public function __construct(
+        public ?string $agent = null,
+        public int $priority = 0,
+    ) {
+    }
+}
diff --git a/src/agent/src/Attribute/AsOutputProcessor.php b/src/agent/src/Attribute/AsOutputProcessor.php
@@ -0,0 +1,26 @@
+<?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\Attribute;
+
+#[\Attribute(\Attribute::TARGET_CLASS | \Attribute::IS_REPEATABLE)]
+final readonly class AsOutputProcessor
+{
+    /**
+     * @param string|null $agent the service id of the agent which will use this processor,
+     *                           null to register this processor for all existing agents
+     */
+    public function __construct(
+        public ?string $agent = null,
+        public int $priority = 0,
+    ) {
+    }
+}
diff --git a/src/ai-bundle/config/services.php b/src/ai-bundle/config/services.php
@@ -68,8 +68,6 @@
                 service('ai.agent.response_format_factory'),
                 service('serializer'),
             ])
-            ->tag('ai.agent.input_processor')
-            ->tag('ai.agent.output_processor')
 
         // tools
         ->set('ai.toolbox.abstract', Toolbox::class)
@@ -111,8 +109,6 @@
             ])
         ->set('ai.tool.agent_processor', ToolProcessor::class)
             ->parent('ai.tool.agent_processor.abstract')
-            ->tag('ai.agent.input_processor')
-            ->tag('ai.agent.output_processor')
             ->arg('index_0', service('ai.toolbox'))
         ->set('ai.security.is_granted_attribute_listener', IsGrantedToolAttributeListener::class)
             ->args([
diff --git a/src/ai-bundle/doc/index.rst b/src/ai-bundle/doc/index.rst
@@ -150,6 +150,34 @@ Use the `Agent` service to leverage models and tools::
         }
     }
 
+**Register Processors**
+
+By default, all services implementing the ``InputProcessorInterface`` or the
+``OutputProcessorInterface`` interfaces are automatically applied to every ``Agent``.
+
+This behavior can be overridden/configured with the ``#[AsInputProcessor]`` and
+the ``#[AsOutputProcessor]`` attributes::
+
+    use Symfony\AI\Agent\Input;
+    use Symfony\AI\Agent\InputProcessorInterface;
+    use Symfony\AI\Agent\Output;
+    use Symfony\AI\Agent\OutputProcessorInterface;
+
+    #[AsInputProcessor(priority: 99)] // This applies to every agent
+    #[AsOutputProcessor(agent: 'my_agent_id')] // The output processor will only be registered for 'my_agent_id'
+    final readonly class MyService implements InputProcessorInterface, OutputProcessorInterface
+    {
+        public function processInput(Input $input): void
+        {
+            // ...
+        }
+
+        public function processOutput(Output $output): void
+        {
+            // ...
+        }
+    }
+
 **Register Tools**
 
 To use existing tools, you can register them as a service:
diff --git a/src/ai-bundle/src/AiBundle.php b/src/ai-bundle/src/AiBundle.php
@@ -14,6 +14,8 @@
 use Google\Auth\ApplicationDefaultCredentials;
 use Symfony\AI\Agent\Agent;
 use Symfony\AI\Agent\AgentInterface;
+use Symfony\AI\Agent\Attribute\AsInputProcessor;
+use Symfony\AI\Agent\Attribute\AsOutputProcessor;
 use Symfony\AI\Agent\InputProcessor\SystemPromptInputProcessor;
 use Symfony\AI\Agent\InputProcessorInterface;
 use Symfony\AI\Agent\OutputProcessorInterface;
@@ -22,6 +24,7 @@
 use Symfony\AI\Agent\Toolbox\Tool\Agent as AgentTool;
 use Symfony\AI\Agent\Toolbox\ToolFactory\ChainFactory;
 use Symfony\AI\Agent\Toolbox\ToolFactory\MemoryToolFactory;
+use Symfony\AI\AiBundle\DependencyInjection\ProcessorCompilerPass;
 use Symfony\AI\AiBundle\Exception\InvalidArgumentException;
 use Symfony\AI\AiBundle\Profiler\TraceablePlatform;
 use Symfony\AI\AiBundle\Profiler\TraceableToolbox;
@@ -83,6 +86,13 @@
  */
 final class AiBundle extends AbstractBundle
 {
+    public function build(ContainerBuilder $container)
+    {
+        parent::build($container);
+
+        $container->addCompilerPass(new ProcessorCompilerPass());
+    }
+
     public function configure(DefinitionConfigurator $definition): void
     {
         $definition->import('../config/options.php');
@@ -143,10 +153,25 @@ public function loadExtension(array $config, ContainerConfigurator $container, C
             ]);
         });
 
+        $builder->registerAttributeForAutoconfiguration(AsInputProcessor::class, static function (ChildDefinition $definition, AsInputProcessor $attribute): void {
+            $definition->addTag('ai.agent.input_processor', [
+                'agent' => $attribute->agent,
+                'priority' => $attribute->priority,
+            ]);
+        });
+
+        $builder->registerAttributeForAutoconfiguration(AsOutputProcessor::class, static function (ChildDefinition $definition, AsOutputProcessor $attribute): void {
+            $definition->addTag('ai.agent.output_processor', [
+                'agent' => $attribute->agent,
+                'priority' => $attribute->priority,
+            ]);
+        });
+
         $builder->registerForAutoconfiguration(InputProcessorInterface::class)
-            ->addTag('ai.agent.input_processor');
+            ->addTag('ai.agent.input_processor', ['tagged_by' => 'interface']);
         $builder->registerForAutoconfiguration(OutputProcessorInterface::class)
-            ->addTag('ai.agent.output_processor');
+            ->addTag('ai.agent.output_processor', ['tagged_by' => 'interface']);
+
         $builder->registerForAutoconfiguration(ModelClientInterface::class)
             ->addTag('ai.platform.model_client');
         $builder->registerForAutoconfiguration(ResultConverterInterface::class)
@@ -436,9 +461,6 @@ private function processAgentConfig(string $name, array $config, ContainerBuilde
             ->setArgument(0, new Reference($config['platform']))
             ->setArgument(1, new Reference('ai.agent.'.$name.'.model'));
 
-        $inputProcessors = [];
-        $outputProcessors = [];
-
         // TOOL & PROCESSOR
         if ($config['tools']['enabled']) {
             // Create specific toolbox and process if tools are explicitly defined
@@ -492,26 +514,28 @@ private function processAgentConfig(string $name, array $config, ContainerBuilde
 
                 $toolProcessorDefinition = (new ChildDefinition('ai.tool.agent_processor.abstract'))
                     ->replaceArgument(0, new Reference('ai.toolbox.'.$name));
-                $container->setDefinition('ai.tool.agent_processor.'.$name, $toolProcessorDefinition);
 
-                $inputProcessors[] = new Reference('ai.tool.agent_processor.'.$name);
-                $outputProcessors[] = new Reference('ai.tool.agent_processor.'.$name);
+                $container->setDefinition('ai.tool.agent_processor.'.$name, $toolProcessorDefinition)
+                    ->addTag('ai.agent.input_processor', ['agent' => $name, 'priority' => -10])
+                    ->addTag('ai.agent.output_processor', ['agent' => $name, 'priority' => -10]);
             } else {
                 if ($config['fault_tolerant_toolbox'] && !$container->hasDefinition('ai.fault_tolerant_toolbox')) {
                     $container->setDefinition('ai.fault_tolerant_toolbox', new Definition(FaultTolerantToolbox::class))
                         ->setArguments([new Reference('.inner')])
                         ->setDecoratedService('ai.toolbox');
                 }
 
-                $inputProcessors[] = new Reference('ai.tool.agent_processor');
-                $outputProcessors[] = new Reference('ai.tool.agent_processor');
+                $container->getDefinition('ai.tool.agent_processor')
+                    ->addTag('ai.agent.input_processor', ['agent' => $name, 'priority' => -10])
+                    ->addTag('ai.agent.output_processor', ['agent' => $name, 'priority' => -10]);
             }
         }
 
         // STRUCTURED OUTPUT
         if ($config['structured_output']) {
-            $inputProcessors[] = new Reference('ai.agent.structured_output_processor');
-            $outputProcessors[] = new Reference('ai.agent.structured_output_processor');
+            $container->getDefinition('ai.agent.structured_output_processor')
+                ->addTag('ai.agent.input_processor', ['agent' => $name, 'priority' => -20])
+                ->addTag('ai.agent.output_processor', ['agent' => $name, 'priority' => -20]);
         }
 
         // TOKEN USAGE TRACKING
@@ -530,25 +554,28 @@ private function processAgentConfig(string $name, array $config, ContainerBuilde
                 }
 
                 if ($container->hasDefinition('ai.platform.token_usage_processor.'.$platform)) {
-                    $outputProcessors[] = new Reference('ai.platform.token_usage_processor.'.$platform);
+                    $container->getDefinition('ai.platform.token_usage_processor.'.$platform)
+                        ->addTag('ai.agent.output_processor', ['agent' => $name, 'priority' => -30]);
                 }
             }
         }
 
         // SYSTEM PROMPT
         if (\is_string($config['system_prompt'])) {
-            $systemPromptInputProcessorDefinition = new Definition(SystemPromptInputProcessor::class, [
-                $config['system_prompt'],
-                $config['include_tools'] ? new Reference('ai.toolbox.'.$name) : null,
-                new Reference('logger', ContainerInterface::IGNORE_ON_INVALID_REFERENCE),
-            ]);
+            $systemPromptInputProcessorDefinition = (new Definition(SystemPromptInputProcessor::class))
+                ->setArguments([
+                    $config['system_prompt'],
+                    $config['include_tools'] ? new Reference('ai.toolbox.'.$name) : null,
+                    new Reference('logger', ContainerInterface::IGNORE_ON_INVALID_REFERENCE),
+                ])
+                ->addTag('ai.agent.input_processor', ['agent' => $name, 'priority' => -30]);
 
-            $inputProcessors[] = $systemPromptInputProcessorDefinition;
+            $container->setDefinition('ai.agent.'.$name.'.system_prompt_processor', $systemPromptInputProcessorDefinition);
         }
 
         $agentDefinition
-            ->setArgument(2, $inputProcessors)
-            ->setArgument(3, $outputProcessors)
+            ->setArgument(2, []) // placeholder until ProcessorCompilerPass process.
+            ->setArgument(3, []) // placeholder until ProcessorCompilerPass process.
             ->setArgument(4, new Reference('logger', ContainerInterface::IGNORE_ON_INVALID_REFERENCE))
         ;
 
diff --git a/src/ai-bundle/src/DependencyInjection/ProcessorCompilerPass.php b/src/ai-bundle/src/DependencyInjection/ProcessorCompilerPass.php
@@ -0,0 +1,66 @@
+<?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\AiBundle\DependencyInjection;
+
+use Symfony\Component\DependencyInjection\Compiler\CompilerPassInterface;
+use Symfony\Component\DependencyInjection\ContainerBuilder;
+use Symfony\Component\DependencyInjection\Reference;
+
+class ProcessorCompilerPass implements CompilerPassInterface
+{
+    public function process(ContainerBuilder $container): void
+    {
+        $inputProcessors = $container->findTaggedServiceIds('ai.agent.input_processor');
+        $outputProcessors = $container->findTaggedServiceIds('ai.agent.output_processor');
+
+        foreach ($container->findTaggedServiceIds('ai.agent') as $serviceId => $tags) {
+            $agentInputProcessors = [];
+            $agentOutputProcessors = [];
+            foreach ($inputProcessors as $processorId => $processorTags) {
+                foreach ($processorTags as $tag) {
+                    if ('interface' === ($tag['tagged_by'] ?? null) && \count($processorTags) > 1) {
+                        continue;
+                    }
+
+                    $agent = $tag['agent'] ?? null;
+                    if (null === $agent || $agent === $serviceId) {
+                        $priority = $tag['priority'] ?? 0;
+                        $agentInputProcessors[] = [$priority, new Reference($processorId)];
+                    }
+                }
+            }
+
+            foreach ($outputProcessors as $processorId => $processorTags) {
+                foreach ($processorTags as $tag) {
+                    if ('interface' === ($tag['tagged_by'] ?? null) && \count($processorTags) > 1) {
+                        continue;
+                    }
+
+                    $agent = $tag['agent'] ?? null;
+                    if (null === $agent || $agent === $serviceId) {
+                        $priority = $tag['priority'] ?? 0;
+                        $agentOutputProcessors[] = [$priority, new Reference($processorId)];
+                    }
+                }
+            }
+
+            $sortCb = static fn (array $a, array $b): int => $b[0] <=> $a[0];
+            usort($agentInputProcessors, $sortCb);
+            usort($agentOutputProcessors, $sortCb);
+
+            $agentDefinition = $container->getDefinition($serviceId);
+            $agentDefinition
+                ->setArgument(2, array_column($agentInputProcessors, 1))
+                ->setArgument(3, array_column($agentOutputProcessors, 1));
+        }
+    }
+}
diff --git a/src/ai-bundle/tests/DependencyInjection/ProcessorCompilerPassTest.php b/src/ai-bundle/tests/DependencyInjection/ProcessorCompilerPassTest.php
