Symfony AI: when artificial intelligence becomes native to your applications

Symfony AI is a set of components and bundles, launched by the Symfony project in July 2025, for bringing AI models into a PHP application: a unified way to call providers (OpenAI, Anthropic, Mistral, Gemini, self-hosted models…), agents that can call your business tools, document search (RAG) and the MCP protocol. As of September 2026, it is at version 0.14 and still experimental: usable in production, as long as you treat it as a dependency that is still moving.

In this article, we cover what it includes, what its status implies, a complete code example and where MCP fits. It is the basis of the advice we give clients who have a Symfony application and want to add AI to it.

What Symfony AI includes in 2026

Symfony AI lives in its own repository (symfony/ai), separate from the framework, so it can keep pace with the AI ecosystem. It builds on the work of the PHP-LLM organization and now has more than 90 packages. A dedicated team, the Symfony AI Core Team, maintains it.

The main benefit is the Platform layer: your code talks to an interface, and the provider is chosen in configuration. Moving from Mistral to Anthropic, or from a public API to a self-hosted model, means changing a few lines of YAML, then checking on your evaluation datasets that answer quality holds up. Prompts often need retuning from one model to another.

Experimental status: what it means

The first tagged release, 0.1.0, shipped in December 2025. Since then, a minor version has come out roughly every month (0.14 at the end of September 2026), each with a migration guide. The components are flagged experimental: they are not covered by Symfony’s backward compatibility promise. In other words, maintenance is not “handled by the framework”: your team has to keep up with the changes.

Our rules for using it in production:

• Pin versions: a ^0.14 constraint in Composer locks the minor version. We only upgrade after reading the UPGRADE.md file.
• Isolate AI behind your own interfaces (for example a SupportAssistant), so the rest of the application does not depend on the Symfony AI API.
• Test: unit tests for tools, integration tests for the agent with a mocked model, and evaluation datasets built from real questions to measure quality every time the model or version changes.
• Track costs: the AI Bundle reports token usage in each response’s metadata. Feed it into your monitoring.

Example: a support agent that checks your orders

The most common case: an assistant that answers customers from real data without giving them access to the database. Installation with Mistral as the provider:

composer require symfony/ai-bundle symfony/ai-agent symfony/ai-mistral-platform

The configuration declares the provider, then an agent with its system prompt and tools. In recent versions, tools are explicit: an agent only has access to the tools it lists.

# config/packages/ai.yaml
ai:
    platform:
        mistral:
            api_key: '%env(MISTRAL_API_KEY)%'
    agent:
        support:
            platform: 'ai.platform.mistral'
            model: 'mistral-small-latest'
            prompt:
                text: 'You are the customer support assistant. Answer only from the information returned by your tools. If you do not know, say so.'
            tools:
                - 'App\Ai\Tool\OrderStatus'

The tool is an ordinary PHP class. The key point: your code enforces permissions. The model never sees the database; it only receives what the tool returns, here the orders of the logged-in user.

namespace App\Ai\Tool;

use App\Repository\OrderRepository;
use Symfony\AI\Agent\Toolbox\Attribute\AsTool;
use Symfony\Bundle\SecurityBundle\Security;

#[AsTool('order_status', 'Returns the status of an order placed by the logged-in customer, from its reference')]
final readonly class OrderStatus
{
    public function __construct(
        private OrderRepository $orders,
        private Security $security,
    ) {
    }

    /**
     * @param string $reference Order reference, for example ORD-2026-0042
     */
    public function __invoke(string $reference): array
    {
        $order = $this->orders->findOneBy([
            'reference' => $reference,
            'customer' => $this->security->getUser(),
        ]);

        if (null === $order) {
            return ['found' => false];
        }

        return [
            'found' => true,
            'status' => $order->getStatus()->value,
            'shippedAt' => $order->getShippedAt()?->format('Y-m-d'),
        ];
    }
}

Finally, a service in your application calls the agent:

namespace App\Support;

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

final readonly class SupportAssistant
{
    public function __construct(
        #[Autowire(service: 'ai.agent.support')]
        private AgentInterface $agent,
    ) {
    }

    public function answer(string $question): string
    {
        $result = $this->agent->call(new MessageBag(Message::ofUser($question)));

        return $result->getContent();
    }
}

