# ElevenLabs Agents

[ElevenLabs Agents](https://elevenlabs.io/docs/eleven-agents/overview) 是用于构建和部署对话式语音 Agent 的托管平台。它负责协调语音识别、语音合成、轮次处理、工具和对话传输。Agent 可以监听、决策并作出响应，应用无需自行组装每个媒体组件。

组织可能仍希望 Agent 的语言模型流量使用与其他 AI 应用相同的访问控制、路由策略和遥测。为此，ElevenLabs 支持 Custom LLM。Agent 的语音会话继续在 ElevenLabs 中运行，而兼容 OpenAI 的 Chat Completions 请求通过 AISIX 发送到已配置的模型服务提供方。

在此集成中，ElevenLabs 将专用的 AISIX 调用方 API Key 保存为 Secret，在 `model` 中发送 AISIX 模型别名，并以流式方式向网关的 `/v1/chat/completions` 端点发送请求。AISIX 治理模型请求和响应；ElevenLabs 继续处理音频和对话体验。

## 前置条件[​](#prerequisites "前置条件的直接链接")

开始前，请准备以下内容：

* 可使用 ElevenLabs Agents 的 ElevenLabs 账户。
* 一个可编辑的 ElevenLabs Agent。
* 可从公网访问的 AISIX HTTPS 代理 URL。
* 专用于该 Agent 的 AISIX 调用方 API Key。
* 调用方 Key 可以通过[兼容 OpenAI 的 API](https://docs.apiseven.com/ai-gateway/endpoints/openai-compatible-chat.md)访问的模型别名。

不要在 ElevenLabs 中存储上游服务提供方 Key。Custom LLM Secret 应只包含 AISIX 调用方 Key。

## 配置 Custom LLM[​](#configure-the-custom-llm "配置 Custom LLM的直接链接")

在 ElevenLabs Dashboard 中打开 Agent，然后配置模型：

1. 在 **Agent** 页面打开 **LLM**。
2. 打开主要模型选择器，然后选择 **Custom LLM**。
3. 保持 **Chat Completions** 作为 API 格式。
4. 将 **Server URL** 设置为 AISIX 代理 API 根路径并包含 `/v1`，例如 `https://gateway.example.com/v1`。ElevenLabs 会附加 `/chat/completions`。
5. 将 **Model ID** 设置为 AISIX 模型别名，例如 `voice-agent-prod`。
6. 在 **API Key** 下创建或选择一个包含 AISIX 调用方 Key 的 Secret。
7. 选择 **Test Connection**。

连接测试应收到成功的兼容 OpenAI 的响应流。如果失败，请确认该 URL 可从公网访问，并且调用方 Key 有权访问该别名。

连接测试成功后，关闭 LLM 设置并发布 Agent。

## 验证对话[​](#verify-a-conversation "验证对话的直接链接")

打开 **Preview** 并开始一段简短对话。说出一个简单请求，例如“请用一个短句回答”。

确认以下结果：

* Agent 返回语音响应。
* AISIX 记录一条成功的 `POST /v1/chat/completions` 请求。
* 记录的调用方身份和模型与专用的 ElevenLabs Key 和 AISIX 别名一致。

ElevenLabs 负责语音转文本结果、生成的语音、录音设置和对话文本。AISIX 看到的是兼容 OpenAI 的模型请求和响应文本，而不是原始音频流。

## 谨慎使用工具[​](#use-tools-carefully "谨慎使用工具的直接链接")

ElevenLabs 系统工具和自定义工具要求 Custom LLM 生成兼容的函数调用。在生产环境启用工具前，请确认所选模型别名会通过 AISIX 返回工具名称和参数，并且 ElevenLabs 会按预期执行工具。

纯文本连接测试成功并不能证明工具兼容。投入生产前，请测试 Agent 使用的每个系统工具或自定义工具，包括一次轮次中调用多个工具的场景。

## 排查连接问题[​](#troubleshoot-the-connection "排查连接问题的直接链接")

| 现象                   | 检查项                                                                                           |
| ---------------------- | ------------------------------------------------------------------------------------------------ |
| Server URL 无效        | 输入到 `/v1` 为止的 AISIX HTTPS 基础 URL，不要添加 `/chat/completions`；Dashboard 会附加该后缀。 |
| 连接测试返回 `401`     | 确认所选 ElevenLabs Secret 包含 AISIX 调用方 Key。                                               |
| 连接测试返回 `403`     | 确认调用方 Key 允许访问所选模型别名。                                                            |
| 连接测试返回 `404`     | 确认 Model ID 是 AISIX 模型别名，并且 AISIX 代理路由可访问。                                     |
| Agent 一直等待而不说话 | 检查 AISIX 响应流和上游延迟，然后验证 ElevenLabs 的语音与轮次设置。                              |

## 后续步骤[​](#next-steps "后续步骤的直接链接")

* [流式传输](https://docs.apiseven.com/ai-gateway/endpoints/streaming.md)：查看网关的流式行为。
* [工具调用](https://docs.apiseven.com/ai-gateway/endpoints/tool-calling.md)：验证通过 AISIX 的函数调用。
* [指标与用量事件](https://docs.apiseven.com/ai-gateway/observability/metrics-and-usage-events.md)：监控模型延迟和请求结果。
