Session Initialization

Understanding the Architecture

When deploying voice AI agents, managing the connection between the user and your conversational voice AI is the critical first step. The architecture essentially consists of:

• Piopiy Agent/Runner: The background service that connects to external transports (Telephony/WebRTC), handles connection requests, and manages session setup.
• VoiceAgent: Your voice AI application running as an asynchronous instance within the server-level session.
• Client Application: The user-facing app (phone, web browser, mobile app, etc.).

How Sessions Work

Piopiy handles all incoming connections automatically by invoking a callback function you define. This ensures that every concurrent connection is isolated.

import asyncio
import os
from piopiy.agent import Agent
from piopiy.voice_agent import VoiceAgent

async def on_new_session(agent_id, call_id, from_number, to_number, metadata=None):
    print(f"Incoming connection {call_id}")
    
    # 1. Initialize persona and context
    voice_agent = VoiceAgent(
        instructions="You are an advanced voice AI.",
        greeting="Hello! How can I help you today?",
    )

    # 2. Configure providers
    # ... Initialize STT, LLM, TTS here ...

    # 3. Define Action and Start
    await voice_agent.Action(stt=stt, llm=llm, tts=tts)
    await voice_agent.start()

async def main():
    agent = Agent(
        agent_id=os.getenv("AGENT_ID"),
        agent_token=os.getenv("AGENT_TOKEN"),
        create_session=on_new_session,
    )
    await agent.connect()

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

Callback Parameters

The create_session callback (in this case on_new_session) receives several key arguments from the Piopiy infrastructure:

Parameter	Description
agent_id	The ID of the agent receiving the connection.
call_id	A unique UUID for the specific call/session.
from_number	The geographic or internal number of the caller.
to_number	The number dialed by the user.
metadata	Additional dynamic parameters passed during session creation.
metadata	An optional dictionary containing custom context passed from your client or dashboard.

Connection Types Under the Hood

1. TeleCMI Telephony Connections

At its core, Piopiy integrates natively with the TeleCMI network to provide reliable inbound and outbound calling. When a user dials the phone number you purchased in your dashboard, TeleCMI routes the audio directly to Piopiy's media server.

1. The TeleCMI infrastructure receives the phone call natively.
2. TeleCMI natively manages the media routing and securely signals your Agent via WebSocket.
3. Your on_new_session callback executes automatically with details like from_number and call_id.
4. Your VoiceAgent starts immediately and begins streaming audio back through TeleCMI's robust telephony network.

2. TeleCMI WebRTC Connections

In addition to traditional phone calls, Piopiy agents can be deployed seamlessly on the web or mobile applications using the TeleCMI WebRTC stack.

1. Your web or mobile client requests a connection to the TeleCMI WebRTC gateway.
2. TeleCMI securely establishes the real-time audio connection.
3. The exact same on_new_session callback fires in your Python backend.
4. Your VoiceAgent interacts natively over the browser's audio connection without changing any backend logic.

Process Isolation

By design, Piopiy strictly isolates sessions by assigning a dedicated asynchronous execution context for each call:

• Resource Management: Each VoiceAgent instance runs independently.
• Error Isolation: If one user's session encounters an API failure (like a rate limit from an LLM), it will not crash or affect any other concurrent callers.
• Clean Cleanup: Resources, WebSockets, and audio streams are automatically freed when the session ends or the user hangs up.

Key Takeaways

• All inbound connections automatically invoke your on_new_session callback.
• Keep session-level state (like the VoiceAgent instance and initialized provider classes) constrained inside the callback to isolate data between concurrent callers.
• Handle startup timing correctly by yielding execution with await voice_agent.start().
• The exact same backend code handles both TeleCMI Telephony and TeleCMI WebRTC endpoints natively.

What's Next

• Telephony: Move from session wiring to real phone-number deployment.
• Transports Integration: Learn more about configuring TeleCMI transports for phone calls and WebRTC connections.