Debugging Claude Agents in Financial Services Workflows

The first time a Claude agent that reconciles ledger entries spun in a loop for nine minutes — re-fetching the same account balance forty times before its token budget ran out — I learned that debugging an agent is nothing like debugging a function. There was no stack trace. The model wasn't wrong about any individual step. It was wrong about the shape of the work, and the only evidence was a 200KB transcript of tool calls that all looked plausible in isolation. In a financial-services context, that ambiguity is expensive: a wrong tool call against a payments API isn't a failed unit test, it's a real side effect you may have to reverse.

This post is about making agent failures legible. Specifically the three that show up over and over when you build verifiable financial agents with the Claude Agent SDK: infinite or near-infinite loops, tool calls aimed at the wrong tool or the wrong moment, and hallucinated arguments — an account number, a date range, a currency code the model invented because the prompt left a gap. None of these are exotic. All of them are debuggable once you stop treating the agent as a black box and start treating its transcript as a structured log.

Why agent bugs hide better than ordinary bugs

A traditional bug is deterministic and local: same input, same crash, same line. An agentic bug is probabilistic and distributed across a trajectory. The same prompt can produce a clean five-step run on Monday and a thirty-step thrash on Tuesday because the model sampled a slightly different first move and never recovered. That non-determinism is why "it worked when I tried it" is meaningless evidence for an agent, and why your debugging tooling has to capture every run, not just the failing one you happened to notice.

The second reason agent bugs hide is that the failure and the cause are often far apart. A loop that surfaces at step 28 frequently originates in a tool description written at design time — a get_transaction tool whose docstring doesn't say what it returns when the transaction doesn't exist, so the model keeps retrying as if the empty result were a transient error. The visible symptom is the loop; the actual defect is a one-line schema omission. You will waste hours staring at step 28 if you don't have the discipline to walk the trajectory backward to the first surprising action.

A useful definition to anchor on: an agent failure mode is a recurring, classifiable pattern of incorrect agent behavior whose root cause lives in the prompt, the tool surface, or the model's reasoning rather than in any single deterministic line of code. Treating failures as a taxonomy — rather than as one-off mysteries — is what makes them tractable.

Building a transcript you can actually read

Before you can debug anything, you need the raw material. With the manual agentic loop in the Claude API, you control the loop, which means you control logging. On every turn, persist the full response.content (not just the text) along with response.stop_reason, the usage block, and a monotonic turn counter. Append each tool's tool_use_id, name, parsed input, and the result you fed back. Crucially, log the inputs as the parsed object — Claude 4.x models can vary JSON escaping in tool-call inputs, so never grep the serialized string; parse it and store the structured value.

The single most valuable derived signal is a per-tool call-count and an argument hash. If get_balance({"account": "A-1099"}) appears with an identical argument hash three times in one trajectory, you have a loop forming, and you want an alert at turn 3, not turn 40. Capturing this is cheap and turns the most expensive failure mode into a bounded one.

flowchart TD
  A["Agent turn N"] --> B{"stop_reason?"}
  B -->|end_turn| C["Done — emit transcript"]
  B -->|tool_use| D["Hash tool name + parsed args"]
  D --> E{"Hash seen >= 3x?"}
  E -->|Yes| F["Flag: loop forming — break & inspect"]
  E -->|No| G{"Args valid vs schema?"}
  G -->|No| H["Flag: hallucinated arg"]
  G -->|Yes| I["Execute tool, log result"]
  I --> A

Failure mode one: the loop

Loops come in two flavors. The identical loop repeats the same call with the same arguments — almost always because the tool result didn't change the model's information state. The fix is rarely "add a retry cap" (that just hides it); it's to make the result self-describing. If your lookup_invoice tool returns {} for a missing invoice, change it to return {"found": false, "reason": "no invoice with that id in period"}. The model loops because the empty object looks like a glitch worth retrying; the explicit negative result tells it to move on.

