CertSafari
    Anthropic Claude Certified Developer – Foundations (CCDV-F) - December 7 onwards· Lessons

    Domain 1 · Lesson 3/24

    Diagnosing agent failures from a trace

    Agent Pattern Diagnosis

    17 min read
    5.67% of exam
    9 sources
    Published 18 Nov 2026
    Docs as of 18 Nov 2026

    What you will be able to do

    • Read a misbehaving agent's trace and name the pattern that is missing or misapplied
    • Choose stop_reason-based termination over text matching and treat turn caps as a backstop
    • Fix tool-call thrash by returning instructive is_error results instead of bare error strings
    • Match context bloat, lost state and forgotten instructions to subagent isolation, memory, compaction or deterministic controls

    Key concept

    Structural signals over textual guesses — An agent loop is fixed by acting on the structured signals the runtime already gives you, such as stop_reason, is_error and the result subtype, and by choosing where information lives (subagent, memory file, re-injected config). Guessing from what the model wrote is not a fix. Most misbehaving agents ignore one of these signals or put information somewhere it gets lost.

    1.From symptom to missing pattern

    An agent is usually simple at its core, so most misbehaviour traces back to one missing pattern. An agent is a model calling tools in a loop and reading what comes back. Each pass adds tool results to the conversation, the model decides what to do next, and the loop ends when the model answers without calling a tool. When a run goes wrong, the trace shows you which part of that cycle failed: the exit, the feedback from a tool, the growth of context, or what the agent remembers.

    Diagnosis means mapping the symptom to the cycle. A run that ends halfway was stopped by the wrong exit test. A run that repeats one call until it hits its cap was getting tool feedback it could not act on. A run that slows down and loses focus over a long task is carrying too much context. An agent that forgets yesterday's decisions, or an instruction from an hour ago, kept that information somewhere that does not survive. Each symptom has its own corrective pattern, and the wrong pattern can make the trace look better while leaving the cause in place.

    Common trace symptoms and the pattern that corrects them
    Symptom in the traceMissing or misapplied patternCorrective pattern
    Run ends mid-task after the model writes a word like "complete"Termination keyed on textLoop while stop_reason is tool_use; finish on end_turn
    Identical tool call repeated until the turn capTool feedback the model cannot act ontool_result with is_error and an instructive message
    Main conversation swollen with file contents from researchNo context isolationDelegate the reads to a subagent; only its final message returns
    Agent forgets earlier work in a new conversationNo persistent memoryMemory tool files read back at task start
    Instruction from an early message ignored after summarizationInstruction stored only in conversation historyPut it in re-injected config, or enforce it with a hook

    Statelessness is the most basic missing pattern. Each model call sees only what you send. In the agent loop, Claude receives the system prompt, the tool definitions and the conversation history along with the prompt. A chat feature that sends each user message as a one-element messages array has dropped the history, so the assistant cannot recall anything said a minute earlier. The fix is to send back the accumulated conversation on every request.

    Checkpoint 1 of 9· Match them up

    Match each symptom seen in an agent trace to the pattern that corrects it

    Tap a term, then the definition that fits it.

    Sources12

    2.Loop termination: exit on stop_reason, not on text

    On the Messages API, a client-side tool loop is keyed on stop_reason. When Claude wants a tool run, the response comes back with stop_reason: "tool_use" and one or more tool_use blocks. Your code runs each tool, sends the results back as tool_result blocks, and repeats. Any other stop reason (end_turn, max_tokens, stop_sequence, refusal) exits the loop. Only end_turn means Claude produced its final answer. The others mean it stopped for a reason your application has to handle. max_tokens, for example, means the response was cut off, not that the task is done.

    Every text-based exit has the same flaw. A rarer marker such as <<TASK_FINISHED>> makes false matches less likely, but the exit still depends on what the model chose to write, not on whether it asked for a tool. A second model call that judges whether the text "reads like a final answer" adds cost, plus a new guess, on top of a signal the API already provides. A fixed five-iteration limit is worse: a task that needs seven tool rounds always ends with two of them undone.

    A turn or budget cap is still useful, as a backstop rather than as the exit. Anthropic's guidance on agents notes that tasks usually end on completion, but that it is common to add stopping conditions such as a maximum number of iterations to keep control. In the Agent SDK, a run that hits the cap ends with a result whose subtype says so. error_max_turns means the run hit the maxTurns limit before finishing, and error_max_budget_usd is the cost equivalent. Neither of these results has a result field, so read the subtype before you treat the output as an answer.

    Agent SDK (TypeScript): distinguish a finished run from one that hit a limit by checking the result subtypetypescript
        if (message.type === "result") {
          if (message.subtype === "success") {
            console.log(message.result);
          } else {
            console.log(`Stopped: ${message.subtype}`);
          }
        }

    One more stop reason looks like an ending but is not. Server-executed tools such as web search run their own loop on Anthropic's infrastructure, and that loop has an iteration limit. If the model is still working when it reaches the limit, the response arrives with stop_reason: "pause_turn". The work is unfinished: send the conversation back, including the paused response, so the model can carry on.

    Checkpoint 2 of 9· Check yourself

    A request with web search enabled comes back with stop_reason "pause_turn" and a partly written reply. What should the application do next?

    Checkpoint 3 of 9· Check yourself

    An Agent SDK run with maxTurns set ends with a result message whose subtype is error_max_turns. How should your code handle it?

    Checkpoint 4 of 9· Exam question

    Which stop_reason on a Messages API response tells an agent loop that the model wants a tool executed and the loop should continue?

    Checkpoint 5 of 9· Exam question

    A loop built on the Messages API stops whenever the assistant's text contains the word "complete". In production the model sometimes writes "Step one is complete, now checking the tests", and the run ends with half the work undone. What is the correct termination pattern?

    Sources321

    3.Tool-call thrash: give the agent an error it can act on

    An agent that repeats the same failing call is usually getting feedback it cannot use. Suppose a lookup_order tool returns the bare string "error" whenever an order ID is malformed. The model learns that something failed, but not what to change. With nothing to adjust, it sends the same ID again and keeps doing so until the turn cap stops it. The loop is behaving correctly: it runs tools while the model asks for them. The broken part is the content going back into the loop.

    The fix is a tool_result that marks the failure and explains it. Set is_error: true and use the content to say what went wrong. For the order lookup, that means stating the ID format and giving a valid example. When a tool result reports an error, Claude will try the tool again with the missing or corrected information. If the call failed because the model lacked information, such as a missing parameter, a longer-term fix is to write more detailed descriptions in the tool definition. Error messages are covered in more depth under tool response shaping.

    A tool_result that tells Claude the call failed and whyjson
    {
      "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
        }
      ]
    }

    The tempting fixes all leave the uninformative feedback in place. Raising the cap from 25 to 100, or adding a delay between retries, just pays for more identical calls. A system-prompt rule allowing two calls per tool stops the thrash sooner, but the agent still never learns the correct ID format, so the task fails anyway. Splitting the tool into three tools by order type, each with its own short error string, multiplies the problem by three.

    Checkpoint 6 of 9· Check yourself

    In a trace, the agent calls lookup_order with the same malformed order ID on every turn. Each time, the tool returns the bare string "error". This repeats until the run reaches its turn cap. Which change fixes the cause rather than the symptom?

    Checkpoint 7 of 9· Exam question

    A support agent calls lookup_order, and the tool returns the bare string "error" whenever the order ID is malformed. The trace shows the agent retrying the identical call with the same ID 25 times until it hits its turn cap. Which change best corrects this behavior?

    Sources4

    4.Context growth: isolate work in subagents

    Context grows with every turn of a loop. Each file read, search result and command output stays in the conversation and is sent again on every later request. A research step that reads dozens of files leaves all of that text in the main agent's context long after the research is finished. The result is slower, more expensive turns and an agent that struggles to find the details that still matter.

    Subagent isolation is the corrective pattern. Each subagent runs in its own conversation. Its intermediate tool calls and results stay inside it, and only its final message comes back to the parent. A research subagent can explore many files while the parent receives a short summary instead of every file it read. Isolation also helps in two other ways. Independent subagents can run in parallel, and each one can be limited to specific tools, so a reviewer given only Read and Grep cannot change the files it analyses.

    Isolation only works if the result that comes back is small. A subagent definition that has no tools list inherits every tool available to subagents, and one with no maxTurns has no limit of its own on agentic turns. When a delegated task returns too much or runs away, look at what the subagent definition is missing. Writing the definitions themselves is the subject of Agent SDK construction.

    Checkpoint 8 of 9· Match them up

    A team's subagent setup shows each of the problems below. Pair each problem with the change that addresses it.

    Tap a term, then the definition that fits it.

    Sources56

    5.Lost state: memory, compaction and instructions that survive

    State lost between conversations points to a missing memory pattern. The memory tool lets Claude create, read, update and delete files in a memory directory that persists between sessions. When the tool is enabled, Claude checks that directory before it starts a task. It writes down what it learns as it works and reads those files back in later conversations. Information is loaded only when it is needed, which also keeps the active context focused on the current task. An agent that starts every session with no idea what it decided yesterday is missing exactly this.

    State lost within one long session is a context-management problem. Compaction replaces older turns with a summary so a long agent task fits in the context window. It also keeps the active context small, because response quality degrades as the conversation grows. In Claude Code, running /clear between unrelated tasks stops old conversation from crowding out the files needed next. The strategies are taught in full in context management for long-running sessions. The diagnostic point is what does and does not survive a summary.

    What survives automatic compaction in Claude Code
    Where the information livesAfter compaction
    System prompt and output styleBoth still apply
    Project-root CLAUDE.md and unscoped rulesRe-injected from disk
    Auto memoryRe-injected from disk
    Context that hooks added earlierSummarized with the rest of the conversation
    Instructions given in conversation messagesSummarized with the rest of the conversation

    This table explains a common trace. An agent was told in its first user message never to modify files under /legacy. After automatic summarization it edits one anyway, because that instruction lived only in conversation history and the summary dropped it. Moving the rule into the project-root CLAUDE.md fixes this, because that file is re-injected from disk after compaction. If a rule must hold no matter what the model remembers, such as never running rm -rf on production paths, a prompt is the wrong mechanism. Hooks can intercept and block tool calls before they run, which is the deterministic guardrail pattern.

    Checkpoint 9 of 9· Match them up

    An agent's rules and notes can live in different places. Pair each place with what happens to its contents when the conversation is compacted or a new session starts.

    Tap a term, then the definition that fits it.

    Sources7891

    Sources

    (9)

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

    1. 1.
      “Claude receives your prompt, along with the system prompt, tool definitions, and conversation history.”
      ↩︎ From symptom to missing pattern
      “Hit the maxTurns limit before finishing”
      ↩︎ Loop termination: exit on stop_reason, not on text
      “You can use hooks to intercept, modify, or block tool calls before they run.”
      ↩︎ Lost state: memory, compaction and instructions that survive
      “Claude continues calling tools and processing results until it produces a response with no tool calls.”
      ↩︎ Key concept
      “Check the subtype field to determine whether the task succeeded or hit a limit.”
      ↩︎ Exam trap 3
      “Check the subtype field to determine whether the task succeeded or hit a limit.”
      ↩︎ Checkpoint
      “Each set of tool results feeds back to Claude for the next decision.”
      ↩︎ Checkpoint
    2. 2.
      “They are typically just LLMs using tools based on environmental feedback in a loop.”
      ↩︎ From symptom to missing pattern
      “include stopping conditions (such as a maximum number of iterations) to maintain control.”
      ↩︎ Loop termination: exit on stop_reason, not on text
    3. 3.
      “Claude responds with stop_reason: "tool_use" and one or more tool_use blocks.”
      ↩︎ Loop termination: exit on stop_reason, not on text
      “or stopped for another reason that your application should handle”
      ↩︎ Loop termination: exit on stop_reason, not on text
      “If the model is still iterating when it hits the cap, the response comes back with stop_reason: "pause_turn" instead of "end_turn".”
      ↩︎ Exam trap 1
      “In practice this reads as: while stop_reason == "tool_use", run the tools and continue the conversation.”
      ↩︎ Prediction
      “A paused turn means the work isn’t complete; re-send the conversation (including the paused response) to let the model continue where it left off.”
      ↩︎ Checkpoint
    4. 4.
      “you can return the error message in the content along with "is_error": true”
      ↩︎ Tool-call thrash: give the agent an error it can act on
      “The best approach during development is to try the request again with more-detailed description values in your tool definitions.”
      ↩︎ Tool-call thrash: give the agent an error it can act on
      “and Claude will attempt to use the tool again with the missing information filled in”
      ↩︎ Exam trap 2
    5. 5.
      “intermediate tool calls and results stay inside the subagent; only its final message returns to the parent.”
      ↩︎ Context growth: isolate work in subagents
      “The parent receives a concise summary, not every file the subagent read.”
      ↩︎ Context growth: isolate work in subagents
      “If omitted, inherits every tool available to subagents”
      ↩︎ Context growth: isolate work in subagents
      “intermediate tool calls and results stay inside the subagent; only its final message returns to the parent.”
      ↩︎ Checkpoint
      “A doc-reviewer subagent might only have access to Read and Grep tools, ensuring it can analyze but never accidentally modify your documentation files.”
      ↩︎ Checkpoint
    6. 6.
      “An agent running in a loop generates more and more data that could be relevant for the next turn of inference”
      ↩︎ Context growth: isolate work in subagents
    7. 7.
      “When the memory tool is enabled, Claude automatically checks its memory directory before starting a task.”
      ↩︎ Lost state: memory, compaction and instructions that survive
    8. 8.
      “it keeps the active context small, because response quality degrades as a conversation grows.”
      ↩︎ Lost state: memory, compaction and instructions that survive
    9. 9.
      “Old conversation crowds out the files you need next and costs tokens on every message.”
      ↩︎ Lost state: memory, compaction and instructions that survive
      “Summarized with the rest of the conversation”
      ↩︎ Exam trap 4
      “Project-root CLAUDE.md and unscoped rules | Re-injected from disk”
      ↩︎ Checkpoint

    Ready to test yourself?

    Practise Anthropic Claude Certified Developer – Foundations (CCDV-F) - December 7 onwards in quiz mode.

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