Error Propagation in Multi-Agent Systems

Official Exam Guide Objectives

Task 5.3: Implement error propagation strategies across multi-agent systems.

Knowledge of

• Structured error context (failure type, attempted query, partial results, alternative approaches) as enabling intelligent coordinator recovery decisions
• The distinction between access failures (timeouts needing retry decisions) and valid empty results (successful queries with no matches)
• Why generic error statuses ("search unavailable") hide valuable context from the coordinator
• Why silently suppressing errors (returning empty results as success) or terminating entire workflows on single failures are both anti-patterns

Skills in

• Returning structured error context including failure type, what was attempted, partial results, and potential alternatives to enable coordinator recovery
• Distinguishing access failures from valid empty results in error reporting so the coordinator can make appropriate decisions
• Having subagents implement local recovery for transient failures and only propagate errors they cannot resolve, including what was attempted and partial results
• Structuring synthesis output with coverage annotations indicating which findings are well-supported versus which topic areas have gaps due to unavailable sources

What You Need to Know

How failure information travels decides whether a multi-agent system degrades gracefully or fails without anyone noticing. A subagent hits a timeout, a permission refusal, a malformed query — and what it sends back up determines every option the coordinator has afterwards. The exam tests three things here: what structured error context contains, the two anti-patterns, and a distinction most developers get wrong.

Structured Error Context

A failing subagent owes the coordinator enough to decide with. Four elements:

1. Failure type. Which kind of failure this is: transient (a timeout or rate limit, so another attempt may work), validation (the input was wrong, so fix it), business (a rule refused it, so find another route or escalate), or permission (access denied, and no retry helps until authorisation changes).

2. What was attempted. The actual query, the parameters, the system it went to. "Searched academic database for 'renewable energy policy' with date range 2022-2024" can be acted on — narrowed, redirected, retried. "Search failed" cannot.

3. Partial results gathered before failure. Three sources retrieved before the timeout are three sources. Discarding them because the operation as a whole did not finish throws away work that already succeeded.

4. Potential alternative approaches. The subagent knows its own domain, and the coordinator does not. A database being unreachable, a query worth broadening, a cached result worth checking — these are suggestions only the failing agent is positioned to make.

{
  "status": "partial_failure",
  "failureType": "transient",
  "attemptedAction": {
    "tool": "search_academic_db",
    "query": "renewable energy policy",
    "dateRange": "2022-2024"
  },
  "partialResults": [
    {
      "title": "EU Renewable Energy Directive 2023",
      "source": "EUR-Lex",
      "retrieved": true
    }
  ],
  "alternativeApproaches": [
    "Retry with narrower date range (2023-2024)",
    "Search alternative database: government_publications",
    "Use cached results from previous research session"
  ]
}

With that in hand every option is open: repeat the call, take one of the alternatives, proceed on what was gathered, or escalate — and each is a decision rather than a guess.

The Two Anti-Patterns

The exam tests these explicitly. Both are catastrophic in different ways:

Silent suppression: returning empty results marked as success. The subagent times out and reports { "results": [], "status": "success" }. As far as the coordinator can tell, the search ran and the topic is empty — so it does not retry, does not try elsewhere, and synthesises a report missing an entire area of research. The report reads as complete.

That invisibility is what makes it the worst of the two. A crash announces itself; this does not, and nothing downstream can distinguish a subject that was searched and found barren from one that was never searched at all. The customer-support version is a support agent telling someone they have no account, because the lookup service was down and reported nothing found.

Workflow termination: killing the entire pipeline on a single failure. One subagent times out and everything stops. Four others finished successfully and their work is discarded along with the failure. The response is out of proportion to the event, and it leaves no path forward except starting again.

Between the two sits the correct behaviour: the failure is reported in full, the coordinator judges how much it costs, and the system proceeds on partial results or targeted recovery.

Access Failure vs Valid Empty Result

This distinction is critical and the exam tests it directly:

Access failure: the source was never reached — a timeout, a refused connection, a permission denial. The query did not run, so whether anything matches remains unknown. A retry, as-is or adjusted, is worth considering.

Valid empty result: the source was reached and the query ran. Nothing matched, and that is the answer. Retrying re-executes a successful operation to obtain the same correct result.

Conflating these leads to two problems:

• Treating access failures as valid empty results means you never retry when you should.
• Treating valid empty results as access failures means you waste time retrying a query that will always return nothing.

// Access failure — the tool never reached the data, so a retry may work.
const accessFailure = {
  status: "error",
  failureType: "transient",
  message: "Connection timeout after 30s",
  shouldRetry: true,
};

