Ai Conversational Agent Bundle Laravel Package

Getting Started

• Install with composer require odiseoteam/ai-conversational-agent-bundle. Note that v0.2.0 adds a hard dependency on symfony/ai-platform, so Composer will pull that in (and will fail if you are pinned to an incompatible version).
• This is a Symfony bundle, not a Laravel package. There is no service provider, no auto-discovery, no config/ai.php. In a Laravel app you either run it inside a Symfony kernel or wire the underlying services by hand in a service provider.
• In Symfony, enable the bundle in config/bundles.php and configure it under config/packages/. Start by reading the bundle's configuration reference — that is where provider, model, persistence and retention are all defined.
• First use case to try: a single-turn conversation with persistence on. Instantiate the agent, send a message, confirm the conversation is stored, then reload it and send a follow-up. That single loop exercises the three things that changed most in 0.2.0 (persistence, retention, adapters).
• In Laravel, the practical first step is a thin wrapper service: bind the agent in a service provider, put credentials in config/services.php, and call it from a controller or queued job.

Implementation Patterns

Agent as an injected service. Treat the agent as a singleton resolved from the container, not something you new per request. Configuration (provider, model, thinking effort) is validated once at agent start in 0.2.0, so a misconfigured agent fails fast at resolution time rather than mid-conversation.

Persistence + retention as a pair. Persistence stores conversations; retention decides how long they live. Set retention deliberately — a TTL plus a max-messages-per-conversation cap is the usual combination. For chat UIs you typically want "keep the last N turns for context, prune the rest on a schedule."

Provider adapters. 0.2.0 introduced the adapter layer and shipped the OpenAI adapter alongside the existing provider. Model/provider selection is configuration, not code — write your calling code against the agent interface and swap adapters in config so you can move providers without touching call sites.

Prompt caching is opt-in and currently off. The bundle asks the host for cache_retention: none, meaning repeated system prompts are re-billed every call. If you have a long, static system prompt, budget for it or keep the prompt lean.

Reasoning effort. Thinking effort is checked when the agent starts. Use it only with reasoning-capable models; for standard chat models, leave it unset and rely on the default.

Evals as a CI job. Eval runs now continue past a failing case instead of aborting, which makes them useful as a regression suite: run the whole set, then read the report. In Laravel, schedule evals as a queued job and assert on the report artifact, not on the process exit code alone.

Localization. The 0.2.0 refactor moved translation handling around. If you had custom message overrides, re-verify your keys after upgrading rather than assuming they still resolve.

Gotchas and Tips

• symfony/ai-platform is now required. This is the most likely upgrade blocker. Check your lock file before bumping; a transitive conflict here will block the whole upgrade.
• Persistence needs schema. Enabling persistence without running the bundle's migrations (or mapping its entities) fails at the first write, not at boot. Do the migration step before your first conversation.
• Retention defaults are permissive. An unset retention policy means conversations accumulate indefinitely. Set it on day one — retrofitting a prune job onto a bloated table is unpleasant.
• cache_retention: none is silent. There is no warning that caching is disabled; you will only notice it on the bill. Instrument token usage per call if cost matters.
• Thinking effort on the wrong model. Configure it against a non-reasoning model and you get either an error at agent start or a silently ignored setting, depending on the adapter. Pin the model explicitly next to the effort setting so the pair is obvious.
• Evals swallowing failures. "Keep the run going when a case breaks" is good for coverage and bad for CI gating — a green pipeline no longer implies green evals. Parse the report.
• Adapters are not behaviourally identical. Message formatting, tool-calling and system-prompt handling differ per provider. Smoke-test your prompts against each adapter you enable rather than assuming a drop-in swap.
• It is 0.x. Pin exact versions in composer.json and read the changelog before every minor bump; the 0.1.0 → 0.2.0 jump already reshuffled folder layout, localization and provider handling.
• Laravel friction is real. No facades, no config publishing, no queue integration out of the box. Budget a small adapter layer rather than expecting the bundle to feel native.