Subagent Error Handling

Definition

How a subagent should respond to tool failures: resolve locally where possible, recognise when a retry cannot help, and propagate structured context back to the orchestrator.

Key points

• Order of behaviour: (1) attempt to resolve locally first; (2) recognise when retry won't help (validation/permission errors are non-retryable); (3) propagate structured context upward rather than a bare failure.
• Relies on Structured Tool Errors fields (errorCategory, isRetryable) to make the retry-vs-escalate decision.
• Aligns with the escalation principle: don't blindly retry; hand up with enough context to act.

Why it matters for the exam

• Multi-Agent Research and Customer Support scenarios test correct subagent failure behaviour.
• The wrong answer is usually "retry indefinitely" or "swallow the error and report success".

Common gotchas

• Retrying a permission or validation error wastes turns — those are non-retryable.
• Propagating a generic message loses the context the orchestrator needs — always pass structured error context.

See also

• Structured Tool Errors
• Task and Agent tool
• Effective Tool Descriptions

Sources

• docs-tools-agents
• netlight-study-guide