AI Bundle Fast Track

The AI Bundle is the Symfony integration for the Platform, Agent, Store, and Chat components. Instead of wiring services by hand, you describe platforms, agents, tools, and stores in config/packages/ai.yaml and the bundle registers everything in the container for you. This guide is a fast track from an empty configuration to an agent that answers questions over your own documents. Each step links to a dedicated cookbook article when you want to go deeper.

Prerequisites

A Symfony application
An API key for at least one AI platform (e.g. OPENAI_API_KEY)

Step 1: Install the Bundle

        1
        $ composer require symfony/ai-bundle
    

With Symfony Flex the bundle is registered automatically and an empty config/packages/ai.yaml is created.

Step 2: Configure One or More Platforms

A platform is the connection to an AI provider. Define each provider under the platform key; every entry becomes a service named ai.platform.<name>:

        1
2
3
4
5
        # config/packages/ai.yaml
ai:
    platform:
        openai:
            api_key: '%env(OPENAI_API_KEY)%'
    

You can configure several providers side by side and pick one per agent later:

        1
2
3
4
5
6
7
8
        ai:
    platform:
        openai:
            api_key: '%env(OPENAI_API_KEY)%'
        anthropic:
            api_key: '%env(ANTHROPIC_API_KEY)%'
        gemini:
            api_key: '%env(GEMINI_API_KEY)%'
    

This registers ai.platform.openai, ai.platform.anthropic, and ai.platform.gemini. See the AI Bundle reference for the full list of supported providers (Azure, Bedrock, VertexAI, Ollama, Perplexity, and more) and for the cached and generic platform decorators.

Step 3: Configure an Agent

An agent combines a platform, a model, and optionally tools and a system prompt. The simplest agent only needs a model — it uses the first configured platform by default:

        1
2
3
4
5
6
7
        ai:
    platform:
        openai:
            api_key: '%env(OPENAI_API_KEY)%'
    agent:
        default:
            model: 'gpt-4o-mini'
    

Each agent is registered as a service. With a single agent you can inject AgentInterface directly:

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
        use Symfony\AI\Agent\AgentInterface;
