Quick Start

Quickstart¶

From Zero to Running Voice Agent in 15 Minutes

This guide gets you from clone to a working voice agent as fast as possible.

What You'll Accomplish¶

flowchart LR A[Clone Repo] --> B[Login to Azure] B --> C[Deploy with azd up] C --> D[Talk to AI Agent] style A fill:#e3f2fd style D fill:#c8e6c9

Step	Time	What Happens
Clone & Login	2 min	Get the code, authenticate
Deploy	12 min	Azure resources + app deployment
Test	1 min	Open browser, start talking

Before You Start¶

Prerequisites Required

Make sure you've completed the Prerequisites first:

[x] Azure CLI installed and logged in
[x] Azure Developer CLI installed
[x] Docker running
[x] Azure subscription with Contributor access

Clone the Repository¶

git clone https://github.com/Azure-Samples/art-voice-agent-accelerator.git
cd art-voice-agent-accelerator

# Login to Azure CLI (opens browser)
az login

# Login to Azure Developer CLI
azd auth login

Deploy Everything¶

azd up

What azd up Does

This single command handles everything:

Creates Azure resources (~12 min)
- Azure OpenAI (GPT-4o)
- Azure Speech Services
- Azure Communication Services
- Cosmos DB, Redis, Storage
- Container Apps (frontend + backend)
Builds and deploys your application
Generates .env.local for local development

During Deployment¶

You'll be prompted for:

Prompt	What to Enter
Environment name	A short name (e.g., `dev`, `myname-dev`)
Azure subscription	Select from list
Azure location	Choose a region (e.g., `eastus`, `westus2`)
Remote state storage	Press `Y` (recommended)

Deployment Hooks¶

The deployment runs automated scripts before and after provisioning Azure resources. Expand the sections below to see exactly what each script creates and configures.

Pre-Provisioning Script (preprovision.sh)

This script runs before Azure resources are created to validate your environment and set up prerequisites.

Validation Checks Extensions Installed Resource Providers Region Availability Terraform State

Check	Description
CLI Tools	Validates `az`, `azd`, `jq`, and `docker` are installed
Azure Auth	Confirms you're logged into Azure CLI
Subscription	Sets `ARM_SUBSCRIPTION_ID` for Terraform

The script automatically installs these Azure CLI extensions:

az extension add --name quota --upgrade
az extension add --name redisenterprise --upgrade  
az extension add --name cosmosdb-preview --upgrade

Registers required Azure resource providers:

Microsoft.Compute
Microsoft.ContainerService
Microsoft.CognitiveServices
Microsoft.Communication
Microsoft.DocumentDB
Microsoft.Cache
Microsoft.Storage
Microsoft.App
Microsoft.OperationalInsights

Verifies the selected Azure region supports:

Azure OpenAI
Azure Speech Services
Azure Communication Services
Container Apps

Sets up remote state storage in Azure for Terraform:

Creates a storage account for state files
Configures state locking with blob leases

Post-Provisioning Script (postprovision.sh)

This script runs after Azure resources are created to configure your application.

Cosmos DB Initialization Phone Number Configuration App Configuration Sync Local Development File

Creates the initial database structure:

Container	Purpose
`sessions`	Active call session data
`transcripts`	Conversation transcripts
`profiles`	User/agent profiles
`scenarios`	Agent scenario configurations

Interactive Prompt

You'll be asked if you want to configure a phone number for PSTN calls.

Yes: Guides you through phone number purchase/assignment
No: Skip for browser-only voice (you can add later)

Updates Azure App Configuration with:

Backend and frontend URLs
Service endpoints
Feature flags
Connection strings (references to Key Vault)

Generates .env.local with all required environment variables:

# Generated by postprovision.sh
AZURE_OPENAI_ENDPOINT=https://...
AZURE_SPEECH_REGION=eastus
COSMOS_DB_ENDPOINT=https://...
# ... additional variables

Ready for Local Dev

This file enables immediate local development without manual configuration.

Deployment Output¶

When complete, you'll see:

Deploying services (azd deploy)

  (✓) Done: Deploying service rtaudio-client
  (✓) Done: Deploying service rtaudio-server

SUCCESS: Your application was deployed to Azure!

  Frontend: https://ca-frontend-xxxxx.azurecontainerapps.io
  Backend:  https://ca-backend-xxxxx.azurecontainerapps.io

Open Your Voice Agent¶

Copy the Frontend URL from the deployment output
Open it in your browser
Allow microphone access when prompted
Start talking! 🎤

You're Done!

Your AI voice agent is now running. Try asking it questions about insurance, account balances, or just have a conversation.

Create a Demo Profile¶

Before testing personalized conversations, create a demo profile with synthetic customer data that agents use for context-aware interactions.

Step 1: Open Profile DialogStep 2: Fill Profile FormStep 3: Complete FormStep 4: View ProfileStep 5: Reset Session (Optional)Lookup Existing Profile

