Elevenlabs Agents

ElevenLabs代理集成

一个完整的工具包，用于将ElevenLabs对话式人工智能代理与Claude Code和其他人工智能助手集成。该存储库包含克劳德代码技能和MCP服务器，用于无缝的语音AI交互。

概述

此存储库提供了两个互补的组件：

1. 克劳德代码技能 (skill/)-Claude Code的预构建技能定义，包括使用示例和API参考
2. MCP服务器 (mcp-server/)-作为无服务器功能在Vercel上运行的模型上下文协议服务器

这些功能共同使人工智能助理能够与ElevenLabs语音代理进行交互，发起对话，拨打出站电话，并检索对话记录。

快速开始

适用于Claude Code用户

在Claude代码配置中安装该技能：

# Copy skill to Claude Code skills directory
cp -r skill ~/.claude/skills/elevenlabs-agents

然后将MCP服务器添加到您的Claude Code MCP配置中：

{
  "mcpServers": {
    "elevenlabs-agents": {
      "url": "https://your-app.vercel.app/mcp",
      "transport": "http"
    }
  }
}

对于开发者

将MCP服务器部署到Vercel：

cd mcp-server
npm install
vercel --prod

重要：设置 ELEVENLABS_API_KEY 作为项目设置中的Vercel环境变量（不在 .env 文件）。

特性

代理管理

• 列出代理：在您的帐户中获取所有可用的ElevenLabs代理
• 获取代理详细信息：检索特定代理的详细信息

对话能力

• 发起代理呼叫：启动与代理的对话并等待完成（默认超时50秒，可配置最多300秒）
• 外拨电话：使用代理拨打任何号码
• 状态跟踪：监控通话进度和完成情况
• 成绩单检索：获取包含元数据的完整对话记录

通话结果

系统处理多种呼叫场景：

• 完成：成功的对话，有完整的成绩单
• 失败：遇到错误的调用
• 无答复：已拨打但从未接听的电话
• 进行中：正在进行或正在处理呼叫

存储库结构

elevenlabs-agents/
├── README.md                    # This file
├── CLAUDE.md                    # Project instructions for Claude Code
├── skill/                       # Claude Code skill files
│   ├── SKILL.md                 # Skill definition and usage guide
│   ├── examples.md              # Comprehensive usage examples
│   └── reference.md             # API reference documentation
└── mcp-server/                  # MCP server implementation
    ├── README.md                # Detailed MCP server documentation
    ├── api/                     # Vercel serverless functions
    ├── lib/                     # Core implementation
    │   ├── elevenlabs/          # ElevenLabs API client
    │   └── mcp/                 # MCP server logic
    ├── test/                    # Test scripts
    ├── package.json
    ├── tsconfig.json
    └── vercel.json              # Vercel configuration

先决条件

• ElevenLabs API密钥：从以下位置获取一个 十一实验室
• Vercel帐户：用于部署MCP服务器
• Node.js 18+：促进地方发展
• （可选）电话号码：用于出站呼叫功能

安装指南

1.获取ElevenLabs API密钥

1. 注册地址： 十一实验室
2. 导航到API设置
3. 生成或复制API密钥

2.将MCP服务器部署到Vercel

cd mcp-server
npm install

# Install Vercel CLI if needed
npm i -g vercel

# Login to Vercel
vercel login

# Deploy to production
vercel --prod

3.在Vercel中配置环境变量

关键的：在Vercel仪表板中设置环境变量，而不是在 .env 文件夹：

1. 转到Vercel项目设置
2. 导航到“环境变量”
3. 添加： ELEVENLABS_API_KEY = your_elevenlabs_api_key_here
4. 适用于生产、预览和开发环境

为什么选择Vercel环境变量？

• 安全：从不承诺版本控制
• 环境特定：dev/ststage/prod的不同键
• 自动：适用于所有无服务器功能
• 标准做法：Vercel推荐的方法

4.添加到克劳德代码

部署后，将MCP服务器URL添加到您的Claude Code配置中：

{
  "mcpServers": {
    "elevenlabs-agents": {
      "url": "https://your-app.vercel.app/mcp",
      "transport": "http"
    }
  }
}

可用的MCP工具

代理管理

• list_agents -获取您帐户中的所有代理
• get_agent -获取特定代理的详细信息

对话

• initiate_agent_call -开始对话并等待完成

- 默认超时：50秒（最多可配置300秒） - 完成后返回完整成绩单

出站呼叫

• list_phone_numbers -获取出站呼叫的可用电话号码
• initiate_outbound_call -拨打任意号码

- 电话格式：E.164（例如+15551234567） - 返回用于跟踪的对话_id

状态和成绩单

• get_call_status -检查对话的当前状态

