Agora ConvoAI 设备服务端

tags: [IoT, Agora, ConvoAI, 服务端, AI语音]
created: 2026-04-13
updated: 2026-04-17
sources: [raw/snippets/bk7258-build/build-and-flash.md, raw/notes/hotmind-family-agent-spec-2026-04-17.md, raw/notes/agora-conversational-ai-join-api-2026-04-15.md]

定义¶

设备与声网 Conversational AI 之间的中间服务层。设备不直接调用声网 API，而是通过自建 HTTP 服务获取凭证、启停 AI Agent。服务端持有声网密钥，设备只持有服务端地址。

关键要点¶

三个端点：
POST /device — 设备获取 app_id + rtc_token（RTC 入场凭证）
POST /agent/start — 创建 AI Agent 并加入 RTC 频道（调声网 ConvoAI REST API）
POST /agent/stop — 停止 Agent（调声网 leave API）
凭证分层：服务端持有 customer_key/secret（Basic Auth 调声网 API）和 app_certificate（生成 RTC Token），设备只需知道服务端 URL
API 域名：全球用 api.agora.io/api/...，不是 api.agora.io/cn/api/...。用中国区域名会报 allocate failed
Token 生命周期：设备端假定 12 小时有效期，过期自动重新请求
设备端 URL 硬编码：CONFIG_AGENT_SERVER_URL 编译时写死，动态 URL 功能（通过 BLE 配网传入）已实现但被注释掉（server_url_write 是空操作）

设备端业务流程¶

WiFi 连接成功
  ├→ POST /device → 获取 app_id + token → 缓存
  ├→ POST /firmware/update → 检查 OTA
  │
用户按键（S2）
  ├→ 本地 RTC 加入频道（用缓存的 app_id + token）
  ├→ POST /agent/start → 云端创建 AI Agent 加入同一频道
  │    └→ 设备与 Agent 实时音视频通话
  │
用户再按键
  ├→ 本地 RTC 离开频道
  └→ POST /agent/stop → 停止 Agent

LLM 槽位指向第三方 OpenAI 兼容端点（被采购的 Agent 形态）¶

在 ConvoAI 编排里，llm_config.url 不一定要指向客户自家平台——可以指向被采购的第三方 OpenAI 兼容 /v1/chat/completions。Hotmind 客户（hotmind-client）的 RFP 就是按这种形态写：

"llm_config": {
  "url": "<被采购方的 /v1/chat/completions>",
  "max_history": 1024,
  "greeting_message": "你好！我是你的家庭小助手……",
  "failure_message": "抱歉，我现在有点累了，稍后再试试！",
  "params": { "max_tokens": 1024, "stream": true, "response_mode": "streaming" }
}

设备上下文（device_id / asset_id / language / timezone）以body 自定义字段（不是 system message）传到第三方 Agent——这是 Voice Agent 接入层的事实约定。Sentino 接 Hotmind 这类客户单时，需要新增"OpenAI 兼容 streaming endpoint"作为 Agent 平台的对外形态——详见 hotmind-client。

ASR audio_vad 关键参数（参考值）：interrupt_duration_ms: 160 / prefix_padding_ms: 800 / silence_duration_ms: 480 / threshold: 0.5——决定打断敏感度。注意：这套参数属于旧版 deprecated turn_detection.type 字段族——Agora 在 v2 join API 文档中明确建议迁移到新版 mode=default + config.start_of_speech + config.end_of_speech 拆分形式，详见 agora-convoai-join-api "turn_detection — 新版 vs 旧版"段落。

云端 v2 join API 概览¶

设备服务端真正调用的是 POST /api/conversational-ai-agent/v2/projects/{appid}/join（Conversational AI Engine v2）。这份 JSON 容纳了四种交互范式（cascade / 半自定义 / MLLM 端到端 / preset）+ 完整字段集（ASR / LLM / TTS / MLLM / turn_detection / SAL 声纹 / avatar / filler_words / labels / RTC 加密 / silence/farewell/graceful 退场 / template_variables / mcp_servers 内置进 LLM 配置层）。

Sentino 走的是"半自定义"模式：Agora 出 ASR + RTC 传输，Sentino LLM endpoint 设 output_modalities=["text","audio"] 同时返回文本和音频，Agora 不调度 TTS——TTS 在 Sentino 内部完成（Minimax / ElevenLabs / Qwen3）。意味着设备服务端给 Sentino 客户场景调 join API 时，不需要也不应配 tts.* 字段。

完整字段集 + Sentino 视角的"哪些用、哪些不用" + 三客户对应关系：详见 agora-convoai-join-api。本页保留设备/服务端凭证流的实操记录。

配置项（config.json）¶

字段	说明
`app_id` / `app_certificate`	声网项目凭证
`customer_key` / `customer_secret`	声网 RESTful API 认证
`llm.url` / `llm.api_key` / `llm.params.model`	LLM 服务配置
`tts.vendor` / `tts.params`	TTS 服务配置（minimax/microsoft/bytedance）；Sentino 客户场景不用此字段，由 LLM endpoint 直出 audio
`asr.language`	ASR 语言（zh-CN）
`parameters.output_audio_codec`	音频编码（G722）

定义¶

关键要点¶

设备端业务流程¶

LLM 槽位指向第三方 OpenAI 兼容端点（被采购的 Agent 形态）¶

云端 v2 join API 概览¶

配置项（config.json）¶

相关概念¶