Update SDK to latest agent API: new event types, prebuilt tools, provider enhancements

- Migrate all event type strings to new dotted convention (e.g. session.started,
  tool.called, user.transcription, agent.speech_interrupted)
- Add 12 new event types: DtmfSent, AgentToolStarted/Completed/Failed,
  UserStateChanged, AgentStateChanged, AgentSpeechCreated/Started/Completed,
  AgentFalseInterruption, ToolExecuted, LlmAvailabilityChanged
- Unify transfer_to_number/transfer_to_sip into single transfer() method
- Add send_dtmf() and handoff() session methods
- Add semantic_vad eagerness presets (high/medium/low/auto) with expansion
- Add prebuilt tools module: EndCall, SendDtmf, WarmTransfer + 7 agent tools
  (CollectEmail, CollectAddress, CollectPhone, CollectName, CollectDOB,
  CollectDigits, CollectCreditCard)
- Update tool.result/tool.error message types
- Add provider validation docs, base_url/region support, updated provider lists
- Add 3 new examples: full_pipeline_fallback, prebuilt_tools, pipeline_mcp
- Update all 15 existing examples to new event types and API
- Expand test suite from 73 to 87 tests covering all new functionality

Author: bevenky

CLAUDE.md

@@ -16,24 +16,25 @@ src/plivo_agentstack/
   utils.py             # Webhook signature validation (v3)
   agent/               # Voice AI Agent stack
     app.py             # VoiceApp WebSocket server
-    client.py          # Agent REST client (agents, calls, numbers, sessions)
-    events.py          # 25+ typed event dataclasses + parse_event()
+    client.py          # Agent REST client (agents, calls, numbers, sessions) + semantic_vad presets
+    events.py          # 38 typed event dataclasses + parse_event()
     session.py         # Per-connection Session handle
+    tools.py           # Prebuilt tools: EndCall, SendDtmf, WarmTransfer, Collect* agent tools
   messaging/           # SMS/MMS/WhatsApp
     client.py          # MessagesClient
     templates.py       # WhatsApp Template builder
     interactive.py     # InteractiveMessage + Location builders
   numbers/             # Phone number management
     client.py          # NumbersClient + LookupResource
 tests/                 # pytest + pytest-asyncio + respx
-examples/              # 15 runnable scripts
+examples/              # 18 runnable scripts
 ```
 
 ## Build & run
 
 ```bash
 pip install -e ".[dev]"       # install in dev mode
