README

Introduction

A vertical-agnostic core for conversational agents in Symfony: the turn loop, tool execution, gates, sessions, streaming, memory, budgets and evals. Verticals (a shopping assistant, an institutional assistant) are built on top of it as capabilities.

Tip

Based on Anthropic's guide to building shopping and merchant agents, The anatomy of effective commerce agents.

Features

✅ Streaming - Model rounds, tool calls and UI components sent as server-sent events
✅ Tool validation - JSON-schema arguments, server-issued ids only and forced lookups
✅ Fencing - Site content, tool results and memory reach the model as data, not instructions
✅ Memory - Facts extracted after the turn by a cheaper model, without identifiers
✅ Budgets - Spend caps per session, client and day, rate limits and a cost ledger
✅ Rules and knowledge - House rules in the cached prompt; policies and guides searched by section
✅ Models - Claude or OpenAI per role through Symfony AI, or your own adapter
✅ Evals - JSON cases graded by code and by a judge, with trials and replays

Note

This bundle is the core of the shopping agent we're building for Sylius. Follow the devlog: Why we're building a shopping agent for Sylius

Getting Started

Install it in 4 steps ⚡

✅ Require the bundle
✅ Connect Claude or OpenAI through Symfony AI
✅ Import the routes and map the Doctrine entities
✅ Register a capability with your tools

👉 Follow the installation guide

Quick Example

composer require odiseoteam/ai-conversational-agent-bundle symfony/ai-bundle symfony/ai-anthropic-platform

A capability gives the agent its tools. Any autoconfigured service implementing CapabilityInterface is picked up:

use Odiseo\AiConversationalAgentBundle\Capability\CapabilityInterface;
use Odiseo\AiConversationalAgentBundle\Capability\ToolContext;
use Odiseo\AiConversationalAgentBundle\Capability\ToolSpec;
use Odiseo\AiConversationalAgentBundle\Streaming\ToolOutcome;

final class OpeningHoursCapability implements CapabilityInterface
{
    public function name(): string
    {
        return 'store.hours';
    }

    public function tools(): array
    {
        return [new ToolSpec('get_opening_hours', "Today's opening hours.", [
            'type' => 'object',
            'properties' => [],
            'additionalProperties' => false,
        ])];
    }

    public function promptFragments(): array { return []; }
    public function groundingRules(): array { return []; }
    public function components(): array { return []; }

    public function execute(string $tool, array $input, ToolContext $context): ToolOutcome
    {
        return new ToolOutcome('Open today from 9:00 to 18:00.');
    }
}

Then talk to it from the terminal:

bin/console agent:chat

Important

Set cache_retention: none on the Anthropic platform. The bundle places its own cache breakpoints, and the bridge's default adds more on top that the next rounds cannot read. See Installation.

Documentation

📦 Installation - The bundle, the model provider, the routes and the Doctrine entities
🧩 Concepts and extension points - Capabilities, gates, sessions and every port a host can replace
🤖 Models and providers - A model per role, prices, capabilities and your own adapter
📏 Rules - The organisation's house rules, their order, caps and sources
📚 Knowledge - Markdown files, the lexical search, other sources and the guide index
⚙️ Runtime changes - Settings, API keys, spend scopes and versions edited without a deploy
🗂️ Logging and retention - The conversational_agent channel and agent:prune
🧪 Evals - Cases, graders, trials and replays with agent:eval
🤝 Contributing - Running the checks and the suite on a real database

Compatibility

Bundle	PHP	Symfony	Database	Model
`0.x`	8.2 · 8.3 · 8.4	7.3 · 7.4 · 8.x	Any Doctrine ORM platform; CI covers SQLite, MySQL and PostgreSQL	Claude or OpenAI, through Symfony AI; or your own `ModelProviderInterface`

The bundle is in 0.x: minor versions may break the API until 1.0.

Professional Support

This bundle is maintained by Odiseo. Want an agent built on it, or help with any Symfony or Sylius project?

🎬 Live walkthrough - A live tour of the bundle and what runs on it
🛠️ Symfony and Sylius development - Help building your own agent or any other project
🔌 Sylius plugins - Browse all our plugins

License

MIT.

odiseoteam / ai-conversational-agent-bundle

Package info

Security

Statistics