> Documentation index: [/llms.txt](/llms.txt). Every page as one file: [/llms-full.txt](/llms-full.txt).

# Hand work to another agent

Hand work to another agent [#hand-work-to-another-agent]

An agent with the Call Agent tool (`call-agent`) hands a subtask to another agent and continues when the report comes back.

|              | Call Agent tool                                                                                    | @mention                                                                                     |
| ------------ | -------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| Who decides  | The agent                                                                                          | The person, in the chat                                                                      |
| What happens | The other agent works in the background; its report comes back to the calling agent, which answers | The mentioned agent answers that one message; the next message goes back to the chat's agent |
| Setup        | Turn it on per agent, below                                                                        | None: type `@` in the message box and pick an agent                                          |

Turn on delegation [#turn-on-delegation]

1. In the calling agent's editor, open **Sub-agents** and turn on **Let this agent call other agents**.
2. Optional: pick the agents it may call. With none picked, it may call any agent you can use in the workspace.
3. On each agent that should receive work, open **General** and turn on **Other agents can hand work to this agent**.

The same fields over the API:

| Field                        | On                | Value                                                          |
| ---------------------------- | ----------------- | -------------------------------------------------------------- |
| `tool_names`                 | The calling agent | Include `call-agent`                                           |
| `enabled_callable_agent_ids` | The calling agent | Agent IDs it may call; `[]` means any agent the person can use |
| `delegable`                  | The called agent  | `true` lets other agents hand it work                          |

| Method  | URL                                    | Auth          |
| ------- | -------------------------------------- | ------------- |
| `PATCH` | `/api/v1/agents-v2/agents/{agent_id}/` | Key or bearer |

See [Create and configure agents](../create-and-configure) for the other agent fields.

Which agents can be called [#which-agents-can-be-called]

* Agents in this workspace, and platform agents installed in it, that accept work.
* Only agents the person running the calling agent could run themselves; the picked list can only narrow this.
* Two built-in helpers are always available. They work with the calling agent's own skills, connections and knowledge, so an agent with no other agent to call can still split work off.
* An agent cannot call itself, and a loop such as A → B → A is refused.

How a delegation runs [#how-a-delegation-runs]

* It runs as the person running the calling agent, with their access and credits; the called agent's owner's connections are never used.
* It always runs in the background. The calling agent ends its turn; the report starts it again, or waits until its current turn ends.
* The report has a status: `completed`, `partial`, `needs_input`, `failed`, `cancelled` or `unknown`, plus the files the other agent made.
* The other agent works in the calling agent's sandbox, so files are shared. The calling agent can also hand over up to 3 files of up to 25 MB each, and extra connections for that one task.
* The other agent cannot ask the person questions; it states its assumptions in the report.
* An approval it needs appears in the person's chat.
* The calling agent can send it a follow-up while it runs, or continue the same session later.

Limits [#limits]

| Limit                                           | Value                                                                                         |
| ----------------------------------------------- | --------------------------------------------------------------------------------------------- |
| Depth                                           | Two levels: the agent you talk to can delegate, and the agent it calls can delegate once more |
| Delegations started in one run                  | 5                                                                                             |
| Delegations running at once in one conversation | 5                                                                                             |
| Requests a delegated agent may make             | A share of the calling agent's run limits                                                     |

Over a limit, the calling agent gets a refusal it can answer with; the person's turn does not fail.

Troubleshooting [#troubleshooting]

| What you see                         | Cause                                                                                           |
| ------------------------------------ | ----------------------------------------------------------------------------------------------- |
| The agent never delegates            | The Call Agent tool is off on it                                                                |
| An agent is missing from its choices | That agent does not accept work, is not installed in the workspace, or the person cannot run it |
| A delegation is refused              | A limit above was reached, or the agent ID is unknown                                           |