// Valid empty result — the query ran and the answer is "nothing matched".
const validEmptyResult = {
  status: "success",
  results: [],
  message: "Query executed successfully. No matching records found.",
  shouldRetry: false,
};

# Access failure — the tool never reached the data, so a retry may work.
access_failure = {
    "status": "error",
    "failureType": "transient",
    "message": "Connection timeout after 30s",
    "shouldRetry": True,
}

# Valid empty result — the query ran and the answer is "nothing matched".
valid_empty_result = {
    "status": "success",
    "results": [],
    "message": "Query executed successfully. No matching records found.",
    "shouldRetry": False,
}

Coverage Annotations

A synthesis drawing on several subagents should state where its support is solid and where it is thin. Where the sources on geothermal energy never arrived, the report says so:

"Section on geothermal energy is limited due to unavailable journal access during research."

The alternative is a report that simply covers geothermal lightly, which a reader will interpret as a judgement about the topic's importance rather than a gap in the research. Annotating turns an invisible omission into a known limitation, and only one of those can be followed up.

Local Recovery for Transient Failures

Transient failures belong to the subagent that hit them. Retries, fallback sources, degraded responses — all of it happens locally, and only what survives that treatment travels upward, carrying what was attempted and whatever partial results exist.

The benefit is structural. A coordinator that handles every transient failure of every subagent has to know each subagent's failure modes, which is knowledge that belongs where the failure occurs. Handling it locally leaves the coordinator dealing only with failures that are genuinely its problem.

Deep Dive

is_error — the API-level mechanism for signalling tool failure

At the Messages API level, tool failure has a specific, documented shape: "if the tool itself throws an error during execution... you can return the error message in the content along with \"is_error\": true," and "Claude will then incorporate this error into its response." Crucially, when a tool_result reports an invalid or missing-parameter call, "Claude will retry 2-3 times with corrections before apologizing to the user" — the model attempts local recovery on its own before giving up, which is the same principle this lesson's subagents apply at a higher level (retry locally, propagate only what survives).

Sourceplatform.claude.com › handle-tool-callsfetched 2026-07-30

Client tools vs server tools — who owns the error

Not every failure needs your is_error handling. Client tools (user-defined tools, and Anthropic-schema tools like bash/text_editor) "run in your application" — Claude responds with stop_reason: "tool_use", your code executes, and you return the tool_result including is_error on failure. Server tools (web_search, web_fetch, code_execution, tool_search) run on Anthropic's infrastructure instead, and "you do not need to handle is_error results for server tools" — Claude handles those failures transparently. Knowing which category a failing tool falls into determines whether your coordinator code is even responsible for catching the error at all.

Sources: https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview (client vs server tool split) · https://platform.claude.com/docs/en/agents-and-tools/tool-use/handle-tool-calls (is_error and server tool errors) (fetched 2026-07-30)

Errors compound in stateful, long-running agent systems

Anthropic's own multi-agent research system was built around the observation that "without effective mitigations, minor system failures can be catastrophic for agents... errors occur, we can't just restart from the beginning." Because agents hold state across many steps, a single unhandled failure doesn't stay local — it can propagate into a wasted multi-step trajectory. This is the production-grade justification for why silent suppression and workflow termination are both wrong: suppression hides the failure until it compounds invisibly, and termination throws away everything the system had already legitimately accomplished.

Sourceanthropic.com › multi-agent-research-systemfetched 2026-07-30

Resume-from-failure instead of restart-from-scratch

The documented fix at Anthropic is durable execution: "we built systems that can resume from where the agent was when the errors occurred." This is the architectural sibling of this lesson's "proceed with partial results" recovery decision — rather than discarding a partially-completed pipeline (workflow termination) or lying about it having succeeded (silent suppression), the system picks up from the last good state.

Sourceanthropic.com › multi-agent-research-systemfetched 2026-07-30

The prototype-to-production gap: one bad step derails the whole trajectory

Anthropic reports that "one step failing can cause agents to explore entirely different trajectories, leading to unpredictable outcomes," and that "the gap between prototype and production is often wider than anticipated" for exactly this reason. A coordinator that receives a generic "search unavailable" status has no way to tell whether the agent should retry, redirect, or continue with what it has — it can only guess, and guessing is how one failure metastasizes into a derailed trajectory. Structured error context (failure type, attempted action, partial results, alternatives) is the concrete fix that keeps a single failure from cascading.

Sourceanthropic.com › multi-agent-research-systemfetched 2026-07-30

Non-determinism means production tracing is required to diagnose failures

