定义¶

POST /api/conversational-ai-agent/v2/projects/{appid}/join 是 Agora Conversational AI Engine 的"创建并加入"端点：单次调用即把 AI Agent 实例化、配置好整套语音对话能力、加入指定 RTC 频道。一份 JSON 请求容纳了三条交互范式（cascade / MLLM / preset），结构化字段覆盖 ASR / LLM / TTS / MLLM / turn detection / SAL 声纹 / avatar / filler words / labels / RTC 加密 / silence/farewell/graceful 退场 / template_variables / mcp_servers 内置进 LLM 配置层。

这是 agora-convoai-server 实操页（凭证管理 + Agent 启停）的"云端能力深度补充"——服务端持有的 customer_key/secret 实际能调用的就是这套 API。

四种交互范式并存¶

Sentino 半自定义模式的工程动机：Sentino Agent 平台在 endpoint 内部做 workflow + tool + text/audio 流式同步——TTS 厂商（Minimax / ElevenLabs / Qwen3）选择、字幕与音频时序、tool call 与播报的衔接、唱歌等特殊音频场景，全部在 Sentino 一侧统一控制。把 TTS 从 Agora 拆出来不是被动选择，而是主动收敛——对 Agora 来说 Sentino 就是一个"会出音频的 LLM"，TTS 是 Sentino 内部细节。

文档原文（llm.output_modalities）：["text", "audio"]：Text plus voice. Write your own logic to process the output of LLM as needed.——这句"Write your own logic" 就是 Sentino 走的路。

顶层字段¶

请求体顶层字段（properties 内）：channel / token / agent_rtc_uid / remote_rtc_uids / enable_string_uid / idle_timeout / geofence / advanced_features / asr / tts（必需）/ llm（必需）/ mllm / avatar / turn_detection / sal / labels / rtc / filler_words / parameters。详见 raw 第 1 节。

Agent Studio + pipeline_id（海外版独有，国内声网版未见）¶

请求体顶层还有一个 pipeline_id 字段（与 properties 平级）——指向 Agora Agent Studio 中已发布 Agent 的唯一 ID。Studio 是 Agora 提供的 Web UI 配置工具，先在 Studio 里把 ASR/LLM/TTS/turn_detection 等配好并 publish，拿到 pipeline_id 后在 join API 调用里直接引用：

{
  "name": "agent_xx",
  "pipeline_id": "<studio published id>",
  "properties": { "channel": "...", "token": "...", "agent_rtc_uid": "..." }
}

字段优先级：properties 里出现的字段按字段级覆盖 Studio 配置；当指定了 pipeline_id 后，asr / tts / llm 在 properties 里变成可选（因为 Studio 已经配过）。

国内 vs 海外功能差异¶

用户对照过英文版（docs.agora.io）与中文版（doc.shengwang.cn）后指出：pipeline_id 与 Agent Studio 是海外版独有的能力——国内声网文档同一接口未暴露此参数。这是 Agora 国内/海外版功能差异的一个具体样本——海外提供"配置-发布-引用"的低代码工作流，国内仍是"每次 API 调用都填完整 JSON"的传统形态。

含义对 Sentino： - 海外客户：可以让客户/操作员在 Studio Web UI 配 ASR vendor / VAD 阈值 / system prompt 等，Sentino 后端调 join 时只传 pipeline_id + 动态字段（channel/token/uid），减少每次都要填一份完整 JSON 的工程负担 - 国内客户：没有 Studio，每次 join 必须传完整配置——这是 yukai-agora-poc "操作员管理后台 + hot-reload prompt" 类需求的部分背景：国内 Agora 不提供 Web 配置工具时，承包方要自己造一个

Sentino 与 Agora Studio 的竞合关系¶

商务关系：Sentino 是 Agora 合作伙伴——在 RTSA / ConvoAI / RTC 等基础设施层是被 Agora 推荐的解决方案商。

产品关系：在 Agent 平台能力上，Agora Studio 与 Sentino 是竞品关系——但深度差异显著：

销售姿态：Studio 是 Sentino 的升级前置场景——客户从 Studio 起步觉得不够时升级到 Sentino，Sentino 不会推 Studio 替代自己。国内 Studio 不可用，Sentino 是默认选项；海外客户从 Studio 起步会发现需要更深的 Agent 工程能力时切换到 Sentino。

详见 yukai-agora-poc 待办——客户原本若用 Studio，Sentino 是升级路径；客户若已在 Sentino，没有理由迁回 Studio。

LLM 配置层的关键事实¶

