feat(python): voice-agents v1 — intent-routing

recipes/python/voice-agents/v1/intent-routing/README.md

@@ -0,0 +1,45 @@
+# Intent-Aware Voice Agent Routing (Voice Agents v1)
+
+Configure a Deepgram Voice Agent with a system prompt that classifies caller intent and routes to department-specific responses — no external telephony dependencies required.
+
+## What it does
+
+Opens a WebSocket connection to Deepgram's Agent API and configures the agent's "think" stage with a system prompt that acts as an IVR (Interactive Voice Response) dispatcher. The prompt instructs the LLM to greet the caller, classify their intent as billing, support, or sales, confirm the department, and then respond with department-appropriate guidance. This demonstrates how prompt engineering alone can drive call routing logic inside a voice agent session.
+
+## Key parameters
+
+| Parameter | Value | Description |
+|-----------|-------|-------------|
+| `think.prompt` | IVR routing prompt | System prompt that defines intent categories and per-department behavior |
+| `think.provider.model` | `"gpt-4o-mini"` | LLM that performs intent classification and generates responses |
+| `listen.provider.model` | `"nova-3"` | STT model for the listen stage |
+| `speak.provider.model` | `"aura-2-thalia-en"` | TTS model for spoken responses |
+| `audio.input.encoding` | `"linear16"` | Input audio encoding |
+| `audio.input.sample_rate` | `24000` | Input audio sample rate |
+
+## Example output
+
+```
+Voice agent configured with intent-routing IVR prompt
+Connection opened
+Event: SettingsApplied
+Connection closed
+```
+
+## Prerequisites
+
+- Python 3.10+
+- Set `DEEPGRAM_API_KEY` environment variable
+- Install: `pip install -r recipes/python/requirements.txt`
+
+## Run
+
+```bash
+python example.py
+```
+
+## Test
+
+```bash
+pytest example_test.py -v
+```

recipes/python/voice-agents/v1/intent-routing/example.py

@@ -0,0 +1,49 @@
+"""Voice agent with an IVR system prompt that classifies caller intent
+(billing, support, sales) and responds with department-specific guidance."""
+
+from deepgram import DeepgramClient
+from deepgram.agent.v1.types import (
+    AgentV1Settings, AgentV1SettingsAgent,
+    AgentV1SettingsAgentListen, AgentV1SettingsAgentListenProvider_V1,
+    AgentV1SettingsAudio, AgentV1SettingsAudioInput,
+)
+from deepgram.core.events import EventType
+from deepgram.types.speak_settings_v1 import SpeakSettingsV1
+from deepgram.types.speak_settings_v1provider import SpeakSettingsV1Provider_Deepgram
+from deepgram.types.think_settings_v1 import ThinkSettingsV1
+from deepgram.types.think_settings_v1provider import ThinkSettingsV1Provider_OpenAi
+
+IVR_PROMPT = (
+    "You are an IVR agent for Acme Corp. Greet the caller, classify their intent "
+    "as billing, support, or sales. Billing: invoices and payments. Support: "
+    "troubleshoot issues. Sales: pricing and plans. Confirm the department first."
+)
+
+def main():
+    client = DeepgramClient()
+    with client.agent.v1.connect() as agent:
+        settings = AgentV1Settings(
+            audio=AgentV1SettingsAudio(
+                input=AgentV1SettingsAudioInput(encoding="linear16", sample_rate=24000)
+            ),
+            agent=AgentV1SettingsAgent(
+                listen=AgentV1SettingsAgentListen(
+                    provider=AgentV1SettingsAgentListenProvider_V1(type="deepgram", model="nova-3")
+                ),
+                think=ThinkSettingsV1(
+                    provider=ThinkSettingsV1Provider_OpenAi(type="open_ai", model="gpt-4o-mini"),
+                    prompt=IVR_PROMPT,
+                ),
+                speak=SpeakSettingsV1(
+                    provider=SpeakSettingsV1Provider_Deepgram(type="deepgram", model="aura-2-thalia-en")
+                ),
+            ),
+        )
+        agent.send_settings(settings)
+        print("Voice agent configured with intent-routing IVR prompt")
+        agent.on(EventType.OPEN, lambda _: print("Connection opened"))
+        agent.on(EventType.CLOSE, lambda _: print("Connection closed"))
+        agent.start_listening()
+
+if __name__ == "__main__":
+    main()

recipes/python/voice-agents/v1/intent-routing/example_test.py

@@ -0,0 +1,16 @@
+import subprocess
+from pathlib import Path
+
+def test_example_runs():
+    """Runs the intent-routing voice agent example and verifies it produces output."""
+    example = Path(__file__).parent / "example.py"
+    result = subprocess.run(
+        ["python", str(example)],
+        capture_output=True,
+        text=True,
+        timeout=60,
+    )
+    assert result.returncode == 0, (
+        f"Example failed\nSTDOUT: {result.stdout}\nSTDERR: {result.stderr}"
+    )
+    assert result.stdout.strip(), "Example produced no output"