Because "agents make dynamic decisions and are non-deterministic between runs, even with identical prompts," Anthropic found that "adding full production tracing let us diagnose why agents failed and fix issues systematically," while monitoring "agent decision patterns and interaction structures—all without monitoring the contents of individual conversations." The same structured fields a coordinator needs for automated recovery (failure type, attempted query, partial results) are also what a human debugging the system after the fact needs — structured error context serves both real-time recovery and post-hoc diagnosis.

Sourceanthropic.com › multi-agent-research-systemfetched 2026-07-30

Quick Reference

Exam Traps

Practice Scenario

Build Exercise

Build a Structured Error Propagation System

Difficulty: Advanced (3/4)

50 minutes

1. Define a structured error schema with fields: failureType (transient/validation/business/permission), attemptedAction (tool, query, parameters), partialResults (array of any retrieved data), and alternativeApproaches (suggested recovery strategies)

Why: Structured error context enables intelligent coordinator recovery. The four elements give the coordinator everything it needs to decide: retry, try an alternative, proceed with partial results, or escalate. Generic error messages like search unavailable prevent all informed recovery.

You should see: A TypeScript interface or JSON schema with failureType as an enum of the four categories, attemptedAction as an object with tool/query/parameters, partialResults as an array, and alternativeApproaches as a string array. Each field should have a description explaining its purpose.

2. Implement a subagent that distinguishes access failures (timeout, connection error) from valid empty results (successful query, no matches) in its error reporting

Why: Conflating access failures with valid empty results is a critical error the exam tests directly. Access failures mean the query did not execute and should be retried. Valid empty results mean the query succeeded and found nothing, which IS the answer. Treating them the same leads to either never retrying when you should or wasting time retrying queries that will always return nothing.

You should see: A subagent function that catches exceptions (timeouts, connection errors) and reports them as access failures with shouldRetry: true, while successful queries returning no results are reported as success with an empty results array and shouldRetry: false.

3. Build local retry logic for transient failures within the subagent (3 retries with exponential backoff) before propagating to the coordinator

Why: Subagents should handle their own transient failures locally before escalating. This reduces coordinator complexity as the coordinator does not need to manage retry logic for every possible transient failure across every subagent. Only persistent failures that survive local retry should propagate.

You should see: A retry wrapper with exponential backoff (e.g., 1s, 2s, 4s) that attempts the operation up to 3 times before propagating the structured error to the coordinator. Partial results gathered before failure should be preserved across retries.

4. Create a coordinator that receives structured errors and decides between retry with modified query, alternative approach, or proceed with partial results

Why: The coordinator is the intelligent recovery decision-maker. With structured error context, it can make informed choices rather than applying blanket policies. This is the correct middle ground between silent suppression (ignoring failures) and workflow termination (killing the pipeline on one failure).

You should see: A coordinator function that examines the failure type, checks partial results, evaluates alternative approaches, and selects the appropriate recovery strategy. It should handle all four failure types differently and never silently suppress errors.

5. Add coverage annotations to synthesis output noting which findings are well-supported versus which topic areas have gaps due to unavailable sources

Why: Coverage annotations let the consumer know what the report covers fully and where there are known limitations. Without them, a gap looks like the topic was not relevant rather than the source being unavailable. This transparency is far better than silently omitting topics.

You should see: A synthesis output that includes a coverage section listing each topic area with its data quality status: well-supported, limited (with reason), or unavailable (with reason). Failed subagent topics should be explicitly noted, not silently omitted.

Sources

• Claude Certified Architect Foundations Exam Guide — Domain 5, Task Statement 5.3 — Anthropic
• Anthropic Multi-Agent Patterns — Anthropic
• Handle tool calls — Anthropic
• How we built our multi-agent research system — Anthropic

Appendix A — Build Exercise Step Hints

Progressive hints revealed by the "Stuck? Get a nudge" control on each step.

Step 1. Define a structured error schema with fields: failureType (transient/validation/business/permission), attemptedAction (tool, query, parameters), partialResults (array of any retrieved data), and alternativeApproaches (suggested recovery strategies)

Why: Structured error context enables intelligent coordinator recovery. The four elements give the coordinator everything it needs to decide: retry, try an alternative, proceed with partial results, or escalate. Generic error messages like search unavailable prevent all informed recovery.

You should see: A TypeScript interface or JSON schema with failureType as an enum of the four categories, attemptedAction as an object with tool/query/parameters, partialResults as an array, and alternativeApproaches as a string array. Each field should have a description explaining its purpose.

interface StructuredError {
  status: "error" | "partial_failure";
  failureType: "transient" | "validation" | "business" | "permission";
  attemptedAction: {
    tool: string;
    query: string;
    parameters: Record<string, unknown>;
  };
  partialResults: Array<{ title: string; source: string; retrieved: boolean }>;
  alternativeApproaches: string[];
  message: string;
}

