AI Bundle

Basic Example with OpenAI

1
2
3
4
5
6
7
8

# config/packages/ai.yaml
ai:
    platform:
        openai:
            api_key: '%env(OPENAI_API_KEY)%'
    agent:
        default:
            model: 'gpt-4o-mini'

Advanced Example with Multiple Agents

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124

# config/packages/ai.yaml
ai:
    platform:
        anthropic:
            api_key: '%env(ANTHROPIC_API_KEY)%'
        azure:
            # multiple deployments possible
            gpt_deployment:
                base_url: '%env(AZURE_OPENAI_BASEURL)%'
                deployment: '%env(AZURE_OPENAI_GPT)%'
                api_key: '%env(AZURE_OPENAI_KEY)%'
                api_version: '%env(AZURE_GPT_VERSION)%'
        bedrock:
            # multiple instances possible - for example region depending
            default: ~
            eu:
                bedrock_runtime_client: 'async_aws.client.bedrock_runtime_eu'
        deepgram:
            api_key: '%env(DEEPGRAM_API_KEY)%'
        elevenlabs:
            api_key: '%env(ELEVEN_LABS_API_KEY)%'
        gemini:
            api_key: '%env(GEMINI_API_KEY)%'
        perplexity:
            api_key: '%env(PERPLEXITY_API_KEY)%'
        # VertexAI with project-scoped endpoint (requires google/auth)
        vertexai:
            location: '%env(GOOGLE_CLOUD_LOCATION)%'
            project_id: '%env(GOOGLE_CLOUD_PROJECT)%'
            api_key: '%env(GOOGLE_CLOUD_VERTEX_API_KEY)%' # Optional: uses ADC by default

        # Or with global endpoint (API key only, no google/auth needed)
        # vertexai:
        #     api_key: '%env(GOOGLE_CLOUD_VERTEX_API_KEY)%'
        ollama:
            endpoint: '%env(OLLAMA_HOST_URL)%'
        transformersphp: ~
    agent:
        rag:
            platform: 'ai.platform.azure.gpt_deployment'
            model: 'gpt-4o-mini'
            memory: 'You have access to conversation history and user preferences' # Optional: static memory content
            prompt: # The system prompt configuration
                text: 'You are a helpful assistant that can answer questions.' # The prompt text
                include_tools: true # Include tool definitions at the end of the system prompt
            tools:
                # Referencing a service with #[AsTool] attribute
                - 'Symfony\AI\Agent\Bridge\SimilaritySearch\SimilaritySearch'

                # Referencing a service without #[AsTool] attribute
                - service: 'App\Agent\Tool\CompanyName'
                  name: 'company_name'
                  description: 'Provides the name of your company'
                  method: 'foo' # Optional with default value '__invoke'

                # Referencing an agent => agent in agent 🤯
                - agent: 'research'
                  name: 'wikipedia_research'
                  description: 'Can research on Wikipedia'
        research:
            platform: 'ai.platform.anthropic'
            model: 'claude-3-7-sonnet-latest'
            tools: # Tools are opt-in: if undefined, the agent gets no tools; use "tools: true" to inject all tools.
                - 'Symfony\AI\Agent\Bridge\Wikipedia\Wikipedia'
            fault_tolerant_toolbox: false # Disables fault tolerant toolbox, default is true
            max_tool_calls: 75 # Cap of tool-calling iterations per agent call (default 50); set to null to disable the limit
        search_agent:
            platform: 'ai.platform.perplexity'
            model: 'sonar'
            tools: false
        audio:
            platform: 'ai.platform.elevenlabs'
            model: 'text-to-speech'
            tools: false
        nova:
            platform: 'ai.platform.bedrock.default'
            model: 'nova-pro'
            tools: false
    store:
        chromadb:
            # multiple collections possible per type
            default:
                collection: 'my_collection'
        cache:
            research:
                service: 'cache.app'
                cache_key: 'research'
                strategy: 'chebyshev'
        memory:
            ollama:
                strategy: 'manhattan'
    vectorizer:
        # Reusable vectorizer configurations
        openai_embeddings:
            platform: 'ai.platform.openai'
            model:
                name: 'text-embedding-3-small'
                options:
                    dimensions: 512
        mistral_embeddings:
            platform: 'ai.platform.mistral'
            model: 'mistral-embed'
    indexer:
        # DocumentIndexer: no loader, accepts documents directly via index($document)
        default:
            vectorizer: 'ai.vectorizer.openai_embeddings'
            store: 'ai.store.chromadb.default'

        # SourceIndexer: loader without source, call index('/path/to/file') at runtime
        research:
            loader: 'Symfony\AI\Store\Document\Loader\TextFileLoader'
            vectorizer: 'ai.vectorizer.mistral_embeddings'
            store: 'ai.store.memory.research'

        # ConfiguredSourceIndexer: loader + pre-configured source, call index() with no arguments
        docs:
            loader: 'Symfony\AI\Store\Document\Loader\RstToctreeLoader'
            source: '/path/to/docs/index.rst'
            vectorizer: 'ai.vectorizer.openai_embeddings'
            store: 'ai.store.chromadb.default'
            # optional: apply transformers (e.g. chunking) and filters
            transformers:
                - 'Symfony\AI\Store\Document\Transformer\TextSplitTransformer'
            filters: []

