Download the PHP package webwerkwien/contao-ai-backend-bundle without Composer

contao-ai-backend-bundle

In-browser AI agent for the Contao 5 and 6 backend. Editors and admins chat with a Claude (or GPT) agent that can read and modify Contao content through a curated set of tools — no SSH, no CLI. Plus an HTTPS bridge endpoint that lets contao-ai-cli trigger bulk macro operations from the terminal without switching to the browser.

Pre-1.0. Runs in production on the author's own installations. Interfaces — tool signatures, bridge JSON, DCA fields — still change between minor versions, and symfony/ai is itself pre-1.0. Read the changelog before updating.

You bring your own LLM API key. Each backend user must provide an Anthropic or OpenAI key in their profile (System → Users → AI agent). Without a key, the chat module is disabled for that user. The bundle does not ship with a service-level key.

The contao-ai ecosystem

What it does

contao-ai-backend-bundle is the browser client for AI-powered Contao content management. Authentication, session, CSRF and permissions ride on top of the existing Contao backend — each backend user brings their own API key. A second entry point exposes the macro tools (record_clone, record_rewrite) over HTTPS for the contao-ai-cli bridge workflow.

Requirements

• PHP ^8.2
• Contao ^5.3

Also installed: webwerkwien/contao-ai-core-bundle and symfony/ai-*.

Installation

The Contao Manager auto-discovers the bundle via the contao-manager-plugin entry.

Per-user setup

In System → Users → (user), these fields appear in the AI agent legend:

Providers

Installed with the bundle:

To add another, install its package — that is the whole procedure:

The list in the Platform select is derived from the installed symfony/ai-*-platform packages, read from each bridge's own factory signature. Nothing to register, no code to change. composer suggests lists further ones.

Grant the AI Chat module under "Allowed modules" to enable the chat entry. The CLI bridge does not require the module mount but still respects the same per-record permission voters.

Available tools

Permissions inherit from Contao's existing module rights. Admins see everything. Non-admins only see tools whose backing module they are allowed to use, and delete sub-tools are admin-only regardless of module membership. Per-record checks (page hierarchy, news-archive access, article parent-page, FAQ category access) run via Symfony voters (ContaoCorePermissions::USER_CAN_*) before each call.

CLI bridge — terminal access for admins and agents

Editors use the chat module above. Developers and admins live in the terminal — and switching to a browser for bulk LLM jobs ("translate all news in archive 5", "clone this page tree with all children") is a workflow break.

The bundle exposes a HTTPS endpoint at POST /_ai_cli/macro that the contao-ai-cli Python client (contao-ai-cli bridge ...) calls with a Bearer token. The macro tools (record_clone, record_rewrite) execute server-side with the full voter pipeline + atomic tl_version audit — same code path as the chat module, just a different transport.

Why /_ai_cli/macro and not /contao/...?

The contao_backend firewall would 302-redirect any unauthenticated request to /contao/login before our Bearer auth runs. Routing the bridge outside /contao/* lets it fall through to the frontend (anonymous) firewall, where the controller does its own auth.

Security model

Two things decide how you deploy this. Everything else is implementation detail and lives in the changelog.

⚠️ API keys are stored in plain text in tl_user.ai_api_key — Contao 5 has no field encryption. Treat read access to the database as equivalent to holding every key in it, and grant it accordingly.

⚠️ Content the agent reads can try to instruct it. Tool output is wrapped, truncated and declared as untrusted data, destructive operations need a real user turn, and an injected instruction can never exceed the rights of the user whose session is running — but none of that is isolation. A change made this way stays within that user's rights and is versioned in tl_version under their name, so it is visible and revertible. Be deliberate about pointing the agent at tables that take input from outside the editorial team: form submissions, comments, imported feeds.

Beyond that: the agent acts as the logged-in backend user and re-checks that user's permissions per record, *_delete tools are admin-only, write tools accept only an explicit allow-list of fields, and every write is attributed to the acting user in tl_version and the system log.

Streaming

Chat responses arrive as text/event-stream (SSE-style frames over fetch-ReadableStream, since EventSource cannot POST). Events:

• start — model id
• message — content chunk (currently emitted once per response; chunked streaming will be added when the underlying platform bridge supports it)
• done — successful completion
• error — kind: access_denied | tool_refused | tool_failed | agent_failed

The four error kinds split into two groups, and the split matters:

The first two are answers and carry no report — offering to report them would train users to send noise and bury the two cases that are genuinely defects. The last two carry report, a ready-to-forward Markdown block.

Who sees what is decided server-side, at the moment the event is emitted. An admin receives the full report including the (masked) exception message; anyone else receives the summary with the message stripped, so the H-6 guarantee — the raw exception never reaches the client — keeps holding unchanged for the audience it was written for. The browser only expands the block; it never fetches more.

Development

License

MIT — see LICENSE.

This software is provided "as is", without warranty of any kind. The authors accept no liability for any damages arising from its use.