docs.VoiceRun

Quick Start Guide

Build, release, and route traffic to your first VoiceRun agent with the current organization-scoped workflow.

Hello Voice Agent Example#

This guide will walk you through creating a simple voice agent that greets users and echoes back what they say.

Prerequisites#

  • A VoiceRun account
  • Python 3.10+
  • The VoiceRun CLI (pip install voicerun-cli or uv tool install voicerun-cli)

Getting Started#

Step 1: Sign in and create a project#

vr signin
vr init hello-agent
cd hello-agent

The generated project includes handler.py, values files, and declarative resource templates under .voicerun/templates/.

Step 2: Write the handler#

Replace the generated handler with this example:

Python Example:

async def handler(event: Event, context: Context):
    # Handle start of conversation with "StartEvent" and send a welcome message
    if isinstance(event, StartEvent):
        yield TextToSpeechEvent(text="Hello! I'm your voice agent. How can I help you today?")

    # Handle user input with "TextEvent" whether it is text or transcribed speech
    # and send back what the user said
    if isinstance(event, TextEvent):
        user_message = event.data.get("text", "N/A")
        yield TextToSpeechEvent(text=user_message)

Step 3: Validate and push#

vr validate --environment development
vr push

vr validate renders and checks the declarative resources. vr push uploads the handler and records the agent and function IDs in .voicerun/agent.lock.

Step 4: Create an organization environment and release#

vr create environment development
vr release development

The release binds the pushed function to the organization-scoped environment and stores an immutable snapshot of the rendered resources. Copy the release ID printed by vr release.

Step 5: Create a web entrypoint#

vr create entrypoint web hello-web \
  --release <RELEASE_ID> \
  --allowed-origin http://localhost:3000

The entrypoint is the public route for browser sessions. Use its ID with the React integration, or create a phone entrypoint for telephony.

Step 6: Test and observe#

vr debug --release <RELEASE_ID>
vr session list

The debugger runs the released configuration. Session commands expose events, transcripts, recordings, traces, and evaluations.

What the Code Does#

The example agent demonstrates the basic event-driven architecture:

  1. StartEvent: When a session begins, the agent greets the user with a welcome message
  2. TextEvent: When the user speaks or types, the agent echoes back what was said

This simple pattern is the foundation for building more complex conversational agents.

Next Steps#

  • Check out the Guides for step-by-step agent implementations
  • Add non-sensitive configuration to Deployment.spec.variables
  • Store credentials as organization secrets and reference them from declarative resources
  • Learn more about all available Events in the Event Reference
  • Explore the Developer Guide for advanced features like A/B testing and background tasks

Troubleshooting#

  • Agent not responding: Confirm the entrypoint routes to the intended release
  • Syntax errors: Verify your code matches the Python syntax requirements
  • Voice not working: Check the Deployment.spec.tts fields in the rendered manifest
  • Configuration missing: Run vr render and confirm the release contains the expected variables and organization-secret placeholders
quickstartintroductiongetting-started