Add multi-agent bundle configuration with validation

- Add minimum 2 handoffs validation to MultiAgent
- Configure multi-agent systems via AiBundle YAML configuration
- Add comprehensive documentation for multi-agent bundle config
- Update orchestrator example to use AgentInterface in handoffs
- Make delegation log message more concise
- Remove trailing newline from composer.json

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>

Author: OskarStark

composer.json

@@ -17,4 +17,3 @@
         "sort-packages": true
     }
 }
-

demo/config/packages/ai.yaml

@@ -49,6 +49,24 @@ ai:
                 - agent: 'blog'
                   name: 'symfony_blog'
                   description: 'Can answer questions based on the Symfony blog.'
+        orchestrator:
+            model:
+                class: 'Symfony\AI\Platform\Bridge\OpenAi\Gpt'
+                name: !php/const Symfony\AI\Platform\Bridge\OpenAi\Gpt::GPT_4O_MINI
+            prompt: 'You are an intelligent agent orchestrator that routes user questions to specialized agents.'
+            tools: false
+        technical:
+            model:
+                class: 'Symfony\AI\Platform\Bridge\OpenAi\Gpt'
+                name: !php/const Symfony\AI\Platform\Bridge\OpenAi\Gpt::GPT_4O_MINI
+            prompt: 'You are a technical support specialist. Help users resolve bugs, problems, and technical errors.'
+            tools: false
+        general:
+            model:
+                class: 'Symfony\AI\Platform\Bridge\OpenAi\Gpt'
+                name: !php/const Symfony\AI\Platform\Bridge\OpenAi\Gpt::GPT_4O_MINI
+            prompt: 'You are a helpful general assistant. Assist users with any questions or tasks they may have.'
+            tools: false
     store:
         chroma_db:
             symfonycon:
@@ -68,6 +86,14 @@ ai:
                 - 'Symfony\AI\Store\Document\Transformer\TextTrimTransformer'
             vectorizer: 'ai.vectorizer.openai'
             store: 'ai.store.chroma_db.symfonycon'
+    multi_agent:
+        support:
+            orchestrator: 'ai.agent.orchestrator'
+            handoffs:
+                - to: 'ai.agent.technical'
+                  when: ['bug', 'problem', 'technical', 'error', 'code', 'debug']
+                - to: 'ai.agent.general'
+                  when: []
 
 services:
     _defaults:

examples/multi-agent/orchestrator.php

@@ -50,10 +50,9 @@
 
 $multiAgent = new MultiAgent(
     orchestrator: $orchestrator,
-    agents: [$technical, $general],
     handoffs: [
-        new Handoff(to: 'technical', when: ['bug', 'problem', 'technical', 'error']),
-        new Handoff(to: 'general'),
+        new Handoff(to: $technical, when: ['bug', 'problem', 'technical', 'error']),
+        new Handoff(to: $general),
     ],
     logger: logger()
 );

src/agent/src/MultiAgent/MultiAgent.php

@@ -45,6 +45,10 @@ public function __construct(
         if ([] === $handoffs) {
             throw new InvalidArgumentException('Handoffs array cannot be empty.');
         }
+
+        if (\count($handoffs) < 2) {
+            throw new InvalidArgumentException('MultiAgent requires at least 2 handoffs. For a single handoff, use the agent directly.');
+        }
     }
 
     public function getName(): string
@@ -119,7 +123,7 @@ public function call(MessageBag $messages, array $options = []): ResultInterface
             return $this->orchestrator->call($messages, $options);
         }
 
-        $this->logger->debug('MultiAgent: Delegating to target agent', ['agent_name' => $agentName]);
+        $this->logger->debug('MultiAgent: Delegating to agent', ['agent_name' => $agentName]);
         $originalMessages = new MessageBag(self::findUserMessage($userMessages));
 
         return $targetAgent->call($originalMessages, $options);

src/ai-bundle/config/options.php

