Merge pull request #549 from future-agi/doc/voice-observe

voice observability doc

Author: hadarishav

src/lib/navigation.ts

@@ -198,14 +198,8 @@ export const tabNavigation: NavTab[] = [
               { title: 'Group Traces by Session', href: '/docs/observe/features/session' },
               { title: 'Users', href: '/docs/observe/features/users' },
               { title: 'Alerts & Monitors', href: '/docs/observe/features/alerts' },
-              { title: 'Dashboards', href: '/docs/observe/features/dashboard' },
-            ]
-          },
-          {
-            title: 'Voice Observability',
-            items: [
-              { title: 'Overview', href: '/docs/observe/voice' },
-              { title: 'Set Up Voice Observability', href: '/docs/observe/voice/set-up' },
+              { title: 'Annotation Queue Using SDK', href: '/docs/observe/features/annotation-queue-using-sdk' },
+              { title: 'Voice Observability', href: '/docs/observe/features/voice' },
             ]
           },
           {

src/pages/docs/integrations/index.mdx

@@ -55,8 +55,8 @@ The Langfuse card above is for SDK-level tracing integration (sending new traces
 <CardGroup cols={2}>
   <Card title="LiveKit" href="/docs/integrations/traceai/livekit" />
   <Card title="Pipecat" href="/docs/integrations/traceai/pipecat" />
-  <Card title="VAPI" href="/docs/observe/voice/set-up" />
-  <Card title="Retell" href="/docs/observe/voice/set-up" />
+  <Card title="VAPI" href="/docs/observe/features/voice" />
+  <Card title="Retell" href="/docs/observe/features/voice" />
 </CardGroup>
 
 ### Other

src/pages/docs/observe/features/voice.mdx

@@ -0,0 +1,106 @@
+---
+title: "Voice Observability"
+description: "Connect a voice provider (Vapi, Retell) and get call logs as traces in Observe without any SDK instrumentation."
+---
+
+
+## About
+
+Voice agents are hard to debug. Conversations happen in real time, across multiple turns, and when something goes wrong you usually find out from a user complaint, not a log. **Voice observability** fixes this by pulling call logs from your voice provider into Observe automatically. No SDK or code changes needed. Connect a provider (Vapi, or Retell) using its API key and assistant ID, and every call shows up as a trace with its transcript, recording URLs, cost, and duration. From there you can run [evaluations](/docs/observe/features/evals), set [alerts](/docs/observe/features/alerts), search, filter, and export, the same way you would with any other trace.
+
+<iframe
+  className="w-full aspect-video rounded-xl"
+  src="https://www.youtube.com/embed/9XHrT2VFbjQ"
+  title="YouTube video player"
+  frameBorder="0"
+  allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
+  allowFullScreen
+></iframe>
+---
+
+## When to use
+
+- **Visibility into voice agent calls**: See all conversations for a voice agent in one project without adding SDK instrumentation.
+- **Evaluate voice conversations**: Run evals (quality, bias, adherence) on conversation spans from voice calls.
+- **Alerts on voice metrics**: Set monitors on voice project metrics and get notified when something degrades.
+- **Transcripts and recordings for debugging**: Access transcript and recording URLs from the trace view.
+- **Multiple voice providers**: Support for Vapi, Retell so you can monitor agents regardless of provider.
+
+---
+
+## How to
+
+<Steps>
+  <Step title="Get provider credentials">
+    From your voice provider's dashboard, obtain:
+    - **API key**
+    - **Assistant ID** (or agent ID)
+
+    These are required when observability is enabled. Supported providers: [Vapi](https://dashboard.vapi.ai), [Retell](https://www.retellai.com/).
+  </Step>
+
+  <Step title="Create an agent definition with observability">
+    Go to the **Agent definition** section and click **Create agent definition**.
+    ![Agent definition list](/screenshot/product/observe/voice/agent_definition_list.png)
+
+    Fill in agent name, provider, and other required fields. The API key and Assistant ID are masked for security.
+    ![Create agent definition form](/screenshot/product/observe/voice/agent_definition_filled.png)
+
+    Check **Enable Observability**. The API key and Assistant ID are required only if observability is enabled.
+    ![Agent definition details](/screenshot/product/observe/voice/agent_definition_details.jpeg)
+
+    Click **Create**. You are redirected to the agent list where the new agent is now visible.
+    ![Agent definition list with new agent](/screenshot/product/observe/voice/agent_definition_list_with_new.jpeg)
+  </Step>
+
+  <Step title="View call logs in Observe">
+    Open the **Projects** tab. A project with the same name as your agent lists all call logs.
+    ![Projects list](/screenshot/product/observe/voice/project_list.png)
+
+    Open the project to see the voice observability table (calls with status, duration, cost).
+    ![Voice observability table](/screenshot/product/observe/voice/voice_observability_table.png)
+
+    Click a call to open the detail drawer (transcript, recording URLs, call data).
+    ![Call log detail drawer](/screenshot/product/observe/voice/call_log_detail_drawer_marked.jpeg)
+  </Step>
+
+  <Step title="Update or disable observability">
+    Click an agent definition to open the edit form. You can edit any field.
+
+    - If you **disable** observability, the API key and Assistant ID become optional.
+    - If you **enable** observability (or keep it on), API key and Assistant ID are required.
+
+    <Tabs>
+      <Tab title="Observability disabled">
+        ![Agent with observability disabled](/screenshot/product/observe/voice/agent_update_observability_disabled.png)
+      </Tab>
+      <Tab title="Observability enabled">
+        ![Agent with observability enabled](/screenshot/product/observe/voice/agent_update_observability_enabled.png)
+      </Tab>
+    </Tabs>
+  </Step>
+</Steps>
+
+## Supported providers
+
+- [Vapi](https://dashboard.vapi.ai)
+- [Retell](https://www.retellai.com/)
+
+---
+
+## Next Steps
+
+<CardGroup cols={2}>
+  <Card title="Set Up Observability" icon="play" href="/docs/observe/features/quickstart">
+    Connect the SDK and start capturing traces.
+  </Card>
+  <Card title="Run Evals on Traces" icon="chart-line" href="/docs/observe/features/evals">
+    Run evaluations on your traced spans to score quality.
+  </Card>
+  <Card title="Alerts & Monitors" icon="zap" href="/docs/observe/features/alerts">
+    Get notified when metrics cross a threshold.
+  </Card>
+  <Card title="Users" icon="tags" href="/docs/observe/features/users">
+    View activity and metrics per end user.
+  </Card>
+</CardGroup>

src/pages/docs/observe/index.mdx

@@ -39,7 +39,7 @@ It tracks every response your application generates, groups them by session and
   <Card title="Alerts & Monitors" icon="zap" href="/docs/observe/features/alerts">
     Configure alerts for real-time issue detection.
   </Card>
-  <Card title="Voice Observability" icon="plug" href="/docs/observe/voice">
+  <Card title="Voice Observability" icon="plug" href="/docs/observe/features/voice">
     Monitor voice agent interactions and call quality.
   </Card>
 </CardGroup>