"llm": {
  "vendor": "custom | azure",
  "style": "openai | gemini | anthropic | dify",
  "url": "<callback /v1/chat/completions>",
  "params": { ... },
  "system_messages": [ ... ],
  "max_history": 32,                          // 1-1024
  "input_modalities":  ["text"]   /* 或 ["text","image"] */,
  "output_modalities": ["text"]   /* 或 ["audio"] / ["text","audio"] */,
  "mcp_servers":       [ ... ],
  "template_variables": { ... }
}

Sentino 的标准接入配置：

• vendor=custom + style=openai
• url 指向 https://api.sentino.jp/v1/agent/chat
• output_modalities=["text", "audio"] ← 关键：让 Sentino LLM 同时返回文本和音频，Agora 不再调度 TTS
• 不配 tts.*——TTS 在 Sentino endpoint 内部（Minimax / ElevenLabs / Qwen3 选型）
• 不配 llm.mcp_servers——工具调度在 Sentino endpoint 内部（REST + function calling）

调用 join 接口的代码参考 Sentino 内部 sentino-convo-ai 仓库。

这是 hotmind-client 与 yukai-agora-poc 共用的接入参数。

output_modalities 三种取值的边界： | 取值 | Agora 行为 | 谁出音频 | |---|---|---| | ["text"] | 调度 TTS vendor 把 LLM 文本合成音频 | Agora（cascade） | | ["audio"] | LLM 直接出音频，文本不上报 | LLM endpoint（Sentino 不用——会失去文本字幕/记录） | | ["text", "audio"] | LLM 同时出文本+音频，Agora 不调 TTS | LLM endpoint（Sentino 选这个） |

mcp_servers 内置：MCP 渗透到语音基础设施层的硬证据¶

LLM 配置内有 mcp_servers 数组——可声明多个 MCP server（带 auth 与 tools 白名单），由 Agora 在 LLM 推理时代为调用工具，绕过承包方 LLM 自己实现 function calling。

含义有三层：

1. MCP 已成语音平台一等公民配置项——不只"客户开放 server / 乙方不一定 client"（mcp-protocol 已记录），更进一步是语音平台厂商作为 MCP client 把 MCP 内置进基础设施
2. 存在"绕过 Sentino LLM"的捷径：当客户既开放了 MCP server、又用 Agora ConvoAI 做编排时，Agora 可以直接调客户 MCP，根本绕过 Sentino LLM —— hotmind-client 客户最终选 Sentino 而不是这条捷径，是因为需要 Sentino 的 Agent 工程能力（多意图拆分 / 家庭成员消歧 / 危险操作判定 / prompt 调优），不是为了纯工具中转
3. Sentino 当前不依赖 mcp_servers 字段——Sentino LLM endpoint 内部走 REST + function calling，工具调用不在 Agora 这层；但这个字段的存在进一步明确了 Sentino 的差异化护城河位置 = Agent 工程层而非工具中转层

turn_detection — 新版 vs 旧版（Agora 显式建议迁移）¶

新版（推荐）¶

"turn_detection": {
  "mode": "default",
  "config": {
    "speech_threshold": 0.5,
    "start_of_speech": {
      "type": "vad | keywords | disabled",
      "vad": { "threshold": 0.5, "prefix_padding_ms": 800 },
      "keywords": ["小爱", "小度"]
    },
    "end_of_speech": {
      "type": "vad | semantic",
      "vad": { "silence_duration_ms": 480, "interrupt_duration_ms": 160 }
    }
  }
}

关键改进：把 SoS（Start of Speech）与 EoS（End of Speech）拆成两个独立子配置——

• SoS 可以是 VAD / 关键词唤醒 / disabled（永远在听）
• EoS 可以是 VAD 静音判断 或 semantic EoS（用语义模型判断用户是否说完一句完整意图）

semantic EoS 是 voice-presence "对话动态"维度的工程化具体实现——它解决的是 VAD 单纯靠静音长度判断会把"我想想……"误判为说完的问题。

旧版（deprecated）¶

"turn_detection": {
  "type": "agora_vad | server_vad | semantic_vad",
  "interrupt_mode": "interrupt | append | ignore | keywords | adaptive",
  "interrupt_duration_ms": 160,
  "prefix_padding_ms": 800,
  "silence_duration_ms": 480,
  "threshold": 0.5
}

文档原文："To create more natural conversations and reduce unintended interruptions, Agora recommends using the latest version of turn_detection above."

agora-convoai-server 当前 ASR audio_vad 段落记录的参数（interrupt_duration_ms: 160 / prefix_padding_ms: 800 / silence_duration_ms: 480 / threshold: 0.5）属于旧版 deprecated 字段——新版应分到 SoS/EoS 子配置。

SAL（Selective Attention Locking）声纹能力¶

