diff --git a/fern/debugging.mdx b/fern/debugging.mdx new file mode 100644 index 00000000..2adce35a --- /dev/null +++ b/fern/debugging.mdx @@ -0,0 +1,179 @@ +--- +title: Debugging voice agents +subtitle: Learn to identify, diagnose, and fix common issues with your voice assistants and workflows +slug: debugging +--- + +## Overview + +Voice agents involve multiple AI systems working together—speech recognition, language models, and voice synthesis. When something goes wrong, systematic debugging helps you quickly identify and fix the root cause. + +**Common debugging scenarios:** +- Agent doesn't understand user input correctly +- Responses are inappropriate or inconsistent +- Call quality issues or audio problems +- Tool integrations failing or returning errors +- Workflow logic not executing as expected + +## Quick diagnostics + +Start with these immediate checks before diving deeper: + + + + Test your voice agent directly in the [dashboard](https://dashboard.vapi.ai/): + + - **Assistants**: `Dashboard > Assistants > [Select Assistant] > Talk to Assistant` + - **Workflows**: `Dashboard > Workflows > [Select Workflow] > Call` + - Eliminates phone network variables + - Provides real-time transcript view + - Shows tool execution results immediately + + + Navigate to the `Observe` section in your [dashboard](https://dashboard.vapi.ai/) sidebar: + + - **Call Logs**: Review call transcripts, durations, and error messages + - **API Logs**: Check API requests and responses for integration issues + - **Webhook Logs**: Verify webhook deliveries and server responses + + + Use [dashboard](https://dashboard.vapi.ai/) testing features: + + - **Voice Test Suites**: `Test > Voice Test Suites` (assistants only) + - **Tool Testing**: `Tools > [Select Tool] > Test` with sample payloads + + + Check if AI service providers are experiencing issues: + + - Visit [Vapi Status Page](https://status.vapi.ai/) for real-time provider status + - Review speech-to-text, language model, and voice synthesis availability + - Check for ongoing maintenance or outages + + + +## Dashboard debugging resources + +The [Vapi dashboard](https://dashboard.vapi.ai/) provides powerful debugging features to help you identify and fix issues quickly: + +### Call Logs + +Navigate to `Observe > Call Logs` to: +- Review complete call transcripts +- Check call duration and completion status +- Identify where calls failed or ended unexpectedly +- See tool execution results and errors +- Analyze conversation flow in workflows + +### API Logs + +Navigate to `Observe > API Logs` to: +- Monitor all API requests and responses +- Check for authentication errors +- Verify request payloads and response codes +- Debug integration issues with external services + +### Webhook Logs + +Navigate to `Observe > Webhook Logs` to: +- Verify webhook deliveries to your server +- Check server response codes and timing +- Debug webhook authentication issues +- Monitor event delivery failures + +### Voice Test Suites + +Navigate to `Test > Voice Test Suites` to: +- Run automated tests on your assistants (not available for workflows) +- Test conversation flows with predefined scenarios +- Verify assistant behavior across different inputs +- Monitor performance over time + +### Tool Testing + +For any tool in your `Tools` section: +- Navigate to `Tools > [Select Tool]` +- Use the `Test` button to send sample payloads +- Verify tool responses and error handling +- Debug parameter extraction and API calls + +## Speech and language issues + +| Problem | Symptoms | Solution | +|---------|----------|----------| +| **Transcription accuracy** | Incorrect words in transcripts, missing words/phrases, poor performance with accents | Switch to more accurate transcriber. | +| **Intent recognition** | Agent responds to wrong intent, fails to extract variables, workflow routing to wrong nodes | Make system prompt / node prompt more specific; use clear enum values; adjust the temperature to ensure consistent outputs | +| **Response quality** | Different responses to identical inputs, agent forgets context, doesn't follow instructions | Review system prompt / node prompt specificity; check model configuration; adjust temperature to achieve consistency | + +**Debug steps for response quality:** +1. **Review system prompt** - Navigate to your assistant/workflow in the [dashboard](https://dashboard.vapi.ai/) and check the system prompt specificity +2. **Check model configuration** - Scroll down to `Model` section and verify: + - You're using an appropriate model (e.g., `gpt-4o`) + - `Max Tokens` is sufficient for response length + - Necessary tools are enabled and configured correctly + +| Response Issue | Solution | +|----------------|----------| +| **Responses too long** | Add "Keep responses under X words" to system prompt | +| **Robotic speech** | Switch to a different voice provider | +| **Forgetting context** | Use models with larger context windows | +| **Wrong information** | Check tool outputs and knowledge base accuracy via `Call Logs` | + +## Tool and workflow debugging + +| Problem Type | Issue | Solution | +|--------------|-------|----------| +| **Tool execution** | Tools failing, HTTP errors, parameter issues | Navigate to `Observe > Call Logs` and check tool execution section, test tools individually at `Tools > [Select Tool] > Test`, validate configuration | +| **Variable extraction** | Variables not extracted, wrong values, missing data | Be specific in variable descriptions, use distinct enum values, add validation prompts | +| **Workflow logic** | Wrong node routing, conditions not triggering, variables not passing | Use `Call Logs` to trace conversation path, verify edge conditions are clear, check global node conflicts | + +**Variable extraction details:** + +| Problem | Cause | Solution | +|---------|-------|----------| +| **Variables not extracted** | Unclear description | Be specific in variable descriptions: "Customer's 10-digit phone number" | +| **Wrong variable values** | Ambiguous enum options | Use distinct enum values: "schedule", "cancel", "reschedule" | +| **Missing required variables** | User didn't provide info | Add validation prompts to request missing data | + +## Common error patterns + +| Error Pattern | Likely Cause | Quick Fix | +|---------------|--------------|-----------| +| **"I didn't understand"** | Speech recognition issue | Check transcriber model, add custom keyterms | +| **Irrelevant responses** | Poor prompt engineering | Be more specific in system prompt | +| **Call drops immediately** | Configuration error | Check all required fields in assistant/workflow settings | +| **Tool errors** | API integration issue | Test tools individually, verify endpoint URLs | +| **Long silences** | Model processing delay | Use faster models or reduce response length | + +## Getting help + +When you're stuck: + + + Join the Vapi Discord for real-time help from the community and team + + + + Check the API reference for detailed configuration options + + + + Check real-time status of Vapi services and AI providers + + +**Before asking for help:** +- Include call ID and timestamp from `Call Logs` in your [dashboard](https://dashboard.vapi.ai/) +- Describe expected vs. actual behavior +- Share relevant configuration (without API keys) +- Include error messages from [dashboard](https://dashboard.vapi.ai/) logs diff --git a/fern/docs.yml b/fern/docs.yml index 6a829009..9c0b446b 100644 --- a/fern/docs.yml +++ b/fern/docs.yml @@ -244,6 +244,9 @@ navigation: - page: Prompting guide path: prompting-guide.mdx icon: fa-light fa-pen-to-square + - page: Debugging voice agents + path: debugging.mdx + icon: fa-light fa-bug - section: Testing collapsed: true icon: fa-light fa-clipboard-check