Advanced Configuration

For more control, such as including tool definitions in the system prompt, use the array format:

1
2
3
4
5
6
7

ai:
    agent:
        my_agent:
            model: 'gpt-4o-mini'
            prompt:
                text: 'You are a helpful assistant that can answer questions.'
                include_tools: true # Include tool definitions at the end of the system prompt

The array format supports these options:

• text (string): The system prompt text that will be sent to the AI model (either text or file is required)
• file (string): Path to a file containing the system prompt (either text or file is required)
• include_tools (boolean, optional): When set to true, tool definitions will be appended to the system prompt
• enable_translation (boolean, optional): When set to true, enables translation for the system prompt text (requires symfony/translation)
• translation_domain (string, optional): The translation domain to use for the system prompt translation

File-Based Prompts

For better organization and reusability, you can store system prompts in external files. This is particularly useful for:

• Long, complex prompts with multiple sections
• Prompts shared across multiple agents or projects
• Version-controlled prompt templates
• JSON-structured prompts with specific formatting

Configure the prompt with a file path:

1
2
3
4
5
6

ai:
    agent:
        my_agent:
            model: 'gpt-4o-mini'
            prompt:
                file: '%kernel.project_dir%/prompts/assistant.txt'

The file can be in any text format (.txt, .json, .md, etc.). The entire content of the file will be used as the system prompt text.

1
2
3
4
5
6

You are a helpful and knowledgeable assistant.

Guidelines:
- Be clear and direct in your responses
- Provide examples when appropriate
- Be respectful and professional at all times

1
2
3
4
5
6
7
8

{
  "role": "You are an expert code reviewer",
  "responsibilities": [
    "Review code for bugs and potential issues",
    "Suggest improvements for code quality"
  ],
  "tone": "constructive and educational"
}

Translation Support

To use translated system prompts, you need to have the Symfony Translation component installed:

1

$ composer require symfony/translation

Then configure the prompt with translation enabled:

1
2
3
4
5
6
7
8

ai:
    agent:
        my_agent:
            model: 'gpt-4o-mini'
            prompt:
                text: 'agent.system_prompt'  # Translation key
                enable_translation: true
                translation_domain: 'ai_prompts'  # Optional: specify translation domain

The system prompt text will be automatically translated using the configured translator service. If no translation domain is specified, the default domain will be used.

Message Template Support

The Platform's feature for using message templates is set up by the bundle, and conditionally also registers the expression language support if the `symfony/expression-language` package is installed.

More about message templates can be found in the Platform documentation.

Static Memory (Simple)

The simplest way to add memory is to provide a string that will be used as static context:

1
2
3
4
5
6
7

ai:
    agent:
        my_agent:
            model: 'gpt-4o-mini'
            memory: 'You have access to user preferences and conversation history'
            prompt:
                text: 'You are a helpful assistant.'

This static memory content is consistently available to the agent across all conversations.

Dynamic Memory (Advanced)

For more sophisticated scenarios, you can reference an existing service that implements dynamic memory. Use the array syntax with a service key to explicitly reference a service:

1
2
3
4
5
6
7
8

