Skip to main content
Version: 2026.1

Agents and Switching

An agent is a named configuration: system message, model, skill set, MCP tool groups, widget allow-list, and an optional pauseAfter threshold. Switching between agents is a first-class user action — one dropdown click and the conversation carries on with a different specialist. For the YAML schema, see Configuration → Agents; for the SDK-level mechanics, see Architecture → Agent Framework.

Agents that ship out of the box​

The PimcoreAgentBundle comes with two presets:

AgentRole
General AssistantReads data and assets, shows previews, searches the web, asks the user questions.
Data ManagementEverything General does, plus proposal workflows for writes.

When additional bundles are installed alongside the agent bundle, additional presets might appear.

All three presets can be cloned, overridden, or disabled in the Studio UI. Any Pimcore bundle can ship additional presets — see Configuration → Shipping Presets.

Switching — the user experience​

There are two ways for a user to switch agents:

  1. Manually — open the agent dropdown in the chat header and pick a different one.
  2. Proactively from the agent — if the current agent notices your request would be better handled by another, it proposes the switch via a pimcore_switch_agent widget. One click and you're there; ignore it and nothing happens.

From the user's perspective, conversation history is preserved across the switch. The new agent sees what the previous agent and the user said — you don't need to re-explain.

What "preserved history" actually means​

History survives a switch, but only within a bounded window. The bundle injects the last 30 messages from your transcript into the new agent's system message as a one-shot context block. Each message part is capped at 5,000 characters. Widget payloads (search results, proposals) are carried across as labelled JSON, not just their narrative summary — so the "search with agent A, switch to agent B to edit the results" flow actually works end-to-end.

Older messages are dropped. If a conversation is 500 messages long and you want agent B to know about something from message #3, restate it. The cost is paid once at the moment of the switch; subsequent messages on the same agent hit a warm-cache hot path and rebuild nothing.

Trade-offs worth knowing​

  • Repeated switching is not free. A → B → C → A is three switches and three context-block rebuilds. Sticking with one agent for a coherent sub-task is cheaper.
  • Only the final assistant message per turn carries across. Intermediate tool-call reasoning, unless the previous agent summarised it in text, does not reach the new agent.
  • Widget data is preserved, errors are not. A failed turn in the previous agent won't poison the new agent's system prompt.

Why the bundle can proactively suggest switches​

Every agent's system prompt is extended at resolve time with an awareness block listing the other available agents: their names, descriptions, when each is a good choice. This gives the LLM enough context to offer a switch proactively. The agent cannot switch on its own — the user has to click the widget button. The tool call itself is the confirmation gate, which keeps one-click switches at the top of the conversation instead of requiring a yes/no exchange first.

Further reading​