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

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:

1. •Client's "Research" document
2. •Previous meeting transcripts (intro calls)

If not available, generates with provided notes only.

Cost

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:

1. •Search transcript-search for past client meetings
2. •Extract relationship history, pain points, and preferences
3. •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:

1. •Voice agent completes discovery or feedback call
2. •Extract call summary, insights, and action items
3. •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:

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