voice-agents（语音 Agent）

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