CertSafari
    Anthropic Claude Certified Architect – Foundations (CCAR-F)· Lessons

    Domain 5 · Lesson 27/30

    Error propagation in multi-agent systems

    Implement error propagation strategies across multi-agent systems

    18 min read
    2.5% of exam
    8 sources
    Published 20 Oct 2026
    Docs as of 14 Oct 2026

    What you will be able to do

    • Design the error payload a subagent returns so a coordinator can choose a recovery action
    • Tell an access failure apart from a valid empty result and report each one differently
    • Explain why hiding a failure as an empty success and halting the whole workflow over one failed source are both anti-patterns, and what to do instead
    • Decide which failures a subagent should retry on its own and which it should send to the coordinator
    • Annotate a final synthesis with which findings are well supported and which topics have gaps

    Key concept

    Structured error propagation — A coordinator knows about a failure only through what the subagent reports. Subagents therefore fix transient failures themselves and send up anything they cannot fix as structured context: what failed, what was tried, what was recovered and what else could work. The coordinator then has enough to choose a recovery instead of guessing.

    1.The coordinator recovers from what it is told

    In a multi-agent system, an error is only useful if it reaches the agent that can act on it. In a Hub-and-spoke coordinator design, the coordinator sends work to subagents and builds its answer from what they return. It never sees their tool calls, retries or raw responses. Each subagent works in its own context, and only its final message goes back to the parent. That isolation is what keeps the coordinator's context clean, and it also means the coordinator learns about a failure only if the subagent describes it.

    Take a research coordinator that sends four subagents to cover regulatory filings, news, patents and analyst reports. Suppose the patents subagent hits a database that refuses connections. The coordinator's next move depends entirely on that subagent's final message. It could retry later, send the work to another source, narrow the question, or go ahead and flag the gap. If the message says what happened, the coordinator can pick one. If it only says that something went wrong, the coordinator has nothing to choose with.

    Agents handle failures well when someone tells them about the failure. Anthropic's experience building its multi-agent research system was that telling an agent a tool is failing and letting it adapt works well. A coordinator is an agent too, so the same applies one level up. A subagent's error report is the tool result the coordinator reasons from.

    Checkpoint 1 of 9· Check yourself

    A research coordinator sends a patents subagent to search a patent database. The database refuses connections. The subagent retries twice and then returns only: "Patent search could not be completed." What does the coordinator have to decide its recovery from?

    Sources12

    2.Structured error context instead of a generic status

    A generic status like "search unavailable" says that something failed but not why, what was tried, or what can still be saved. A coordinator that gets only that string can't tell a ten-second network blip from an expired credential. It doesn't know whether half the results already arrived, and it can't see any route other than retrying the same call. The useful details existed inside the subagent and were dropped on the way up.

    At the level of a single tool, the basic pattern is to report the error instead of crashing, with a flag that marks it as an error:

    A tool-level error result: the failure is flagged and the message names the causejson
    {
      "role": "user",
      "content": [
        {
          "type": "tool_result",
          "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
          "content": "ConnectionError: the weather service API is not available (HTTP 500)",
          "is_error": true
        }
      ]
    }

    That flag and message tell an agent what failed during one call. A subagent reporting to a coordinator has to say more, because the coordinator is deciding about a whole piece of work, not one call. The tool-level categories and retryability flags from Error categories and isRetryable metadata become one field in a larger report. That report should contain:

    • Failure type: the category, such as a timeout, an authentication failure, a rate limit or an invalid query, so the coordinator knows whether retrying could help
    • What was attempted: the exact query or action and the source it went to, so the coordinator doesn't send the same doomed request again
    • Partial results: anything gathered before the failure, such as three of four pods' logs or the first 40 of 200 filings, so finished work isn't thrown away
    • Possible alternatives: a read replica, a different index, a broader date range or a second provider that could fill the gap

    Other report designs look reasonable but leave out the next step. A fixed code like UNAVAILABLE is easy for code to branch on, but it is the generic string again in capitals. The coordinator can branch on it without knowing which branch to take. A numeric code with the raw message and a severity rating describes the failure without saying what was tried or saved. Retry counts, timestamps and subagent IDs are monitoring data. They help a human debug later but don't help the coordinator recover now. Writing full details to a log and keeping the coordinator's message short puts the information where the coordinator can't read it. Sending the subagent's whole reasoning trace and raw output goes too far the other way: it floods the coordinator's context, which is the problem context isolation was meant to prevent.

    Checkpoint 2 of 9· Fill the gap

    A tool call to the weather service failed. Which field name, set to true, tells the agent that this tool_result is an error and not a successful answer?

    {
      "role": "user",
      "content": [
        {
          "type": "tool_result",
          "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
          "content": "ConnectionError: the weather service API is not available (HTTP 500)",
          " ? ": true
        }
      ]
    }

    Checkpoint 3 of 9· Check yourself

    A filings subagent's database times out partway through its work. You are designing the final message it returns. Which payload best lets the coordinator choose how to recover?

    Checkpoint 4 of 9· Exam question

    A document-search subagent hits an authentication error against a knowledge base and simply returns the string 'search unavailable' to the coordinator. The coordinator has no other information to act on. What is the primary problem with this design, and what should replace it?

    Checkpoint 5 of 9· Exam question

    A team is designing the error payload that subagents return to a coordinator when a tool call fails. Which set of fields best supports intelligent coordinator recovery decisions?

    Sources3

    3.Access failures, empty results and silent suppression

    "No results" can mean two opposite things, and the coordinator needs to know which. The point is covered at tool level in Access failure vs valid empty result. Across agents the stakes are higher. A query that ran and matched nothing is a finding: the discontinued SKU really has no rows, and the narrow fact pattern really matches zero cases. A query that never completed, because it timed out, hit an exhausted connection pool or used an expired key, says nothing about whether matches exist. A timeout is especially ambiguous because the request may have run on the server. Each one needs its own report: an empty result reported as a success with zero items, and an access failure reported as an error with the structured context described in the previous section.

    Silent suppression turns a gap in coverage into false evidence. An empty list marked as a success tells the coordinator that the source was checked and held nothing. The coordinator then reasons correctly from a false input and states that no relevant filings exist, when in fact nobody looked. This can't be repaired downstream. A validation pass on an empty list can't tell a real zero from a hidden failure, because the only point where that difference was visible was inside the subagent when the call failed. Report the access failure as an error at that point.

    The opposite reaction is also a mistake: ending the whole workflow because one source failed. An expired filings key doesn't make the news, patent and analyst subagents' results any less valid. Throwing them away wastes completed work, and restarting from scratch is expensive. Anthropic's research system resumes from where the agent was when the error happened, because restarts are expensive and frustrating for users. One source failing is a reason to recover or flag a gap, not to stop.

    Both reactions are anti-patterns, and they fail in opposite directions. Silently suppressing an error produces an answer that looks complete and is wrong, because the failure is invisible to everyone downstream. Terminating the entire workflow on a single failure produces no answer at all, although most of the work was sound. Each one is tempting for a reason: suppression keeps the dashboard green, and termination feels cautious. The way out of both is the same. The subagent reports the failure honestly, with its type, the attempted query, partial results and alternatives. The coordinator then keeps the valid results, recovers what it can, and marks what it could not cover.

    Checkpoint 6 of 9· Match them up

    Match each situation in a four-source research pipeline to the right way to handle it.

    Tap a term, then the definition that fits it.

    Checkpoint 7 of 9· Exam question

    A regulatory-filings subagent cannot reach its data provider because the provider's API key expired. Instead of surfacing the failure, the subagent returns an empty findings list with status 'success' so the pipeline continues cleanly. The coordinator later synthesizes a report claiming full regulatory coverage. What went wrong?

    Sources42

    4.Recover locally, propagate what's left

    The subagent that hits a failure is in the best position to fix it, so it should try first. A rate limit, an overloaded server or a dropped connection usually clears after a short, limited number of retries with backoff. The subagent has the query, the credentials and the partial results in its own context, so it can retry cheaply. Sending every short-lived failure up to the coordinator would fill the coordinator's context with problems that would have fixed themselves. The Agent SDK sorts failures the same way for its own subagent retries, using an error_category field:

    Agent SDK error_category values and where each failure is best handled
    error_categoryLikely to clear on retry?Handled by
    rate_limitYes, after a delaySubagent retries locally with backoff
    overloadedYes, after a delaySubagent retries locally with backoff
    server_errorOftenSubagent retries a limited number of times, then reports up
    authentication_failedNoReported to coordinator right away
    cloud_credential_errorNoReported to coordinator right away
    unknownCan't tellLimited retries, then reported up with full context

    Retries need a limit and must match the failure type. Single tool calls already work this way: an agent given an invalid tool request retries 2–3 times with corrections and then gives up. Backoff makes no sense for an authentication failure, because waiting won't fix a credential. Retrying it only delays the report the coordinator needs. Once local recovery is used up, or never applied, the subagent sends up what remains. That report includes each attempt it made and why it failed, the partial results it is keeping, and the alternatives it can see. A retry count alone isn't enough. It shows effort, not what the coordinator should do next.

    With that report, the coordinator has real choices and doesn't need to stop the run. It can send a follow-up asking the same subagent to try the suggested replica. It can send the gap to another subagent that has a different source. Or it can accept the partial results and continue with the gap noted. This combines retry logic in code with an agent that adapts to what it is told. The subagent handles what it can fix, and the coordinator handles what the subagent can't.

    Checkpoint 8 of 9· Check yourself

    Your news subagent gets an overloaded error from its search provider on the first call. After a second query works, the next call returns authentication_failed. It already holds 12 articles. Which retry policy should it follow?

    Sources4562

    5.Coverage annotations in the final synthesis

    Errors that were reported correctly still need to show up in the final answer. Otherwise the reader of the synthesis makes the same mistake a coordinator would make with a suppressed failure. A report that just leaves out the patents section, without saying why, looks the same as one where patents were searched and nothing was found. Coverage annotations fix this by marking two things on the output:

    • Support per finding: whether a claim is backed by several independent sources, by one source, or only by partial results from a source that failed partway
    • Gaps per topic: which topic areas are thin or missing because a source was unavailable, naming the source, the reason, and what was tried

    An annotated report might read: "Regulatory filings: well supported by 14 filings from two providers. Patent landscape: gap. The patent database rejected our credentials and a fallback search of a public index returned partial results for 2024 only, so findings before 2024 are unverified." Someone reading that knows exactly how far to trust each section and what to fill in by hand.

    Coverage annotations need room in the output format from the start. A synthesis schema where every topic must contain findings pushes the model to fill gaps with weak material instead of marking them. Give each topic a support level and an optional gap note. Then a missing source becomes a field that is filled in, not a hole that someone has to notice.

    Checkpoint 9 of 9· Check yourself

    In a four-source research pipeline, the patent database sometimes rejects credentials while the other sources keep working. How should the coordinator's synthesis output schema handle each topic so the final report stays trustworthy?

    Sources47

    Sources

    (8)

    Every claim above is drawn from one of these pages, quoted as it was written on the date shown.

    1. 1.
      “intermediate tool calls and results stay inside the subagent; only its final message returns to the parent.”
      ↩︎ The coordinator recovers from what it is told
      “intermediate tool calls and results stay inside the subagent; only its final message returns to the parent.”
      ↩︎ Key concept
    2. 2.
      “letting the agent know when a tool is failing and letting it adapt works surprisingly well.”
      ↩︎ The coordinator recovers from what it is told
      “restarts are expensive and frustrating for users.”
      ↩︎ Access failures, empty results and silent suppression
      “We combine the adaptability of AI agents built on Claude with deterministic safeguards like retry logic and regular checkpoints.”
      ↩︎ Recover locally, propagate what's left
      “When errors occur, we can't just restart from the beginning: restarts are expensive and frustrating for users.”
      ↩︎ Exam trap 3
    3. 3.
      “When a tool raises an error, send the error message back with is_error: true instead of crashing.”
      ↩︎ Structured error context instead of a generic status
      “Claude reads the error and can retry with corrected input, ask the user for clarification, or explain the limitation.”
      ↩︎ Structured error context instead of a generic status
      “Claude reads the error and can retry with corrected input, ask the user for clarification, or explain the limitation.”
      ↩︎ Exam trap 1
      “When a tool raises an error, send the error message back with is_error: true instead of crashing.”
      ↩︎ Checkpoint
    4. 4.
      “is_error (optional): Set to true if the tool execution resulted in an error.”
      ↩︎ Access failures, empty results and silent suppression
      “If a tool request is invalid or missing parameters, Claude will retry 2-3 times with corrections before apologizing to the user.”
      ↩︎ Recover locally, propagate what's left
      “Claude will then incorporate this error into its response to the user.”
      ↩︎ Coverage annotations in the final synthesis
      “is_error (optional): Set to true if the tool execution resulted in an error.”
      ↩︎ Exam trap 2
    5. 5.
      “The values are rate_limit, overloaded, authentication_failed, server_error, cloud_credential_error, and unknown.”
      ↩︎ Recover locally, propagate what's left
      “The values are rate_limit, overloaded, authentication_failed, server_error, cloud_credential_error, and unknown.”
      ↩︎ Exam trap 4
    6. 7.
      “If the task might not have all the information your schema requires, make those fields optional.”
      ↩︎ Coverage annotations in the final synthesis
      “Match schema to task. If the task might not have all the information your schema requires, make those fields optional.”
      ↩︎ Checkpoint

    Also cited

    Spotted a mistake, or was something unclear? Tell us.