Skip to main content
Version: 2026.1

Tool Bundles

A tool bundle is a named, developer-defined capability pack. It groups a combination of skills, SDK tools, Pimcore MCP tool groups, Pimcore MCP meta-groups, and rich-chat widgets under one name, so a person configuring an agent can add the whole known-good combination in one click instead of picking each item separately.

Why bundles exist​

An agent's capabilities are six independent multiselects (skills, includeSdkTools, pimcoreMcpServers, pimcoreMetaGroups, richChatWidgets, allowedFileStagingSets), and some tasks only work when a specific combination is present. For example, proposing data object updates needs the data-object-proposals skill together with both the pimcore-data-objects-read and pimcore-data-objects-write MCP tool groups - missing any one of them leaves the agent unable to complete the task, and which items belong together is not obvious from the multiselects alone. A tool bundle captures that combination once, under a name, so it can be reused across agents.

Defining a bundle​

Bundles are declared under pimcore_agent.tool_bundles, a map keyed by bundle name, directly in Symfony configuration:

pimcore_agent:
  tool_bundles:
    document-template-editing:
      displayName: 'Document Template Editing'
      description: 'Create and update Pimcore document templates.'
      skills: [general, document-template-generation]
      includeSdkTools: [edit]
      pimcoreMcpServers: [pimcore-agent-templates, pimcore-documents-read, pimcore-documents-write]

displayName and description are raw strings, the same as agent and skill descriptions - there is no translation involved. Every list field defaults to [] when omitted, so a bundle only needs to declare the fields it actually contributes to.

Bundles are developer/config-defined only. There is no Pimcore Studio editor for creating, editing, or deleting a bundle definition - Pimcore Studio only lets you select existing bundles on an agent (see The Tool Bundles picker in Pimcore Studio below).

Field reference​

FieldTypeDefaultMeaning
displayNamestringrequiredLabel shown in the Tool Bundles picker and in the "Included via bundles" preview.
descriptionstring''Short description shown next to the bundle in the picker.
skillsstring[][]Skill names this bundle contributes. See Skills.
includeSdkToolsstring[][]SDK tools this bundle contributes. See Tool Security Reference.
pimcoreMcpServersstring[][]Direct Pimcore MCP tool group names this bundle contributes. See MCP Servers.
pimcoreMetaGroupsstring[][]Meta-tool Pimcore group names this bundle contributes. See MCP Servers.
richChatWidgetsstring[][]Rich chat widget identifiers this bundle contributes. See Features → Rich Chat Widgets.

What a bundle does not cover​

Two capability fields stay out of bundles by design and remain manual, per-agent settings: third-party mcpServers (inline external connection objects) and allowedFileStagingSets. Bundles cover the combination that is hardest to get right by hand - skills, SDK tools, and Pimcore MCP groups/meta-groups - plus rich-chat widgets; external MCP servers and file staging keep their existing manual configuration.

Referencing bundles from an agent​

An agent adds bundles by name in a new toolBundles list, alongside any of its existing manual selections:

name: data-management
displayName: Data Management
description: Search and edit Pimcore data.

toolBundles:                         # Bundle names. See 04_Configuration/11_Tool_Bundles.md
  - data-management
  - general-data-search

skills:                              # Manual picks still work alongside bundles
  - general

pimcoreMcpServers:
  - pimcore-tags-read                # A manual addition on top of what the bundles contribute

Manual selections and bundle selections are independent and additive - an agent can carry both at once, and removing a bundle does not remove a manually picked item that happens to overlap with it.

Expansion at export​