from typing import Any, Literal, TypedDict


class AttemptedAction(TypedDict):
    tool: str
    query: str
    parameters: dict[str, Any]


class PartialResult(TypedDict):
    title: str
    source: str
    retrieved: bool


class StructuredError(TypedDict):
    status: Literal["error", "partial_failure"]
    failureType: Literal["transient", "validation", "business", "permission"]
    attemptedAction: AttemptedAction
    partialResults: list[PartialResult]
    alternativeApproaches: list[str]
    message: str

Step 2. Implement a subagent that distinguishes access failures (timeout, connection error) from valid empty results (successful query, no matches) in its error reporting

Why: Conflating access failures with valid empty results is a critical error the exam tests directly. Access failures mean the query did not execute and should be retried. Valid empty results mean the query succeeded and found nothing, which IS the answer. Treating them the same leads to either never retrying when you should or wasting time retrying queries that will always return nothing.

You should see: A subagent function that catches exceptions (timeouts, connection errors) and reports them as access failures with shouldRetry: true, while successful queries returning no results are reported as success with an empty results array and shouldRetry: false.

async function searchSubagent(query, dateRange) {
  try {
    const results = await searchDatabase(query, dateRange);
    if (results.length === 0) {
      // Valid empty result — query executed, no matches
      return {
        status: "success",
        results: [],
        message: "Query executed successfully. No matching records found.",
        shouldRetry: false
      };
    }
    return { status: "success", results, shouldRetry: false };
  } catch (error) {
    // Access failure — query did not execute
    return {
      status: "error",
      failureType: "transient",
      message: `Connection timeout after 30s: ${error.message}`,
      shouldRetry: true,
      attemptedAction: { tool: "search_database", query, parameters: { dateRange } },
      partialResults: [],
      alternativeApproaches: ["Retry with narrower date range", "Try alternative database"]
    };
  }
}

def search_subagent(query: str, date_range: dict) -> dict:
    try:
        results = search_database(query, date_range)
        if not results:
            # Valid empty result — query executed, no matches
            return {
                "status": "success",
                "results": [],
                "message": "Query executed successfully. No matching records found.",
                "shouldRetry": False,
            }
        return {"status": "success", "results": results, "shouldRetry": False}
    except Exception as error:
        # Access failure — query did not execute
        return {
            "status": "error",
            "failureType": "transient",
            "message": f"Connection timeout after 30s: {error}",
            "shouldRetry": True,
            "attemptedAction": {
                "tool": "search_database",
                "query": query,
                "parameters": {"dateRange": date_range},
            },
            "partialResults": [],
            "alternativeApproaches": [
                "Retry with narrower date range",
                "Try alternative database",
            ],
        }

Step 3. Build local retry logic for transient failures within the subagent (3 retries with exponential backoff) before propagating to the coordinator

Why: Subagents should handle their own transient failures locally before escalating. This reduces coordinator complexity as the coordinator does not need to manage retry logic for every possible transient failure across every subagent. Only persistent failures that survive local retry should propagate.

You should see: A retry wrapper with exponential backoff (e.g., 1s, 2s, 4s) that attempts the operation up to 3 times before propagating the structured error to the coordinator. Partial results gathered before failure should be preserved across retries.

async function withRetry(fn, maxRetries = 3) {
  let lastError = null;
  let allPartialResults = [];
  
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      const result = await fn();
      return result;
    } catch (error) {
      lastError = error;
      if (error.partialResults) {
        allPartialResults.push(...error.partialResults);
      }
      const delay = Math.pow(2, attempt) * 1000; // 1s, 2s, 4s
      await new Promise(resolve => setTimeout(resolve, delay));
    }
  }
  
  // All retries exhausted — propagate structured error
  return {
    status: "error",
    failureType: "transient",
    message: `Failed after ${maxRetries} retries: ${lastError.message}`,
    partialResults: allPartialResults,
    alternativeApproaches: ["Try alternative data source", "Proceed with partial results"]
  };
}

import time


def with_retry(fn, max_retries: int = 3):
    last_error = None
    all_partial_results = []

    for attempt in range(max_retries):
        try:
            return fn()
        except Exception as error:
            last_error = error
            all_partial_results += getattr(error, "partial_results", [])
            time.sleep(2**attempt)  # 1s, 2s, 4s

    # All retries exhausted — propagate structured error
    return {
        "status": "error",
        "failureType": "transient",
        "message": f"Failed after {max_retries} retries: {last_error}",
        "partialResults": all_partial_results,
        "alternativeApproaches": [
            "Try alternative data source",
            "Proceed with partial results",
        ],
    }

