Documentation / Agent troubleshooting
Agent troubleshooting
Identify the failing step and verify a fix with a new test.
Start with the run where the problem occurred. Record the agent, time, channel, question and expected result. This separates audio, instruction, tool and configuration failures.
Voice and connection
| Symptom | First step |
|---|---|
| Microphone blocked | Grant microphone access for the origin and use HTTPS or localhost |
| Connected but no sound | Check output device, volume and another device |
| Incorrect transcript | Test in a quiet environment and check language/STT |
| Replies during a pause | Review turn-stop settings |
| Ends early | Check inactivity, available duration and end-call tool |
Compare voice with a text test. If text works and voice does not, investigate audio before rewriting all instructions.
Tools and documents
If the agent does not call an API, check that the tool is attached to the agent, has a clear description and received required parameters. If it executes but fails, review URL, timeout, credential and service response.
If document information is missing, confirm processing and attachment to the agent. Ask a question explicitly answered by the document. Uploading a file to the workspace does not select it in the agent settings.
Telephony
For inbound calls, check the number, provider and associated agent. Review telephony setup before investigating the prompt.
Version and result
If changes do not appear in new conversations, check the published version. Compare the transcript and tool calls with the agent's goal before adjusting the prompt.
Verify the fix
Change one thing at a time and repeat the same scenario. Keep identifiers for both the failing and corrected runs. When contacting support, send those identifiers and the failing step, without API keys or credentials.