"sal": {
  "sal_mode": "locking | recognition",
  "sample_urls": ["https://.../voiceprint.pcm"]    // max 1, 16kHz PCM, 10-15s
}

• locking：声纹锁定。Agent 只对预先注册的特定声纹响应。
• recognition：声纹识别。识别说话人是谁但不锁定。

Agora 平台层提供了声纹能力，但应用层是否使用是产品决策。hotmind-client 客户在家庭多用户场景主动放弃声纹消歧，选择靠对话语义匹配（schedule_member_list 查家庭成员档案）做消歧。理由是声纹不稳定 / 隐私敏感 / 老人小孩声纹易错——这是"硬件/平台能力 ≠ 产品最优选"的反直觉但更可靠的工程选择，与 first-principles-deletion "复杂底层方案不一定比简单上层方案更可靠"同源。

MLLM（端到端语音模型）¶

"mllm": {
  "vendor": "openai | gemini | vertexai",
  "url": "<websocket endpoint>",
  "style": "openai",
  "input_modalities": ["audio"],
  "output_modalities": ["text", "audio"]
}

启用 MLLM（在 advanced_features.enable_mllm=true）后建立 WebSocket 到 OpenAI Realtime / Gemini Live / VertexAI 端点，绕过 ASR/LLM/TTS 三段拆分。

Sentino 当前不走这条——半自定义模式（Sentino LLM 直出 text+audio，Agora 不调 TTS 也不调 MCP）。但 MLLM 与 voice-presence 直接相关：端到端音频模型在 turn-taking / 副语言（叹气、笑声）/ 音色一致性上理论上比 ASR/LLM/TTS 拆分 pipeline 有上限优势。作为 Sentino 未来可能切换的形态记录——什么时候考虑切，需要评估"端到端音频模型 vs Sentino 半自定义 + workflow/tool 内部调度"的 Agent 工程能力差距。

其他字段速览¶

Sentino 视角速查¶

与三个客户项目的对应¶

• yukai-agora-poc：半自定义模式 + Memex 做记忆 + 三模式状态机在 Sentino LLM 侧实现 + TTS 唱歌在 Sentino 内部 TTS vendor 选型评估（不是 Agora tts.vendor，而是 Sentino endpoint 内部从 Minimax/ElevenLabs/Qwen3 选哪一个能唱）
• hotmind-client：半自定义模式 + vendor=custom + style=openai + output_modalities=["text","audio"] + 客户的 ConvoAI 配 ASR + VAD（TTS 不需要客户配，由 Sentino LLM 直出 audio 替代）+ 客户 body 自定义字段透传 device_id/asset_id/language/timezone
• sentino-iot：自家设备路径——服务端持有 customer_key/secret 并代设备调用 join API，本概念页是 agora-convoai-server 中"云端这一段"的接口规范

接口文档参考¶

• 英文版：https://docs.agora.io/en/conversational-ai/rest-api/agent/join
• 中文版（声网）：https://doc.shengwang.cn/doc/convoai/restful/convoai/operations/start-agent —— 同一接口的中文文档，国内对接时优先用此份

待办与开放问题¶

• 旧版 turn_detection 字段在 agora-convoai-server 配置文档中存在，安排"迁移到新版 SoS/EoS"工程更新
• filler_words / silence_config / farewell_config / graceful_enabled 在 Sentino Agent 平台是否已有等价实现，待清单核对
• Sentino 自家 LLM endpoint 是否支持 template_variables 解析（让 Agora 可以注入动态值到 system prompt）；与 body 自定义字段的关系
• MLLM 端到端模式作为 Sentino 潜在替代路径——切换时机评估
• enable_aivad 与 enable_bhvs 文档未展开语义，需进一步问 Agora 或在实测中观察

相关概念¶

• agora-convoai-server — 设备/服务端凭证管理 + Agent 启停的实操层，本页是它"云端能力"的深度补充
• agora-rtc-voice — Agora RTC 底层音频通道
• agora-rtsa-sdk — 嵌入式设备端 C SDK：本页 rtc.encrypt 8 种加密模式与 parameters.data_channel 的设备侧实现层
• voice-presence — semantic EoS 是其工程化具体实现
• mcp-protocol — Agora 把 mcp_servers 内置进 LLM 配置层是 MCP 渗透到语音基础设施的硬证据
• sentino-memex — Sentino 自家记忆方案，在 cascade LLM 一侧承接长期记忆能力
• sentino-agent — Sentino Agent 平台是 LLM 槽位的实际承载方
• hotmind-client — vendor=custom + style=openai 接入实证；声纹能力主动放弃的样本
• yukai-agora-poc — 半自定义模式 + Memex 实际交付
• sentino-iot — 设备路径下的服务端代为调用 join API