use Symfony\AI\Platform\Message\Message;
use Symfony\AI\Platform\Message\MessageBag;

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

    public function ask(string $question): string
    {
        $messages = new MessageBag(Message::ofUser($question));

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

When you define multiple agents, point each one at the platform it should use and inject a specific one with the ai.agent.<name> service id:

        1
2
3
4
5
6
7
8
        ai:
    agent:
        assistant:
            platform: 'ai.platform.openai'
            model: 'gpt-4o-mini'
        researcher:
            platform: 'ai.platform.anthropic'
            model: 'claude-3-7-sonnet-latest'
    

        1
2
3
4
5
6
7
8
        use Symfony\AI\Agent\AgentInterface;
use Symfony\Component\DependencyInjection\Attribute\Autowire;

public function __construct(
    #[Autowire(service: 'ai.agent.researcher')]
    private AgentInterface $researcher,
) {
}
    

You can also chat with any configured agent straight from the console:

        1
        $ php bin/console ai:agent:call assistant
    

Step 4: Add a System Prompt

The system prompt shapes how the agent behaves. For simple cases pass a string:

        1
2
3
4
5
        ai:
    agent:
        assistant:
            model: 'gpt-4o-mini'
            prompt: 'You are a concise assistant for a Symfony application.'
    

Use the array form for more control — for example, to append the available tool definitions to the prompt, or to load a long prompt from a file:

        1
2
3
4
5
6
7
8
9
10
11
        ai:
    agent:
        assistant:
            model: 'gpt-4o-mini'
            prompt:
                text: 'You are a concise assistant for a Symfony application.'
                include_tools: true
        reviewer:
            model: 'gpt-4o-mini'
            prompt:
                file: '%kernel.project_dir%/prompts/reviewer.md'
    

The array form also supports translated prompts via enable_translation and translation_domain. See the AI Bundle reference for all prompt options.

Step 5: Give the Agent Tools

Tools let an agent call your PHP code. Any service carrying the AsTool attribute is auto-registered in the tool registry, but each agent has to opt in to the tools it should use:

        1
2
3
4
5
6
7
8
9
10
        use Symfony\AI\Agent\Toolbox\Attribute\AsTool;

#[AsTool('company_name', 'Provides the name of your company')]
final class CompanyName
{
    public function __invoke(): string
    {
        return 'ACME Corp.';
    }
}
    

To define which tools an agent receives, list them explicitly — or set tools: true to inject all registered tools. Without the tools option, the agent gets no tools at all:

        1
2
3
4
5
6
        ai:
    agent:
        assistant:
            model: 'gpt-4o-mini'
            tools:
                - 'Symfony\AI\Agent\Bridge\SimilaritySearch\SimilaritySearch'
    

Several built-in tools ship as standalone packages with Flex recipes, so installing them is enough to make them available:

        1
2
3
        $ composer require symfony/ai-brave-tool
$ composer require symfony/ai-wikipedia-tool
$ composer require symfony/ai-open-meteo-tool
    

For writing and securing your own tools, see Tool Calling with Agents, Dynamic Toolbox for Flexible Tools, and Human-in-the-Loop Tool Confirmation.

Step 6: Configure a Store, Vectorizer, and Indexer

To let the agent answer over your own data, you need a vector store, a vectorizer that turns text into embeddings, and an indexer that fills the store. All three are configured in YAML:

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
        ai:
    platform:
        openai:
            api_key: '%env(OPENAI_API_KEY)%'

    store:
        chromadb:
            knowledge_base:
                collection: 'docs'

    vectorizer:
        embeddings:
            platform: 'ai.platform.openai'
            model: 'text-embedding-3-small'

    indexer:
        docs:
            loader: 'Symfony\AI\Store\Document\Loader\TextFileLoader'
            vectorizer: 'ai.vectorizer.embeddings'
            store: 'ai.store.chromadb.knowledge_base'
    

For local experiments you can swap ChromaDB for the in-memory store. Prepare the store infrastructure and run the indexer from the console:

        1
2
        $ php bin/console ai:store:setup chromadb.knowledge_base
$ php bin/console ai:store:index docs --source=/path/to/document.txt
    

An indexer without a loader becomes a DocumentIndexer that you feed documents directly in PHP by injecting IndexerInterface. See Implementing Retrieval Augmented Generation (RAG) for the full indexing pipeline, chunking, and metadata handling.

Step 7: Search the Store with the Agent

The SimilaritySearch tool runs a semantic search over a store and feeds the matching documents back to the model. It needs a retriever, which pairs a vectorizer with a store:

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
        ai:
    retriever:
        docs:
            vectorizer: 'ai.vectorizer.embeddings'
            store: 'ai.store.chromadb.knowledge_base'

    agent:
        assistant:
            model: 'gpt-4o-mini'
            prompt:
                text: 'Answer questions using only the SimilaritySearch tool. If you cannot find relevant information, say so.'
            tools:
                - 'Symfony\AI\Agent\Bridge\SimilaritySearch\SimilaritySearch'

services:
    Symfony\AI\Agent\Bridge\SimilaritySearch\SimilaritySearch:
        $retriever: '@ai.retriever.docs'
    

Now calling the agent with a user question triggers a similarity search automatically, and the answer is grounded in your indexed documents. You can also use a retriever on its own by injecting RetrieverInterface for plain semantic search without an agent.

Putting It Together

A complete fast-track configuration looks like this:

        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
        # config/packages/ai.yaml
ai:
    platform:
        openai:
            api_key: '%env(OPENAI_API_KEY)%'

    store:
        chromadb:
            knowledge_base:
                collection: 'docs'

    vectorizer:
        embeddings:
            platform: 'ai.platform.openai'
            model: 'text-embedding-3-small'

    indexer:
        docs:
            loader: 'Symfony\AI\Store\Document\Loader\TextFileLoader'
            vectorizer: 'ai.vectorizer.embeddings'
            store: 'ai.store.chromadb.knowledge_base'

    retriever:
        docs:
            vectorizer: 'ai.vectorizer.embeddings'
            store: 'ai.store.chromadb.knowledge_base'

    agent:
        assistant:
            model: 'gpt-4o-mini'
            prompt:
                text: 'Answer questions using only the SimilaritySearch tool. If you cannot find relevant information, say so.'
            tools:
                - 'Symfony\AI\Agent\Bridge\SimilaritySearch\SimilaritySearch'
    

From here you can grow in any direction: add more platforms and agents, route between them with multi-agent orchestration, persist conversations with message stores and chats, or expose your tools over MCP.

Learn More

AI Bundle - Full AI Bundle configuration reference
Tool Calling with Agents - Let agents call your PHP functions
Implementing Retrieval Augmented Generation (RAG) - Build a complete RAG pipeline
Multi-Agent Orchestration - Route requests to specialist agents
Building a Chatbot with Memory - Persist conversation history
Build an MCP Server - Expose your tools over MCP

This work, including the code samples, is licensed under a Creative Commons BY-SA 3.0 license.

TOC

Version