Examples / Recipes

The Piopiy Voice AI Orchestrator includes a variety of examples located in the example/ folder of the repository. These examples demonstrate how to build voice agents using different combinations of LLM, ASR, and TTS providers.

Getting Started with Examples

Each example is designed to be runnable. Before running them, ensure you have:

1. Installed the SDK with the relevant provider extras.
2. Set your AGENT_ID and AGENT_TOKEN in your environment.
3. Set the required API keys for the providers used in the example.

# Example setup
export AGENT_ID="your_agent_id"
export AGENT_TOKEN="your_agent_token"
export OPENAI_API_KEY="your_openai_key"

# Run an example
python example/basic/basic.py

Available Examples

Example	Folder	LLM	ASR	TTS / Speech	Highlights
Voice Assistant	example/voice_assistant/	OpenAI	Deepgram	Cartesia	Simple, clean voice assistant template.
Phone Agent	example/phone_agent/	OpenAI	Deepgram	Cartesia	Outbound programmable server calling template.
Tool Calling Agent	example/tool_calling_agent/	OpenAI	Deepgram	Cartesia	Defines Python tools that the LLM invokes mid-call.
Call Transfer	example/call_transfer/	OpenAI	Deepgram	Cartesia	Hand off a live call to a human expert.
Switch Providers	example/switch_providers/	Multi	Deepgram	Multi	Dynamically switch TTS mid-conversation.
MCP Sales	example/mcp_sales/	OpenAI	Deepgram	Cartesia	Search external knowledge bases using MCP.
Basic Loop	example/basic/	OpenAI	Deepgram	Cartesia	Minimal voice loop showcasing Silero VAD.
Chatterbox	example/chatterbox/	OpenAI	Deepgram	OpenAI	Uses OpenAI for both LLM and TTS.
Tool Usage (Weather)	example/function_calling/	OpenAI	Deepgram	Cartesia	Simple tool-calling workflow for weather.
Sales Assistant (CRM)	example/function_calling/	OpenAI	Deepgram	Cartesia	CRM assistant with structured tool outputs.
MCP Knowledge	example/mcp_sales/	OpenAI	Deepgram	Cartesia	Adds Model Context Protocol (MCP) tools.
Open Source Stack	example/chatterbox/	Ollama	Whisper	Chatterbox	Fully local/open-source stack.
Offline TTS	example/kokoro/	Ollama	Whisper	Kokoro	Offline TTS using Kokoro ONNX models.
Provider Switching	example/switch_providers/	Multiple	Multiple	Multiple	Demonstrates hot-swapping ASR/TTS.
High Quality Voice	example/murf/	OpenAI	Deepgram	Murf.ai	Integration with Murf.ai premium voices.
Ultravox Omni	example/ultravox/	Ultravox	-	Cartesia	Using an all-in-one speech-to-speech model.

---

Use the navigation menu on the left to explore the detailed code, configuration, and step-by-step guides for each of these examples. All examples are fully open source and available in the telecmi/agents repository.