The drifting loop is subtler: slightly different arguments each time, often a date window the model keeps widening or a search term it keeps rephrasing, hunting for a record that doesn't exist. Here the defect is usually a missing exit condition in the instructions. Add an explicit stopping rule — "if two searches return no results, report that the record was not found rather than searching again" — and consider a server-side ceiling via task budgets so the model can see its own remaining budget and wind down gracefully instead of thrashing.

Failure mode two: the wrong tool call

Wrong-tool errors split into wrong selection and wrong timing. Wrong selection — calling refund_payment when the user asked for the refund status — is a tool-description problem nine times out of ten. When two tools have overlapping verbs, the model picks on vibes. Disambiguate in the descriptions, prescriptively: "Use get_refund_status to read state. Use issue_refund only to create a new refund; this moves money and is irreversible." Naming the side effect and its irreversibility measurably reduces mis-selection.

Wrong timing is when the right tool fires too early — before a required confirmation, or before reading the data it needs to parameterize the call. For high-stakes financial actions, the structural fix is to not rely on the model's timing at all: promote the action to a gated dedicated tool and run the manual loop so you can intercept the tool_use block, require a human or rules-engine approval, and only then execute. The model proposing a transfer and your harness deciding whether to honor it are two different responsibilities, and in finance they should stay separate.

Failure mode three: hallucinated arguments

A hallucinated argument is a syntactically valid tool input the model fabricated rather than derived — a routing number that passes a regex but corresponds to no real bank, a settlement date pulled from nowhere. These are the most dangerous failures in finance because they often succeed: the API accepts the call, the side effect lands, and nothing alerts until reconciliation. Your strongest defense is making fabrication structurally hard. Use strict: true on tools so inputs are schema-validated, constrain enumerable fields with enum (currency codes, account types), and validate every argument against a system of record in your tool handler before executing — reject with is_error: true and a clear message so the model corrects rather than guesses again.

When you do catch a hallucinated argument, walk the trajectory back to find where the value should have come from. Usually the model needed a fact it didn't have and the prompt implicitly invited it to fill the gap. The fix is to give it a retrieval tool for that fact and an instruction that it must look the value up rather than supply one — closing the gap at its source instead of patching the symptom.

Frequently asked questions

How do I reproduce an agent bug that only happens sometimes?

You can't make sampling deterministic, but you can replay deterministically. Persist the full message history and tool results from the failing run, then re-feed that exact transcript to inspect where the trajectory first diverged from a good run. Pair this with a small batch of repeated runs on the same prompt to estimate how often the failure fires — a bug that hits one run in twenty still needs a fix, and the frequency tells you how urgent.

Should I lower the effort parameter to stop overthinking loops?

Sometimes. Lower effort yields fewer, more consolidated tool calls and less exploratory thrashing, which can resolve drifting loops on simple tasks. But for genuinely multi-step reconciliation work, dropping effort too far causes under-thinking and a different class of error. Treat effort as a dial to sweep against your evals, not a fixed loop fix — and keep adaptive thinking on so the model interleaves reasoning between tool calls.

What's the fastest signal that a trajectory has gone wrong?

A per-tool argument-hash repeat count. It catches the most expensive failure (loops) at turn 3 instead of turn 40, costs almost nothing to compute, and doubles as a metric you can chart across runs to spot regressions after a prompt change.

Bring verifiable agents to your phone lines

The same trajectory-logging and failure-mode discipline that keeps a financial agent honest applies to voice. CallSphere builds voice and chat agents that answer every call, call tools mid-conversation, and stay debuggable end to end — see it live at callsphere.ai.

Source & attribution: This is an independent, original explainer inspired by Anthropic's coverage on the Claude blog. Claude, Claude Code, Claude Cowork, Claude Opus, and the Model Context Protocol are products and trademarks of Anthropic. CallSphere is not affiliated with or endorsed by Anthropic.