@@ -594,6 +594,40 @@
                     ->end()
                 ->end()
             ->end()
+            ->arrayNode('multi_agent')
+                ->info('Multi-agent orchestration configuration')
+                ->useAttributeAsKey('name')
+                ->arrayPrototype()
+                    ->children()
+                        ->stringNode('orchestrator')
+                            ->info('Service ID of the orchestrator agent')
+                            ->isRequired()
+                        ->end()
+                        ->arrayNode('handoffs')
+                            ->info('Handoff rules for agent routing')
+                            ->isRequired()
+                            ->requiresAtLeastOneElement()
+                            ->arrayPrototype()
+                                ->children()
+                                    ->stringNode('to')
+                                        ->info('Service ID of the target agent')
+                                        ->isRequired()
+                                    ->end()
+                                    ->arrayNode('when')
+                                        ->info('Keywords or phrases that trigger this handoff')
+                                        ->scalarPrototype()->end()
+                                        ->defaultValue([])
+                                    ->end()
+                                ->end()
+                            ->end()
+                        ->end()
+                        ->stringNode('logger')
+                            ->info('Service ID of the logger')
+                            ->defaultNull()
+                        ->end()
+                    ->end()
+                ->end()
+            ->end()
         ->end()
     ;
 };

src/ai-bundle/docs/multi-agent.md

@@ -0,0 +1,111 @@
+# Multi-Agent Configuration
+
+The AI Bundle provides a configuration system for creating multi-agent orchestrators that route requests to specialized agents based on defined handoff rules.
+
+## Configuration
+
+Configure multi-agent systems in your `config/packages/ai.yaml` file:
+
+```yaml
+ai:
+    multi_agent:
+        # Define named multi-agent systems
+        support:
+            # The main orchestrator agent that analyzes requests
+            orchestrator: 'ai.agent.orchestrator'
+            
+            # Handoff rules defining when to route to specific agents
+            # Minimum 2 handoffs required (otherwise use the agent directly)
+            handoffs:
+                # Route to technical agent for specific keywords
+                - to: 'ai.agent.technical'
+                  when: ['bug', 'problem', 'technical', 'error', 'code', 'debug']
+                
+                # Fallback to general agent when no specific conditions match
+                - to: 'ai.agent.general'
+                  when: []
+            
+            # Optional: Custom logger service
+            logger: 'monolog.logger.ai'
+```
+
+## Service Registration
+
+Each multi-agent configuration automatically registers a service with the ID pattern `ai.multi_agent.{name}`.
+
+For the example above, the service `ai.multi_agent.support` is registered and can be injected:
+
+```php
+use Symfony\AI\Agent\AgentInterface;
+use Symfony\Component\Routing\Attribute\Route;
+use Symfony\Contracts\Service\Attribute\Target;
+
+class SupportController
+{
+    public function __construct(
+        #[Target('supportMultiAgent')]
+        private AgentInterface $supportAgent,
+    ) {
+    }
+    
+    #[Route('/ask-support')]
+    public function askSupport(string $question): Response
+    {
+        $messages = new MessageBag(Message::ofUser($question));
+        $response = $this->supportAgent->call($messages);
+        
+        return new Response($response->getContent());
+    }
+}
+```
+
+## Handoff Rules
+
+Handoff rules determine when to delegate to specific agents:
+
+### `to` (required)
+The service ID of the target agent to delegate to.
+
+### `when` (optional)
+An array of keywords or phrases that trigger this handoff. When the orchestrator identifies these keywords in the user's request, it delegates to the specified agent.
+
+If `when` is empty or not specified, the handoff acts as a fallback for requests that don't match other rules.
+
+## How It Works
+
+1. The orchestrator agent receives the initial request
+2. It analyzes the request content and matches it against handoff rules
+3. If keywords match a handoff's `when` conditions, the request is delegated to that agent
+4. If no specific conditions match, a fallback handoff (with empty `when`) is used
+5. The delegated agent processes the request and returns the response
+
+## Requirements
+
+- At least 2 handoff rules must be defined (for a single handoff, use the agent directly)
+- The orchestrator and all referenced agents must be registered as services
+- All agent services must implement `Symfony\AI\Agent\AgentInterface`
+
+## Example: Customer Service Bot
+
+```yaml
+ai:
+    multi_agent:
+        customer_service:
+            orchestrator: 'ai.agent.analyzer'
+            handoffs:
+                # Technical support
+                - to: 'ai.agent.tech_support'
+                  when: ['error', 'bug', 'crash', 'not working', 'broken']
+                
+                # Billing inquiries
+                - to: 'ai.agent.billing'
+                  when: ['payment', 'invoice', 'billing', 'subscription', 'price']
+                
+                # Product information
+                - to: 'ai.agent.product_info'
+                  when: ['features', 'how to', 'tutorial', 'guide', 'documentation']
+                
+                # General inquiries (fallback)
+                - to: 'ai.agent.general_support'
+                  when: []
+```

