docs.VoiceRun

Quick Start Guide

Get started building your first voice agent with VoiceRun in minutes.

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
  • Limited Python experience
  • A little bit of creativity

Getting Started#

Step 1: Sign up for an account#

Visit the signup page to create your VoiceRun account.

Step 2: Create an agent#

From your dashboard, navigate to the Agents Portal and click on "Create New Agent".

Step 3: Add details#

Give your agent a name, a description, and select a default voice. The description will be used to help the agent understand the user's request better by adding context.

Step 4: Add an environment#

Navigate to the "Environments" tab in your agent settings and click "+ Environment". Environments can be used to manage different configurations for your agent.

Step 5: Create a function#

In the "Functions" section, create a new function that will handle your agent's logic. Use the sample code below as a starting point.

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 6: Deploy to your environment#

Once your function is ready, click the "Save" button and then the "Deploy Version" button from the three dot menu. Select the environment you created earlier to complete.

Step 7: Test in debugger#

Open the "Debugger" panel to test your agent. Click "Start" to begin a conversation with your agent and see how it responds to different inputs. You can view the event logs to troubleshoot any issues.

Step 8: Test over the phone#

From the "Environments" tab, you can select an environment and click the "Add Phone Number" button. This will add a phone number to your agent. You can then call the number and speak with your agent.

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 environment variables for API keys and configuration
  • 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: Check that your function is deployed to the correct environment
  • Syntax errors: Verify your code matches the Python syntax requirements
  • Voice not working: Ensure you've selected a valid voice name from the available options
  • Environment variables missing: Add any required API keys or configuration in the environment settings
quickstartintroductiongetting-started