-pytest tests/ -v              # run all tests (~70)
+pytest tests/ -v              # run all tests (~87)
 ruff check src/ tests/        # lint
 ```
 
@@ -49,6 +50,81 @@ ruff check src/ tests/        # lint
 - **No bare `except`**: always catch specific exceptions
 - **asyncio_mode = "auto"**: all async test functions run without explicit markers
 
+## Event type strings
+
+All WebSocket events use dotted naming convention:
+
+| Event | Type string | Dataclass |
+|---|---|---|
+| Session started | `session.started` | `AgentSessionStarted` |
+| Session ended | `session.ended` | `AgentSessionEnded` |
+| Session error | `session.error` | `Error` |
+| Tool called | `tool.called` | `ToolCall` |
+| Tool executed (MCP) | `tool.executed` | `ToolExecuted` |
+| Turn completed | `turn.completed` | `TurnCompleted` |
+| Turn metrics | `turn.metrics` | `TurnMetrics` |
+| User transcription | `user.transcription` | `Prompt` |
+| User DTMF | `user.dtmf` | `Dtmf` |
+| DTMF sent | `dtmf.sent` | `DtmfSent` |
+| User idle | `user.idle` | `UserIdle` |
+| User speech started | `user.speech_started` | `VadSpeechStarted` |
+| User speech stopped | `user.speech_stopped` | `VadSpeechStopped` |
+| User turn completed | `user.turn_completed` | `TurnDetected` |
+| User state changed | `user.state_changed` | `UserStateChanged` |
+| Agent handoff | `agent.handoff` | `AgentHandoff` |
+| Agent speech interrupted | `agent.speech_interrupted` | `Interruption` |
+| Agent speech created | `agent.speech_created` | `AgentSpeechCreated` |
+| Agent speech started | `agent.speech_started` | `AgentSpeechStarted` |
+| Agent speech completed | `agent.speech_completed` | `AgentSpeechCompleted` |
+| Agent false interruption | `agent.false_interruption` | `AgentFalseInterruption` |
+| Agent state changed | `agent.state_changed` | `AgentStateChanged` |
+| Agent tool started | `agent_tool.started` | `AgentToolStarted` |
+| Agent tool completed | `agent_tool.completed` | `AgentToolCompleted` |
+| Agent tool failed | `agent_tool.failed` | `AgentToolFailed` |
+| LLM availability | `llm.availability_changed` | `LlmAvailabilityChanged` |
+| Voicemail detected | `voicemail.detected` | `VoicemailDetected` |
+| Voicemail beep | `voicemail.beep` | `VoicemailBeep` |
+| Participant added | `participant.added` | `ParticipantAdded` |
+| Participant removed | `participant.removed` | `ParticipantRemoved` |
+| Call transferred | `call.transferred` | `CallTransferred` |
+| Play completed | `play.completed` | `PlayCompleted` |
+
+Audio stream events use the Plivo protocol: `start`, `media`, `dtmf`, `playedStream`, `clearedAudio`, `stop`.
+
+## Session methods
+
+- **Managed mode**: `send_tool_result()`, `send_tool_error()`
+- **Text mode (BYOLLM)**: `send_text()`, `extend_wait()`, `send_raw()`
+- **Audio stream**: `send_media()`, `send_checkpoint()`, `clear_audio()`
+- **Control**: `update()`, `inject()`, `handoff()`, `speak()`, `play()`, `transfer()`, `send_dtmf()`, `hangup()`
+- **Background audio**: `play_background()`, `stop_background()`
+
+## Prebuilt tools
+
+Simple tools (customer-side): `EndCall`, `SendDtmf`, `WarmTransfer` — each has `.tool` (schema), `.instructions` (prompt hint), `.match(event)`, `.handle(session, event)`.
+
+Agent tools (server-side sub-agents): `CollectEmail`, `CollectAddress`, `CollectPhone`, `CollectName`, `CollectDOB`, `CollectDigits`, `CollectCreditCard` — each has `.definition` (for `agent_tools=[]`), `.prompt_hint` (for system prompt).
+
+## Supported providers
+
+| Component | Providers |
+|---|---|
+| STT | deepgram, google, azure, assemblyai, groq, openai |
+| LLM | openai, anthropic, groq, google, azure, together, fireworks, perplexity, mistral |
+| TTS | elevenlabs, cartesia, google, azure, openai, deepgram |
+| S2S | openai_realtime, gemini_live, azure_openai |
+
+Provider names are case-insensitive. BYOK API keys are validated at agent creation time.
+
+All provider configs (STT, LLM, TTS) accept optional `base_url` for custom endpoints. ElevenLabs TTS also accepts `region` (`"us"` default, `"in"` for India residency). Azure OpenAI uses `azure_deployment`, `azure_endpoint`, `api_version`.
+
+## Semantic VAD
+
+Agent creation supports `semantic_vad` as a string preset or dict:
+- `"high"` / `"medium"` / `"low"` / `"auto"` — eagerness presets
+- `{"eagerness": "high", "min_interruption_duration_ms": 200}` — preset + overrides
+- Raw dict — full manual control
+
 ## Testing patterns
 
 - **HTTP mocking**: use `respx` (not `unittest.mock` for HTTP). Fixture `mock_api` provides a router scoped to `https://api.plivo.com`
@@ -64,6 +140,7 @@ ruff check src/ tests/        # lint
 - VoiceApp auto-detects sync vs async handlers — sync runs in thread pool via `asyncio.to_thread()`
 - Unknown WebSocket events parse to raw `dict` (forward-compatible)
 - HttpTransport retries on 429 (respects `Retry-After`) and 5xx with exponential backoff
+- Agent REST client auto-expands `semantic_vad` presets to full config dicts
 
 ## Git & commit rules
 
@@ -78,5 +155,6 @@ ruff check src/ tests/        # lint
 
 - New REST resources: add to the appropriate sub-client (`agent/client.py`, `messaging/client.py`, `numbers/client.py`), wire into the parent client, add tests with `respx` mocks
 - New WebSocket events: add a `@dataclass` to `agent/events.py`, register in `_EVENT_REGISTRY`, add parse test in `test_events.py`
