voice-agents

语音 Agent

概述

为客户发现、反馈和回访电话创建 ElevenLabs Conversational AI 语音 Agent。根据客户背景自动生成 Agent 配置。

快速决策树

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

环境设置

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

常见用法

创建发现 Agent

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

创建反馈 Agent

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

试运行（预览）

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

范围类型

范围	用途
discovery	采访客户团队，了解其运营情况、痛点和技术栈
feedback	收集已完成项目的反馈
check-in	定期进行客户关系回访
qualification	在销售前筛选主动咨询的潜在客户
onboarding	引导新联系人收集所需信息

生成的 Agent 配置

脚本会生成：

Agent 名称

[{Company Name}] {Scope} Agent v1

首条消息

针对语音优化的问候语，其中会：

• 说明来电代表 Casper Studios
• 确认接听者是否为合适的联系人
• 说明与范围相符的来电目的
• 说明预计所需时间（10-15 分钟）
• 征求对方确认

系统提示词

全面的对话指南，包括：

• 身份和背景
• 语气和沟通风格
• 对话流程（5-7 个阶段）
• 访谈技巧
• 防护措施和边界

输出

{
  "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"
}

补充背景信息

脚本可选择从 Google Drive 获取背景信息：

1. 客户的“Research”文档
2. 之前的会议记录（初次通话）

如果无法获取，脚本只会根据提供的备注生成内容。

费用

服务	费用
OpenRouter（提示词生成）	~$0.01-0.03
ElevenLabs Agent 创建	免费
Google Drive	免费

安全说明

凭据处理

• 将 ELEVENLABS_API_KEY 存储在 .env 文件中（切勿提交到 git）
• 将 OPENROUTER_API_KEY 存储在 .env 文件中（切勿提交到 git）
• 如果密钥遭到泄露，请在相应的控制面板中重新生成
• 切勿在脚本输出中记录或打印 API 密钥

数据隐私

• 语音 Agent 会与客户进行实时对话
• 通话内容可能包含敏感的业务讨论
• Agent 提示词可能包含内部业务背景信息
• ElevenLabs 会存储对话日志
• 提示词中可能包含来自 Google Drive 的客户背景信息

访问范围

• ELEVENLABS_API_KEY - 可全面访问语音 Agent 的创建和管理功能
• OPENROUTER_API_KEY - 用于生成提示词的大模型访问权限
• Google OAuth - 可选，用于补充客户背景信息

合规注意事项

• 录音同意：告知来电者对话可能会被录音
• AI 披露：披露来电者正在与 AI Agent 对话
• 来电者隐私：对话数据由 ElevenLabs 服务处理
• GDPR：涉及欧盟来电者的对话需要获得适当同意
• TCPA/CCPA：遵守适用的电信法规
• 通话录音法律：录音法律因司法管辖区而异（一方同意或双方同意）
• 数据保留：查看 ElevenLabs 的数据保留政策
• Agent 防护措施：确保 Agent 遵守适当的对话边界

故障排除

常见问题

问题：Agent 创建失败

症状： 创建语音 Agent 时出现 API 错误 原因： 配置无效、缺少字段或 API 问题 解决方案：

• 验证 Agent 配置的 JSON 格式
• 确保包含所有必需字段（name、first_message、system_prompt）
• 检查提示词长度是否超出限制
• 查看 ElevenLabs API 文档，了解相关要求

问题：语音 ID 无效

症状： 出现“Voice not found”或“invalid voice_id”错误 原因： 语音 ID 不存在或无权访问 解决方案：

• 使用语音库中的有效 ElevenLabs 语音 ID
• 在 https://elevenlabs.io/app/voice-library 查看语音是否可用
• 确认该语音不是其他账户的自定义语音
• 如果无法使用自定义语音，请使用默认语音

问题：API 配额超限

症状：“Quota exceeded”或速率限制错误 **原因：**已达到 ElevenLabs 订阅限制 解决方案：

• 在 https://elevenlabs.io/app/subscription 查看用量
• 升级订阅等级以获得更大容量
• 减少并发 Agent 数量
• 删除未使用的 Agent 以释放名额

问题：Agent 在通话中没有响应

**症状：**Agent 已创建，但在对话中没有响应 **原因：**系统提示词问题、Webhook 配置问题或服务故障 解决方案：

• 先在 ElevenLabs 控制台中直接测试 Agent
• 检查系统提示词，确保指令清晰
• 检查 Webhook URL 是否可访问（如果已配置）
• 确认 ElevenLabs 服务状态

问题：OpenRouter 提示词生成失败

**症状：**生成 Agent 提示词时出错 **原因：**OpenRouter API 问题或模型无效 解决方案：

• 确认 OPENROUTER_API_KEY 设置正确
• 在 OpenRouter 检查模型是否可用
• 如果当前模型不可用，请尝试其他模型
• 使用 --dry-run 运行，在不调用 API 的情况下进行测试

问题：Google Drive 上下文未加载

**症状：**创建的 Agent 没有客户上下文 **原因：**OAuth 问题或未找到客户文件夹 解决方案：

• 确认 Google OAuth 凭据（参见 google-workspace 技能）
• 检查客户文件夹是否位于预期位置
• 也可通过 --notes 标志提供上下文
• 先在不进行上下文增强的情况下运行，以排查问题

资源

• references/elevenlabs.md - ElevenLabs API 详情

集成模式

上下文感知 Agent

技能： transcript-search → voice-agents 用例： 利用客户历史记录创建语音 Agent 流程：

1. 使用 transcript-search 搜索过去的客户会议
2. 提取关系历史、痛点和偏好
3. 将上下文纳入语音 Agent 系统提示词，实现个性化对话

将 Agent 备注写入 CRM

技能： voice-agents → attio-crm **用例：**记录语音 Agent 通话摘要 流程：

1. 语音 Agent 完成需求调研或反馈通话
2. 提取通话摘要、见解和行动事项
3. 在 Attio 公司记录中创建备注，记录通话详情

研究增强型 Agent

技能： parallel-research → voice-agents **用例：**为语音 Agent 配备公司情报 流程：

1. 对目标公司运行 parallel-research
2. 提取近期新闻、融资情况、技术栈和痛点
3. 将研究结果纳入 Agent 提示词，以便开展知情对话