创建对话式智能体
更新时间不可用
创建一个对话式智能体 (Conversational AI agent) 实例，并加入 RTC 频道。
https://api.agora.io/cn/api/conversational-ai-agent/v2/projects/{appid}/joinappidstring你的项目使用的 App ID。
Authorizationstring发送 HTTP 请求时，你可以从以下鉴权方式中任选其一：
- 使用 Token 认证（推荐）：参考实现 HTTP 鉴权生成 Token 并填入
AuthorizationHeader。传参示例：Authorization: agora token="007abcxxxxxxx123"。 - 使用 Basic Auth：参考实现 HTTP 鉴权生成 Base64 编码的
Authorization字段。传参示例：Authorization: Basic NDI1OTQ3N2I4MzYy...YwZjA=。
namestring智能体唯一标识，相同标识不可重复创建。
智能体详细配置。
channelstring智能体加入的 RTC 频道名。
tokenstring加入 RTC 频道使用的 Token，即用于鉴权的动态密钥。如果你的项目已启用 App 证书，则务必在该字段中传入你项目的动态密钥。详见使用 Token 鉴权。
agent_rtc_uidstring智能体在 RTC 频道内的用户 ID。
注意
同一 channel 内的用户 ID 不可重复，否则智能体加入频道会失败。
remote_rtc_uidsarray<string>智能体在 RTC 频道中订阅的用户 ID 列表，只有订阅的用户才能与智能体互动。目前只支持订阅一个用户 ID。
enable_string_uidboolean是否启用 String UID：
true：智能体和订阅用户 ID 均使用 String UID。false：（默认）智能体和订阅用户 ID 均使用 Int UID。
注意
同一频道内，Int 型和 String 型的用户 ID 不可混用。更多使用 String UID 的相关信息请参考如何使用 String 型用户 ID。
idle_timeoutintegerRTC 频道的最大空闲时间，单位为秒。系统检测到 remote_rtc_uids 中指定的用户已全部离开频道后，会开始计算空闲时长；空闲时长超过该值时，智能体会自动停止并退出频道。
- 取值范围为
[0, 259200]，默认值为30。其中259200秒即 72 小时，超过该值会报错。 - 设置为
0仅表示不因“频道空闲超时”退出。 - 无论
idle_timeout取值为何，单次任务的最长运行时间均为 72 小时；达到 72 小时后，智能体会自动退出。
高级功能配置。
enable_salboolean是否启用选择性注意力锁定（Selective Attention Locking, SAL）功能。启用后，在 sal 字段中完成相关设置，智能体即可识别用户的声纹特征，有效区分不同说话者，屏蔽 95% 的环境人声、噪声。
说明
该功能目前处于 Beta 阶段。
enable_toolsboolean是否启用工具调用功能。启用后，智能体可以调用 llm.tools 中声明的自定义工具和 llm.mcp_servers 中配置的 MCP 工具，实现查询业务数据、执行外部操作等业务逻辑。
true：启用自定义工具和 MCP 工具调用。false：（默认）不启用工具调用，也不会访问工具端点。
注意
即使该字段为 false 或省略，请求中传入的 llm.tools 仍需通过字段类型、大小、模板语法和工具名称重复性校验。
自动语音识别 (ASR) 配置。
languagestring用户与智能体互动时使用的语言：
zh-CN：中文（支持中英文混合）en-US：英语
vendorstringASR 服务供应商，可选以下值：
fengming：（默认）声网凤鸣 ASR。tencent：腾讯 ASR。microsoft：微软 ASR。
keywordsarray<string>ASR 热词列表，用于提升指定词汇的识别效果。详见配置 ASR 热词。
-
仅当
properties.asr.vendor未填、为null、为空字符串或fengming时可设置properties.asr.keywords。 -
热词数量最多支持 128 个。
-
如果显式设置了其他 ASR 供应商，同时设置该字段，请求会报错：
Invalid value at properties.asr.keywords: can only be set when properties.asr.vendor is unset or fengming.
注意
设置热词可能影响其他词汇的识别准确度，请根据业务场景谨慎配置。
ASR 配置参数。不同 ASR 供应商下该参数结构不同。
注意
各供应商示例代码中未提及的参数，声网对话式 AI 引擎不保证完全支持。
腾讯云 ASR，具体协议详见腾讯云官方文档。以下为示例：
"params": {
"secret_id": secret_id,
"app_id": app_id,
"secret_key": secret_key,
"engine_model_type": "16k_zh",
"voice_id": "TBgVFCsxdn3i2DGt",
}
文本转语音 (TTS) 模块配置。
vendorstringTTS 供应商，支持传入以下值：
minimax：Minimax TTStencent：腾讯 TTSbytedance：火山引擎 TTSmicrosoft：微软 Azure TTScosyvoice：(Beta) 阿里云 CosyVoice TTSbytedance_duplex：火山引擎双向流式 TTSstepfun：(Beta) 阶跃星辰 TTSgeneric_http：(Beta) 通过 OpenAI TTS 协议接入自研或第三方 TTS 引擎。详见通过 RESTful API 接入自定义 TTS。
skip_patternsarray<integer>过滤模式配置，用于控制是否跳过 LLM 返回文本中括号内的内容，避免智能体播报不必要的结构性提示信息如语气、动作描述等。默认值为 []，即不过滤任何内容。可选值如下，传入即启用该功能：
1：跳过中文圆括号（ ）中的内容2：跳过中文方括号【 】中的内容3：跳过英文圆括号 ( ) 中的内容4：跳过英文方括号 [ ] 中的内容5：跳过英文花括号 { } 中的内容
指定 TTS 供应商的配置参数。
说明
你可以参考调用示例中不同 TTS 供应商的参数填写样例。
Minimax TTS，具体协议详见 Minimax 官方文档。以下为示例：
"params": {
"key": "xxxx",
"model": "speech-01-turbo",
"voice_setting": {
"voice_id": "female-shaonv",
"speed": 1,
"vol": 1,
"pitch": 0,
"emotion": "happy",
"latex_read": True,
"english_normalization": True,
},
"audio_setting": {
"sample_rate": 16000
},
"pronunciation_dict": {
"tone": ["这是/(zei3)(si4)", "消息/(xiao3)(xi4)"]
},
# voice_id和timber_weights二选一必填
# "timber_weights": [{
# "voice_id": "male-qn-qingse",
# "weight": 1
# },
# {
# "voice_id": "female-shaonv",
# "weight": 5
# }],
"language_boost": "auto"
}
腾讯云 TTS，具体协议详见腾讯云官方文档。以下为示例：
"params": {
"app_id": "xxxx",
"secret_id": "xxxx",
"secret_key": "xxxx",
"voice_type": 601005,
"volume": 0,
"speed": 0,
"emotion_category": "happy",
"emotion_intensity": 100
}
火山 TTS，具体协议详见火山引擎官方文档。以下为示例：
"params": {
"token": "xxxxx",
"app_id": "xxxx",
"cluster": "volcano_tts",
"voice_type": "BV700_streaming",
"speed_ratio": 1.0,
"volume_ratio": 1.0,
"pitch_ratio": 1.0,
"emotion": "happy"
}
微软 Azure TTS。以下为示例和参数说明：
"params": {
"key": "<your_microsoft_key>",
"region": "chinaeast2",
"voice_name": "zh-CN-YunxiNeural",
"speed": 1.0,
"volume": 70
}
key：（必需）String。微软 Azure 的 API key。region：（必需）String。微软 TTS 服务的区域。voice_name：（必需）String。音色。speed：（可选）Number。语速。取值范围为 [0.5, 2.0]，默认值为 1.0。用于指示文本的语速。语速可以在单词或句子级别应用。volume：（可选）Number。音量。取值范围为 [0.0, 100.0]，默认值为 100。例如，值为 75 表示音量设置为最大音量的 75%。sample_rate：（可选）Integer。音频采样率 (Hz)。可选取值为 [16000, 24000, 48000]，默认值为 24000。
说明
更多信息请参考微软官方文档。
阿里云 CosyVoice TTS，具体协议详见阿里云官方文档。以下为示例：
"params": {
"api_key": "your_cosyvoice_api_key",
"model": "cosyvoice-v1",
"sample_rate": 16000,
"voice": "longxiaochun"
}
火山引擎双向流式 TTS，具体协议详见火山引擎官方文档。以下为示例：
"params": {
"app_id": "your_bytedance_tts_app_id",
"token": "your_bytedance_tts_token",
"speaker": "zh_female_shuangkuaisisi_moon_bigtts"
}
阶跃星辰 TTS，具体协议详见阶跃星辰官方文档。以下为示例：
"params": {
"api_key": "your_stepfun_tts_key",
"model": "step-tts-mini",
"voice_id": "cixingnansheng"
}
大语言模型 (LLM) 配置。
urlstringLLM 回调地址，要求与 OpenAI 协议兼容。
api_keystringLLM 鉴权 API key。默认为空，生产环境中务必启用 API key。
system_messagesarray<object>一组每次调用 LLM 时被附加在最前的预定义信息，用于控制 LLM 输出。可以是角色设定、提示词和回答样例等。要求与 OpenAI 协议兼容。
max_historyintegerLLM 中缓存的短期记忆条目数。取值范围为 [1,1024]。短期记忆包括用户和智能体对话消息、工具调用信息和时间戳。智能体和用户会单独记录短期记忆条目。
input_modalitiesarray<string>LLM 的输入模态，支持：
["text"]：（默认）仅文字。["text", "image"]：文字加图片。推荐配置，要求所选 LLM 支持视觉模态输入。
output_modalitiesarray<string>LLM 的输出模态，支持：
["text"]：（默认）仅文字。输出的文字会经过 TTS 模块转换成语音后发布至 RTC 频道。["audio"]：仅语音。语音会直接发布至 RTC 频道。["text", "audio"]：文字加语音。你可以自行编写逻辑，按需处理 LLM 的输出。
greeting_messagestring智能体问候语文本。如果填写，则在频道内没有订阅用户列表 (remote_rtc_uids) 中的用户时，智能体会自动向首位加入频道的订阅用户发送问候语。
- 你可以单独配置该字段，走原有实时 TTS 开场白路径。
- 也可以在配置
greeting_audio_url时，将该字段作为录音开场白的兜底文本。 - 当
greeting_interruptable = true且录音开场白被用户打断时，系统会结合greeting_message估算已播报的文本片段，并将其注入短期记忆以保持对话上下文连贯。
greeting_interruptableboolean智能体问候语是否可被打断：
true：（默认）可打断，遵循全局打断配置 (interruption)。false：不可打断，问候语会完整播放；播放期间识别到的用户 ASR 文本会被静默接收，待问候语结束后拼接为单轮 user 消息，再统一送入大模型进行一次推理和回复。
greeting_audio_urlstring智能体问候语录音文件的 URL。配置后，系统会优先下载并播放该录音作为开场白。
支持以下格式的音频文件：
mp3wavpcm
使用说明如下：
- 仅支持
http://或https://开头的 URL；空字符串、非 URL 字符串或长度超过2048字节时，请求会返回400错误。 - 对于
pcm文件，需要额外通过greeting_configs.audio_pcm_sample_rate指定采样率。 - 系统会将导入的音频统一转换为与
tts.params.sample_rate一致的采样率后再进行播报。
注意
- 配置
greeting_audio_url时，必须同时配置greeting_message用于异常回退；否则请求会返回400错误。 - 当
greeting_audio_url对应的录音下载失败、解码失败或格式不支持时，系统会自动使用greeting_message进行 TTS 合成并继续播报。
智能体问候语播报配置。
modestring智能体问候语播报模式，支持以下选项：
"single_every"：（默认）每次有用户加入空频道时，智能体都播报一次问候语。"single_first"：仅首位用户加入空频道时，智能体播报一次问候语。
delay_msinteger智能体问候语播报延迟时间 (ms)，取值范围为 [0, 5000]。配置后，智能体问候语会在用户加入频道后等待指定时间再播报。
audio_download_timeout_msinteger录音开场白下载超时时间，单位为毫秒。仅在配置 greeting_audio_url 时生效。
- 取值范围为
[200, 10000]。 null和字段缺失均视为未配置，此时使用默认值1000。- 超时后系统会回退到
greeting_message的 TTS 路径。
audio_pcm_sample_rateinteger录音开场白为 PCM 文件时的采样率，单位为 Hz。仅在配置 greeting_audio_url 且录音格式为 PCM 时生效。
- 默认值为
16000。 mp3和wav文件无需配置该字段。
template_variablesobject动态参数配置，用于在智能体的 system_messages、greeting_message、failure_message 和 parameters.silence_config.content 文本中插入变量。键值对形式，键为变量名，值为变量值。
使用方式:在 Prompt 文本中使用 {{variable_name}} 格式引用变量，系统会自动将其替换为 template_variables 中定义的对应值。
注意
变量名和变量值不支持引用其他变量。例如自定义变量 "farewell": "期待下次再见，{{name}}"，其中的 {{name}} 不会被解析。
failure_messagestring智能体处理失败提示语。如果填写，则在 LLM 调用错误时会通过 TTS 模块返回。
vendorstringLLM 供应商，支持以下两种设置：
-
商业大模型供应商，支持以下值：
aliyun：阿里云bytedance：字节跳动deepseek：深度求索tencent：腾讯
设置后，可提高兼容性，减少因携带 LLM 不支持的信息而导致请求失败的情况。
-
自定义 LLM，即设为
"custom"。设置后智能体调用 custom LLM 时，除了role和content外，将额外携带以下信息：turn_id：唯一的对话轮次标识符。turn_id从 0 开始递增，用户和智能体的一轮对话对应一个turn_id。timestamp：请求时间戳，精度为毫秒。
MCP (Model Context Protocol) 服务器配置列表。通过配置 MCP 服务器，智能体可以调用外部服务提供的工具，实现更复杂的业务逻辑。
namestringMCP 服务器的唯一标识。长度不超过 48 字符，支持以下字符：
- 所有小写英文字母：a 到 z
- 所有大写英文字母：A 到 Z
- 所有数字字符：0 到 9
- "." 和 "-"
endpointstringMCP 服务器的端点地址，智能体将通过该地址与 MCP 服务器通信。
transportstring传输协议类型，支持传入以下值：
"streamable_http"：流式 HTTP 协议
headersobject请求 MCP 服务器时携带的 HTTP 头部信息，例如认证信息。
allowed_toolsarray<string>允许智能体调用的工具列表。只有在此列表中的工具才能被智能体使用。
说明
allowed_tools 字段生效规则:
- 不填写
allowed_tools字段：所有工具都生效 - 填写
allowed_tools字段：- 填写为
[]：所有工具不生效 - 填写为
["*"]：所有工具生效 - 填写为
["aa", "bb", "cc"]：aa、bb、cc生效 - 填写为
["aa", "bb", "*"]：所有工具生效
- 填写为
timeout_msintegerMCP 服务器请求超时时间，单位为毫秒。请求超时后，智能体将不会等待 MCP 服务器响应，而是继续执行后续逻辑。
自定义工具列表。配置后，大模型可以根据对话内容选择工具并生成参数，由对话式 AI 引擎校验参数、调用对应的 HTTPS 端点，再将结果返回给大模型继续生成回复。
自定义工具、MCP 工具、内置工具和模型原生工具共用同一个工具名称空间，名称按 ASCII 大小写不敏感的方式比较。完成 MCP 发现和过滤后，向大模型提供的工具总数最多为 32 个；名称冲突或超过上限时，智能体启动失败，不会自动覆盖、重命名或截断工具。
注意
- 使用工具前需将
advanced_features.enable_tools设为true。 - 当前仅支持同步调用标准文本 LLM，暂不支持自定义 LLM、MLLM、Dify、异步工具和已存储工具引用。
typestring工具类型，当前仅支持 function。
namestring模型可见的工具名称。需以英文字母开头，仅包含英文字母和数字，长度为 1 到 64 个字符。
自定义工具、MCP 工具、内置工具和模型原生工具的名称按 ASCII 大小写不敏感的方式比较，不能重复；名称不能使用 mcp 前缀或 ragsearch_tool。
descriptionstring工具说明，用于帮助大模型判断何时调用工具以及工具返回什么。请勿包含密钥等敏感信息。
parameters工具参数定义采用 JSON Schema 格式，并按 OpenAI Function Calling 的 non-strict 模式传递给大模型。详情见 OpenAI Function Calling：
使用规则：
- 根节点的
type必须为object。 - 支持 JSON Schema 的常用类型，包括
object、array、string、integer、number、boolean和null。 - 支持标准 JSON Schema 中与工具参数相关的关键字，例如
type、description、enum、properties、required、additionalProperties和items。 - 对象可使用
properties、required和additionalProperties。additionalProperties可以省略；省略时按 JSON Schema 语义允许额外属性。若要禁止未声明的额外参数，请显式设置为false。 - 数组参数应通过
items指定元素 schema；是否支持 tuple schema 取决于所选 LLM。 - 可选参数不要放入
required。不要依赖特定模型对$ref、$defs、format、pattern、范围限制或组合 schema 等高级关键字的支持；如果使用这些关键字，请先确认所选 LLM 的兼容性。 - 序列化后的 schema 最大为 64 KiB。
示例：
{
"type": "object",
"properties": {
"order_id": {
"type": "string",
"description": "订单 ID"
}
},
"required": ["order_id"],
"additionalProperties": false
}
工具执行方式。
modestring执行模式，当前仅支持同步执行 sync。
自定义工具的 HTTP 请求配置。
模板采用单次替换，不会递归展开。支持以下变量：
{{args.<name>}}：通过校验的大模型工具参数，可用于 URL 的路径或查询参数以及请求体，不可用于 Header。{{template_variables.<name>}}：创建智能体时配置的模板变量，可用于 URL 的路径或查询参数、Header 值以及请求体。{{tool_call_id}}：当前工具调用的关联 ID，可用于 URL、Header 值或请求体。
模板变量的使用规则如下：
- Header 和请求体：每个值只能填写固定值，或完整填写一个占位符，例如
{{args.order_id}}。不支持拼接文本，例如order-{{args.order_id}}；也不支持嵌套字段、数组索引或递归引用。 - URL 路径和查询参数：可以在固定 URL 中使用占位符，例如
/orders/{{args.order_id}}。 - 如果占位符引用的变量不存在或值为
null，工具调用会返回UnresolvedTemplate。 - URL 和 Header 中的变量值只能是字符串、数字或布尔值。
注意
认证信息只能作为完整的 Header 值传入。请勿将认证信息放入 URL 或请求体。所有 Header 值均按敏感信息处理，不会传递给大模型或写入普通日志、事件、字幕和 TTS。
methodstringHTTP 请求方法，支持：
GET：用于查询数据，不支持请求体。配置body会导致请求校验失败。POST：用于提交数据，可同时配置 URL 查询参数、请求 Header 和请求体。
urlstring自定义工具请求的绝对 HTTPS URL。
URL 的路径和查询参数支持嵌入以下单层占位符：
{{args.<name>}}{{template_variables.<name>}}{{tool_call_id}}
例如：https://api.example.com/orders/{{args.order_id}}?tenant={{template_variables.tenant_id}}。
使用限制：
- 占位符名称必须完整，不支持嵌套字段、数组索引或递归展开。
- 仅 URL 的路径和查询参数可以使用占位符；协议、用户信息、主机和端口不可模板化。
- 不允许在 URL 中嵌入用户名、密码或其他认证信息。
- URL 中的占位符值只能是 string、number 或 boolean。
- 每个渲染后的路径变量值最大为 1024 UTF-8 字节，每个查询变量值最大为 4096 UTF-8 字节，最终 URL 最大为 8192 UTF-8 字节。
headersobject自定义工具请求携带的自定义 Header，最多支持 32 项。
Header 值支持：
- 静态 string、number 或 boolean。
- 完整的
{{template_variables.<name>}}占位符。 - 完整的
{{tool_call_id}}占位符。
使用限制：
- Header 名长度为 1 到 128 个字符，且必须符合 HTTP token 规范。
- Header 名不可模板化，Header 值不支持
{{args.<name>}}。 - 占位符必须作为完整 Header 值，不支持与其他文本拼接，也不支持嵌套字段、数组索引或递归展开。
- 每个渲染后的 Header 值最大为 4096 UTF-8 字节，所有 Header 合计最大为 16 KiB。
- 如果自定义 Header 与声网生成的系统 Header 重名，以声网生成的值为准。
所有 Header 值均按敏感信息处理，不会传递给大模型，也不会写入普通日志、事件、字幕或 TTS。
bodyunknown自定义工具的 HTTP 请求体，仅支持用于 POST。为 GET 配置该字段会导致请求校验失败。
请求体支持 object、array、string、number、boolean 和 null，并可使用任意层级的 JSON 结构。请求体中的叶子值可以是：
- JSON 常量。
- 完整的
{{args.<name>}}占位符。 - 完整的
{{template_variables.<name>}}占位符。 - 完整的
{{tool_call_id}}占位符。
占位符必须作为完整的叶子值，不支持与其他文本拼接，也不支持嵌套字段、数组索引或递归展开。占位符替换后会保留变量原始的 JSON 类型；工具参数在序列化为 JSON 请求体时会自动转义。
timeout_msintegerHTTP 请求超时时间 (ms)，取值范围为 [1000, 100000]，默认为 10000。
headersobject请求 LLM 时附带的自定义请求 Header。你可以通过该字段透传业务自定义字段、租户标识等业务相关信息。
说明
- 该参数传入的请求 Header 会与对话式 AI 引擎默认生成的请求 Header 合并；当键冲突时，以对话式 AI 引擎生成的请求 Header 为准（例如认证相关 Header）。
- Header 键按字符串精确匹配进行合并（区分大小写），声网建议统一使用标准写法，避免同名不同大小写导致歧义。
paramsobject在消息体内传输的 LLM 附加信息，例如使用的模型、最大 Token 数限制等。不同的 LLM 供应商支持的配置不同，请参考对应文档按需填入。
数字人 (Avatar) 配置。
enableboolean是否为智能体启用数字人功能：
true：启用。启用后需配置vendor和params字段。false：（默认）不启用。
注意
开启数字人功能将产生 RTC 视频通话费用，详见 RTC 计费说明。
vendorstring数字人供应商，支持传入以下值：
sensetime：商汤数字人spatius：Spatius 数字人
指定数字人供应商的配置参数。
说明
你可以参考调用示例中不同数字人供应商的参数填写样例。
商汤数字人配置参数，具体协议详见商汤官方文档。以下为示例：
"params": {
"agora_token": "agora_token",
"agora_uid": "agora_uid",
"appId": "sensetime_app_id",
"app_key": "sensetime_app_key",
"sceneList": [
{
"digital_role": {
"face_feature_id": "face_feature_id",
"position": {"x": 0, "y": 0},
"url": "https://example-digital-human-models/avatar_id.zip"
}
}
]
}
注意
- 以下商汤数字人配置字段当前不支持在
params中透传：tts_config、tts_query、audios、quick_response、quick_response_preload_list、opening_words。 agora_uid必须为大小不超过 32 位(0到2³²-1))的纯数字字符串，例如"1234"。agora_uid作为数字人在 RTC 频道内使用的用户 ID，同一channel内的用户 ID 不可重复，否则数字人加入频道会失败。
Spatius 数字人配置参数，具体协议详见Spatius 官方文档。以下为示例：
"params": {
"spatius_api_key": "spatius_api_key",
"spatius_app_id": "spatius_app_id",
"spatius_avatar_id": "spatius_avatar_id",
"agora_uid": "agora_uid",
"agora_token": "agora_token",
"region": "cn-beijing",
"sample_rate": 16000,
"session_expire_minutes": 30
}
spatius_api_key：（必需）String。Spatius API Key，仅在服务端使用。spatius_app_id：（必需）String。Spatius App ID。spatius_avatar_id：（必需）String。要渲染的数字人形象 ID。agora_uid：（必需）String。Avatar Publisher 的 Agora UID，必须独立于用户 UID 和 Agent UID。agora_token：（必需）String。为agora_uid在目标频道生成的 RTC Token。region：（可选）String。Spatius 服务节点。中国大陆场景可设为cn-beijing。sample_rate：（可选）Integer。音频采样率，建议与tts.params.audio_setting.sample_rate保持一致，通常为16000或24000。session_expire_minutes：（可选）Integer。Spatius token 有效时长，单位为分钟，默认为30。
对话轮次检测设置，用于控制语音活动检测和对话轮次判定逻辑。
说明
自 v2.6 起，turn_detection 仅负责开始说话（SoS）和结束说话（EoS）的检测。关键词打断和关闭打断后的处理策略已迁移至顶级 interruption 字段。
modestring对话轮次检测模式，当前支持以下值：
"default"：（默认）默认模式，使用标准的对话轮次检测配置。
对话轮次检测详细配置。
speech_thresholdnumber语音识别灵敏度，取值范围为 (0.0, 1.0)。决定音频信号中何种程度的声音被视为"语音活动"。较低的值会使智能体更容易检测到语音，较高的值则可能忽略微弱声音。
对话开始 (Start of Speech, SoS) 检测配置，用于判定用户何时开始说话。
modestring对话开始检测模式，支持以下值：
"vad"：（默认）基于 VAD（语音活动检测）触发，使用音频信号检测。"manual"：手动 SoS 模式。关闭服务端自动 SoS 检测，由客户端通过 RTM 消息显式声明用户开始说话。"keywords"：已废弃，请改用properties.interruption.mode = "keywords"配置关键词打断。"disabled"：已废弃，请改用properties.interruption.enable = false配合properties.interruption.disabled_config.strategy配置关闭打断后的处理策略。
注意
使用 "manual" 时：
- 必须同时开启
advanced_features.enable_rtm = true。 - 必须同时设置
parameters.data_channel = "rtm"。 - 不支持传入
manual_config；该模式下无需公开配置项。
对话开始检测配置参数。不同检测模式下该参数结构和支持的字段不同。
你需要根据 mode 传入对应的配置字段。例如 mode 为 "vad" 时，需传入 vad_config。不可同时传入多个模式配置。
当 mode 为 "manual" 时，无需传入任何 manual_config，且公开接口不支持该字段。
基于 VAD 的对话开始检测配置。以下为示例：
"vad_config": {
"interrupt_duration_ms": 160,
"speaking_interrupt_duration_ms": 160,
"prefix_padding_ms": 800,
}
interrupt_duration_msinteger智能体空闲或倾听时的人声持续阈值 (ms)，取值范围为 [120, 1200]。持续检测到人声信号的最小时间长度，避免误打断。
speaking_interrupt_duration_msinteger智能体说话时的人声持续阈值 (ms)，取值范围为 [120, 1200]。持续检测到人声信号的最小时间长度，避免误打断。通常设置得比 interrupt_duration_ms 更长，以避免智能体说话时被较短人声误打断。
prefix_padding_msinteger前缀填充阈值 (ms)，取值范围为 [0, 5000]。开始新的语音片段所需的最短语音持续时间，避免非常短的声音触发语音活动检测。
已废弃。请改用顶级 interruption.mode = "keywords" 配合 interruption.keywords_config.trigger_keywords 实现关键词打断。
已废弃。请改用 interruption.enable = false 配合 interruption.disabled_config.strategy 配置关闭打断后的处理策略。
对话结束 (End of Speech, EoS) 检测配置，用于判定用户何时结束说话。
modestring对话结束检测模式，支持以下值：
"vad"：（默认）基于 VAD（语音活动检测）触发，检测静音持续时间。"semantic"：优雅打断，基于语义触发，使用语义理解模块判定用户是否结束说话还是短暂停顿。该模式目前仅支持识别中文和英文文本。"manual"：手动 EoS 模式。关闭服务端自动 EoS 判停，由客户端通过 RTM 消息显式声明用户结束说话。
注意
使用 "manual" 时：
- 必须同时开启
advanced_features.enable_rtm = true。 - 必须同时设置
parameters.data_channel = "rtm"。 - 不支持传入
manual_config；该模式下无需公开配置项。
对话结束检测配置参数。不同检测模式下该参数结构和支持的字段不同。
你需要根据 mode 传入对应的配置字段。例如 mode 为 "vad" 时，需传入 vad_config。不可同时传入多个模式配置。
当 mode 为 "manual" 时，无需传入任何 manual_config，且公开接口不支持该字段。
基于 VAD 的对话结束检测配置。以下为示例：
"vad_config": {
"silence_duration_ms": 480
}
silence_duration_msinteger静音持续阈值 (ms)，取值范围为 [120, 2000]。语音结束时的最短静音持续时间，确保短暂的停顿不会过早结束语音片段。
基于语义的对话结束检测配置。以下为示例：
"semantic_config": {
"silence_duration_ms": 240,
"max_wait_ms": 3000,
"pause_state_enabled": true
}
silence_duration_msinteger静音持续阈值 (ms)，取值范围为 [120, 2000]。语音结束时的最短静音持续时间，确保短暂的停顿不会过早结束语音片段。
max_wait_msinteger最大等待时间 (ms)，取值范围为 [500, 10000]，传入 -1 表示永远等待。等待语义判定的最长时间，超时后将基于当前状态判定对话是否结束。
pause_state_enabledboolean是否判定用户有暂停对话的意图:
true：（默认）智能体会根据语义判断用户是否想要暂停对话。例如，当用户输入以“等一下”、“稍等”等词结束时，智能体可根据语义判断用户有暂停对话的意图并等待用户后续输入，而不是判断用户输入结束并直接发送给 LLM。false：智能体不判定用户是否想要暂停对话。
智能打断控制配置，用于统一管理智能体被用户打断的行为策略。
enableboolean是否开启智能体打断功能：
true：（默认）开启。false：关闭。关闭后，智能体不会被中途打断。
modestring打断触发方式，支持以下值：
"start_of_speech"：（默认）用户开始说话时触发打断。"keywords"：用户说出指定关键词时触发打断，在keywords_config字段中配置触发关键词。
基于关键词触发打断的配置。仅在 mode = "keywords" 时生效。
trigger_keywordsarray<string>触发打断的关键词列表。最多支持设置 128 个关键词。
关闭打断功能后的处理策略。仅在 interruption.enable 为 false 时生效。
strategystring关闭打断功能后的处理策略，支持以下值：
"append"：追加模式，人声不打断智能体。智能体会在当前交互结束后处理刚才收到的人声请求。"ignore"：忽略模式，智能体忽略人声请求。如果智能体正在说话或思考中途收到人声，智能体会直接忽略并丢弃人声请求，不存入上下文。
选择性注意力锁定（Selective Attention Locking, SAL）配置。
说明
该功能目前处于 Beta 阶段。
sal_modestring选择性注意力锁定模式，支持以下选项：
"locking"：（默认）主讲人锁定模式。智能体锁定主讲人，屏蔽 95% 的环境人声、噪声。该模式可通过两种方式启用：- 无感识别：用户在对话初期大声、清晰地说话，智能体即可自动将用户识别为主讲人。
- 预注册：创建智能体时，通过
sample_urls字段预注册一名主讲人的声纹 URL，智能体将根据预注册的声纹 URL 锁定主讲人。
"recognition"：声纹识别模式。你可以通过sample_urls字段预注册声纹 URL，目前仅支持单声纹注册。智能体将识别不同的说话人并抑制其他背景人声和环境噪音。识别到的说话人身份会通过metadata字段里的vpids字段标识并发送给 LLM，你需要将llm.vendor设置为"custom"，并参考自定义大模型了解如何让 LLM 处理说话人信息。
sample_urlsobject注册声纹 URL，为键值对形式，键为注册的声纹名称，值为对应说话者的声纹 URL 下载地址。
注意
- 传入的声纹名称不可设置为
"unknown"，这是一个保留关键字，用于标识未知说话人。 - 对于注册的声纹，需满足以下条件：
- 数量: 每个任务请求的注册声纹URL数量，目前仅支持单声纹，数量为 1 个。
- 大小: 单个声纹文件不得超过 2 MB。
- 时长：时长为 10 到 15 秒, 其中有效音频不小于 8 秒（不能有太多静音段）。
- 格式: 必须为 16k 采样率、16bit 位深、单声道的 PCM 音频文件，文件名后缀必须为
.pcm。
labelsobject自定义标签，键值对形式，键为标签名，值为标签值。用于让智能体携带自定义业务信息。
这些自定义信息会与智能体绑定，并在对话式 AI 引擎所有类型消息通知回调的 payload 字段中返回，可用于实现自定义业务逻辑，例如标记活动 ID、客户分组、业务场景等。
RTC 媒体内容加密配置。
encryption_keystring字符串类型的加密密钥，长度不受限制。声网建议使用 32 字节的密钥。
注意
如果未设置加密密钥或将其设置为空，则无法使用内置加密。
encryption_saltstring用于加密的盐值，Base64 编码的字符串，解码后长度为 32 字节。
注意
该参数仅在 encryption_mode 设为 7（AES_128_GCM2）或 8（AES_256_GCM2）时生效。在此情况下，请确保该参数不为空。
encryption_modeinteger内置加密模式，支持以下值：
1: AES_128_XTS - 128 位 AES 加密，XTS 模式。2: AES_128_ECB - 128 位 AES 加密，ECB 模式。3: AES_256_XTS - 256 位 AES 加密，XTS 模式。4: SM4_128_ECB - 128 位 SM4 加密，ECB 模式。5: AES_128_GCM - 128 位 AES 加密，GCM 模式。6: AES_256_GCM - 256 位 AES 加密，GCM 模式。7: AES_128_GCM2 - 128 位 AES 加密，GCM 模式。该模式需设置 salt（encryption_salt）。8: AES_256_GCM2 - 256 位 AES 加密，GCM 模式。该模式需设置 salt（encryption_salt）。
建议
声网建议使用 7（AES_128_GCM2）或 8（AES_256_GCM2）模式，这两种模式支持使用加密盐以提升安全性。
承接词功能 (Beta) 配置，用于在 LLM 响应等待时播报承接词，缓解用户等待焦虑，提升对话流畅度。
承接词播报遵循以下规则：
- 播报顺序：当多个承接词或 LLM 响应等待播报时，按照文本到达的先后顺序进行播报。
- 打断控制：继承全局配置中的打断模式设置 (
turn_detection.config)。
enableboolean是否启用承接词功能：
true：启用。false：（默认）不启用。
承接词触发配置，定义何时触发承接词播报。
固定时间触发配置。省略时使用默认的 1500 ms 等待阈值。
response_wait_msintegerLLM 响应等待阈值 (ms)，取值范围为 [100, 10000]。当 LLM 处于等待状态（例如等待 RAG 检索结果、工具调用结果）的持续时间达到该阈值且未生成响应内容时，触发承接词播报。
承接词内容配置，定义承接词的来源和选择规则。
modestring承接词内容模式，支持以下值：
"static"：（默认）静态承接词。使用预定义的承接词列表。"generated"：生成承接词。由声网托管的生成能力根据当前上下文生成一句承接词；当生成结果不可用时，使用static_config中的静态承接词兜底。
静态承接词配置。启用承接词时必需配置。mode 为 "generated" 时，该配置用于生成承接词不可用时的静态兜底。
phrasesarray<string>承接词短语列表。
- 支持 1 到 100 个非空字符串。
- 每个短语最多支持 20 个单词（拉丁文字）或 20 个字符（中文及其他非拉丁文字）。
selection_rulestring承接词选择规则，支持以下值：
"shuffle"：随机打乱。在所有承接词都被使用完一轮前，已使用的承接词不会重复播报；只有所有承接词播报完后，才会重新随机打乱并开始新的一轮。"round_robin"：轮询。从承接词列表中顺序选取并播报，所有承接词播报完一轮后，开始新的循环播报。
生成承接词配置。仅当 mode 为 "generated" 时生效。
promptstring生成承接词的 Prompt 指令。该字段为可选非空字符串；如果传入该字段，该 Prompt 会完整替换声网默认 Prompt，并对相同的对话上下文窗口生效。
context_message_limitinteger动态承接词使用的对话消息数量上限，包含触发当前回合的用户消息。
1：（默认）仅使用当前用户消息。2到6：除当前用户消息外，还会按时间顺序使用符合上限的近期用户和智能体文本消息。
history_character_limitinteger动态承接词使用的历史消息文本字符数上限，仅统计历史消息的 Unicode code points，不包含当前用户消息。
0：不限制历史消息文本字符数，但完整输入仍受托管模型的有效输入容量限制。1到10000：超过上限时，从最旧的历史消息开始整条移除，不截断消息。
智能体参数配置。
智能体静默设置。
timeout_msinteger智能体最大静默时间 (ms)，取值范围为 [0,60000]。智能体创建成功，且用户加入频道后，智能体不处于倾听、思考或说话状态的持续时间称为智能体静默时间。静默时间达到设定值后，智能体将播报静默提示消息。该功能可用于在用户不活跃时让智能体提醒用户。
- 设置为
0（默认值）：表示不启用该功能。 - 设置为
(0,60000]时，必须同时设置content才能正常播报静默提示，否则设置无效。
actionstring静默时间达到设定值后，智能体采取的行为，可设为以下值：
"speak"：（默认）使用 TTS 模块播报静默提示内容 (content)。"think"：将静默提示内容 (content) 追加在上下文的最后，并传递给 LLM。
contentstring静默提示消息的内容。设置的内容会根据 action 中的设置以不同的方式使用。
智能体优雅挂断设置。
graceful_enabledboolean是否启用优雅退出（Graceful Leave）功能：
true：启用。开启后，调用 POST 停止对话式智能体接口，让智能体退出频道时，会确保智能体处于静默状态（IDLE）后再离开频道。false：（默认）不启用。
graceful_timeout_secondsinteger优雅退出超时时间 (s)，表示在退出频道前等待智能体进入静默状态（IDLE）的最长时间，超出该时间后，即便智能体不处于静默状态，也会立即退出频道。该字段仅在 graceful_enabled 为 true 时生效，取值范围为 [0,120]。
data_channelstring智能体数据传输通道，可选以下值：
rtm：使用 RTM 传输。该配置仅在advanced_features.enable_rtm为true时生效。datastream：（默认）使用 RTC 的DataStream传输。
注意
如果 turn_detection.config.start_of_speech.mode 或 turn_detection.config.end_of_speech.mode 为 manual，则必须同时开启 advanced_features.enable_rtm = true，并将该字段设为 rtm。
enable_metricsboolean是否接收智能体性能数据：
true：接收。false：（默认）不接收。
该配置仅在 advanced_features.enable_rtm 为 true 时生效。你可以参考监听智能体事件了解如何使用客户端组件接收智能体性能数据，或参考接收 Webhook 事件了解如何使用 Webhook 接收智能体性能数据。
enable_error_messageboolean是否接收智能体错误事件：
true：接收。false：（默认）不接收。
该配置仅在 advanced_features.enable_rtm 为 true 时生效。你可以参考监听智能体事件了解如何使用客户端组件接收智能体错误事件。
opt_outboolean是否关闭当前会话的数据留存:
false：（默认）不关闭。true：关闭会话数据留存。关闭后将无法依托历史内容开展故障排查、效果复盘与智能体优化。
注意
为保障服务运行、智能体迭代调优与故障排查，默认在最短必要周期内临时留存会话交互文本、音频。若您的业务对数据存储有严格的安全或合规要求，建议启用该字段，关闭当前会话的数据留存。
响应
- 若返回的状态码为
200则表示请求成功。响应包体中包含本次请求的结果。 - 若返回的状态码不为
200则表示请求失败。响应包体中包含错误的类别和描述，你可以参考响应状态码了解可能的原因。
响应 Body
agent_idstring智能体唯一标识。
create_tsinteger智能体创建时间戳。
statusstring智能体运行状态：
IDLE(0)：空闲状态的智能体。STARTING(1)：正在启动的智能体。RUNNING(2)：正在运行的智能体。STOPPING(3)：正在停止的智能体。STOPPED(4)：已完成退出的智能体。FAILED(6)：执行失败的智能体。
请求示例
curl --request POST \
--url "https://api.agora.io/cn/api/conversational-ai-agent/v2/projects/:appid/join" \
--header 'Authorization: agora token="007abcxxxxxxx123"' \
-H 'Content-Type: application/json' \
-d '{
"name": "unique_name",
"properties": {
"channel": "channel_name",
"token": "token",
"agent_rtc_uid": "123",
"remote_rtc_uids": [
"321"
],
"enable_string_uid": false,
"idle_timeout": 120,
"llm": {
"url": "https://api.minimax.chat/v2/text/chatcompletion_v2",
"api_key": "xxx",
"system_messages": [
{
"role": "system",
"content": "You are a helpful chatbot."
}
],
"greeting_message": "您好，有什么可以帮您？",
"failure_message": "抱歉，我无法回答这个问题。",
"max_history": 32,
"params": {
"model": "abab6.5s-chat",
"max_token": 1024,
"userName": "Tomas"
}
},
"asr": {
"language": "zh-CN",
"vendor": "fengming"
},
"tts": {
"vendor": "minimax",
"skip_patterns": [
1
],
"params": {
"group_id": "xxxx",
"key": "xxxx",
"model": "speech-01-turbo",
"voice_setting": {
"voice_id": "female-shaonv",
"speed": 1,
"vol": 1,
"pitch": 0,
"emotion": "happy"
},
"audio_setting": {
"sample_rate": 16000
}
}
}
}
}'响应示例
{
"agent_id": "1NT29X10YHxxxxxWJOXLYHNYB",
"create_ts": 1737111452,
"status": "RUNNING"
}