Demo Guide

Demo Guide¶

Choose Your Path¶

Step 1: Create a Demo Profile¶

Before you can have a personalized conversation with the AI agents, you need to create a demo profile. This generates synthetic customer data that agents use for context-aware interactions.

Create Your Profile¶

1. Open the frontend application at http://localhost:5173 (or your deployed URL)

2. Click the profile icon (👤) in the bottom navigation bar

3. Click "Create Demo Profile" to open the profile creation form

4. Fill in the required fields:

   Field	Description	Example
   Full Name	Your display name for the demo	John Smith
   Email	Use your real work email if testing MFA features	john.smith@yourcompany.com
   Phone Number (optional)	E.164 format for SMS demos	+14155551234
   Preferred Channel	MFA delivery preference	email or sms

1. Click "Create Profile" — The system generates:
   • A unique client_id for your session
   • Synthetic financial data (account balances, transaction history)
   • Customer intelligence data (communication preferences, relationship history)
   • Demo-safe verification codes

What Gets Generated¶

Your demo profile includes rich context that agents use for personalized interactions:

Step 2: Create and Configure Agents (Intermediate)¶

The Agent Builder lets you create custom AI agents directly from the frontend without editing YAML files.

Open the Agent Builder¶

1. Click the robot icon (🤖) in the bottom navigation bar
2. The Agent Builder panel opens on the left side

Understanding Agent Configuration¶

Configure Tools¶

Tools give agents capabilities to take actions. Each agent's tools are defined in their agent.yaml file:

# Example from concierge/agent.yaml
tools:
  - verify_client_identity
  - get_account_summary
  - handoff_card_recommendation
  - handoff_investment_advisor
  - transfer_call_to_call_center

Understanding Scenarios¶

Scenarios define the complete multi-agent orchestration graph. Each scenario specifies:

1. Which agents are included in the conversation flow
2. The starting agent for the scenario
3. Handoff routes — directed edges defining agent-to-agent transfers
4. Handoff behavior — discrete (silent) or announced (target agent greets)

Scenarios are defined in YAML files under apps/artagent/backend/registries/scenariostore/:

Handoff Configuration (Scenario-Level)¶

Handoffs are now configured at the scenario level, not per-agent. Each handoff is a directed edge in the agent graph:

# Example from banking/orchestration.yaml
handoffs:
  - from: BankingConcierge
    to: CardRecommendation
    tool: handoff_card_recommendation
    type: discrete            # Silent transition
    share_context: true

  - from: CardRecommendation
    to: BankingConcierge
    tool: handoff_concierge
    type: discrete            # Seamless return

Handoff Types:

Example: Banking Scenario Graph:

Configure VAD (Voice Activity Detection)¶

VAD settings control how the system detects when you're speaking:

Voice Configuration¶

Popular voice options:

Step 3: Start a Voice Conversation¶

Launch the Voice Interface¶

1. Click the person icon (👤) in the bottom navigation to access conversation mode
2. You'll see two orchestration options:

Choose Your Orchestration Mode¶

The system supports two orchestration modes. Select based on your latency and customization needs:

Voice Live (Recommended for Low Latency)¶

Audio streams directly to OpenAI's Realtime API:

🎤 Your Voice  →  OpenAI Realtime API  →  🔊 Audio Response

Best for: Lowest latency requirements, simple demos, when Azure Speech customization isn't needed.

Cascade (Recommended for Control)¶

Audio flows through Azure Speech services with separate STT and TTS:

🎤 Your Voice  →  Azure STT  →  LLM  →  Azure TTS  →  🔊 Audio

Best for: Custom VAD/segmentation control, Azure Neural Voice selection, phrase list customization, fine-grained audio control.

Start Speaking¶

1. Allow microphone access when prompted
2. Wait for the greeting — the active agent introduces itself
3. Start your conversation!

Step 4: Understanding the Conversation Flow¶

What to Observe During Conversations¶

Key Metrics to Watch¶

Handoff Behavior¶

When an agent hands off to another agent, behavior depends on the handoff type defined in the scenario:

Context is always transferred:

1. handoff_context — Includes reason, summary, and relevant data
2. previous_agent — Target agent knows who handed off
3. share_context: true — Preserves full conversation history (configurable)

Example: Announced Handoff (Fraud)

Example: Discrete Handoff (Same-team specialist)

Watch for Anomalies¶

Demo Scenarios to Try¶

Basic Scenarios¶

MFA Scenarios (Requires Real Email)¶

Handoff Scenarios¶

Barge-in Testing¶

Troubleshooting¶

Quick Diagnostics¶

# Check backend health
curl http://localhost:8010/health

# Check readiness (all dependencies)
curl http://localhost:8010/readiness

# View available agents
curl http://localhost:8010/api/v1/agents

# View available scenarios
ls apps/artagent/backend/registries/scenariostore/

# Check scenario configuration
cat apps/artagent/backend/registries/scenariostore/banking/orchestration.yaml

Environment Variables Checklist¶

Ensure your root .env file contains:

# ===== Required for Voice =====
AZURE_SPEECH_REGION=eastus          # Your Speech Services region
AZURE_SPEECH_KEY=<your-key>         # Or use managed identity

# ===== Required for AI =====
AZURE_OPENAI_ENDPOINT=https://<your-aoai>.openai.azure.com
AZURE_OPENAI_KEY=<your-key>
AZURE_OPENAI_DEPLOYMENT=gpt-4o      # Your deployment name

# ===== For Demo Profiles =====
AZURE_COSMOS_CONNECTION_STRING=<cosmos-conn-string>
AZURE_COSMOS_DATABASE_NAME=financial_services_db

# ===== For Session State =====
REDIS_HOST=<redis-host>
REDIS_PORT=6380
REDIS_PASSWORD=<redis-password>

# ===== Orchestration Mode =====
ACS_STREAMING_MODE=VOICE_LIVE       # or MEDIA for Cascade

# ===== Dev Tunnel (local dev) =====
BASE_URL=https://<tunnel-url>       # From devtunnel host

Common Issues¶

# Verify scenario handoff configuration
cat apps/artagent/backend/registries/scenariostore/banking/orchestration.yaml

Log Locations¶

Getting Help¶

• GitHub Issues — Report bugs
• Troubleshooting Guide — Detailed solutions
• API Reference — Endpoint documentation

Next Steps¶

Key Configuration Locations¶