voice-agents

What this skill does

# 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

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

## Common Usage

### Create Discovery Agent
```bash
python scripts/create_voice_agent.py "Microsoft" --scope discovery --notes "CRM migration project"
```

### Create Feedback Agent
```bash
python scripts/create_voice_agent.py "Acme Corp" --scope feedback --notes "Post-project review"
```

### Dry Run (Preview)
```bash
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

```json
{
  "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

| 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:**
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