When a customer asks “Where is my order ORD-2026-0042?”, the model decides to call order_status, the agent runs the PHP method and sends the result back to the model, which writes the answer. The tool description and the @param comment are used to generate the schema the model reads: they deserve the same care as API documentation.

For a real service, add: human confirmation before any action that changes data, usage limits, logging of tool calls, and test questions that cover the “I don’t know” cases. To answer from your documentation, the Store component adds document search: that is the principle of RAG.

MCP: what it is for, and what it is not for

The Model Context Protocol (MCP) is an open protocol that standardizes how an AI client (an assistant such as Claude or ChatGPT, an IDE, your own agents) discovers and calls the tools, resources and prompts exposed by an MCP server. It is not a way to switch model providers: that is the job of the Platform layer.

The MCP Bundle covers two uses:

1. Exposing your application as an MCP server, over STDIO or HTTP. Your teams or your customers can then query your application from their AI assistant.
2. Consuming existing MCP servers from your agents: in the agent configuration, an mcp_server entry adds a remote server’s tools to the agent’s own.

An MCP tool is also declared with an attribute:

namespace App\Mcp;

use App\Repository\ProductRepository;
use Mcp\Capability\Attribute\McpTool;
use Mcp\Capability\Attribute\Schema;

final class ProductStockTool
{
    public function __construct(private ProductRepository $products)
    {
    }

    #[McpTool(name: 'product-stock', description: 'Available stock for a product reference')]
    public function __invoke(
        #[Schema(description: 'Product reference (SKU)')]
        string $sku,
    ): array {
        $product = $this->products->findOneBy(['sku' => $sku]);

        return ['sku' => $sku, 'available' => $product?->getStock() ?? 0];
    }
}

An MCP server exposes actions on your information system: treat it like a public API, with authentication, per-tool permissions and logging. That is what we put in place in our MCP server projects.

When to choose Symfony AI, Neuron AI or a provider SDK

• Symfony AI: your application runs on Symfony, you want to be able to switch providers, you need tools, RAG or MCP, and you accept keeping up with upgrades.
• Neuron AI: a PHP agent framework independent of the web framework, useful if your application is not built on Symfony or if you already use it.
• The provider’s SDK: a simple call (summary, classification, extraction) to a single provider. Fewer dependencies, but switching providers costs more.

Whatever you choose, two rules stay the same: AI stays behind an interface in your code, and quality is measured with evaluation datasets, not by impression.

What to plan for before you start

Symfony AI cuts down integration code. It does not replace the work that keeps an AI service reliable in production:

• Clean data and clear permissions: an agent is only as reliable as the tools and documents you give it.
• Continuous evaluation: an agent does not get better on its own by answering questions. It improves when the team adjusts prompts, tools, data or model, based on user feedback and test datasets.
• Cost control: cache responses where relevant, use a lightweight model for simple tasks and a more capable one for the rest, fail over automatically to a second provider during an outage, track tokens.
• Confidentiality: with the API and enterprise offerings of the major providers, your data is not used for training by default. If it must not leave your infrastructure, Symfony AI can call a self-hosted model.

How we support you

We design, build and maintain business applications and AI features, including on Symfony.

On a Symfony AI project, our tech lead owns the architecture, runs code reviews and remains your technical point of contact. Our teams apply the same standard as on the rest of the application: systematic code review, automated tests, continuous integration, secrets management, separate environments, and for AI, evaluation datasets and quality and cost monitoring. Your code, your access, your API keys: everything stays yours.

Depending on what you need:

• add an assistant or an agent to your customer service or internal tools: AI agents and chatbots;
• build smart search, extraction or summarization into your product: AI features for your product;
• make your application available to AI assistants: MCP server development;
• take a prototype to production: AI POC to production;
• modernize or extend the application itself: Symfony development.

Do you have a Symfony application and an AI use case in mind? Let’s talk: we will look at whether Symfony AI is the right tool, and how to integrate it cleanly.

FAQ