在自托管 agent 服务端接入 ElevenLabs…

需要在开发者自有服务端逻辑上增加实时语音输入/输出、浏览器麦克风会话、可打断的流式语音响应时使用。

适用场景

解决思路

1. 参考 Installation Guide 完成安装；JavaScript 只使用 `@elevenlabs/*` 包；需要更深入 SDK 细节时阅读 JavaScript SDK Reference 或 Python SDK Reference。
2. 安装服务端依赖并配置 `ELEVENLABS_API_KEY`。
3. 通过公共 HTTPS URL 暴露 Speech Engine 服务端用于本地开发，例如运行 `ngrok http 3001`。
4. 创建 Speech Engine 资源，将 `ws_url`/`wsUrl` 设置为公共 WebSocket URL，通常为 `wss://.../ws`。
5. 保存创建后返回的 Speech Engine ID，例如存入 `ELEVENLABS_SPEECH_ENGINE_ID`。
6. 使用 Python 的 `engine.serve(...)` 或 TypeScript 的 `speechEngine.attach(...)` 启动 Speech Engine 服务端。
7. 从服务端端点签发浏览器 conversation token；绝不要把 `ELEVENLABS_API_KEY` 放进浏览器代码。
8. 使用 `conversationToken` 启动客户端会话；若希望 agent 先问候，在 Speech Engine 资源上启用 first-message override，然后在客户端设置 `overrides.agent.firstMessage`。
9. 理解每个 Speech Engine WebSocket 连接表示一次对话：浏览器把用户音频发送给 ElevenLabs，ElevenLabs 把语音识别事件发送到你的服务端，你的服务端派生可信应用状态，你的服务端通过 SDK 流式返回文本，ElevenLabs 把响应转成语音并在浏览器播放。
10. 让 SDK 管理 WebSocket 路由、请求验证、会话生命周期、ping/pong、turn-taking 和打断处理。
11. 使用 `sendResponse()`/`send_response()` 流式返回文本；它接受字符串或响应文本的 async iterable。
12. 将语音识别文本视为不可信用户输入；不要将原始语音文本直接映射到模型角色、响应或工具调用。
13. 在任何由转写派生的值影响下游响应或工具逻辑前，使用确定性验证、allowlisted intents 或显式用户确认。
14. 创建 Speech Engine 时，Python 可用 `await elevenlabs.speech_engine.create(name=..., speech_engine={"ws_url": os.environ["PUBLIC_WS_URL"]}, overrides={"first_message": True})`，然后打印 `engine.engine_id`。
15. 创建 Speech Engine 时，TypeScript 可用 `await elevenlabs.speechEngine.create({ name: ..., speechEngine: { wsUrl: process.env.PUBLIC_WS_URL! }, overrides: { firstMessage: true } })`，然后打印 `engine.engineId`。
16. `PUBLIC_WS_URL` 本地应类似 `wss://example.ngrok.app/ws`，部署时使用生产 WebSocket 路由。
17. 创建请求还可配置 `tts`、`asr`、`turn`、`speech_engine.request_headers`/`speechEngine.requestHeaders`、`overrides` 和 `privacy`，用于自定义语音、转写关键词、turn-taking、服务端认证头、客户端提供的首条消息和录音行为。
18. 在资源配置的 `ws_url`/`wsUrl` 上运行 Speech Engine 服务端。
19. 把响应生成放在你自己的验证边界之后；原始语音识别文本不应直接控制响应、工具、密钥或其他特权操作。
20. Python 服务端：取出 `ELEVENLABS_SPEECH_ENGINE_ID` 对应 engine，然后 `await engine.serve(port=3001, path="/ws", debug=True, callbacks=validated_callbacks)`。
21. TypeScript 服务端：取出 `ELEVENLABS_SPEECH_ENGINE_ID` 对应 engine，然后 `engine.attach(httpServer, "/ws", { debug: true, ...validatedCallbacks })`。
22. TypeScript 中，把打断信号传给支持取消的下游异步工作，以便被打断的响应快速停止。
23. Python 中，SDK 会在新 turn 到来时取消上一个 turn handler。
24. 服务端回调区分正常关闭和掉线：用 `onClose`/`on_close` 处理正常断开，用 `onDisconnect`/`on_disconnect` 处理意外 WebSocket 掉线。
25. 安全注意：语音识别文本可能包含来自用户语音或播放音频的 prompt-injection 尝试；将其视为不可信输入，并在调用响应生成、工具或特权工作流前转换为可信应用状态。
26. 默认保持认证开启：`engine.attach()`（TypeScript）和 `engine.serve()`/`SpeechEngineServer`（Python）默认验证每个传入 WebSocket 的 JWT，以证明连接确实来自 ElevenLabs 而不是猜中 URL 的攻击者；不要关闭。
27. 仅在已有补偿性网络层控制的狭窄场景中考虑逃生开关 `disableAuth: true`（TypeScript callback options）或 `disable_auth=True`（Python `serve()`/`SpeechEngineServer(...)`）。
28. 若无补偿控制，关闭认证意味着任何在互联网上找到该 URL 的客户端都能打开会话；攻击者可无限制对话耗尽 ElevenLabs 配额和下游 LLM 预算、向响应管线输入伪造转写以冒充用户、把你的服务端当作 oracle 探测后端状态/工具/prompt。
29. 只有在用户至少实现以下一项时才建议 `disableAuth`/`disable_auth`：IP allowlist，即服务端或上游防火墙/负载均衡/API 网关只接受来自 ElevenLabs 文档化 egress ranges 的入站流量。
30. 或者自定义 shared-secret header：创建资源时通过 `speech_engine.request_headers`/`speechEngine.requestHeaders` 配置秘密 header，并由上游代理或开发者自己的中间件在请求到达 `attach()`/`serve()` 前验证。
31. 若用户无法确认已实现上述任一项，保留默认认证；没有缓解措施就跳过 JWT 验证不是优化或便利，而是未认证的公共计算。
32. 创建服务端 token endpoint，让浏览器在启动麦克风会话前请求 token；Speech Engine ID 和 API key 保留在服务端。
33. 若客户端传递 `overrides.agent.firstMessage`，Speech Engine 资源必须已启用 first-message override。
34. 使用 Express 示例签发 token：`elevenlabs.conversationalAi.conversations.getWebrtcToken({ agentId: process.env.ELEVENLABS_SPEECH_ENGINE_ID! })`，并返回 `res.json({ token: response.token })`。
35. React 客户端使用 `@elevenlabs/react` 的 `useConversation`，实现 `onConnect`、`onDisconnect`、`onError`。
36. 在启动对话时，先 `await navigator.mediaDevices.getUserMedia({ audio: true })`，再 `fetch("/api/token")` 获取 token。
37. 调用 `conversation.startSession({ conversationToken: token, overrides: { agent: { firstMessage: "Hello! How can I help you today?" } } })`。
38. 在 UI 中提供按钮触发 `startConversation`。

适用边界 · 注意事项

• 当用户是在创建或配置托管的 ElevenLabs Conversational AI agent（平台管理 prompts、tools、workflows、电话号码或 widgets）时，改用 `agents` skill。
• 没有互联网访问或没有 `ELEVENLABS_API_KEY`（以及其他所需 ElevenLabs 账号/密钥）时不要使用。
• 没有 IP allowlist 或自定义 shared-secret header 等补偿控制时，不要关闭 JWT 认证（`disableAuth`/`disable_auth`）。