Step 4. Create a coordinator that receives structured errors and decides between retry with modified query, alternative approach, or proceed with partial results

Why: The coordinator is the intelligent recovery decision-maker. With structured error context, it can make informed choices rather than applying blanket policies. This is the correct middle ground between silent suppression (ignoring failures) and workflow termination (killing the pipeline on one failure).

You should see: A coordinator function that examines the failure type, checks partial results, evaluates alternative approaches, and selects the appropriate recovery strategy. It should handle all four failure types differently and never silently suppress errors.

async function coordinatorRecovery(error) {
  switch (error.failureType) {
    case "transient":
      if (error.partialResults.length >= 3) {
        return { action: "proceed_partial", data: error.partialResults };
      }
      if (error.alternativeApproaches.length > 0) {
        return { action: "try_alternative", approach: error.alternativeApproaches[0] };
      }
      return { action: "retry_modified", modification: "narrower query" };
    case "validation":
      return { action: "fix_query", details: error.message };
    case "permission":
      return { action: "alert_admin", details: error.attemptedAction };
    case "business":
      return { action: "escalate_human", context: error };
  }
}

def coordinator_recovery(error: dict) -> dict:
    failure_type = error["failureType"]
    if failure_type == "transient":
        # Partial results beat a blind retry — the work already done is kept.
        if len(error["partialResults"]) >= 3:
            return {"action": "proceed_partial", "data": error["partialResults"]}
        if error["alternativeApproaches"]:
            return {
                "action": "try_alternative",
                "approach": error["alternativeApproaches"][0],
            }
        return {"action": "retry_modified", "modification": "narrower query"}
    if failure_type == "validation":
        return {"action": "fix_query", "details": error["message"]}
    if failure_type == "permission":
        return {"action": "alert_admin", "details": error["attemptedAction"]}
    if failure_type == "business":
        return {"action": "escalate_human", "context": error}

Step 5. Add coverage annotations to synthesis output noting which findings are well-supported versus which topic areas have gaps due to unavailable sources

Why: Coverage annotations let the consumer know what the report covers fully and where there are known limitations. Without them, a gap looks like the topic was not relevant rather than the source being unavailable. This transparency is far better than silently omitting topics.

You should see: A synthesis output that includes a coverage section listing each topic area with its data quality status: well-supported, limited (with reason), or unavailable (with reason). Failed subagent topics should be explicitly noted, not silently omitted.

function addCoverageAnnotations(synthesis, subagentResults) {
  const coverage = subagentResults.map(result => {
    if (result.status === "success" && result.results.length > 0) {
      return { topic: result.topic, status: "well-supported", sources: result.results.length };
    }
    if (result.status === "partial_failure") {
      return { topic: result.topic, status: "limited", reason: `Only ${result.partialResults.length} of expected sources available` };
    }
    return { topic: result.topic, status: "unavailable", reason: result.message };
  });
  
  return {
    ...synthesis,
    coverageAnnotations: coverage,
    caveat: coverage.filter(c => c.status !== "well-supported")
      .map(c => `Section on ${c.topic} is ${c.status}: ${c.reason}`)
      .join("\n")
  };
}

def add_coverage_annotations(synthesis: dict, subagent_results: list[dict]) -> dict:
    coverage = []
    for result in subagent_results:
        if result["status"] == "success" and result["results"]:
            coverage.append(
                {"topic": result["topic"], "status": "well-supported",
                 "sources": len(result["results"])}
            )
        elif result["status"] == "partial_failure":
            coverage.append(
                {
                    "topic": result["topic"],
                    "status": "limited",
                    "reason": (
                        f"Only {len(result['partialResults'])} of expected sources available"
                    ),
                }
            )
        else:
            coverage.append(
                {"topic": result["topic"], "status": "unavailable", "reason": result["message"]}
            )

    # Naming the gap is the point: a silently shorter section reads as complete.
    return {
        **synthesis,
        "coverageAnnotations": coverage,
        "caveat": "\n".join(
            f"Section on {c['topic']} is {c['status']}: {c.get('reason')}"
            for c in coverage
            if c["status"] != "well-supported"
        ),
    }

Appendix B — Interactive Study Prompts

Two prompts to paste into Claude. B1 drills the judgement the exam actually measures; B3 reviews the code you wrote for the Build Exercise above. The exam simulator between them is the interactive quiz on this page.

B1. Concept Check — Discrimination Drill

B2. Exam Simulator

B3. Build Coach — Code Review

The Build Exercise and its hint ladder are already on this page. This prompt is for the one thing the page cannot do: review the code you actually wrote.