Anthropic CCA-F: Debugging Agent Loops
An agent loop can produce a convincing final answer while failing badly along the way. It might search the same source repeatedly, recover from an error by making it worse, or announce that an action succeeded without receiving proof. Debugging such a run requires looking at its sequence of decisions and effects—not just the final paragraph Claude wrote.
The useful question is operational: when a Claude agent stalls, retries or loses state, what evidence tells the engineer where it failed and what it is safe to do next? The method below treats the loop as a stateful application with observable steps. It does not prescribe a specific agent framework, model version or certification exam.
Imagine a fictional field-service assistant investigating an intermittent network fault at a branch office. It may read diagnostics and propose a technician visit, but an operations lead must approve the exact site and time window before a visit is booked. The scheduling API times out after the host has recorded an attempted booking. Claude later announces that a technician is confirmed, although no booking receipt has reached the application. That statement must remain unverified until the scheduler provides an authoritative result.
| Trace time* | Event | What the system knows | Safe next action |
|---|---|---|---|
| 10:02:11 | Authorized network-health lookup succeeds | Site identifier and outage context observed | Prepare evidence |
| 10:02:16 | Technician visit proposal recorded | Proposed site and time window exist; no visit booked | Request approval |
| 10:03:02 | Lead approves exact site, slot and visit type | Approved proposal version is stored in trusted application state | Dispatch once |
| 10:03:04 | Dispatch attempt recorded; scheduler request times out | Completion is unknown, not disproved | Query booking by stable operation ID |
| 10:03:15 | Scheduler confirms booking | One durable visit-booking ID exists | Notify requester using confirmed booking ID |
*Illustrative timestamps and records; this is neither a real service visit nor a production incident.
The fourth row is the failure: the client lacks an acknowledgement, not proof that the booking failed. Replaying the request from Claude’s guess could schedule a second technician or reserve the same time twice. Recovery starts with the durable attempt ID and the scheduler’s documented status semantics. A failed lookup does not establish non-execution if the service is eventually consistent.
Conversation history is useful context, but it is not a transaction ledger. A restart, truncation, summarization or agent handoff may drop a detail that matters for safety. Persist a small structured state object containing the active case, approved proposal version, last dispatched operation and known result.
| State | What it means | Allowed transition |
|---|---|---|
collecting_evidence |
Only read calls permitted | Propose a bounded action or stop |
awaiting_approval |
Proposal exists, write blocked | Approval or rejection recorded |
dispatch_attempt_recorded |
Host recorded a side-effecting attempt before calling the scheduler | Confirm external outcome or hold; recording is not proof of delivery |
outcome_unknown |
No definitive completion evidence | Status lookup, escalation or safe hold |
committed |
Durable result independently confirmed | Explain outcome; do not write again |
stopped |
Budget, permission or evidence limit reached | Human or deterministic recovery path |
States should not be set merely because Claude chooses a persuasive phrase. The application assigns them from verified operations. A human approval should bind to exact parameters, not a general request that can silently change. If the proposed site, visit slot, assigned resource or scope changes, invalidate the old approval and check authority again before dispatch.
This separation also makes a failed run resumable. A fresh process can load the approved proposal and last operation ID without asking the model to infer what happened from a compressed conversation summary.
Not every failure deserves another tool call. An authorization denial is different from a temporary network error; stale evidence is different from a malformed schema; repeated searches that return nothing new are different from searches still narrowing a question.
| Observed symptom | Likely failure class | Better response than “try again” |
|---|---|---|
| Tool arguments fail validation | Contract or input error | Check required fields and source values; stop on repeated identical invalid input |
| Correct request is denied | Permission or policy boundary | Escalate through authorized workflow; do not rephrase to bypass |
| Three searches return the same evidence | No progress / tool-selection problem | Stop or switch to a genuinely distinct permitted source |
| Read service returns a transient error | Availability problem | Bound retries and backoff only for repeatable reads |
| Write request loses acknowledgement | Uncertain side-effect outcome | Query durable status; do not blindly replay |
| Agent uses superseded policy text | Context/version hygiene failure | Load authoritative source version and invalidate stale assumptions |
In each row, the log should expose the observation on which the classification rests. “The model felt stuck” is not a diagnostic category. “Same search tool, same arguments, same result digest on three consecutive attempts” is something an operator can verify and test.
A sound retry policy depends on the operation. A read-only lookup that times out before returning data may be safe to repeat under rate and resource limits. A booking request may already have committed. Where the scheduler enforces idempotency for a documented operation key, use that contract; merely sending an arbitrary key offers no protection. Otherwise, prefer a status lookup and reconciliation process over an automatic second dispatch.
The following is application-level pseudocode, not executable Claude SDK code:
if read_call_failed_transiently:
retry_read_with_limit_and_backoff()
elif booking_attempt_recorded and acknowledgement_missing:
state = "outcome_unknown"
observed = scheduler.lookup_by_operation_id(operation_id)
if observed.confirmed and observed.booking_id:
state = "committed"
report_confirmed_booking(observed.booking_id)
else:
stop_and_escalate_for_reconciliation()
elif request_denied_by_policy:
stop_without_retrying()
A missing booking ID or a “not found” lookup is not automatically permission to retry: the scheduler may be delayed or the result may be cached. A new dispatch is allowed only after the service can establish safe retry semantics and the original approval remains valid, or after an authorized person reconciles the case. Otherwise the correct state stays unknown.
A debugger cannot reconstruct a run from a free-text “tool failed” message. The application needs an operation ID, a typed result state and clear write-authority checks; reliable Claude tool contracts define that interface. This article tests how the running agent and host behave when the interface becomes ambiguous.
“Stop when finished” is not a useful production rule. The host should know how to recognize completion or when to abandon automatic work. A case might be complete only when required evidence fields are present, the approved visit has a confirmed booking ID, and the final response accurately reflects that status.
Other stop reasons matter just as much: a maximum tool-call count, time limit, cost budget, repeated identical errors, missing access, conflicting evidence, or a pending human decision. A stopped run is not necessarily a failed product. Refusing to continue without authority may be the correct outcome.
When testing termination, induce the problem deliberately. Make the same search return the same record, deny access to a needed tool, create an unavailable downstream dependency or change an approved action’s parameters after review. The application should stop predictably and expose an intelligible reason to the operator.
An actionable agent trace identifies the run ID, step number, tool selected, input class or safe digest, permitted scope, result status, latency, retry count, evidence reference and state transition. Logs should redact secrets, user tokens and sensitive customer data. A thousand-line transcript is not inherently better than a few well-structured events that reveal why the run changed state.
Model-generated explanations belong beside—not in place of—the operational trace. The final answer “visit booked” is truthful only when the scheduling service supplies a confirmed visit identifier. An evaluator should inspect the trajectory as well as the end state: Which tools were chosen? Were results used appropriately? Did the agent repeat failed calls? Did it cross a permission boundary? Did it present an unverified assertion as completed work?
Long conversations introduce a separate failure risk. A task can be resumed with outdated retrieved material, obsolete approvals or a previously rejected plan if summaries fail to preserve source currency. Store a compact, versioned evidence record: authoritative document ID, retrieval date, active constraints, unresolved questions, and the latest verified operation state. Discard stale working notes from the active decision context without deleting the audit trail. This is different from simply maximizing context length; comparing retrieval with long-context approaches is useful only when it changes the decision’s evidence quality.
Multi-agent systems create extra places where state can be misunderstood. A research agent may pass sources to a planning agent; a planning agent may recommend an action; an execution service may possess a narrow write capability. The research agent should not be able to authorize the final write by supplying a confident summary.
A handoff should include the task identifier, evidence version, known facts, unresolved assumptions and any narrowly scoped approval reference. The receiver validates the payload rather than inheriting the sender’s privileges. If the handoff is incomplete, the safe behavior may be to stop and ask for a controlled retry or human review.
Good human-review boundaries for Claude agents specify when an automated run must pause before a consequential action. In a debugging trace, that pause must be visible as a state transition; an absent approval should block execution even if the model thinks the next step is obvious.
A pilot can succeed on a friendly task and still fail when a real tool returns a surprising result. The following tests are more diagnostic than checking whether the assistant produces a fluent final answer.
| Injected condition | Expected observation | Release acceptance |
|---|---|---|
| Search returns identical evidence three times | No-progress counter rises | Run stops or selects a genuinely different authorized source |
| Approved site or time window changes after review | Approval/version mismatch | Write remains blocked pending new authorization |
| Booking attempt times out while scheduler may commit | Outcome temporarily unknown | Status lookup confirms one booking and no repeated dispatch |
| Tool output contains instruction-like content | Lower-trust evidence is identified | Instruction cannot alter permission or tool rules |
| Long conversation contains superseded policy | Old and current versions disagree | Source priority/version check prevents stale action |
| Budget expires midtask | Explicit stop reason | No hidden retry, and unresolved state is reported accurately |
Track the rates of repeated tool calls, ambiguous side-effect outcomes, false completion claims, unauthorized proposals and manual recovery. A decrease in tool count alone is not an improvement if evidence quality falls. The goal is a run that remains truthful and bounded when the model, integration or source content is imperfect.
A recovered agent is not one that merely reaches a conclusion after an error. It is one for which the application can show the last trustworthy event, the reason for the fault, the exact state that survived, the control used before retrying or escalating, and the evidence behind the final claim. If the outcome cannot be established, it should remain marked unknown.
That discipline makes loops easier to debug and safer to operate. Claude can contribute planning and interpretation, while the application remains responsible for transitions, permissions, commitments and the records needed to explain what actually happened.