> For the complete documentation index, see [llms.txt](https://docs.ibexa.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ibexa.ai/manual/agents/agent-delegation.md).

# Agent Delegation

Agent delegation lets one agent hand off part of its work to another, more specialised agent - its **sub-agent** - instead of trying to do everything itself. A coordinating agent (often called an **Orchestrator**) receives the overall request and routes specific sub-tasks to the specialist agents best suited for each piece of work, then combines their responses into a final answer.

This guide explains why and when to use delegation, the platform concepts involved, and walks through setting up a working multi-agent workflow step by step.

## Why Use Delegation?

* **Limited context window** - every instruction and tool you add to an agent is loaded on *every* run, even when it isn't needed for the current request. Splitting work across agents keeps each one's instructions short, fast, and focused on its own job.
* **Divide and conquer** - a small, single-purpose agent with a narrow job and a handful of tools is easier to write good instructions for, easier to test, and easier to reason about than one large agent trying to handle every case.
* **Least privilege** - a specialist sub-agent can hold the credentials and tools it needs (e.g. an external API key) without exposing them to every other agent that might want to use its capability.
* **Maintainability** - if a specialist's underlying tool or process changes, you only need to update that one sub-agent. The orchestrator and every other agent that delegates to it are unaffected.

> **Note on cost:** Delegating a task still runs the sub-agent's own model call, on top of the orchestrator's run. For frequent or high-volume delegation, keep an eye on credit usage - see [Budget](/manual/organisation/budget.md).

## Key Concepts

### Sub-Agents

Any agent can be marked **"Can be sub-agent"** in its Execution settings (see [Agents](/manual/agents.md#step-6-general-properties)), making it eligible to be called by other agents. An agent with this flag unchecked can still run on its own, but no other agent can delegate to it.

### Linked Sub-Agents

An agent can only call sub-agents that are explicitly **linked** to it in its **Sub-Agents** settings (see [Agents](/manual/agents.md#viewing-an-agent)). This is a deliberate access boundary - an agent cannot discover or call any other agent in your organisation outside its configured links. Sub-agents that are disabled are never surfaced, even if a link exists.

### The Agents MCP Server

Delegation is powered by the built-in **Agents MCP Server** (`internal://agents`), which lets a parent agent discover, inspect, and run its linked sub-agents. See [Agents MCP Server](/manual/organisation/built-in-mcp-servers/agents-mcp-server.md) for the full tool reference (`list_agents`, `get_agent`, `run_agent`).

### The `@identifier` Syntax

To refer to a sub-agent in a message or in an agent's instructions, use the `@identifier` syntax - for example `@twitter-post-adapter`. Replace `identifier` with the exact identifier of the sub-agent (without the `@` prefix when calling MCP tools). Using the exact identifier helps the orchestrator address the intended sub-agent unambiguously.

## Before You Begin

* Any member of your organisation can create agents and mark them as sub-agents.
* Linking a sub-agent to an orchestrator, or editing an existing agent's instructions, requires being that agent's **creator**, or having **Owner**/**Administrator** permissions.

## Setting Up a Multi-Agent Workflow

### Step 1: Configure and Verify the Built-in MCP Server

Before agents can communicate, ensure the built-in **Agents MCP Server** is active.

1. Go to **Organisation → MCP Servers**.
2. Verify that the server with the identifier `agents` (address `internal://agents`) is **Enabled**.

### Step 2: Create Specialist Sub-Agents

Specialist agents perform specific, narrow tasks. For a multi-agent workflow, each must be explicitly marked as available for delegation.

1. Go to **Agents** and select **Add Agent**.
2. Write focused **Instructions** describing exactly what this specialist should do (and, ideally, what it should say if asked something outside its role).
3. **Identifier**: keep the auto-generated short, URL-friendly identifier, or provide your own (e.g. `twitter-post-adapter`).
4. **Description**: clearly describe what the agent does - this helps the orchestrator (and its underlying model) understand when to call it.
5. In **Step 5: Execution**, check **"Can be sub-agent"**.

#### Example Specialist Agents

* **Twitter Adapter**
  * **Identifier**: `twitter-post-adapter`
  * **Role**: Adapts long-form content into concise, engaging Twitter posts.
* **LinkedIn Adapter**
  * **Identifier**: `linkedin-post-adapter`
  * **Role**: Adapts content into professional LinkedIn posts with relevant hashtags.

### Step 3: Create the Orchestrator Agent

The orchestrator coordinates the workflow by receiving the initial input and routing sub-tasks to the specialist agents.

1. Create an agent, e.g. with the identifier `content-orchestrator`.
2. **Add MCP Tools**: in the **Tools** section, add the `internal://agents` server. This gives the orchestrator access to the `list_agents`, `get_agent`, and `run_agent` tools.
3. **Link Sub-Agents**: in the **Sub-Agents** settings, link every specialist the orchestrator should be able to call (e.g. `twitter-post-adapter` and `linkedin-post-adapter`). An agent can only call sub-agents that are explicitly linked to it.
4. In the orchestrator's instructions, mention when and how it should delegate, using the `@identifier` syntax - for example: *"When asked to adapt content for social media, delegate to `@twitter-post-adapter` for Twitter and `@linkedin-post-adapter` for LinkedIn."*

## Practical Example: Content Adaptation Workflow

Imagine you have a blog post that needs to be promoted across social media.

1. A user sends the blog post to the **Orchestrator**.
2. The **Orchestrator** uses `list_agents` to see available specialists.
3. The **Orchestrator** calls `run_agent` for the **Twitter Adapter** to generate a tweet.
4. The **Orchestrator** calls `run_agent` for the **LinkedIn Adapter** to generate a LinkedIn post.
5. The **Orchestrator** returns the complete social media package to the user.

> See the [Extending Your General Assistant with a Link Manager Sub-Agent](/tutorials/building-a-link-manager-sub-agent.md) tutorial for a full, hands-on walkthrough of this pattern - delegating a narrow, tool-heavy task (managing short links) from a General Assistant to a dedicated sub-agent.

## Troubleshooting

| Issue                                                                       | What to do                                                                                                                                |
| --------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| The orchestrator can't find a sub-agent it should be able to call           | Confirm the sub-agent has **"Can be sub-agent"** checked, and that it is explicitly linked in the orchestrator's **Sub-Agents** settings. |
| The orchestrator answers a specialised request itself instead of delegating | Make the delegation instruction in the orchestrator's own instructions more explicit, and reference the sub-agent's exact `@identifier`.  |
| Delegation fails with a permissions or connection error                     | Check that the built-in **Agents MCP Server** (`internal://agents`) is **Enabled** under **Organisation → MCP Servers**.                  |
| A linked sub-agent is never called even though it should match              | The sub-agent may be **Disabled** - disabled sub-agents are never surfaced to the orchestrator, even if linked.                           |