+- New prebuilt tools: add to `agent/tools.py`, export in `agent/__init__.py`
 - New examples: add to `examples/`, use `from plivo_agentstack import AsyncClient` and `from plivo_agentstack.agent import VoiceApp, ...` pattern. Update README Quick start section
 - Keep dependencies minimal — core deps are `httpx`, `websockets`, `starlette` only

README.md

@@ -29,8 +29,8 @@ Inbound/Outbound Call
         |
    WebSocket ──────► Your VoiceApp server
         |                   |
-   Audio stream        @app.on("tool_call")
-   VAD / Turn          @app.on("prompt")       ← BYOLLM
+   Audio stream        @app.on("tool.called")
+   VAD / Turn          @app.on("user.transcription")  ← BYOLLM
    STT → LLM → TTS    @app.on("turn.completed")
         |                   |
    Caller hears        session.send_tool_result()
@@ -42,15 +42,20 @@ Inbound/Outbound Call
 ### Agent capabilities
 
 - **Tool calling** - LLM invokes tools, you handle them and return results
-- **Mid-call model switching** - swap LLM model/prompt/tools via `session.update()` for agent handoff
+- **Agent tools** - server-side sub-agents for multi-turn data collection (email, address, phone, name, DOB, digits, credit card)
+- **Prebuilt tools** - ready-to-use EndCall, SendDtmf, WarmTransfer with `match()` + `handle()` patterns
+- **Mid-call model switching** - swap LLM model/prompt/tools via `session.update()` or `session.handoff()` for agent handoff
 - **Multi-party conferences** - add participants with `calls.dial()`, warm transfer patterns
 - **Voicemail detection** - async AMD with beep detection for outbound calls
 - **Background audio** - ambient sounds (office, typing, call-center) mixed with agent speech
-- **DTMF handling** - detect keypress events for IVR flows
-- **Interruption (barge-in)** - caller can interrupt the agent mid-speech
+- **DTMF handling** - receive keypress events and send DTMF tones for IVR navigation
+- **Interruption (barge-in)** - caller can interrupt the agent mid-speech, false interruption detection
+- **Semantic VAD** - unified VAD + turn detection + interruption with eagerness presets (high/medium/low/auto)
 - **User idle detection** - configurable reminders and auto-hangup on silence
 - **Per-turn metrics** - latency breakdown (STT, LLM TTFT, TTS) for monitoring
 - **Audio streaming** - raw audio relay with `send_media()`, checkpoints, and `clear_audio()`
+- **Provider fallback** - automatic failover chains for STT, LLM, and TTS providers
+- **MCP integration** - connect MCP servers (HTTP/stdio) for external tool discovery
 - **BYOK (Bring Your Own Keys)** - pass API keys for Deepgram, OpenAI, ElevenLabs, Cartesia, etc.
 
 ## SDK features
@@ -60,7 +65,8 @@ Inbound/Outbound Call
 - **Standalone mode** - `app.run(port=9000)` starts a WebSocket server with graceful shutdown
 - **Sync + async handlers** - sync handlers run in a thread pool automatically
 - **Automatic retries** - exponential backoff on 429 (respects `Retry-After`) and 5xx
-- **Typed events** - 25 dataclasses for all WebSocket events (`ToolCall`, `TurnMetrics`, `StreamMedia`, ...)
+- **Typed events** - 38 dataclasses for all WebSocket events (`ToolCall`, `TurnMetrics`, `AgentToolCompleted`, ...)
+- **Prebuilt tools** - EndCall, SendDtmf, WarmTransfer, CollectEmail, CollectAddress, CollectPhone, CollectName, CollectDOB, CollectDigits, CollectCreditCard
 - **Per-session state** - `session.data` dict persists across events within a call
 - **Messaging** - SMS, MMS, WhatsApp with template and interactive message builders
 - **Numbers** - search, buy, manage, and carrier lookup