- 状态：已启动、正在进行、正在处理、已完成、失败

• get_call_transcript -检索任何已完成通话的完整记录

- 为已完成、失败和无人接听的电话工作 - 包括对话轮次、时间戳、成本和元数据

使用示例

快速试剂测试

// List agents
const agents = await useMCP('elevenlabs-agents', 'list_agents');

// Test an agent
const result = await useMCP('elevenlabs-agents', 'initiate_agent_call', {
  agent_id: 'agent_xxx',
  initial_message: 'Hello, can you tell me about your services?'
});

console.log(result.transcript);

出站电话

// Check available phone numbers
const numbers = await useMCP('elevenlabs-agents', 'list_phone_numbers');

// Initiate call
const call = await useMCP('elevenlabs-agents', 'initiate_outbound_call', {
  agent_id: 'agent_xxx',
  to_number: '+15551234567'
});

// Poll for status
const status = await useMCP('elevenlabs-agents', 'get_call_status', {
  conversation_id: call.conversation_id
});

// Get transcript when done
if (status.call_outcome === 'completed') {
  const transcript = await useMCP('elevenlabs-agents', 'get_call_transcript', {
    conversation_id: call.conversation_id
  });
}

常见工作流

开发工作流程

1. 对以下内容进行更改 mcp-server/ 代码
2. 本地测试： cd mcp-server && npm run dev
3. 部署预览： vercel
4. 使用预览URL在Claude代码中进行测试
5. 部署生产： vercel --prod

测试代理更改

1. 更新ElevenLabs仪表板中的代理配置
2. 使用 list_agents 验证更改
3. 测试用 initiate_agent_call 用于快速验证
4. 监控成绩单以确保质量

建筑

无服务器设计

• HTTP传输：作为Vercel无服务器函数运行
• 无状态：没有持久连接或状态
• 超时感知：默认50秒，最大300秒（Vercel限制）
• 重试逻辑：API调用的带指数退避的自动重试

投票策略

• 以2秒的间隔开始
• 指数退避（1.5倍乘数）
• 最大间隔：10秒
• 继续对瞬态错误进行轮询

错误处理

• 网络错误：最多重试3次
• API错误：使用状态代码和消息格式化
• 工具错误：以MCP错误格式包装

本地开发

在本地运行MCP服务器

cd mcp-server

# Set environment variable
export ELEVENLABS_API_KEY=your_api_key

# Run with stdio transport (for testing)
node lib/mcp/server.ts

# Or run with Vercel dev server (HTTP transport)
npm run dev

然后测试 http://localhost:3000/api/mcp

运行测试

cd mcp-server
npm test

故障排除

“身份验证失败”错误

• 验证 ELEVENLABS_API_KEY 在Vercel环境变量中设置（不是 .env)
• 检查ElevenLabs仪表板中的API密钥是否有效
• 确保密钥具有适当的权限

对话超时

• 默认超时时间为50秒；增加通过 timeout 参数（如果需要）
• 最大超时时间为300秒（Vercel无服务器限制）
• 对于较长的对话，使用带状态轮询的出站呼叫
• 检查Vercel函数日志是否有错误

“没有可用的电话号码”

• 验证ElevenLabs帐户中是否配置了电话号码
• 检查电话号码权限和状态
• 使用 list_phone_numbers 查看可用号码

出站呼叫未连接

• 确保电话号码为E.164格式（+15551234567）
• 检查收件人手机是否可以接听电话
• 验证Twilio集成在ElevenLabs中是否处于活动状态

安全最佳实践

• 永远不要提交API密钥：仅使用Vercel环境变量
• CORS已配置：正确设置MCP客户端访问
• 环境隔离：dev/ststage/prod的单独键
• 定期轮换：定期更新API密钥

文档

技能文档

• skill/SKILL.md -技能定义和使用指南
• skill/examples.md -综合使用示例
• skill/reference.md -API参考文件

MCP服务器文档

• mcp-server/README.md -详细的服务器文档
• CLAUDE.md -Claude Code项目说明

外部资源

• ElevenLabs API文档
• 模型上下文协议
• Vercel文档

贡献

欢迎投稿！请确保：

1. TypeScript类型定义正确
2. 错误处理全面
3. 测试通过： cd mcp-server && npm test
4. 文档已更新
5. 记录环境变量

局限性

• 超时：由于Vercel的限制，每个请求最多300秒（5分钟）
• 无状态：无后台作业处理或持久状态
• 同步：所有操作在单个请求生命周期内完成

对于超过5分钟的对话，使用带状态轮询的出站呼叫模式。

许可证

麻省理工学院

支持

• 问题:
• 十一实验室: ElevenLabs文档
• MCP协议: MCP文件
• 维塞尔: Vercel文档