Agent-to-agent calls
An agent-to-agent call is when one agent delegates a piece of work to another agent and reads back the result. This is the mechanism behind the hierarchical pattern: a coordinator agent calls one or more specialists, then continues with their answers.
What a delegated call carries
When a coordinator delegates, the call includes:
| Item | Meaning |
|---|---|
| Target agent | The specialist to run, matched by its name or ID. |
| Instructions | A clear, specific task for the specialist to perform. |
| Role description | A short note on the specialist’s expertise, surfaced in the UI. |
| Status | A human-readable message describing what is happening, shown while the call runs. |
| Include history | Whether the previous step’s output is passed along as extra context. |
The specialist runs as a full agent with its own model, tools, and knowledge, and shares the coordinator’s workspace so both can read and write the same files during the task.
What the coordinator gets back
The specialist streams its reply to the user in real time. The coordinator itself receives a distilled version:
- If the specialist wraps its conclusion in a
<final_answer>…</final_answer>block, the coordinator gets just that block. - Otherwise it gets the specialist’s text, trimmed to keep the coordinator’s context lean on long tasks.
Each returned result is prefixed with the specialist’s name (for example, [From Researcher] …) so the coordinator knows which agent produced it.
Tip: have specialists end with a short
<final_answer>summary. The coordinator then receives a clean, predictable result instead of the full transcript.
Failure handling
If a delegated call cannot complete, the coordinator receives a diagnostic message instead of silence, so it can retry with a simpler task or stop delegating. Common cases:
- No matching agent — the requested name or ID doesn’t match an available specialist; the error lists the agents that are available.
- No instructions — the call was made without a task to perform.
- Empty response — the specialist produced no answer, often because its token or context budget ran out mid-task.
Setting it up
Agent-to-agent calls happen at runtime when the coordinator decides to delegate. To enable this:
- Build the specialist agents you want to delegate to, each with a focused job. See Building an agent.
- Build the coordinator and write its instructions to describe when and to whom it should delegate.
- Test from the builder preview with prompts that require delegation, and confirm each specialist returns the result you expect.