When a caller says the agent did not work, there are several possible failures hiding inside that sentence. The call may never have reached the agent, speech may have been misunderstood, or a business action may have failed after a perfectly understandable exchange.
I would preserve the call reference and reconstruct the event sequence before changing the prompt. A prompt edit cannot repair every part of a phone system.
What is voice-agent observability?
It is the evidence needed to understand how a session behaved: events, timings, tool activity and outcomes. Audio and transcripts can help, but access to them should follow the organization's data-handling choices.
The key is correlation. A phone event, an agent session and a customer-system operation can each have their own identifier. Store the references needed to move between them without copying sensitive content into every log.
A useful investigation follows one task across its boundaries:
Twilio call reference -> LiveKit session reference
|
v
Next.js operation reference
|
v
CRM record referenceThis is an illustrative integration map. Your actual services and identifiers may differ, but the records should still support the same investigation.
Write down what failed before collecting more logs
Start with a narrow expected outcome. For example: the caller should have reached the office, or a service request should have appeared in the staff inbox. Then state the observed outcome without explaining its cause yet.
That prevents an assumption from becoming the incident title. “The model ignored the caller” is already a diagnosis. “The caller's corrected address was absent from the saved request” leaves room to inspect the actual failure.
| Evidence | Question it helps answer |
|---|---|
| Carrier event | Did the call reach the configured destination? |
| Session timeline | Did the agent join, speak and receive input? |
| Recognition result | What words reached the conversation logic? |
| Tool arguments and response status | What operation was requested and what came back? |
| Saved record | What state did the business system actually retain? |
Keep content collection proportionate. A call reference and error category can be enough for an aggregate dashboard; a restricted investigation may require more detail.
Compare timing boundaries that mean the same thing
A slow greeting and a slow later reply are different experiences. Measure call pickup to first audible response separately from a normal turn. For later turns, define whether the clock starts at the last user audio, recognized end of turn, or another event.
Do not add overlapping timing spans and call the sum end-to-end latency. Check the documented metric boundaries, then compare like with like across releases.
LiveKit provides session traces and stage metrics for supported deployments. Its data hooks also expose session-level reports and other observation surfaces. Verify the current SDK's data shape before building a parser against it.
Turn a confirmed cause into a repeatable check
After locating the fault, preserve a fictional or properly redacted reproduction. Give it a clear expected outcome. Changing the original customer transcript into a reusable test should not expose private details in a repository.
My Voice Reliability Lab demonstrates a narrower idea: compare the conversation and requested action against the resulting record. It is not a replacement for carrier logs, runtime monitoring or a production incident process.
The lab can help frame the test you add after a repair. If the failure involved a dropped transfer, a text-only action test will not cover the phone route; keep an audio or routing check as well.
Questions about debugging voice agents
Should we record every call to diagnose failures?
Not automatically. Decide what is necessary, who can access it and how long it is retained. Metadata and structured outcomes can answer some questions without storing complete recordings.
Why can a transcript look correct while the result is wrong?
A transcript does not prove that the integration accepted the action or that the final record matches it. Inspect the response and saved state separately.
When should we change the prompt?
When the evidence points to instructions, interpretation or tool selection. If the carrier never connected the call or the API credential expired, fix that boundary instead.
For a diagnosis, bring the expected result, observed result and a redacted timeline. That is a more useful starting point than a screenshot saying the call failed.