> 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/organisation/built-in-mcp-servers/agents-mcp-server.md).

# Agents MCP Server

The **Agents MCP Server** is a built-in server that lets one agent delegate tasks to other agents - its **linked sub-agents** - during a execution. Using this server, a parent agent can discover which sub-agents are available, inspect their capabilities, and hand off specific tasks to them. Each sub-agent runs its own conversation, can ask follow-up questions, and returns a response that the parent agent can then use to continue its own work. This is the foundation of multi-agent workflows on the platform: a coordinating agent handles the overall task and routes sub-tasks to specialist agents best suited for each piece of work.

## Connection Parameters

| **Parameter**      | **Value**                                             |
| ------------------ | ----------------------------------------------------- |
| **Server address** | `internal://agents`                                   |
| **Server type**    | Internal (built-in, no external credentials required) |

## Key Concepts

### Linked Sub-Agents

An agent can only call sub-agents that are explicitly **linked** to it in the agent's settings. 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.

### Agent Identifiers

Every agent has a unique **identifier** - a short, URL-friendly string like `data-analyst` or `content-writer`. This is the same identifier used in the `@mention` syntax in conversations (e.g. `@data-analyst`). When calling tools on this server, identifiers are always used **without** the `@` prefix.

### Input and Output Schemas

Some agents declare a structured **input schema** and/or **output schema**. When an input schema is present, the context passed to `run_agent` must be a valid JSON object matching that schema - plain text is not accepted. When an output schema is declared, the agent's response comes back as a structured JSON object rather than a free-text string. Always call `get_agent` first to check whether a target agent requires structured input.

### Sub-Agent Conversations

Each `run_agent` call either starts a new sub-agent conversation or continues an existing one. The response always includes a `conversation_id`. If the sub-agent asks a clarification question or needs further input, the parent agent can pass that `conversation_id` back in the next `run_agent` call to continue the same conversation - the sub-agent retains the full history of previous turns.

## Available Tools

| **Tool**            | **Description**                                                                                                                                                                                                                                                                                                                          |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `list_agents`       | List all enabled sub-agents that are linked to the current agent. Returns each agent's identifier, name, and description. Call this first to discover which agents are available before delegating a task.                                                                                                                               |
| `get_agent`         | Get full details about a specific linked sub-agent by its identifier. Returns the agent's name, description, and its input/output schemas if declared. Call this before `run_agent` to understand exactly what input the sub-agent expects and what format it returns.                                                                   |
| `get_current_agent` | Get details about the current agent - the agent that is running and calling this tool. Returns its own identifier, name, description, and input/output schemas. Use this to recall your own configured purpose and the input/output contract you are expected to follow.                                                                 |
| `run_agent`         | Delegate a task to a linked sub-agent and return its response. The result includes a `conversation_id` that can be passed back in a subsequent call to continue the same conversation - useful when the sub-agent asks for clarification or needs additional instructions. Only agents linked to the current parent agent can be called. |