ai:
    agent:
        my_agent:
            model: 'gpt-4o-mini'
            memory:
                service: 'my_memory_service'  # Explicitly references an existing service
            prompt:
                text: 'You are a helpful assistant.'

Memory as System Prompt

Memory can work independently or alongside the system prompt:

• Memory only: If no prompt is provided, memory becomes the system prompt
• Memory + Prompt: If both are provided, memory is prepended to the prompt

1
2
3
4
5
6
7
8
9
10
11
12
13

ai:
    agent:
        # Agent with memory only (memory becomes system prompt)
        memory_only_agent:
            model: 'gpt-4o-mini'
            memory: 'You are a helpful assistant with conversation history'

        # Agent with both memory and prompt (memory prepended to prompt)
        memory_and_prompt_agent:
            model: 'gpt-4o-mini'
            memory: 'Previous conversation context...'
            prompt:
                text: 'You are a helpful assistant.'

Custom Memory Provider Requirements

When using a service reference, the memory service must implement the MemoryProviderInterface:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

use Symfony\AI\Agent\Input;
use Symfony\AI\Agent\Memory\Memory;
use Symfony\AI\Agent\Memory\MemoryProviderInterface;

final class MyMemoryProvider implements MemoryProviderInterface
{
    public function load(Input $input): array
    {
        // Return an array of Memory objects containing relevant conversation history
        return [
            new Memory('Username: OskarStark'),
            new Memory('Age: 40'),
            new Memory('User preferences: prefers concise answers'),
        ];
    }
}

Multi-Agent vs Agent-as-Tool

The AI Bundle supports two different approaches for combining multiple agents:

1. Agent-as-Tool: An agent can use another agent as a tool during its processing. The main agent decides when and how to call the secondary agent, similar to any other tool. This is useful when:

   • The main agent needs optional access to specialized capabilities
   • The decision to use the secondary agent is context-dependent
   • You want the main agent to control the entire conversation flow
   • The secondary agent provides supplementary information

   Example: A general assistant that can optionally query a research agent for detailed information.

2. Multi-Agent Orchestration: A dedicated orchestrator analyzes each request and routes it to the most appropriate specialized agent. This is useful when:

   • You have distinct domains that require different expertise
   • You want clear separation of concerns between agents
   • The routing decision should be made upfront based on the request type
   • Each agent should handle the entire conversation for its domain

   Example: A customer service system that routes to technical support, billing, or general inquiries based on the user's question.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

# config/packages/ai.yaml
ai:
    multi_agent:
        # Define named multi-agent systems
        support:
            # The main orchestrator agent that analyzes requests
            orchestrator: 'orchestrator'

            # Handoff rules mapping agents to trigger keywords
            # At least 1 handoff required
            handoffs:
                technical: ['bug', 'problem', 'technical', 'error', 'code', 'debug']

            # Fallback agent for unmatched requests (required)
            fallback: 'general'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

use Symfony\AI\Agent\AgentInterface;
use Symfony\AI\Platform\Message\Message;
use Symfony\AI\Platform\Message\MessageBag;
use Symfony\Component\DependencyInjection\Attribute\Autowire;

final class SupportController
{
    public function __construct(
        #[Autowire(service: 'ai.multi_agent.support')]
        private AgentInterface $supportAgent,
    ) {
    }

    public function askSupport(string $question): string
    {
        $messages = new MessageBag(Message::ofUser($question));
        $response = $this->supportAgent->call($messages);

        return $response->getContent();
    }
}

1
2
3
4
5
6

use Symfony\AI\Agent\MultiAgent\Handoff;

$technicalHandoff = new Handoff(
    to: $technicalAgent,
    when: ['code', 'debug', 'implementation', 'refactor', 'programming']
);

1
2
3
4
5
6
7
8
9

ai:
    multi_agent:
        customer_service:
            orchestrator: 'analyzer'
            handoffs:
                tech_support: ['error', 'bug', 'crash', 'not working', 'broken']
                billing: ['payment', 'invoice', 'billing', 'subscription', 'price']
                product_info: ['features', 'how to', 'tutorial', 'guide', 'documentation']
            fallback: 'general_support'  # Fallback for general inquiries

ai:platform:invoke