The agent-server has no bundle concept: it only ever consumes the flat skills / includeSdkTools / pimcoreMcpServers / pimcoreMetaGroups / richChatWidgets arrays. The expansion from toolBundles into those flat arrays happens entirely on the Pimcore PHP side, at export (GET …/configurations/export):

  • Every name in an agent's toolBundles list is resolved against the tool-bundle registry.
  • Each resolved bundle's five capability lists are unioned into the agent's own flat arrays, deduplicated. The effective set for each field is union(selected bundles' contents) ∪ manual selections.
  • Unknown bundle names are ignored, the same way an unknown skill name is silently dropped.
  • The toolBundles field itself is removed from the exported agent - it never reaches the agent-server.
  • Expansion runs before file-staging auto-registration, so a bundle that contributes the pimcore-agent-templates MCP server still triggers auto-registration of the file-staging tool group correctly.

Because expansion happens at export rather than being merged into the stored form fields, bundles are all-or-nothing: there is no way to subtract a single item a bundle contributes while keeping the rest of that bundle. To exclude one item, configure the agent manually instead of through a bundle for that capability.

The Tool Bundles picker in Pimcore Studio​

Open an agent in System → Pimcore Agent → Agent Configuration and switch to the Tools & Skills tab. A Tool Bundles multiselect sits at the top of the tab, listing every bundle's displayName. Selecting one or more bundles reveals a read-only Included via bundles preview directly below it: the union of the selected bundles' skills, SDK tools, MCP groups, meta-groups, and rich-chat widgets, grouped and labelled the same way the manual multiselects label their own options (skill chips carry a (system) / (custom) source suffix, MCP group chips show their tool count).

The preview is informational only - it shows what the bundle chips contribute without writing those items into the manual multiselects below. The existing manual multiselects (SDK Tools, Skills, Pimcore MCP Servers (Direct), Pimcore Meta Groups, Rich Chat Widgets) remain fully editable and unaffected by bundle selection; both sets union at export as described above.

Overriding a shipped bundle​

A bundle entry is a whole node, not a set of independently mergeable fields. To override a shipped bundle (from the Pimcore Agent Bundle itself or from another bundle), define a bundle with the same name in your own project configuration, for example config/packages/pimcore_agent.yaml. The project's definition replaces the shipped one entirely rather than deep-merging list by list, so the override must repeat every field it wants to keep, not only the fields it wants to change.

Unlike agents and skills, tool bundles have no Pimcore Studio CRUD layer - there is no administrator-editable copy that sits above container config. The only two sources are bundle-shipped config and project config, and a same-name definition in project config always wins.

Shipping a bundle from your own bundle​

A bundle author ships tool bundles the same way the Pimcore Agent Bundle ships its own: declare pimcore_agent.tool_bundles inside the auto-loaded config/pimcore/config.yaml (or the optional-dependency prepend() pattern for a bundle that does not require PimcoreAgentBundle) described in Shipping Presets. There is no separate paths registration key for bundles - the map is declared inline under pimcore_agent.tool_bundles, directly alongside pimcore_agent.agents.paths and pimcore_agent.skills.paths in the same file.

Shipped presets​

The Pimcore Agent Bundle ships four curated bundles out of the box:

BundleDisplay nameContents
data-managementData Managementskills: pql-search, general, summarize, data-object-proposals, asset-metadata-proposals, tag-proposals; includeSdkTools: ask_user; pimcoreMcpServers: pimcore-data-objects-read, pimcore-data-objects-write, pimcore-assets-read, pimcore-assets-write, pimcore-tags-read, pimcore-tags-write; richChatWidgets: pimcore_open_element, show_data_object_preview, show_asset_preview, show_data_table
document-editingDocument Editingskills: document-editing, general, pql-search; includeSdkTools: ask_user; pimcoreMcpServers: pimcore-assets-read, pimcore-data-objects-read, pimcore-documents-read, pimcore-documents-write; richChatWidgets: pimcore_open_element, show_data_object_preview, show_asset_preview
document-template-editingDocument Template Editingskills: general, document-template-generation; includeSdkTools: edit; pimcoreMcpServers: pimcore-agent-templates, pimcore-documents-read, pimcore-documents-write
general-data-searchGeneral Data Searchskills: pql-search, general, summarize; pimcoreMcpServers: pimcore-data-objects-read, pimcore-assets-read, pimcore-documents-read; pimcoreMetaGroups: pimcore-tags-read; richChatWidgets: pimcore_open_element, show_data_object_preview, show_asset_preview, show_data_table