@@ -80,14 +86,17 @@ Requires Python 3.10+.
 
 Sign up at [cx.plivo.com/signup](https://cx.plivo.com/signup) to get your `PLIVO_AUTH_ID` and `PLIVO_AUTH_TOKEN`, set them as environment variables, then see the [`examples/`](examples/) directory for runnable scripts:
 
-- [**Full AI pipeline**](examples/full_pipeline.py) - tool calls, model switching, voicemail detection, transfers
+- [**Full AI pipeline**](examples/full_pipeline.py) - tool calls, agent tools, model switching, voicemail detection, transfers, handoff, metrics
+- [**Provider fallback**](examples/full_pipeline_fallback.py) - resilient multi-provider STT/LLM/TTS fallback chains
+- [**Prebuilt tools**](examples/prebuilt_tools.py) - all 10 prebuilt tools: 7 agent tools + 3 simple tools
 - [**BYOLLM**](examples/byollm.py) - bring your own LLM with OpenAI streaming, per-session conversation history
 - [**BYOLLM echo**](examples/byollm_echo.py) - minimal echo agent for testing, no external dependencies
 - [**Multi-party conference**](examples/multi_party.py) - MPC with mid-call dial, warm transfer to human agents
 - [**Speech-to-speech**](examples/s2s_agent.py) - OpenAI Realtime / Gemini Live integration
 - [**Raw audio streaming**](examples/audio_stream.py) - bidirectional audio relay with checkpoints and pacing
 - [**Background audio**](examples/background_audio.py) - ambient office/typing sounds mixed with agent speech
 - [**Pipeline modes**](examples/pipeline_modes.py) - all five config combinations in one file
+- [**MCP integration**](examples/pipeline_mcp.py) - connect external MCP tool servers
 - [**Metrics & observability**](examples/metrics.py) - per-turn latency breakdown, VAD and turn events
 - [**SMS & MMS**](examples/send_sms.py) - text messages and MMS with media attachments
 - [**WhatsApp**](examples/whatsapp.py) - text, media, templates, buttons, lists, CTA, location
@@ -102,7 +111,7 @@ git clone https://github.com/plivo/plivo-agentstack-python.git
 cd plivo-agentstack-python
 python -m venv .venv && source .venv/bin/activate
 pip install -e ".[dev]"
-pytest tests/ -v          # 70 tests
+pytest tests/ -v          # 87 tests
 ruff check src/ tests/    # lint
 ```
 

examples/agent_basic.py

@@ -69,8 +69,8 @@ async def create_agent() -> str:
                 ],
             },
             tts={
-                "provider": "eleven_labs",
-                "voice": "rachel",
+                "provider": "elevenlabs",
+                "voice": "EXAVITQu4vr4xnSDxMaL",
             },
         )
         agent_uuid = resp["agent_uuid"]
@@ -83,7 +83,7 @@ async def create_agent() -> str:
 app = VoiceApp()
 
 
-@app.on("agent_session.started")
+@app.on("session.started")
 def on_session_started(session, event: AgentSessionStarted):
     logger.info(
         "Session started: session_id=%s call_id=%s caller=%s",
@@ -95,7 +95,7 @@ def on_session_started(session, event: AgentSessionStarted):
     session.data["caller"] = event.caller
 
 
-@app.on("tool_call")
+@app.on("tool.called")
 def on_tool_call(session, event: ToolCall):
     """Handle tool calls from the LLM."""
     logger.info("Tool call: name=%s args=%s", event.name, event.arguments)
@@ -114,7 +114,7 @@ def on_tool_call(session, event: ToolCall):
         session.send_tool_error(event.id, f"Unknown tool: {event.name}")
 
 
-@app.on("agent_session.ended")
+@app.on("session.ended")
 def on_session_ended(session, event: AgentSessionEnded):
     logger.info(
         "Session ended: duration=%ds turns=%s",

examples/agent_fastapi.py

@@ -33,12 +33,12 @@
 voice = VoiceApp()
 
 
-@voice.on("agent_session.started")
+@voice.on("session.started")
 async def on_session_started(session, event: AgentSessionStarted):
     logger.info("Session started: %s", event.agent_session_id)
 
 
-@voice.on("tool_call")
+@voice.on("tool.called")
 async def on_tool_call(session, event: ToolCall):
     """Handle tool calls -- async handlers work natively with FastAPI."""
     logger.info("Tool call: %s(%s)", event.name, event.arguments)
@@ -55,7 +55,7 @@ async def on_tool_call(session, event: ToolCall):
         session.send_tool_error(event.id, f"Unknown tool: {event.name}")
 
 
-@voice.on("agent_session.ended")
+@voice.on("session.ended")
 async def on_session_ended(session, event: AgentSessionEnded):
     logger.info(
         "Session ended: duration=%ds turns=%s",