介绍
# Voice.ai Agents
使用 Voice.ai 的 Agent API 构建最佳的对话式 AI 语音代理。
## ✨ 功能特性
- **Agent 管理** - 创建、更新和删除语音代理 - **一键部署** - 即时部署代理以进行电话通话 - **知识库** - 基于自定义知识的 RAG 代理 - **MCP 集成** - 通过 MCP 将代理连接到外部工具 - **电话号码** - 管理入站/出站电话号码 - **分析** - 追踪通话历史和代理性能
## ⚙️ 配置
### 获取您的 API Key
1. 访问 [Voice.ai 开发者仪表板](https://voice.ai/app/dashboard/developers) 2. 登录或创建账户 3. 生成新的 API Key 4. 复制并妥善保存
### 设置身份验证 (3 种方法)
**方法 1: 环境变量 (推荐)** ```bash export VOICE_AI_API_KEY="your-api-key-here" ```
**方法 2: .env 文件** ```bash # Create .env file in project root echo 'VOICE_AI_API_KEY=your-api-key-here' >> .env ```
**方法 3: OpenClaw 配置** ```json { "skills": { "voice.ai-voice-agents": { "api_key": "your-api-key-here" } } } ```
## 🔐 在执行任何操作之前
> **重要提示:** 在运行任何命令之前，请务必验证身份验证。
```bash # 1. Check if API key is set echo $VOICE_AI_API_KEY
# 2. Test connection (list agents) node scripts/agent.js list
# 3. If errors, re-export your key export VOICE_AI_API_KEY="your-api-key-here" ```
### 静默初始化
设置 API Key 后，SDK 会在运行任何命令时自动初始化。无需手动设置。
## 🚀 快速开始
```bash export VOICE_AI_API_KEY="your-api-key"
# Create an agent node scripts/agent.js create --name "Support Bot" --prompt "You are a helpful assistant"
# List all agents node scripts/agent.js list
# Deploy an agent node scripts/agent.js deploy --id <agent_id> ```
## 🤖 代理配置
| 参数 | 默认值 | 描述 | |------------------------|---------|--------------------------------------| | llm_model | gemini-2.5-flash-lite | 用于响应的 LLM 模型 | | llm_temperature | 0.7 | 响应创造性 (0-2) | | max_call_duration | 900 | 最大通话时长 (秒) | | allow_interruptions | true | 允许用户打断代理 | | auto_noise_reduction | true | 过滤背景噪音 |
## 🎙️ TTS 语音设置
| 参数 | 默认值 | 描述 | |-------------|---------|--------------------------------| | voice_id | - | 用于代理语音的语音 ID | | model | auto | TTS 模型 (自动选择) | | language | en | 语言代码 | | temperature | 1.0 | 语音表现力 (0-2) | | top_p | 0.8 | 采样参数 (0-1) |
## 🌍 支持的语言
`auto`, `en`, `ca`, `sv`, `es`, `fr`, `de`, `it`, `pt`, `pl`, `ru`, `nl`
## 💻 CLI 用法
```bash # Create a new agent node scripts/agent.js create --name "My Agent" --prompt "System prompt here" --greeting "Hello!"
# List all agents node scripts/agent.js list
# Get agent details node scripts/agent.js get --id <agent_id>
# Update an agent node scripts/agent.js update --id <agent_id> --prompt "New prompt"
# Deploy an agent node scripts/agent.js deploy --id <agent_id>
# Pause an agent node scripts/agent.js pause --id <agent_id>
# Delete an agent node scripts/agent.js delete --id <agent_id> ```
## 🤖 OpenClaw 集成
### JSON 配置
```json { "name": "voice.ai-voice-agents", "enabled": true, "config": { "api_key": "${VOICE_AI_API_KEY}", "default_model": "gemini-2.5-flash-lite", "auto_deploy": false } } ```
### 聊天触发器
当您提到以下内容时，OpenClaw 会自动激活此技能： - "voice agent", "voice bot", "phone agent" - "create agent", "deploy agent", "list agents" - "Voice.ai", "voice ai"
## 🗣️ 用户友好的语言
| 当用户说... | 技能执行... | |-------------------|---------------| | "Create a support agent" | 创建具有客服重点提示词的代理 | | "Show my agents" | 列出所有代理及其状态 | | "Deploy the agent" | 部署代理以进行电话通话 | | "Update the greeting" | 更新代理问候语 | | "Delete the test agent" | 删除指定代理 | | "What agents do I have?" | 以友好格式列出代理 | | "Make an FAQ bot" | 使用 FAQ 模板创建代理 | | "Connect to my MCP server" | 配置 MCP 集成 |
## 📁 项目文件
``` voice-ai-agents/ ├── SKILL.md # This documentation ├── voice-ai-agents.yaml # Skill configuration ├── voice-ai-agents-sdk.js # JavaScript SDK └── scripts/ └── agent.js # CLI tool ```
| 文件 | 用途 | |------|---------| | `SKILL.md` | 文档和 OpenClaw 技能定义 | | `voice-ai-agents.yaml` | API 配置、模型、默认值 | | `voice-ai-agents-sdk.js` | 包含所有 API 方法的完整 SDK | | `scripts/agent.js` | 命令行界面 |
## ❌ 错误处理
| 错误 | 原因 | 解决方案 | |-------|-------|----------| | `401 Unauthorized` | API Key 无效或缺失 | 检查 `VOICE_AI_API_KEY` 是否设置正确 | | `403 Forbidden` | API Key 缺少权限 | 生成具有正确范围的新 Key | | `404 Not Found` | 代理 ID 不存在 | 运行 `list` 获取有效的代理 ID | | `429 Too Many Requests` | 超过速率限制 | 等待 60 秒后重试 | | `500 Server Error` | Voice.ai API 问题 | 检查 [状态页面](https://status.voice.ai) | | `ENOTFOUND` | 网络错误 | 检查互联网连接 | | `Agent not deployed` | 代理存在但未激活 | 运行 `deploy --id <agent_id>` |
### 优雅的错误消息
SDK 提供用户友好的错误消息： ``` ❌ Authentication failed. Please check your API key. Get one at: https://voice.ai/app/dashboard/developers
❌ Agent "support-bot" not found. Run 'node scripts/agent.js list' to see available agents.
❌ Rate limit reached. Please wait 60 seconds before retrying. ```
## 📝 触发器
这些短语会在 OpenClaw 中激活 Voice.ai Agents 技能：
| 类别 | 触发短语 | |----------|-----------------| | **创建** | "create voice agent", "make a phone bot", "new agent" | | **列出** | "show agents", "list my agents", "what agents exist" | | **部署** | "deploy agent", "activate agent", "start the bot" | | **更新** | "update agent", "change prompt", "edit greeting" | | **删除** | "delete agent", "remove bot", "destroy agent" | | **信息** | "agent details", "show agent", "get agent info" |
## 🔗 MCP 服务器集成
将您的代理连接到外部工具：
```javascript const agent = await client.createAgent({ name: "MCP Agent", config: { prompt: "You can use tools to help users", mcp_servers: [{ name: "my-tools", url: "https://my-server.com/mcp", auth_type: "bearer_token", auth_token: "secret" }] } }); ```
## 📚 知识库 (RAG)
为您的代理添加自定义知识：
```bash # Create agent with knowledge base node scripts/agent.js create --name "FAQ Bot" --kb-id 123 ```
## 🔗 链接
- [获取 API Key](https://voice.ai/app/dashboard/developers) ← 从这里开始！ - [Voice 代理指南](https://voice.ai/docs/guides/voice-agents/quickstart) - [代理 API 参考](https://voice.ai/docs/api-reference/agent-management/create-agent) - [状态页面](https://status.voice.ai)
## 📋 更新日志
| 版本 | 日期 | 变更 | |---------|------|---------| | 1.0.0 | 2026-01-31 | 初始发布，包含完整的代理管理功能 |
---
由 [Nick Gill](https://github.com/gizmoGremlin) 用 ❤️ 制作