src/ai-bundle/src/AiBundle.php

@@ -21,6 +21,8 @@
 use Symfony\AI\Agent\InputProcessorInterface;
 use Symfony\AI\Agent\Memory\MemoryInputProcessor;
 use Symfony\AI\Agent\Memory\StaticMemoryProvider;
+use Symfony\AI\Agent\MultiAgent\Handoff;
+use Symfony\AI\Agent\MultiAgent\MultiAgent;
 use Symfony\AI\Agent\OutputProcessorInterface;
 use Symfony\AI\Agent\Toolbox\Attribute\AsTool;
 use Symfony\AI\Agent\Toolbox\FaultTolerantToolbox;
@@ -164,6 +166,10 @@ public function loadExtension(array $config, ContainerConfigurator $container, C
             $builder->setAlias(IndexerInterface::class, 'ai.indexer.'.$indexerName);
         }
 
+        foreach ($config['multi_agent'] ?? [] as $multiAgentName => $multiAgent) {
+            $this->processMultiAgentConfig($multiAgentName, $multiAgent, $builder);
+        }
+
         $builder->registerAttributeForAutoconfiguration(AsTool::class, static function (ChildDefinition $definition, AsTool $attribute): void {
             $definition->addTag('ai.tool', [
                 'name' => $attribute->name,
@@ -1203,4 +1209,37 @@ private function processIndexerConfig(int|string $name, array $config, Container
 
         $container->setDefinition('ai.indexer.'.$name, $definition);
     }
+
+    /**
+     * @param array<string, mixed> $config
+     */
+    private function processMultiAgentConfig(string $name, array $config, ContainerBuilder $container): void
+    {
+        $handoffs = [];
+
+        foreach ($config['handoffs'] as $handoffConfig) {
+            $agentReference = new Reference($handoffConfig['to']);
+            
+            $handoffDefinition = new Definition(Handoff::class, [
+                $agentReference,
+                $handoffConfig['when'] ?? [],
+            ]);
+            
+            $handoffs[] = $handoffDefinition;
+        }
+
+        $multiAgentId = 'ai.multi_agent.'.$name;
+        $multiAgentDefinition = new Definition(MultiAgent::class, [
+            new Reference($config['orchestrator']),
+            $handoffs,
+            $name,
+            new Reference($config['logger'] ?? 'logger', ContainerInterface::IGNORE_ON_INVALID_REFERENCE),
+        ]);
+
+        $multiAgentDefinition->addTag('ai.multi_agent', ['name' => $name]);
+        $multiAgentDefinition->addTag('ai.agent', ['name' => $name]);
+
+        $container->setDefinition($multiAgentId, $multiAgentDefinition);
+        $container->registerAliasForArgument($multiAgentId, AgentInterface::class, (new Target($name.'MultiAgent'))->getParsedName());
+    }
 }