The ai:platform:invoke command allows you to directly invoke any configured AI platform with a message. This is useful for testing platform configurations and quick interactions with AI models.

1
2
3
4
5
6
7

$ php bin/console ai:platform:invoke <platform> <model> "<message>"

# Using OpenAI
$ php bin/console ai:platform:invoke openai gpt-4o-mini "Hello, world!"

# Using Anthropic
$ php bin/console ai:platform:invoke anthropic claude-3-5-sonnet-20241022 "Explain quantum physics"

ai:agent:call

The ai:agent:call command provides an interactive chat interface to communicate with configured agents. This is useful for testing agent configurations, tools, and conversational flows.

1
2
3
4
5
6
7

$ php bin/console ai:agent:call <agent>

# Chat with the default agent
$ php bin/console ai:agent:call default

# Chat with a specific agent
$ php bin/console ai:agent:call wikipedia

The command starts an interactive session where you can:

• Type messages and press Enter to send them to the agent
• See the agent's responses in real-time
• View the system prompt that was configured for the agent
• Type exit or quit to end the conversation

If no agent name is provided, you'll be prompted to select one from the available configured agents.

ai:store:setup

The ai:store:setup command prepares the required infrastructure for a store (e.g., creates database tables, indexes, collections).

1
2
3
4

$ php bin/console ai:store:setup <store>

# Setup the chromadb store
$ php bin/console ai:store:setup chromadb.default

1
2
3
4

# config/packages/doctrine.yaml
doctrine:
    dbal:
        schema_filter: '~^(?!ai_)~'

ai:store:drop

The ai:store:drop command drops the infrastructure for a store (e.g., removes database tables, indexes, collections).

1
2
3
4

$ php bin/console ai:store:drop <store> --force

# Drop the chromadb store
$ php bin/console ai:store:drop chromadb.default --force

ai:store:index

The ai:store:index command indexes documents into a store using a configured indexer.

1
2
3
4
5
6
7
8
9
10

$ php bin/console ai:store:index <indexer>

# Index using the default indexer
$ php bin/console ai:store:index default

# Override the configured source with a single file
$ php bin/console ai:store:index blog --source=/path/to/file.txt

# Override with multiple sources
$ php bin/console ai:store:index blog --source=/path/to/file1.txt --source=/path/to/file2.txt

The --source (or -s) option allows you to override the source(s) configured in your indexer. This is useful for ad-hoc indexing operations or testing different data sources.

Agent Service

Use the Agent service to leverage models and tools:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

use Symfony\AI\Agent\AgentInterface;
use Symfony\AI\Platform\Message\Message;
use Symfony\AI\Platform\Message\MessageBag;

final readonly class MyService
{
    public function __construct(
        private AgentInterface $agent,
    ) {
    }

    public function submit(string $message): string
    {
        $messages = new MessageBag(
            Message::forSystem('Speak like a pirate.'),
            Message::ofUser($message),
        );

        return $this->agent->call($messages)->getContent();
    }
}

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:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

use Symfony\AI\Agent\Attribute\AsInputProcessor;
use Symfony\AI\Agent\Attribute\AsOutputProcessor;
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: 'ai.agent.my_agent_name')] // The output processor will only be registered for 'ai.agent.my_agent_name'
final readonly class MyService implements InputProcessorInterface, OutputProcessorInterface
{
    public function processInput(Input $input): void
    {
        // ...
    }

    public function processOutput(Output $output): void
    {
        // ...
    }
}

Register Tools

The following tools can be installed as dedicated packages, no configuration is needed as these bridges come with flex recipes.

1
2
3
4
5
6
7
8
9
10
11

$ composer require symfony/ai-brave-tool
$ composer require symfony/ai-clock-tool
$ composer require symfony/ai-firecrawl-tool
$ composer require symfony/ai-mapbox-tool
$ composer require symfony/ai-open-meteo-tool
$ composer require symfony/ai-scraper-tool
$ composer require symfony/ai-serp-api-tool
$ composer require symfony/ai-similarity-search-tool
$ composer require symfony/ai-tavily-tool
$ composer require symfony/ai-wikipedia-tool
$ composer require symfony/ai-youtube-tool

Some tools may require additional configuration even when installed as dedicated packages. For example, the SimilaritySearch tool requires a retriever:

