---
name: vr-create-agent
description: Create a new VoiceRun voice agent project
---

# Create a VoiceRun Voice Agent

You are helping the user create a new VoiceRun voice agent project. Follow these steps:

## Step 1: Scaffold the project

Run `vr init <name>` to create the project. Ask the user for a project name if they haven't provided one. Use `--yes` to skip interactive prompts if the user wants defaults.

```bash
vr init <name>
```

This creates the following structure:

```
<name>/
├── handler.py              # Main agent code (entry point)
├── README.md               # Project documentation
├── requirements.txt        # Python dependencies (primfunctions)
├── .gitignore              # Git ignore rules
└── .voicerun/              # VoiceRun configuration
    ├── agent.yaml          # Agent metadata (name, description, dependencies)
    ├── values.yaml         # Environment settings (STT model, environment)
    └── templates/
        └── deployment.yaml # Runtime deployment config (STT, VAD, sessions)
```

## Step 2: Customize the handler

Open `handler.py` and help the user customize the agent's logic. The handler is an async generator that receives input events (`StartEvent`, `TextEvent`, `StopEvent`) and yields output events (`TextToSpeechEvent`, etc.).

For comprehensive handler development guidance — including all events, context management, LLM integration with `voicerun_completions`, tool calling, and conversation patterns — use the **vr-handler-dev** skill.

## Step 3: Configure the agent

Help the user edit `.voicerun/agent.yaml` to set:
- `name`: Agent identifier
- `description`: What the agent does
- `dependencies`: Optional references to shared agent packages

Help the user edit `.voicerun/values.yaml` to configure:
- `environment`: development, staging, or production
- `sttModel`: Speech-to-text model (default: `deepgram-flux`)

## Step 4: Write tests and debug

**This step is critical.** Before pushing or deploying, write tests and debug interactively to verify the agent behaves correctly.

For comprehensive testing and debugging guidance — including writing pytest tests, using the Pipeline Debugger (GUI, headless, scripted), outbound phone testing, and CI/CD patterns — use the **vr-debug-test** skill.

Quick reference:

```bash
vr test              # Run all tests
vr test -v           # Verbose output
vr debug             # Launch interactive Pipeline Debugger
vr debug --headless  # Headless mode for CI/coding agents
```

**Do not consider the agent complete until all tests pass.**

## Step 5: Next steps

Once the agent is ready and **all tests pass**, suggest these commands:
- `vr push` - Push the agent to VoiceRun
- `vr deploy <environment> -f .voicerun/values.yaml` - Deploy the agent to an environment (values file is required)
- `vr debug` - Push local code and start an interactive debug session
- `vr test` - Run tests for the voice agent project

Refer the user to the [VoiceRun documentation](https://docs.voicerun.com) for detailed guides, API references, and examples.

Ask the user what they'd like to customize first and guide them through the implementation.
