Skip to main content

Troubleshoot voice agents

Diagnose from the outside inward: delivery, lifecycle version, audio pipeline, instructions and context, actions, then post-call processing.

The agent cannot be created​

Confirm the workspace has capacity under its agent limit and your role has agent-management permission. In the current creation dialog, select Inbound; Outbound Agent is marked Soon and cannot be selected.

Changes disappear or do not reach live calls​

Check the editor save state first. If it shows Save failed, retry before leaving. If the draft test is correct but the phone call is old, publish the draft and place a new call. Live traffic does not read unpublished edits.

Publish is blocked​

Read the validation error and prompt warning list. Common causes include an unavailable model, incompatible architecture settings, a missing required voice, an undefined variable, an unattached function, or a disconnected integration.

Start Agent fails​

An inbound agent needs both a published version and an assigned phone number. Confirm the number belongs to the same workspace and is not assigned elsewhere.

The number rings but the agent does not handle the call​

Confirm:

  • the exact number is assigned to this agent;
  • the agent is Active;
  • the workspace has an eligible subscription and usable credits;
  • billing is not payment-locked; and
  • concurrent-call capacity is available.

Then inspect the call record for a rejection or incomplete status.

The agent hears the caller incorrectly​

Compare audio with the transcript. Verify primary language, Modular speech-recognition provider, key terms, and background conditions. If bilingual, verify the architecture supports the configured secondary-language behavior.

The agent interrupts or responds too slowly​

Tune Response Speed, Words to Interrupt, filler words, and prompt response length. Realtime and Modular pipelines expose different controls. Test with natural pauses and speaker echo, not only clean scripted audio.

The agent invents facts​

Remove unsupported facts from the prompt and variables, inspect knowledge extraction and retrieval, define a source hierarchy, and add an explicit missing-evidence response. Knowledge attachment alone does not enforce grounding.

The function is attached but never runs​

Confirm the published version includes it, the integration is connected, and the prompt contains its exact [[Function: name]] marker plus trigger, required inputs, confirmation, success, and failure rules.

The agent claims an action succeeded when it did not​

Change the prompt so success can be stated only after a successful function result. Test failure and empty-result paths. Inspect the integration destination instead of relying only on spoken confirmation.

The call ends unexpectedly​

Review configured silence and duration controls, workspace credits, payment state, provider events, transfer behavior, and the system safety limit. A disabled configured duration limit does not mean a call can run indefinitely.

Credits differ from the editor estimate​

Confirm whether the call used the current published version. Compare answered duration, published per-minute rate, aggregation or rounding, and separately priced functions or delivery services.

Evidence to collect​

Record the workspace, agent ID, assigned number, published version, call ID, approximate time and timezone, caller/callee numbers with unnecessary digits redacted, expected behavior, observed transcript, function name, and any visible error. Never include credentials.