From the home screen, click the Create Demo Profile button in the top navigation.

The Create Demo Access dialog appears. Fill in the required fields:

Create Demo Access dialog

Field	Description
Full Name	Your display name for the demo
Email Address	Use a real email if testing MFA verification
Verification Method	Choose Email or SMS for MFA codes

Enter your details and select your preferred verification method.

Use Real Email for MFA Testing

If you want to test multi-factor authentication tools, provide your actual email address. The system sends real 6-digit verification codes you'll read back to the agent.

Click Create Demo Profile to generate your synthetic customer data. The profile panel shows your generated data including verification tokens and MFA settings.

Profile created with verification tokens

Profile Expiration

Demo profiles automatically expire after 24 hours. All data is synthetic and safe for demos.

To start a fresh conversation, click the reset button in the bottom toolbar.

Session Reset — Reset conversation and start fresh

Already created a profile? Switch to the Lookup by Email tab and enter the email used during creation.

Lookup Email Entered — Enter email to find existing profile

Quick Troubleshooting¶

Deployment failed with permission error

You need Contributor access on your Azure subscription.

# Check your current permissions
az role assignment list --assignee $(az account show --query user.name -o tsv)

Contact your Azure admin if you don't have sufficient permissions.

Docker is not running

Start Docker Desktop before running azd up.

# Verify Docker is running
docker info

azd up hangs or times out

Some Azure resources take time to provision. If it times out:

# Resume deployment
azd provision
azd deploy

How do I see what was created?

# List all resources
azd env get-values

# Or check in Azure Portal
# Search for your environment name

Build Your First Agent¶

Once your deployment is complete, use the Agent Builder to create and run your first agent.

Step 1: Open Agent BuilderStep 2: Choose TemplateStep 3: Configure BasicsStep 4: Create AgentStep 5: Verify & Test

From the home screen, click the wrench icon on the left toolbar to open the Agent Editor.

Agent Builder - Initial — Agent Builder interface

Pick a starter template to accelerate setup (recommended for first-time use). Confirm the template details and proceed.

Template Selected — Selecting a template

Enter a name and short description for your agent. Keep defaults for optional fields on your first run; you can refine later.

Naming Convention

Use descriptive names like insurance-claims-agent or customer-support-v1.

Click Create to scaffold your agent from the template. Wait for confirmation that resources and defaults are ready.

Updating Existing Agents

If you create an agent with the same name as an existing one, it will update the existing agent rather than creating a duplicate.

After creation, you'll land on the agent's overview page. Follow the prompts to start your agent and validate the health/status endpoints.

Ready to Iterate

Tweak prompts and parameters, then re-run and observe results. Commit changes as you validate behavior.

Images not rendering?

Verify relative paths from docs/getting-started or open the repo in VS Code's Markdown preview.

Configure Your First Scenario¶

Scenarios define what conversations your agent can handle. Create one to customize your agent's behavior.

Step 1: Access ScenariosStep 2: Open BuilderStep 3: Define Knowledge BaseStep 4: Configure FlowStep 5: Connected Auth (Optional)Step 6: Fraud Detection (Optional)Step 7: Create & Test

From the Agent Builder, select Scenario from the tabs at the top of the window. Then click Create New Scenario or select an existing one to edit.

Scenario Home — Select Scenario tab at the top of the Agent Builder

The scenario builder interface appears with tools and configuration options. Start with a blank scenario or use a pre-built template.

Add a general knowledge base or attach specific documents/instructions. This context powers the agent's responses.

Knowledge Base Setup — Configuring the knowledge base

Set greetings, decision logic, and handoff rules (e.g., transfer to human if unresolved).

Component	Purpose
Greeting	Initial message when call connects
Decision Logic	Routes based on caller intent
Handoff Rules	Escalation to human agents

Integrate backend systems for identity verification and account lookups.

Connected Auth Setup — Connected authentication setup

Run parallel workflows for validation or fraud checks alongside the conversation.

Parallel Fraud Detection — Parallel processing configuration

Click Create Scenario to save your configuration. Then start a voice conversation to test:

Mode	Description
VoiceLive	Real-time streaming with lowest latency
Speech Cascade	Traditional STT → LLM → TTS pipeline

Verify the agent greets you and responds correctly using the KB.

Updating Existing Scenarios

If you create a scenario with the same name as an existing one, it will update the existing scenario rather than creating a duplicate. This makes it easy to iterate on your configurations.

Start Simple

Begin with a greeting + KB + handoff rule. Add connected auth and fraud detection as you scale and iterate.

Next Steps¶

What You Want	Guide
Run locally for development	Local Development
Try the full demo with agents	Demo Guide
Understand the architecture	Architecture Overview
Add a phone number for PSTN calls	Phone Number Setup
Customize agents	Agent Framework

Cleanup¶

When you're done, remove all Azure resources:

azd down --force --purge

This deletes everything

This command removes all Azure resources created by azd up. Your code remains intact.