Pimcore Agent Bundle
AI-powered chat agents for Pimcore Studio with human-in-the-loop write control. Agents search, read, and propose changes to data objects, assets, documents, and tags through interactive chat. Start here → docs/01_Getting_Started/ for core concepts.
Features
- Multi-agent system - Agents with a per-agent model/provider, tools, skills, and permissions, configured via YAML or Pimcore Studio. Users switch agents mid-conversation without losing history.
- MCP tool integration - 35+ PHP tools spanning data objects, assets, documents, tags, and agent templates, grouped by read / propose (HITL) / direct-write access. Extensible via Symfony service tags; supports meta-tool discovery, third-party MCP servers, and access from external MCP clients.
- Human-in-the-loop proposals - Propose / review / approve pipeline for every write operation. Interactive diff modals, batch approval, and refinement. No direct writes unless explicitly configured.
- Interactive input -
ask_usermid-turn questions andpauseAfter"continue or stop" checkpoints replace hard timeouts with interactive decisions. - Rich chat widgets - Eight interactive React components rendered in the chat: proposal cards, data tables, element links, agent-switch suggestions, and more.
- Background task execution - Agent tasks run independently of the browser connection with SSE streaming, reconnection support, and cancel capability.
- Real-time multi-client sync - Live turn delivery to every open tab and device via Studio's Mercure per-user topic; PHP remains the durable record, so a reload always reconstructs the session.
- File attachments - Upload files into a session; agents read them through session-scoped, read-only staging.
- Document & areabrick schema for LLMs - Twig-template AST analysis combined with co-located JSON example fixtures lets agents read, edit, and create Pimcore documents and areabricks in one shot. Third-party editable types are picked up automatically from Pimcore's registry; project-specific bricks ship example fixtures alongside their templates.
- Template generation - Agents generate, validate, and HITL-propose Twig page/snippet/partial templates from a sandboxed private root.
- Field hint system - Provider-based format hints for all Pimcore data types. Agents receive
editableDataFormatand metadata for every field, enabling correct data composition. - Skills - Reusable Markdown instruction files that teach agents domain-specific workflows (PQL search, proposal flows, data-import patterns).
- Tool security - SDK tool control with path sandboxing, system-denied tools, and agent-configurable opt-in.
- Session storage - Database-backed persistence via Pimcore. Sessions, messages, proposals, and statuses survive server restarts.
Documentation
Getting Started
| Page | Description |
|---|---|
| Installation | Bundle installation, Docker, Nginx, security, env vars |
| Core Concepts | Glossary - read this once before the rest |
Architecture
Internals - how the system works end-to-end.
| Page | Description |
|---|---|
| Agent Framework | Copilot SDK integration, adapters, LLM auth modes, model configuration |
| Communication Flows | The system map - every runtime flow (chat/SSE, MCP, persistence, config export, Mercure, LLM) and the credential each uses |
| Request Lifecycle | End-to-end chat request, TaskRunner, the three event sinks, SSE streaming, reconnection |
| Authentication | Session cookie + identity cache, the pmcp_ bearer scope, admin bearer token, per-provider LLM auth, rate limits, audit log |
| MCP Integration | Internal vs external servers, the meta-tool, bearer + session-id forwarding, token lifecycle |
| Session Storage | Pimcore DB persistence model |
| Tool Security | Pre-tool-use hook, path sandboxing (mechanism) |
| Configuration System | Three-layer merge, export endpoint, reload paths, skill materialization |
| Field Hint System | How the agent learns the correct JSON shape for every Pimcore field type |
| Document Schema | How get_document_schema / get_area_brick work - AST analyzer + co-located example fixtures + the <index> placeholder convention |
| File Staging | The read-only file-set primitive: developer-configured sets, staging, the roots/denylist model |
| Agent Template Generation | The Twig template write path: private root + namespace, validator/sandbox, test-render, drift-guard lint |
| Real-time Sync | Live multi-client chat via Mercure + GlobalMessageBus, PHP as the record, catch-up/reconnect model |
Features
What the product does, for operators and end users.
| Page | Description |
|---|---|
| Agents and Switching | Shipped presets + how mid-conversation switching feels |
| Rich Chat Widgets | Canonical catalog of the eight built-in widgets |
| HITL Proposals | Propose → review → resolve workflow |
| Interactive Input | ask_user questions + pauseAfter checkpoints |
| File Attachments | Upload flow, staging, session-scoped file access |
| Agent Templates | Generate, validate, and HITL-propose Twig page/snippet/partial templates |
| Built-in Pimcore MCP Servers | The built-in tool-group catalog + how to use it from the built-in Pimcore Agent or an external MCP client |
Configuration
Field-by-field reference.
| Page | Description |
|---|---|
| Agents | YAML schema, editing in Studio, pause thresholds, model validation, hot reload |
| Skills | Skill file format, discovery, user vs bundle skills |
| MCP Servers | Configuring an agent's MCP access - direct vs meta-tool, env interpolation, TTL knob |
| Tool Security Reference | SDK tool catalog, defaults, auto-derived permissions, path sandboxing rules |
| Environment Variables | Complete env-var reference, LLM adapter modes, BYOK limitations |
| Shipping Presets | Ship agents / skills from your own bundle (hard vs optional dependency) |
| File Staging | Configuring the read-only file sets agents can stage |
| Agent Templates | Configuration for agent template generation |
| Provider Compatibility | The localhost compatibility shim for strict LLM providers |
| Inference Providers | Defining LLM backends: auth, endpoint, default model, per-agent selection |
Inference
Choosing and evaluating the LLM behind each agent turn.
| Page | Description |
|---|---|
| Model Requirements | What each agent needs from a model, by task complexity |
| Model Evaluation | Results of evaluating models against the bundle's real agent tasks |
Extending
| Page | Description |
|---|---|
| Custom MCP Tools | Add tools via PHP service tags, group management |
| Custom Rich Chat Widgets | YAML definition + React renderer |
| Custom Proposal Types | Add HITL-controlled writes with approval flows |
| Custom Field Hint Providers | Format hints for custom Pimcore data types |
| Template Examples | JSON example fixtures + dev-time SKILL + CLI helpers for areabricks and document templates |
Operations
| Page | Description |
|---|---|
| Development | Build commands, testing, linting, Docker dev override |
| Troubleshooting | Symptoms → causes → diagnostic commands |