Outbound AI Agent

Overview

Use the Piopiy Python SDK to programmatically initiate outbound calls from your AI agents. This allows you to build proactive voice applications such as automated appointment reminders, verification calls, or proactive customer support.

How it Works

1. Trigger: Your backend application uses the Piopiy SDK's RestClient to request a new call.
2. Connection: Piopiy's telephony network dials the destination number (to_number) using your requested caller ID.
3. Handover: As soon as the call is answered, Piopiy connects the audio stream to your running AI agent worker.
4. Interaction: Your agent logic follows the defined instructions and interacts with the recipient in real-time.

Prerequisites

• AI agent created in dashboard
• Outbound-enabled caller ID/number purchased in dashboard
• Python 3.10 or later

Install Python SDK (piopiy_python)

Terminal

python3 -m venv env
source env/bin/activate
pip install piopiy python-dotenv

piopiy_python is published on PyPI as piopiy.

Create .env

.env

PIOPIY_TOKEN=your_api_token

Set Outbound Values In Code

In trigger_outbound_call.py, set these values directly:

• agent_id: Agent ID from dashboard.
• caller_id: Outbound number from dashboard (E.164 format).
• to_number: Destination number (E.164 format).

Code

Voice AI Agent Code

phone_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 required(name: str) -> str:
    value = os.getenv(name)
    if not value:
        raise RuntimeError(f"Missing required environment variable: {name}")
    return value


async def create_session(call_id=None, from_number=None, to_number=None, **kwargs):
    voice_agent = VoiceAgent(
        instructions="You are a concise outbound assistant.",
        greeting="Hello, this is an automated call from our support team.",
    )

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


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

For provider keys and AGENT_ID/AGENT_TOKEN setup, see Phone Agent Setup.

Python SDK Call Code

trigger_outbound_call.py

import os
from dotenv import load_dotenv
from piopiy_voice import RestClient

load_dotenv()

client = RestClient(token=os.environ["PIOPIY_TOKEN"])

agent_id = "your_agent_id"
caller_id = "+15551234567"
to_number = "+15557654321"

response = client.ai.call(
    caller_id=caller_id,
    to_number=to_number,
    agent_id=agent_id,
)

print(response)

client.ai.call() Parameters

Parameter	Type	Required	Description
caller_id	str	Yes	Your registered Piopiy number (e.g. "+15551234567").
to_number	str	Yes	The destination number to dial (e.g. "+15557654321").
agent_id	str	Yes	The unique ID of the AI agent to handle the call.
variables	dict	No	Custom data to pass to the agent (accessible as metadata in create_session).
options	dict	No	Advanced call options (see below).
failover	dict	No	Backup routing if the primary agent is unavailable.

Call Options

Field	Type	Default	Description
record	bool	False	Enable/disable call recording.
ring_timeout_sec	int	30	How long to ring before timing out.
max_duration_sec	int	3600	Maximum call duration in seconds.

Advanced Call Flows

For high-availability production environments, you can implement failover routing to ensure your calls are always handled, even if your primary agent is unavailable.

See the Failover AI Agent Guide.

Run

Start the agent worker:

Terminal

python phone_agent.py

Trigger outbound call from a second terminal:

Terminal

python trigger_outbound_call.py

Reference

• piopiy_python SDK
• Phone Agent Setup
• AI Agents