Error propagation across agents

Why multi-agent errors are different

In a single loop, a tool error lands straight back in the model’s context and it can react. In a coordinator–subagent system there is a second hop. A subagent runs in its own context, and only its final message returns to the coordinator as the Agent tool result — the coordinator never sees the tool calls, error messages and retries that happened inside. Whatever the subagent writes in that final message is all the coordinator knows. If it says nothing about a failure, the failure has disappeared.

Anthropic’s write-up of its multi-agent research system names the consequence: agents are stateful and long-running, so errors compound, and a minor failure early on can send the rest of the run down the wrong path. Their fixes combine the model’s adaptability with deterministic safeguards — telling the agent when a tool is failing and letting it adapt, plus retry logic, regular checkpoints, and resuming from where the error occurred instead of restarting from scratch.

The opposite extreme is just as bad. If any single subagent error raises an exception that ends the whole task, one flaky data source throws away the work of every other subagent. The goal is neither silence nor collapse, but a failure that arrives, intact, at the level that can decide what to do.

Empty is not the same as failed

The most important distinction in this task statement is between a valid empty result and an access failure. “The search ran and found no matching filings” is a finding; the coordinator should trust it. “The search timed out” means nothing is known; the coordinator should retry, reroute or flag it. If both come back as an empty list, the system cannot tell them apart — and it will report absence of evidence as evidence of absence.

The protocols already give you the tools for this at the lowest level. In the Messages API, a failed tool call returns a tool_result with is_error: true and an instructive message; the documentation advises saying what went wrong and what to try next, such as a rate limit with a retry delay, rather than a bare “failed”. The MCP specification separates protocol errors (unknown tool, malformed request) from tool execution errors, which come back as a normal result with isError: true — API failures, invalid inputs, business-rule violations — and says clients should pass execution errors to the model so it can self-correct. (Designing those error payloads is covered in 2.2.)

What a subagent should hand back

Because the final message is the whole interface, design it as a contract. Ask each subagent (in its system prompt, or via structured output) to return a status, its findings, and — when anything went wrong — the failure type, what it attempted, any partial results, and what it suggests. The coordinator can then act on fields rather than guess from prose.

{
  "status": "partial",
  "subtopic": "Competitor pricing, Nordic region",
  "findings": [
    { "claim": "Brand X cut entry-tier prices 8% in August",
      "source": "https://example.com/brandx-q3", "retrieved": "2026-09-20" }
  ],
  "failures": [
    { "type": "transient",
      "what": "search_news timed out",
      "attempts": 3,
      "retryable": true,
      "not_covered": "Brand Y and Brand Z news since June" }
  ],
  "suggestion": "Retry news later, or use company press feeds"
}

Current Claude Code builds help at this boundary too. The subagent documentation says that a subagent ending on an API error — a usage limit or repeated server error — now reports that failure to the coordinator rather than passing error text off as findings; a foreground subagent that had already written output returns it marked as cut off, and a background one is marked failed with its last output attached. A subagent that stops at its maxTurns limit has its output marked as partial, and it can be resumed to continue instead of being restarted.

What the coordinator does with a failure

Traps the wrong answers are built from

You should now be able to

• Decide which errors a subagent should recover from locally and which it should propagate.
• Design a subagent result format that carries status, failure type, attempts and partial results.
• Distinguish access failures from valid empty results in tool and subagent outputs.
• Use is_error in tool results and know how MCP separates protocol from execution errors.
• Choose between retrying, rerouting, proceeding with annotated gaps and escalating at the coordinator.