Back to Details

voice-agents

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Voice Agents

语音Agent

Overview

概述

Create ElevenLabs Conversational AI voice agents for client discovery, feedback, and check-in calls. Automatically generates agent configuration from client context.
创建用于客户发现、反馈和跟进通话的ElevenLabs对话式AI语音Agent。可根据客户上下文自动生成Agent配置。

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
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
undefined
bash
undefined

Required in .env

Required in .env

ELEVENLABS_API_KEY=your_api_key OPENROUTER_API_KEY=your_api_key # For prompt generation
undefined
ELEVENLABS_API_KEY=your_api_key OPENROUTER_API_KEY=your_api_key # For prompt generation
undefined

Common Usage

常见用法

Create Discovery Agent

创建发现Agent

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

Create Feedback Agent

创建反馈Agent

bash
python scripts/create_voice_agent.py "Acme Corp" --scope feedback --notes "Post-project review"
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
bash
python scripts/create_voice_agent.py "Test Company" --scope discovery --notes "Testing" --dry-run

Scope Types

范围类型

ScopePurpose
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
范围用途
discovery
采访客户团队，了解其业务运营、痛点及技术栈
feedback
收集已完成项目的反馈
check-in
定期进行客户关系跟进
qualification
在销售前筛选潜在客户
onboarding
引导新联系人完成信息收集

Generated Agent Config

生成的Agent配置

The script generates:
脚本会生成以下内容：

Agent Name

Agent名称

[{Company Name}] {Scope} Agent v1
[{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
优化后的语音问候语，包含：
  • 表明代表Casper Studios致电
  • 确认通话对象是否正确
  • 说明与当前范围匹配的通话目的
  • 告知预计时长（10-15分钟）
  • 请求对方确认

System Prompt

系统提示词

Comprehensive conversation guide with:
  • Identity and context
  • Tone and communication style
  • Conversation flow (5-7 stages)
  • Interviewing techniques
  • Guardrails and boundaries
全面的对话指南，包含：
  • 身份与上下文信息
  • 语气与沟通风格
  • 对话流程（5-7个阶段）
  • 访谈技巧
  • 对话边界与约束规则

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"
}
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.
脚本可选择性地从Google Drive获取上下文信息：
  1. 客户的“研究”文档
  2. 过往会议记录（首次通话）
若无法获取上述内容，则仅使用提供的备注生成配置。

Cost

成本说明

ServiceCost
OpenRouter (prompt generation)~$0.01-0.03
ElevenLabs agent creationFree
Google DriveFree
服务成本
OpenRouter（提示词生成）约0.01-0.03美元
ElevenLabs Agent创建免费
Google Drive免费

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
  • 将
    ELEVENLABS_API_KEY
    存储在
    .env
    文件中（切勿提交至git）
  • 将
    OPENROUTER_API_KEY
    存储在
    .env
    文件中（切勿提交至git）
  • 若凭证泄露，从对应控制台重新生成密钥
  • 切勿在脚本输出中记录或打印API密钥

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
  • 语音Agent会与客户进行实时对话
  • 通话内容可能包含敏感业务讨论
  • Agent提示词可能包含内部业务上下文
  • 对话日志由ElevenLabs存储
  • 来自Google Drive的客户上下文可能会被包含在提示词中

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
  • ELEVENLABS_API_KEY
    - 拥有语音Agent创建/管理的完整权限
  • OPENROUTER_API_KEY
    - 用于访问AI模型生成提示词
  • Google OAuth - 可选，用于客户上下文增强

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
  • 录音同意：告知通话者对话可能会被录音
  • AI披露：向通话者说明其正在与AI Agent对话
  • 通话者隐私：对话数据由ElevenLabs服务器处理
  • GDPR：与欧盟通话者的对话需获得适当同意
  • TCPA/CCPA：遵守适用的电信法规
  • 录音法律：录音法律因司法管辖区而异（单方同意vs双方同意）
  • 数据保留：查阅ElevenLabs的数据保留政策
  • Agent约束规则：确保Agent具备适当的对话边界

Troubleshooting

故障排除

Common Issues

常见问题

Issue: Agent creation failed

问题：Agent创建失败

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
症状：创建语音Agent时出现API错误 原因：配置无效、字段缺失或API问题 解决方案：
  • 验证Agent配置的JSON格式
  • 确保所有必填字段（名称、first_message、system_prompt）均已填写
  • 检查提示词长度是否超出限制
  • 查阅ElevenLabs API文档了解要求

Issue: Invalid voice ID

问题：无效的语音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
症状：出现“Voice not found”或“invalid voice_id”错误 原因：语音ID不存在或无法访问 解决方案：

Issue: API quota exceeded

问题：API配额超出

Symptoms: "Quota exceeded" or rate limit error Cause: ElevenLabs subscription limits reached Solution:
症状：出现“Quota exceeded”或速率限制错误 原因：已达到ElevenLabs订阅限制 解决方案：

Issue: Agent not responding in calls

问题：Agent在通话中无响应

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
症状：Agent已创建，但在对话中不响应 原因：系统提示词问题、Webhook配置错误或服务故障 解决方案：
  • 先在ElevenLabs控制台中直接测试Agent
  • 检查系统提示词是否包含清晰的指令
  • 确认Webhook URL可访问（若已配置）
  • 验证ElevenLabs服务状态

Issue: OpenRouter prompt generation failed

问题：OpenRouter提示词生成失败

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
症状：生成Agent提示词时出错 原因：OpenRouter API问题或模型无效 解决方案：
  • 验证
    OPENROUTER_API_KEY
    是否设置正确
  • 检查OpenRouter上的模型可用性
  • 若当前模型不可用，尝试其他模型
  • 使用
    --dry-run
    参数运行，无需调用API即可测试

Issue: Google Drive context not loading

问题：Google Drive上下文无法加载

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
症状：创建的Agent未包含客户上下文 原因：OAuth问题或未找到客户文件夹 解决方案：
  • 验证Google OAuth凭证（参考google-workspace技能）
  • 检查客户文件夹是否位于预期位置
  • 使用
    --notes
    参数提供上下文作为替代方案
  • 先不启用上下文增强，排查问题

Resources

资源

  • references/elevenlabs.md - ElevenLabs API details
  • references/elevenlabs.md - ElevenLabs API详细说明

Integration Patterns

集成模式

Context-Aware Agents

上下文感知Agent

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
技能：transcript-search → voice-agents 使用场景：创建包含客户历史记录的语音Agent 流程：
  1. 使用transcript-search搜索过往客户会议记录
  2. 提取关系历史、痛点及偏好
  3. 将上下文包含在语音Agent的系统提示词中，实现个性化对话

Agent Notes to CRM

Agent通话记录同步至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
技能：voice-agents → attio-crm 使用场景：记录语音Agent的通话摘要 流程：
  1. 语音Agent完成发现或反馈通话
  2. 提取通话摘要、见解及行动项
  3. 在Attio的公司记录中创建包含通话详情的笔记

Research-Enriched Agents

研究增强型Agent

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
技能：parallel-research → voice-agents 使用场景：为语音Agent配备企业情报 流程：
  1. 对目标公司运行parallel-research
  2. 提取近期新闻、融资情况、技术栈及痛点
  3. 将研究内容包含在Agent提示词中，实现更具信息量的对话