1
2
3
4
5
6
7
8
9

services:
    _defaults:
        autowire: true
        autoconfigure: true

    Symfony\AI\Agent\Bridge\SimilaritySearch\SimilaritySearch:
        $retriever: '@ai.retriever.main'
        # optionally customize the result header
        # $promptTemplate: 'Here are the relevant results:'

Configuring Vectorizers

Vectorizers are defined in the vectorizer section of your configuration:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

ai:
    vectorizer:
        openai_small:
            platform: 'ai.platform.openai'
            model:
                name: 'text-embedding-3-small'
                options:
                    dimensions: 512

        openai_large:
            platform: 'ai.platform.openai'
            model: 'text-embedding-3-large'

        mistral_embed:
            platform: 'ai.platform.mistral'
            model: 'mistral-embed'

Using Vectorizers in Indexers

Once configured, vectorizers can be referenced by name in indexer configurations:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

ai:
    indexer:
        documents:
            loader: 'Symfony\AI\Store\Document\Loader\TextFileLoader'
            vectorizer: 'ai.vectorizer.openai_small'
            store: 'ai.store.chromadb.documents'

        research:
            loader: 'Symfony\AI\Store\Document\Loader\TextFileLoader'
            vectorizer: 'ai.vectorizer.openai_large'
            store: 'ai.store.chromadb.research'

        knowledge_base:
            loader: 'Symfony\AI\Store\Document\Loader\InMemoryLoader'
            vectorizer: 'ai.vectorizer.mistral_embed'
            store: 'ai.store.memory.kb'

Document Indexers

If you omit the loader option, a DocumentIndexer is created instead of a SourceIndexer. This is useful when you want to index documents directly in your code without loading them from external sources:

1
2
3
4
5
6

ai:
    indexer:
        my_indexer:
            # No loader - creates a DocumentIndexer
            vectorizer: 'ai.vectorizer.openai_small'
            store: 'ai.store.chromadb.documents'

The resulting service accepts documents directly:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

use Symfony\AI\Store\Document\TextDocument;
use Symfony\AI\Store\IndexerInterface;

class MyService
{
    public function __construct(
        private IndexerInterface $myIndexer,
    ) {
    }

    public function indexContent(string $id, string $content): void
    {
        $this->myIndexer->index(new TextDocument($id, $content));
        // Or multiple documents
        $this->myIndexer->index([$document1, $document2]);
    }
}

Benefits of Configured Vectorizers

• Reusability: Define once, use in multiple indexers
• Consistency: Ensure all indexers using the same vectorizer have identical embedding configuration
• Maintainability: Change vectorizer settings in one place

Configuring Retrievers

Retrievers are defined in the retriever section of your configuration:

1
2
3
4
5
6
7
8
9

ai:
    retriever:
        default:
            vectorizer: 'ai.vectorizer.openai_small'
            store: 'ai.store.chromadb.default'

        research:
            vectorizer: 'ai.vectorizer.mistral_embed'
            store: 'ai.store.memory.research'

Using Retrievers

The retriever can be injected into your services using the RetrieverInterface:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

use Symfony\AI\Store\RetrieverInterface;

final readonly class MyService
{
    public function __construct(
        private RetrieverInterface $retriever,
    ) {
    }

    public function search(string $query): array
    {
        $documents = [];
        foreach ($this->retriever->retrieve($query) as $document) {
            $documents[] = $document;
        }

        return $documents;
    }
}

When you have multiple retrievers configured, you can use the #[Autowire] attribute to inject a specific one:

1
2
3
4
5
6
7
8
9
10
11

use Symfony\AI\Store\RetrieverInterface;
use Symfony\Component\DependencyInjection\Attribute\Autowire;

final readonly class ResearchService
{
    public function __construct(
        #[Autowire(service: 'ai.retriever.research')]
        private RetrieverInterface $retriever,
    ) {
    }
}

Testing agents

Answers of a model are not deterministic, which makes them a poor thing to assert on. What an agent did is deterministic enough: that it called the model, that it reached for a tool, that it did not call the platform twice when once is expected.

The profiler collects exactly that, and AiAssertionsTrait turns it into assertions for functional tests. Enable the profiler on the client before the request, and assert afterwards:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

