VoiceRun Agents Guide

A framework for building conversational AI agents with event-driven architecture.

Overview#

VoiceRun provides a simple, event-driven architecture for creating sophisticated conversational experiences. The framework handles speech-to-text, text-to-speech, and conversation management, allowing you to focus on defining your agent's behavior through Python functions.

Basic Structure#

Every agent function follows this pattern:

handler.py:

from primfunctions.events import Event, StartEvent, TextEvent, StopEvent, TextToSpeechEvent, TimeoutEvent
from primfunctions.context import Context

async def handler(event: Event, context: Context):
    if isinstance(event, StartEvent):
        # Handle session start
        yield TextToSpeechEvent(text="Hello!", voice="nova")

    if isinstance(event, TextEvent):
        # Handle text input
        user_message = event.data.get("text", "N/A")
        yield TextToSpeechEvent(text=f"You said: {user_message}", voice="nova")

    if isinstance(event, TimeoutEvent):
        # Handle timeout
        yield TextToSpeechEvent(text="Are you still there?", voice="nova")

    if isinstance(event, StopEvent):
        # Handle session end
        yield TextToSpeechEvent(text="Goodbye!", voice="nova")

Events#

Your agent receives input events (user actions, system events) and yields output events (speech, actions).

Common input events:

StartEvent — Session begins
TextEvent — User speaks or types
TimeoutEvent — User is silent
StopEvent — Session ends

Common output events:

TextToSpeechEvent — Speak text to user
AudioEvent — Play audio file
TransferSessionEvent — Transfer to another agent or phone number

See the Event Reference for complete documentation of all events.

Context#

The context object provides access to session state and utilities:

# Store and retrieve session data
context.set_data("user_name", "John")
user_name = context.get_data("user_name", "Guest")

# Access environment variables
api_key = context.variables.get("OPENAI_API_KEY")

# Create background tasks
context.create_task(process_order(context))

See the Context Reference for complete documentation including background tasks, A/B testing, and outcome tracking.

Best Practices#

Keep functions simple: Only the handler function is called by the agent, but it can use as many helper functions and files as needed
Use background tasks: For operations that take more than a few seconds, use context.create_task() to avoid blocking the conversation
Track outcomes: Use context.add_outcome() and context.trigger_outcome() to track metrics for analytics