Telephony Quickstart

This setup guide gives you a production-ready phone agent using:

• Deepgram (STT)
• OpenAI (LLM)
• Cartesia (TTS)

Vendors Used In This Setup

Deepgram (STT)

Real-time speech transcription. Get API Key

OpenAI (LLM)

Language reasoning and response generation. Get API Key

Cartesia (TTS)

Low-latency voice synthesis for call playback. Get API Key

Prerequisites

• Dashboard setup completed:
  • Phone agent created
  • AGENT_ID and AGENT_TOKEN copied
  • Phone number purchased and mapped to your agent
• Python 3.10 or later
• API keys for Deepgram, OpenAI, and Cartesia

1. Create virtual environment

Terminal

python3 -m venv env
source env/bin/activate

2. Create .env credentials file

Create a .env file in your project root:

.env

AGENT_ID=your_agent_id
AGENT_TOKEN=your_agent_token
DEEPGRAM_API_KEY=your_deepgram_key
OPENAI_API_KEY=your_openai_key
CARTESIA_API_KEY=your_cartesia_key

3. Install dependencies

Terminal

pip install "piopiy-ai[openai,deepgram,cartesia,silero]" python-dotenv

4. Create my_agent.py

my_agent.py

import asyncio
import os
from dotenv import load_dotenv
from piopiy.agent import Agent
from piopiy.voice_agent import VoiceAgent
from piopiy.services.deepgram.stt import DeepgramSTTService
from piopiy.services.openai.llm import OpenAILLMService
from piopiy.services.cartesia.tts import CartesiaTTSService

load_dotenv()


def get_required_env(name: str) -> str:
    value = os.getenv(name)
    if not value:
        raise RuntimeError(f"Missing required environment variable: {name}")
    return value


async def create_session(agent_id: str, call_id: str, from_number: str, to_number: str, metadata: dict = None, **kwargs):
    print(f"Incoming call {call_id} from {from_number} to {to_number}")

    voice_agent = VoiceAgent(
        instructions="You are a concise, helpful voice support assistant.",
        greeting="Hello, thanks for calling. How can I help you today?",
    )

    stt = DeepgramSTTService(api_key=get_required_env("DEEPGRAM_API_KEY"), model="nova-2")
    llm = OpenAILLMService(api_key=get_required_env("OPENAI_API_KEY"), model="gpt-4o-mini")
    tts = CartesiaTTSService(api_key=get_required_env("CARTESIA_API_KEY"))

    await voice_agent.Action(stt=stt, llm=llm, tts=tts, vad=True, allow_interruptions=True)
    await voice_agent.start()


async def main():
    agent = Agent(
        agent_id=get_required_env("AGENT_ID"),
        agent_token=get_required_env("AGENT_TOKEN"),
        create_session=create_session,
    )
    print("Agent online. Waiting for calls...")
    await agent.connect()


if __name__ == "__main__":
    asyncio.run(main())

Session Parameters

Argument	Description
agent_id	Your agent's unique identifier.
call_id	Unique session identifier used for debugging and reporting.
from_number	The caller's CLI (Caller Line Identity).
to_number	The target number assigned to your AI agent.
metadata	Dynamic parameters provided by the Piopiy infrastructure.
**kwargs	Reserved for future expansion and custom metadata.

5. Run your agent

Terminal

python my_agent.py

Expected terminal output:

Terminal Output

Agent online. Waiting for calls...

6. Validate with a live call

1. Call the number mapped to your agent.
2. Confirm the greeting plays.
3. Speak and confirm the AI replies.
4. Verify call events in terminal logs.