Voice Agents

Overview

Create ElevenLabs Conversational AI voice agents for client discovery, feedback, and check-in calls. Automatically generates agent configuration from client context.

Quick Decision Tree

What type of agent?
│
├── Discovery agent (interview clients)
│   └── --scope discovery
│
├── Feedback agent (post-project)
│   └── --scope feedback
│
├── Check-in agent (relationship)
│   └── --scope check-in
│
├── Qualification agent (leads)
│   └── --scope qualification
│
└── Onboarding agent (new contacts)
    └── --scope onboarding

Environment Setup

# Required in .env
ELEVENLABS_API_KEY=your_api_key
OPENROUTER_API_KEY=your_api_key  # For prompt generation

Common Usage

Create Discovery Agent

python scripts/create_voice_agent.py "Microsoft" --scope discovery --notes "CRM migration project"

Create Feedback Agent

python scripts/create_voice_agent.py "Acme Corp" --scope feedback --notes "Post-project review"

Dry Run (Preview)

python scripts/create_voice_agent.py "Test Company" --scope discovery --notes "Testing" --dry-run

Scope Types

Scope	Purpose
`discovery`	Interview client team about operations, pain points, tech stack
`feedback`	Gather feedback on completed project
`check-in`	Periodic relationship check-ins
`qualification`	Qualify inbound leads before sales
`onboarding`	Guide new contacts through info gathering

Generated Agent Config

The script generates:

Agent Name

[{Company Name}] {Scope} Agent v1

First Message

Voice-optimized greeting that:

Introduces as calling on behalf of Casper Studios
Confirms speaking with right person
States purpose aligned with scope
Sets time expectations (10-15 minutes)
Asks for confirmation

System Prompt

Comprehensive conversation guide with:

Identity and context
Tone and communication style
Conversation flow (5-7 stages)
Interviewing techniques
Guardrails and boundaries

Output

{
  "agent_id": "abc123xyz",
  "agent_name": "[Microsoft] Discovery Agent v1",
  "agent_url": "https://elevenlabs.io/app/conversational-ai/agents/abc123xyz",
  "first_message": "Hi there! This is an AI assistant...",
  "company_name": "Microsoft",
  "scope": "discovery"
}

Context Enrichment

The script optionally fetches context from Google Drive:

Client's "Research" document
Previous meeting transcripts (intro calls)

If not available, generates with provided notes only.

Cost

Service	Cost
OpenRouter (prompt generation)	~$0.01-0.03
ElevenLabs agent creation	Free
Google Drive	Free

Security Notes

Credential Handling

Store ELEVENLABS_API_KEY in .env file (never commit to git)
Store OPENROUTER_API_KEY in .env file (never commit to git)
Regenerate keys from respective dashboards if compromised
Never log or print API keys in script output

Data Privacy

Voice agents conduct live conversations with customers
Call content may include sensitive business discussions
Agent prompts may contain internal business context
Conversation logs are stored by ElevenLabs
Client context from Google Drive may be included in prompts

Access Scopes

ELEVENLABS_API_KEY - Full access to voice agent creation/management
OPENROUTER_API_KEY - AI model access for prompt generation
Google OAuth - Optional, for client context enrichment

Compliance Considerations

Recording Consent: Inform callers that conversations may be recorded
AI Disclosure: Disclose that caller is speaking with an AI agent
Caller Privacy: Conversation data is processed by ElevenLabs servers
GDPR: EU caller conversations require appropriate consent
TCPA/CCPA: Comply with applicable telecommunications regulations
Call Recording Laws: Recording laws vary by jurisdiction (one-party vs two-party consent)
Data Retention: Review ElevenLabs data retention policies
Agent Guardrails: Ensure agents have appropriate conversation boundaries

Troubleshooting

Common Issues

Issue: Agent creation failed

Symptoms: API error when creating voice agent Cause: Invalid configuration, missing fields, or API issue Solution:

Validate agent config JSON format
Ensure all required fields are present (name, first_message, system_prompt)
Check prompt length doesn't exceed limits
Review ElevenLabs API documentation for requirements

Issue: Invalid voice ID

Symptoms: "Voice not found" or "invalid voice_id" error Cause: Voice ID doesn't exist or not accessible Solution:

Use valid ElevenLabs voice ID from your library
Check voice availability at https://elevenlabs.io/app/voice-library
Verify voice is not a custom voice from another account
Use default voice if custom voice unavailable

Issue: API quota exceeded

Symptoms: "Quota exceeded" or rate limit error Cause: ElevenLabs subscription limits reached Solution:

Check usage at https://elevenlabs.io/app/subscription
Upgrade subscription tier for more capacity
Reduce number of concurrent agents
Delete unused agents to free up slots

Issue: Agent not responding in calls

Symptoms: Agent created but doesn't respond in conversations Cause: System prompt issues, webhook configuration, or service issue Solution:

Test agent directly in ElevenLabs console first
Review system prompt for clear instructions
Check webhook URL is accessible (if configured)
Verify ElevenLabs service status

Issue: OpenRouter prompt generation failed

Symptoms: Error generating agent prompt Cause: OpenRouter API issue or invalid model Solution:

Verify OPENROUTER_API_KEY is set correctly
Check model availability at OpenRouter
Try a different model if current one unavailable
Run with --dry-run to test without API calls

Issue: Google Drive context not loading

Symptoms: Agent created without client context Cause: OAuth issue or client folder not found Solution:

Verify Google OAuth credentials (see google-workspace skill)
Check client folder exists in expected location
Provide context via --notes flag as alternative
Run without context enrichment first to isolate issue

Resources

references/elevenlabs.md - ElevenLabs API details

Integration Patterns

Context-Aware Agents

Skills: transcript-search → voice-agents Use case: Create voice agents with client history Flow:

Search transcript-search for past client meetings
Extract relationship history, pain points, and preferences
Include context in voice agent system prompt for personalized conversations

Agent Notes to CRM

Skills: voice-agents → attio-crm Use case: Log voice agent call summaries Flow:

Voice agent completes discovery or feedback call
Extract call summary, insights, and action items
Create note on Attio company record with call details

Research-Enriched Agents

Skills: parallel-research → voice-agents Use case: Arm voice agents with company intelligence Flow:

Run parallel-research on target company
Extract recent news, funding, tech stack, and pain points
Include research in agent prompt for informed conversations