Docs for debugging voice agents

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:
+
+<Steps>
+  <Step title="Test in dashboard">
+    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
+  </Step>
+  <Step title="Check logs">
+    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
+  </Step>
+  <Step title="Test individual components">
+    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
+  </Step>
+  <Step title="Verify provider status">
+    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
+  </Step>
+</Steps>
+
+## 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:
+
+<Card
+  title="Community Support"
+  icon="user-group"
+  href="https://discord.com/invite/pUFNcf2WmH"
+>
+  Join the Vapi Discord for real-time help from the community and team
+</Card>
+
+<Card
+  title="API Reference"
+  icon="book"
+  href="/api-reference"
+>
+  Check the API reference for detailed configuration options
+</Card>
+
+<Card
+  title="Status Page"
+  icon="fa-light fa-heartbeat"
+  href="https://status.vapi.ai/"
+>
+  Check real-time status of Vapi services and AI providers
+</Card>
+
+**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

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