Quickstart

This quickstart will get a working Piopiy voice agent running, passing audio between your computer and Piopiy's high-speed TeleCMITransport.

Prerequisites

To build a Piopiy AI agent, you will need a few accounts and API keys. Piopiy orchestrates the services, but you bring the models and the transport.

1. Transport (Telephony)

You need to connect Piopiy to the phone network. Before proceeding, read our Dashboard Setup Guide to:

• Create an account on the Piopiy Dashboard.
• Obtain your AGENT_ID and AGENT_TOKEN.
• Purchase and assign a phone number to your AI Agent.

2. AI Services (STT, LLM, TTS)

This quickstart uses arguably the fastest available stack today: Deepgram for listening, OpenAI for thinking, and Cartesia for speaking.

If you don't have accounts for these specific providers, you can sign up for free trials or swap them out for other supported providers later.

Deepgram (STT)

Provides ultra-low latency Speech-to-Text transcription. Get API Key

OpenAI (LLM)

Powers the brain of the agent to generate human-like responses. Get API Key

Cartesia (TTS)

Synthesizes the LLM text back into natural, high-speed audio. Get API Key

Set up your environment

We recommend using a virtual environment. Create and activate it:

Terminal

python3 -m venv env
source env/bin/activate

Next, export the API keys for the services you plan to use:

.env / Terminal

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

Install Piopiy

Install the piopiy-ai library along with your chosen provider dependencies (we're using OpenAI, Deepgram, and Cartesia for this example).

Terminal

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

Copy boilerplate code

Create a file named my_agent.py and paste the following boilerplate. This code orchestrates the real-time pipeline between your STT, LLM, and TTS providers via the TeleCMITransport. You can also find this code in our Basic Example.

my_agent.py

import asyncio, os
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

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 support assistant.",
        greeting="Thanks for calling. How can I help you today?",
    )

    stt = DeepgramSTTService(api_key=os.environ["DEEPGRAM_API_KEY"], model="nova-2")
    llm = OpenAILLMService(api_key=os.environ["OPENAI_API_KEY"], model="gpt-4o-mini")
    tts = CartesiaTTSService(api_key=os.environ["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=os.environ["AGENT_ID"],
        agent_token=os.environ["AGENT_TOKEN"],
        create_session=create_session
    )
    print("Agent online. Waiting for calls...")
    await agent.connect()

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

create_session Parameters

When a new call arrives, Piopiy invokes your create_session callback with the following parameters:

Parameter	Type	Description
agent_id	str	Your agent's unique identifier.
call_id	str	A unique identifier for the session. Useful for logging and tracking.
from_number	str	The caller's phone number (in E.164 format) or device ID.
to_number	str	The dialed phone number that reached your agent.
metadata	dict	Additional dynamic parameters passed from the transport or dashboard.
**kwargs	dict	Catch-all for additional metadata and session context.

Run your agent

Execute the Python script. It will connect to the Piopiy infrastructure and wait for incoming calls.

Terminal

python my_agent.py

When the script starts successfully, it connects to Piopiy's high-speed transport and awaits incoming calls. You should see the following output:

Terminal Output

Agent online. Waiting for calls...

Try It Out!

1. Assign a phone number to your Piopiy agent in the dashboard.
2. Call that number from your phone.
3. Confirm you hear the greeting and the agent replies to your speech actively.

Next Steps: Build More

Now that you have your first agent running, explore these advanced templates to add more capabilities to your Voice AI system.

Voice Assistant

A clean, ready-to-use template for a general-purpose AI voice bot.

Phone Agent

Learn how to trigger personalized outbound calls programmatically.

Tool Calling

Give your agent the power to check weather, fetch prices, or search DBs.

Call Transfer

Hand off the conversation to a human expert when things get complex.

Switch Providers

Dynamically switch between multiple TTS or LLM providers mid-call.

MCP Sales

Enable high-level knowledge retrieval using the Model Context Protocol.