How to Use Claude Code to Find and Fix Failed Voice Agent Calls

What failure actually looks like in a voice agent

Voice agents rarely fail with an error. They fail by completing a call badly, which is why the problem hides.

The recurring shapes are worth naming, because they need different fixes. There is the knowledge gap, where the caller asked something the agent had no source for and it improvised. There is the flow break, where the agent got the facts right but never reached the outcome, no booking made, no ticket created, no transfer completed. There is the tool failure, where an integration returned an error or timed out and the agent talked around it instead of surfacing it. There is the handoff failure, where escalation was needed and did not happen, or happened without any context reaching the human. And there is the loop, where the agent and caller circle the same misunderstanding until someone gives up.

Your metrics dashboard usually shows the last one as a long call and the rest as successes. That is the gap Claude Code fills: not counting calls, but reading them.

Give the agent evidence, not controls

Before wiring anything up, decide what the agent can touch. The useful and safe configuration is broad read access and no write path to anything live.

Read: call transcripts with timestamps and speaker labels, structured logs, tool and API traces with request and response payloads, the current prompt and flow configuration, and any post-call disposition data you already record. That is enough to reconstruct what happened in almost every failed call.

Write: files in your repository. Analysis notes, a proposed prompt diff, a test case, a knowledge document. Nothing that reconfigures a running agent, nothing that dials out, nothing that touches a customer.

That boundary is not just risk management, it also makes the output better. An agent that must justify a change in a written proposal produces a reviewable argument. An agent with permission to hot-patch production produces changes nobody understands two weeks later.

The triage loop

Run it as four stages, with a data artifact between each one, so you can inspect and rerun any stage independently.

First, classify. For each failed call, the agent reads the transcript and trace and emits a small structured record: failure category, the turn where it went wrong, the caller intent, a one-line description, and a confidence score. Force a fixed category list and require an unknown option, because a model given only five categories will always find a way to use one.

Second, cluster. Group those records by cause and intent. This is the step that turns noise into engineering work. Two hundred distinct-looking bad calls usually collapse into six or seven recurring causes, and the largest cluster is almost never what the team assumed it was.

Third, propose. For the top clusters, the agent writes what specifically would prevent the failure, and identifies which kind of fix applies: a flow change, an integration fix, a missing escalation path, or a missing piece of knowledge. Each proposal cites the calls it is based on so you can check the reasoning against real transcripts.

Fourth, test. Turn each cluster into a regression case with the caller's actual utterance and the correct outcome. Now you have a suite the next configuration change has to survive, which is the difference between fixing this week's problem and preventing its return.

Most failures are missing knowledge, not bad prompts

The instinct after triage is to rewrite the system prompt. It usually does not work, and it is worth understanding why.

When a caller asks about an edge case in your return policy, a rare plan configuration, or something specific to their account type, no amount of instruction tuning helps if the answer is not available to the agent. The model has nothing to retrieve, so it produces something plausible. You then add a line to the prompt covering that case, and the next unusual question produces the same failure. The prompt grows, latency grows, and the underlying gap never closes.

The durable fix is to make the answer available. RDK indexes your policy documents, product notes, and internal runbooks from local vaults as encrypted private chunks on the RDK network. The voice agent searches those chunks before it answers, so a policy question returns your actual policy rather than a fluent guess. Encryption matters here, because this is exactly the material you cannot paste into a public prompt library.

The cost side moves in the same direction. With stacked retrieval, a private index answers 40 to 65 percent of queries, the public network of published chunks adds another 15 to 20 percent, and the LLM handles the remaining 5 to 10 percent as fallback, so token spend drops 80 to 90 percent. For a voice deployment running thousands of calls a day, that is the difference between a per-call cost that scales painfully and one that does not.

Close the loop so the same call never fails twice

Triage that ends in a fix list is a one-time cleanup. Triage that ends in indexed knowledge compounds.

When you resolve a cluster, write the resolution as a short document: the question callers actually asked, in their words, and the correct answer with any conditions attached. Index it. The next time that question arrives, the voice agent retrieves your answer instead of improvising, and it never becomes a failed call in the first place.

Run the triage pass on a schedule, weekly is usually enough, and track the shape of the clusters rather than a single quality score. A cluster that shrinks after you indexed its answer tells you the loop is working. A new cluster appearing tells you something changed upstream, a new promotion, a new plan type, a policy update, and it tells you before the complaints arrive.

The result is not an agent that fixes itself. It is a system where every failure you diagnose becomes knowledge the agent can retrieve, which is the only version of this that gets better instead of just staying maintained.