use Symfony\AI\AiBundle\Test\AiAssertionsTrait;
use Symfony\Bundle\FrameworkBundle\Test\WebTestCase;

final class AgentTest extends WebTestCase
{
    use AiAssertionsTrait;

    public function testTheAgentSearchesTheBlog()
    {
        $client = static::createClient();
        $client->enableProfiler();

        $client->request('POST', '/chat', ['message' => 'What happened last week?']);

        // Once to decide on the tool, once with its result.
        self::assertPlatformCallCount(2);
        self::assertModelCalled('gpt-4.1');
        self::assertToolCalled('similarity_search');
    }
}

The trait provides:

assertPlatformCallCount(int $expectedCount)

The number of calls made to a platform while handling the request, across all agents.

assertModelCalled(string $model)

That the given model was called at least once.

assertToolCalled(string $tool) and assertToolCallCount(int $expectedCount)

The tools the model actually invoked.

assertToolRegistered(string $tool)

That a tool is configured and therefore available to be called. Careful: the tools are collected from every toolbox of the application, not only from the agent that handled the request - so this says that a tool exists, not that this request used it. assertToolCalled() is what answers the latter.

Reading the collected data

For anything the assertions do not cover, getAiDataCollector() hands back the collector itself. Its data is collected as objects, so the input of a platform call is the MessageBag that was sent, and the metadata is a Metadata instance carrying the token usage the platform reported - there is nothing to parse:

1
2
3
4

$call = self::getAiDataCollector()->getPlatformCalls()[0];

$this->assertNotNull($call['input']->getSystemMessage());
$this->assertGreaterThan(0, $call['metadata']->get('token_usage')->getPromptTokens());

Next to getPlatformCalls(), getToolCalls() and getTools(), the collector exposes the agents, chats, message stores and stores that took part in the request.

Configuring message stores

Message stores are defined in the message_store section of your configuration:

1
2
3
4
5
6
7

ai:
    # ...
    message_store:
        cache:
            youtube:
                service: 'cache.app'
                key: 'youtube'

Configuring Chats

Chats are defined in the chat section of your configuration:

1
2
3
4
5
6

ai:
    # ...
    chat:
        youtube:
            agent: 'ai.agent.youtube'
            message_store: 'ai.message_store.cache.youtube'

Configuring speech

Add a speech key to any agent configuration to enable speech capabilities:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

# config/packages/ai.yaml
ai:
    platform:
        elevenlabs:
            api_key: '%env(ELEVEN_LABS_API_KEY)%'
        openai:
            api_key: '%env(OPENAI_API_KEY)%'

    agent:
        my_agent:
            platform: ai.platform.openai
            model: gpt-4o
            speech:
                text_to_speech_platform: 'ai.platform.elevenlabs'
                tts_model: eleven_multilingual_v2
                tts_options:
                    voice: Dslrhjl3ZpzrctukrQSN
                speech_to_text_platform: 'ai.platform.openai'
                stt_model: whisper

The bundle automatically decorates the agent with SpeechAgent. At least one of text_to_speech_platform or speech_to_text_platform must be configured. Both can be enabled independently:

• TTS only: configure text_to_speech_platform along with tts_model (and optionally tts_options) to convert the agent's text response to audio
• STT only: configure speech_to_text_platform along with stt_model (and optionally stt_options) to transcribe audio input before sending it to the agent
• STS: configure both for a full speech-to-speech pipeline

Speech is disabled by default and can be disabled when needed with speech: false:

1
2
3
4
5

ai:
    agent:
        my_agent:
            model: gpt-4o
            speech: false

Using the result

When TTS is configured, the decorated agent returns the speech result (a BinaryResult) directly. The original text from the LLM is available via the result's metadata (under the text key):

1
2
3
4
5
6

$result = $agent->call($messages);

$result->getMetadata()->get('text');    // text from the LLM
$result->getContent();                  // raw audio bytes
$result->asFile('/tmp/speech.mp3');     // save audio to file
$result->toDataUri('audio/mpeg');       // data URI for embedding in HTML

When only STT is configured (no TTS), the agent returns the same result type as the inner agent (typically a TextResult) without the text metadata.