Core Concepts

Every page in these docs uses the terms below with the meanings defined here. If a concept is unfamiliar, return to this page; if a definition on another page seems to contradict this one, this page wins.

Runtime

Agent

A named configuration that tells the LLM how to behave. An agent bundles: a system message, a model, a set of skills, a set of MCP tool groups, a set of widgets, and policy knobs (pauseAfter, tool overrides). An agent is not a running process - it is a config document that the single per-user SDK session adopts. Switching agents mid-conversation replaces the config but preserves the conversation history.

Session

One user's ongoing conversation with the bundle. A session persists to the Pimcore database (sessions, messages, proposals, statuses) and survives server restarts, browser reloads, and agent switches. A user has many sessions; a session has exactly one current agent at any moment.

Task

One agent response to one user message, run by an in-process task runner independently of the HTTP connection that started it. A task emits a stream of events (text, tool calls, tool results, widgets, completion) buffered in memory with monotonic sequence numbers. A browser can disconnect and reconnect to a live task by passing the last-seen sequence number; a task can be cancelled at any time.

Adapter

The layer between the agent-server and the LLM backend. Two exist:

• Copilot adapter - uses @github/copilot-sdk. The production path. Supports agent switching via resumeSession(id, newConfig).
• Dummy adapter - scripted responses for tests. Never reaches a real LLM.

Inference provider

A named configuration block under pimcore_agent.inference.providers that defines how the agent-server reaches an LLM backend: authentication mode, credentials, endpoint, default model, title model, and (for byok providers) an explicit list of available models with per-model limits. Each agent selects a provider by name; the agent-server resolves the effective model and auth credentials at session-creation time. See Configuration → Inference Providers.

BYOK mode

"Bring Your Own Key". When an inference provider uses auth_mode: byok, the Copilot SDK is pointed at an Anthropic, OpenAI, or compatible key defined in the provider block instead of GitHub's managed backend. BYOK has two practical consequences: (1) no streaming message_delta events from Anthropic - responses arrive as a single assistant.message (the bundle synthesises deltas so the UI still streams); (2) the title model must belong to the same provider as the main model.

Tools

SDK tool

A tool built into the Copilot SDK itself (e.g. read_file, grep, web_fetch, web_search, ask_user). Distinct from MCP tools. Controlled by a security hook in the bundle that denies some tools outright, sandboxes file-access tools to session scratch directories, and requires per-agent opt-in for the rest.

MCP server

A server that exposes tools over the Model Context Protocol. Two kinds:

• Internal MCP servers - authored in PHP inside Pimcore bundles, served at /pimcore-mcp/*. Authenticated with a per-chat-session MCP access token (Authorization: Bearer pmcp_…), so they inherit the chat initiator's Pimcore permissions automatically.
• External MCP servers - third-party servers configured by URL or command. The bundle does not authenticate them for you.

Meta-tool

A generic three-tool wrapper (discover / describe / execute) that the agent-server presents to the LLM instead of exposing every MCP tool's raw schema. Main benefit: shipping dozens of full tool schemas to every turn burns tokens. Configured via pimcoreMetaGroups in an agent's YAML.

Tool group

A named bucket of MCP tools: data-objects, assets, tags, etc. An agent's YAML enables tool groups, not individual tools. The bundle ships 14 groups with 35+ tools - for example search_data_objects, get_asset, assign_tag. Custom bundles can contribute more.

Interaction

Rich Chat Widget

An interactive React component rendered inline in the chat. The LLM triggers a widget by calling a tool name reserved for it (e.g. show_asset_preview, pimcore_open_element). The backend intercepts the tool call, emits an SSE event, and the frontend renders the widget rather than treating the call as a regular tool execution.

Proposal

A pending write operation suggested by the agent that the user must explicitly act on before it is applied. Three kinds ship today: single data-object edit, multi-object overview, tag assignment. A proposal has a lifecycle: propose → review → resolve (approve / reject / refine). A proposal is persisted in the database, so a user can close the browser and return to it later.

HITL

"Human-in-the-Loop." The bundle's policy that no write operation to Pimcore data happens without explicit user approval. Every write path goes through a proposal. There is no "auto-apply" escape hatch; a proposal cannot be bypassed. But agents can be configured with direct write mcp tools allowing LLM to directly execute changes without a proposal, if you want that.

Skill

A reusable Markdown instruction file - SKILL.md with YAML frontmatter - that teaches an agent a domain workflow (e.g. PQL search, proposal review, data-import orchestration). Skills are attached to agents by name. A skill can ship referenced resources in its folder.

Field hint

Structured format metadata attached to every data-object field. Each hint describes what shape a value should take: date format, enum values, child fields of an object, constraints. The agent receives hints alongside field values so it composes edits in the correct format rather than guessing. Hints are produced by provider classes - one per field type, registered via a Symfony service tag - which is the extension point if you add a custom data type.

Configuration

Inference provider config

The pimcore_agent.inference Symfony config tree - not editable through Pimcore Studio. Defines named providers (LLM backends with their auth, endpoint, model list, and limits) and the default_provider used when an agent does not specify one. This is structural configuration, not runtime data; it is exported to the agent-server on startup and on every reload as part of the config export payload.

Bundle preset

An agent or skill shipped by a Pimcore bundle - read-only to end users. Presets live on disk at config/agents/*.yaml and config/skills/<name>/SKILL.md inside the bundle.

User-owned agent

An agent authored or customised in Pimcore Studio. Stored in the Pimcore database. A user-owned agent with the same name as a preset overrides it.

Three-layer merge

The order in which agent/skill configuration is resolved, from lowest to highest precedence:

1. Bundle preset (disk)
2. Container config (Symfony parameters, config.yaml)
3. Studio edits (database / symfony config, LocationAwareConfigRepository)

Later layers override earlier ones. The merged result is published to the agent-server via the config export endpoint on startup and on reload.