# 创建对话式智能体 (/zh-CN/api-reference/api-ref/conversational-ai/join) > For AI agents: see the complete documentation index at [llms.txt](/llms.txt). 创建一个对话式智能体 (Conversational AI agent) 实例,并加入 RTC 频道。 - OpenAPI: /openapi/conversational-ai/rest-api.zh-CN.yaml - Operation ID: start-agent - Method: POST - Path: /v2/projects/{appid}/join - Endpoint: https://api.agora.io/cn/api/conversational-ai-agent/v2/projects/{appid}/join ## Servers - https://api.agora.io/cn/api/conversational-ai-agent ## Authorization This endpoint requires authentication. - `Basic Auth` - `Agora Token` ## Parameters - `Authorization` (header, required, string) - 发送 HTTP 请求时,你可以从以下鉴权方式中任选其一: 1. **使用 Token 认证(推荐)**:参考[实现 HTTP 鉴权](/zh-CN/ai/build/http-basic-auth#使用-token-认证)生成 Token 并填入 `Authorization` Header。传参示例:`Authorization: agora token="007abcxxxxxxx123"`。 2. **使用 Basic Auth**:参考[实现 HTTP 鉴权](/zh-CN/ai/build/http-basic-auth#使用-http-基本认证)生成 Base64 编码的 `Authorization` 字段。传参示例:`Authorization: Basic NDI1OTQ3N2I4MzYy...YwZjA=`。 - Example: `agora token="007abcxxxxxxx123"` - `appid` (path, required, string) - 你的项目使用的 [App ID](/zh-CN/ai/get-started/enable-service#%E8%8E%B7%E5%8F%96-app-id)。 ## Request body - `name` (string, required) - 智能体唯一标识,相同标识不可重复创建。 - `properties` (object, required) - 智能体详细配置。 - `properties.channel` (string, required) - 智能体加入的 RTC 频道名。 - `properties.token` (string) - 加入 RTC 频道使用的 Token,即用于鉴权的动态密钥。如果你的项目已启用 App 证书,则务必在该字段中传入你项目的动态密钥。详见[使用 Token 鉴权](/zh-CN/realtime-media/rtc/build/setup-and-access/token-authentication)。 - `properties.agent_rtc_uid` (string, required) - 智能体在 RTC 频道内的用户 ID。 > [!CAUTION] > 同一 `channel` 内的用户 ID 不可重复,否则智能体加入频道会失败。 - `properties.remote_rtc_uids` (array, required) - 智能体在 RTC 频道中订阅的用户 ID 列表,只有订阅的用户才能与智能体互动。目前只支持订阅一个用户 ID。 - `properties.remote_rtc_uids.items` (string) - `properties.enable_string_uid` (boolean) - 是否启用 String UID: - `true`:智能体和订阅用户 ID 均使用 String UID。 - `false`:(默认)智能体和订阅用户 ID 均使用 Int UID。 > [!CAUTION] > 同一频道内,Int 型和 String 型的用户 ID 不可混用。更多使用 String UID 的相关信息请参考[如何使用 String 型用户 ID](/zh-CN/reference/faq/integration/string_uid)。 - Default: `false` - `properties.idle_timeout` (integer) - RTC 频道的最大空闲时间,单位为秒。系统检测到 `remote_rtc_uids` 中指定的用户已全部离开频道后,会开始计算空闲时长;空闲时长超过该值时,智能体会自动停止并退出频道。 - 取值范围为 `[0, 259200]`,默认值为 `30`。其中 `259200` 秒即 72 小时,超过该值会报错。 - 设置为 `0` 仅表示不因“频道空闲超时”退出。 - 无论 `idle_timeout` 取值为何,单次任务的最长运行时间均为 72 小时;达到 72 小时后,智能体会自动退出。 - Default: `30` - Range: `[0, 259200]` - `properties.advanced_features` (object) - 高级功能配置。 - `properties.advanced_features.enable_rtm` (boolean) - 是否启用实时消息 RTM 服务。启用后智能体会自动登录 RTM 并订阅 `channel` 中指定的频道,可结合 RTM 提供的能力实现一些进阶功能,例如[传递自定义信息](/zh-CN/ai/build/shape-the-conversation/custom-information)。 > [!CAUTION] > 启用 RTM 服务前需要确保 Token 同时具备 RTC 和 RTM 权限。智能体加入 RTM 频道会复用 `token` 字段配置的 Token。你可以参考 [FAQ](/zh-CN/reference/faq/integration/rtc_rtm_token) 了解如何生成同时具备 RTC 和 RTM 权限的 Token。 - Default: `false` - `properties.advanced_features.enable_sal` (boolean) - 是否启用选择性注意力锁定(Selective Attention Locking, SAL)功能。启用后,在 `sal` 字段中完成相关设置,智能体即可识别用户的声纹特征,有效区分不同说话者,屏蔽 95% 的环境人声、噪声。 > [!NOTE] > 该功能目前处于 Beta 阶段。 - Default: `false` - `properties.advanced_features.enable_tools` (boolean) - 是否启用工具调用功能。启用后,智能体可以调用 `llm.tools` 中声明的自定义工具和 `llm.mcp_servers` 中配置的 MCP 工具,实现查询业务数据、执行外部操作等业务逻辑。 - `true`:启用自定义工具和 MCP 工具调用。 - `false`:(默认)不启用工具调用,也不会访问工具端点。 > [!CAUTION] > 即使该字段为 `false` 或省略,请求中传入的 `llm.tools` 仍需通过字段类型、大小、模板语法和工具名称重复性校验。 - Default: `false` - `properties.asr` (object) - 自动语音识别 (ASR) 配置。 - `properties.asr.language` (string) - 用户与智能体互动时使用的语言: - `zh-CN`:中文(支持中英文混合) - `en-US`:英语 - Default: `zh-CN` - `properties.asr.vendor` (string) - ASR 服务供应商,可选以下值: - `fengming`:(默认)声网凤鸣 ASR。 - `tencent`:腾讯 ASR。 - `microsoft`:微软 ASR。 - `stepfun`:阶跃星辰 StepASR。 - `properties.asr.keywords` (array) - ASR 热词列表,用于提升指定词汇的识别效果。详见[配置 ASR 热词](/zh-CN/ai/build/custom-model-integration/asr-keywords)。 - 仅当 `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.` > [!CAUTION] > 设置热词可能影响其他词汇的识别准确度,请根据业务场景谨慎配置。 - Max items: `128` - `properties.asr.keywords.items` (string) - `properties.asr.params` (object) - ASR 配置参数。不同 ASR 供应商下该参数结构不同。 > [!CAUTION] > 各供应商示例代码中未提及的参数,声网对话式 AI 引擎不保证完全支持。 - `properties.tts` (object, required) - 文本转语音 (TTS) 模块配置。 - `properties.tts.vendor` (string, required) - TTS 供应商,支持传入以下值: - `minimax`:Minimax TTS - `minimax_duplex`:MiniMax 双向流式 TTS - `tencent`:腾讯 TTS - `bytedance`:火山引擎 TTS - `microsoft`:微软 Azure TTS - `cosyvoice`:(Beta) 阿里云 CosyVoice TTS - `bytedance_duplex`:火山引擎双向流式 TTS - `stepfun`:(Beta) 阶跃星辰 TTS - `generic_http`:(Beta) 通过 OpenAI TTS 协议接入自研或第三方 TTS 引擎。详见[通过 RESTful API 接入自定义 TTS](/zh-CN/ai/build/custom-model-integration/custom-tts)。 - `properties.tts.batch` (boolean) - 是否由智能体先对文本分句。使用 `minimax_duplex` 时支持以下配置: - `true`:(默认)由智能体先分句,再发送给 MiniMax。 - `false`:按上游原始文本粒度发送,由 MiniMax 累积文本并分句。 - `properties.tts.enable_words` (boolean) - 是否启用逐字字幕。使用 `minimax_duplex` 且需要逐字字幕时,建议显式设置为 `true`。 当设置为 `true` 时,如果未显式配置 `tts.params.subtitle_enable` 和 `tts.params.subtitle_type`,引擎会自动补齐为 `true` 和 `word`。 - `properties.tts.skip_patterns` (array) - 过滤模式配置,用于控制是否跳过 LLM 返回文本中括号内的内容,避免智能体播报不必要的结构性提示信息如语气、动作描述等。默认值为 `[]`,即不过滤任何内容。可选值如下,传入即启用该功能: - `1`:跳过中文圆括号( )中的内容 - `2`:跳过中文方括号【 】中的内容 - `3`:跳过英文圆括号 ( ) 中的内容 - `4`:跳过英文方括号 [ ] 中的内容 - `5`:跳过英文花括号 \{ } 中的内容 > [!CAUTION] > - 当输入文本中存在嵌套括号,且多种括号类型都被配置为跳过时,智能体只处理最外层括号,即系统将从文本的起始位置开始匹配,一旦找到第一个符合跳过规则的最外层括号对,该括号对及其包含的所有内容(包括任何嵌套的其他类型括号)都将被整体跳过。 > - 无论是否打开[实时字幕](/zh-CN/ai/build/transcripts),智能体短期记忆都会包含被过滤的内容,即 LLM 生成的完整文本。 > - 开启[实时字幕](/zh-CN/ai/build/transcripts)时,实时字幕在 TTS 播报时不会包含被过滤的内容,等这句话播报完毕后,字幕会把这些内容添加回来。 > - 火山引擎双向流式 TTS 暂不支持该功能。 - Default: `[]` - `properties.tts.skip_patterns.items` (integer) - `properties.tts.params` (object, required) - 指定 TTS 供应商的配置参数。 > [!NOTE] > 你可以参考调用示例中不同 TTS 供应商的参数填写样例。 - `properties.llm` (object, required) - 大语言模型 (LLM) 配置。 - `properties.llm.url` (string, required) - LLM 回调地址,要求与 OpenAI 协议兼容。 - `properties.llm.api_key` (string) - LLM 鉴权 API key。默认为空,生产环境中务必启用 API key。 - `properties.llm.system_messages` (array) - 一组每次调用 LLM 时被附加在最前的预定义信息,用于控制 LLM 输出。可以是角色设定、提示词和回答样例等。要求与 OpenAI 协议兼容。 - `properties.llm.system_messages.items` (object) - `properties.llm.max_history` (integer) - LLM 中缓存的短期记忆条目数。取值范围为 `[1,1024]`。短期记忆包括用户和智能体对话消息、工具调用信息和时间戳。智能体和用户会单独记录短期记忆条目。 - Default: `32` - `properties.llm.input_modalities` (array) - LLM 的输入模态,支持: - `["text"]`:(默认)仅文字。 - `["text", "image"]`:文字加图片。推荐配置,要求所选 LLM 支持视觉模态输入。 - `properties.llm.input_modalities.items` (string) - `properties.llm.output_modalities` (array) - LLM 的输出模态,支持: - `["text"]`:(默认)仅文字。输出的文字会经过 TTS 模块转换成语音后发布至 RTC 频道。 - `["audio"]`:仅语音。语音会直接发布至 RTC 频道。 - `["text", "audio"]`:文字加语音。你可以自行编写逻辑,按需处理 LLM 的输出。 - `properties.llm.output_modalities.items` (string) - `properties.llm.greeting_message` (string) - 智能体问候语文本。如果填写,则在频道内没有订阅用户列表 (`remote_rtc_uids`) 中的用户时,智能体会自动向首位加入频道的订阅用户发送问候语。 - 你可以单独配置该字段,走原有实时 TTS 开场白路径。 - 也可以在配置 `greeting_audio_url` 时,将该字段作为录音开场白的兜底文本。 - 当 `greeting_interruptable = true` 且录音开场白被用户打断时,系统会结合 `greeting_message` 估算已播报的文本片段,并将其注入短期记忆以保持对话上下文连贯。 - `properties.llm.greeting_interruptable` (boolean) - 智能体问候语是否可被打断: - `true`:(默认)可打断,遵循全局打断配置 (`interruption`)。 - `false`:不可打断,问候语会完整播放;播放期间识别到的用户 ASR 文本会被静默接收,待问候语结束后拼接为单轮 user 消息,再统一送入大模型进行一次推理和回复。 - `properties.llm.greeting_audio_url` (string) - 智能体问候语录音文件的 URL。配置后,系统会优先下载并播放该录音作为开场白。 支持以下格式的音频文件: - `mp3` - `wav` - `pcm` 使用说明如下: - 仅支持 `http://` 或 `https://` 开头的 URL;空字符串、非 URL 字符串或长度超过 `2048` 字节时,请求会返回 `400` 错误。 - 对于 `pcm` 文件,需要额外通过 `greeting_configs.audio_pcm_sample_rate` 指定采样率。 - 系统会将导入的音频统一转换为与 `tts.params.sample_rate` 一致的采样率后再进行播报。 > [!CAUTION] >- 配置 `greeting_audio_url` 时,必须同时配置 `greeting_message`用于异常回退;否则请求会返回 `400` 错误。 >- 当 `greeting_audio_url` 对应的录音下载失败、解码失败或格式不支持时,系统会自动使用 `greeting_message` 进行 TTS 合成并继续播报。 - Format: `uri` - Max length: `2048` - `properties.llm.greeting_configs` (object) - 智能体问候语播报配置。 - `properties.llm.greeting_configs.mode` (string) - 智能体问候语播报模式,支持以下选项: - `"single_every"`:(默认)每次有用户加入空频道时,智能体都播报一次问候语。 - `"single_first"`:仅首位用户加入空频道时,智能体播报一次问候语。 - `properties.llm.greeting_configs.delay_ms` (integer) - 智能体问候语播报延迟时间 (ms),取值范围为 [0, 5000]。配置后,智能体问候语会在用户加入频道后等待指定时间再播报。 - Default: `0` - Range: `[0, 5000]` - `properties.llm.greeting_configs.audio_download_timeout_ms` (integer) - 录音开场白下载超时时间,单位为毫秒。仅在配置 `greeting_audio_url` 时生效。 - 取值范围为 `[200, 10000]`。 - `null` 和字段缺失均视为未配置,此时使用默认值 `1000`。 - 超时后系统会回退到 `greeting_message` 的 TTS 路径。 - Default: `1000` - Range: `[200, 10000]` - `properties.llm.greeting_configs.audio_pcm_sample_rate` (integer) - 录音开场白为 PCM 文件时的采样率,单位为 Hz。仅在配置 `greeting_audio_url` 且录音格式为 PCM 时生效。 - 默认值为 `16000`。 - `mp3` 和 `wav` 文件无需配置该字段。 - Default: `16000` - `properties.llm.template_variables` (object) - 动态参数配置,用于在智能体的 `system_messages`、`greeting_message`、`failure_message` 和 `parameters.silence_config.content` 文本中插入变量。键值对形式,键为变量名,值为变量值。 **使用方式**:在 Prompt 文本中使用 `{{variable_name}}` 格式引用变量,系统会自动将其替换为 `template_variables` 中定义的对应值。 > [!CAUTION] > 变量名和变量值不支持引用其他变量。例如自定义变量 `"farewell": "期待下次再见,{{name}}"`,其中的 `{{name}}` 不会被解析。 - `properties.llm.failure_message` (string) - 智能体处理失败提示语。如果填写,则在 LLM 调用错误时会通过 TTS 模块返回。 - `properties.llm.vendor` (string) - LLM 供应商,支持以下两种设置: - 商业大模型供应商,支持以下值: - `aliyun`:阿里云 - `bytedance`:字节跳动 - `deepseek`:深度求索 - `tencent`:腾讯 设置后,可提高兼容性,减少因携带 LLM 不支持的信息而导致请求失败的情况。 - 自定义 LLM,即设为 `"custom"`。设置后智能体调用 custom LLM 时,除了 `role` 和 `content` 外,将额外携带以下信息: - `turn_id`:唯一的对话轮次标识符。`turn_id` 从 0 开始递增,用户和智能体的一轮对话对应一个 `turn_id`。 - `timestamp`:请求时间戳,精度为毫秒。 - `properties.llm.mcp_servers` (array) - MCP (Model Context Protocol) 服务器配置列表。通过配置 MCP 服务器,智能体可以调用外部服务提供的工具,实现更复杂的业务逻辑。 - `properties.llm.mcp_servers.items` (object) - `properties.llm.mcp_servers.items.name` (string, required) - MCP 服务器的唯一标识。长度不超过 48 字符,支持以下字符: - 所有小写英文字母:a 到 z - 所有大写英文字母:A 到 Z - 所有数字字符:0 到 9 - "." 和 "-" - `properties.llm.mcp_servers.items.endpoint` (string, required) - MCP 服务器的端点地址,智能体将通过该地址与 MCP 服务器通信。 - `properties.llm.mcp_servers.items.transport` (string) - 传输协议类型,支持传入以下值: - `"streamable_http"`:流式 HTTP 协议 - `properties.llm.mcp_servers.items.headers` (object) - 请求 MCP 服务器时携带的 HTTP 头部信息,例如认证信息。 - `properties.llm.mcp_servers.items.allowed_tools` (array) - 允许智能体调用的工具列表。只有在此列表中的工具才能被智能体使用。 > [!NOTE] > `allowed_tools` 字段生效规则: > - 不填写 `allowed_tools` 字段:所有工具都生效 > - 填写 `allowed_tools` 字段: > - 填写为 `[]`:所有工具不生效 > - 填写为 `["*"]`:所有工具生效 > - 填写为 `["aa", "bb", "cc"]`:`aa`、`bb`、`cc` 生效 > - 填写为 `["aa", "bb", "*"]`:所有工具生效 - `properties.llm.mcp_servers.items.allowed_tools.items` (string) - `properties.llm.mcp_servers.items.timeout_ms` (integer) - MCP 服务器请求超时时间,单位为毫秒。请求超时后,智能体将不会等待 MCP 服务器响应,而是继续执行后续逻辑。 - Default: `10000` - `properties.llm.tools` (array) - 自定义工具列表。配置后,大模型可以根据对话内容选择工具并生成参数,由对话式 AI 引擎校验参数、调用对应的 HTTPS 端点,再将结果返回给大模型继续生成回复。 自定义工具、MCP 工具、内置工具和模型原生工具共用同一个工具名称空间,名称按 ASCII 大小写不敏感的方式比较。完成 MCP 发现和过滤后,向大模型提供的工具总数最多为 32 个;名称冲突或超过上限时,智能体启动失败,不会自动覆盖、重命名或截断工具。 > [!CAUTION] > - 使用工具前需将 `advanced_features.enable_tools` 设为 `true`。 > - 当前仅支持同步调用标准文本 LLM,暂不支持自定义 LLM、MLLM、Dify、异步工具和已存储工具引用。 - Max items: `32` - `properties.llm.tools.items` (object) - 自定义工具定义。大模型决定是否调用工具并生成参数;对话式 AI 引擎校验参数后发起一次同步 HTTP 请求,并将结果返回给大模型。 > [!CAUTION] > - 当前仅支持同步 `GET` 和 `POST` 请求,不支持异步调用、自动重试或 HTTP 重定向。 > - 响应包体原始大小上限为 1 MiB,且必须是 UTF-8 文本。 > - `application/json` 和 `+json` 响应会保留 JSON 原始类型,包括 object、array、scalar 和 `null`;其他响应按 UTF-8 字符串处理。 > - 空响应包体返回 `[]`。2xx 响应为 `success`,非 2xx 响应为 `failed`,但均会将响应内容返回给大模型。 - `properties.llm.tools.items.type` (string, required) - 工具类型,当前仅支持 `function`。 - Allowed: `function` - `properties.llm.tools.items.function` (object, required) - `properties.llm.tools.items.function.name` (string, required) - 模型可见的工具名称。需以英文字母开头,仅包含英文字母和数字,长度为 1 到 64 个字符。 自定义工具、MCP 工具、内置工具和模型原生工具的名称按 ASCII 大小写不敏感的方式比较,不能重复;名称不能使用 `mcp` 前缀或 `ragsearch_tool`。 - Pattern: `^[a-zA-Z][a-zA-Z0-9]{0,63}$` - `properties.llm.tools.items.function.description` (string, required) - 工具说明,用于帮助大模型判断何时调用工具以及工具返回什么。请勿包含密钥等敏感信息。 - Min length: `1` - Max length: `1024` - `properties.llm.tools.items.function.parameters` (object, required) - 工具参数定义采用 JSON Schema 格式,并按 OpenAI Function Calling 的 non-strict 模式传递给大模型。详情见 [OpenAI Function Calling](https://platform.openai.com/docs/guides/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。 示例: ```json { "type": "object", "properties": { "order_id": { "type": "string", "description": "订单 ID" } }, "required": ["order_id"], "additionalProperties": false } ``` - `properties.llm.tools.items.execution` (object) - 工具执行方式。 - `properties.llm.tools.items.execution.mode` (string) - 执行模式,当前仅支持同步执行 `sync`。 - Allowed: `sync` - Default: `sync` - `properties.llm.tools.items.server` (object, required) - 自定义工具的 HTTP 请求配置。 模板采用单次替换,不会递归展开。支持以下变量: - `{{args.}}`:通过校验的大模型工具参数,可用于 URL 的路径或查询参数以及请求体,不可用于 Header。 - `{{template_variables.}}`:创建智能体时配置的模板变量,可用于 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 中的变量值只能是字符串、数字或布尔值。 > [!CAUTION] > 认证信息只能作为完整的 Header 值传入。请勿将认证信息放入 URL 或请求体。所有 Header 值均按敏感信息处理,不会传递给大模型或写入普通日志、事件、字幕和 TTS。 - `properties.llm.tools.items.server.method` (string, required) - HTTP 请求方法,支持: - `GET`:用于查询数据,不支持请求体。配置 `body` 会导致请求校验失败。 - `POST`:用于提交数据,可同时配置 URL 查询参数、请求 Header 和请求体。 - Allowed: `GET` | `POST` - `properties.llm.tools.items.server.url` (string, required) - 自定义工具请求的绝对 HTTPS URL。 URL 的路径和查询参数支持嵌入以下单层占位符: - `{{args.}}` - `{{template_variables.}}` - `{{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 字节。 - Min length: `1` - Max length: `2048` - Pattern: `^https://` - `properties.llm.tools.items.server.headers` (object) - 自定义工具请求携带的自定义 Header,最多支持 32 项。 Header 值支持: - 静态 string、number 或 boolean。 - 完整的 `{{template_variables.}}` 占位符。 - 完整的 `{{tool_call_id}}` 占位符。 使用限制: - Header 名长度为 1 到 128 个字符,且必须符合 HTTP token 规范。 - Header 名不可模板化,Header 值不支持 `{{args.}}`。 - 占位符必须作为完整 Header 值,不支持与其他文本拼接,也不支持嵌套字段、数组索引或递归展开。 - 每个渲染后的 Header 值最大为 4096 UTF-8 字节,所有 Header 合计最大为 16 KiB。 - 如果自定义 Header 与声网生成的系统 Header 重名,以声网生成的值为准。 所有 Header 值均按敏感信息处理,不会传递给大模型,也不会写入普通日志、事件、字幕或 TTS。 - `properties.llm.tools.items.server.body` (unknown) - 自定义工具的 HTTP 请求体,仅支持用于 `POST`。为 `GET` 配置该字段会导致请求校验失败。 请求体支持 object、array、string、number、boolean 和 `null`,并可使用任意层级的 JSON 结构。请求体中的叶子值可以是: - JSON 常量。 - 完整的 `{{args.}}` 占位符。 - 完整的 `{{template_variables.}}` 占位符。 - 完整的 `{{tool_call_id}}` 占位符。 占位符必须作为完整的叶子值,不支持与其他文本拼接,也不支持嵌套字段、数组索引或递归展开。占位符替换后会保留变量原始的 JSON 类型;工具参数在序列化为 JSON 请求体时会自动转义。 - `properties.llm.tools.items.server.timeout_ms` (integer) - HTTP 请求超时时间 (ms),取值范围为 [1000, 100000],默认为 10000。 - Default: `10000` - Range: `[1000, 100000]` - `properties.llm.headers` (object) - 请求 LLM 时附带的自定义请求 Header。你可以通过该字段透传业务自定义字段、租户标识等业务相关信息。 > [!NOTE] > - 该参数传入的请求 Header 会与对话式 AI 引擎默认生成的请求 Header 合并;当键冲突时,以对话式 AI 引擎生成的请求 Header 为准(例如认证相关 Header)。 > - Header 键按字符串精确匹配进行合并(区分大小写),声网建议统一使用标准写法,避免同名不同大小写导致歧义。 - `properties.llm.params` (object) - 在消息体内传输的 LLM 附加信息,例如使用的模型、最大 Token 数限制等。不同的 LLM 供应商支持的配置不同,请参考对应文档按需填入。 - `properties.avatar` (object) - 数字人 (Avatar) 配置。 - `properties.avatar.enable` (boolean) - 是否为智能体启用数字人功能: - `true`:启用。启用后需配置 `vendor` 和 `params` 字段。 - `false`:(默认)不启用。 > [!CAUTION] > 开启数字人功能将产生 RTC 视频通话费用,详见 [RTC 计费说明](/zh-CN/realtime-media/rtc/reference/billing-strategy)。 - `properties.avatar.vendor` (string) - 数字人供应商,支持传入以下值: - `sensetime`:商汤数字人 - `spatius`:Spatius 数字人 - `properties.avatar.params` (object) - 指定数字人供应商的配置参数。 > [!NOTE] > 你可以参考调用示例中不同数字人供应商的参数填写样例。 - `properties.turn_detection` (object) - 对话轮次检测设置,用于控制语音活动检测和对话轮次判定逻辑。 > [!NOTE] > 自 v2.6 起,`turn_detection` 仅负责开始说话(SoS)和结束说话(EoS)的检测。关键词打断和关闭打断后的处理策略已迁移至顶级 `interruption` 字段。 - `properties.turn_detection.mode` (string) - 对话轮次检测模式,当前支持以下值: - `"default"`:(默认)默认模式,使用标准的对话轮次检测配置。 - Allowed: `default` - Default: `default` - `properties.turn_detection.config` (object) - 对话轮次检测详细配置。 - `properties.turn_detection.config.speech_threshold` (number) - 语音识别灵敏度,取值范围为 (0.0, 1.0)。决定音频信号中何种程度的声音被视为"语音活动"。较低的值会使智能体更容易检测到语音,较高的值则可能忽略微弱声音。 - Default: `0.5` - Format: `float` - `properties.turn_detection.config.start_of_speech` (object) - 对话开始 (Start of Speech, SoS) 检测配置,用于判定用户何时开始说话。 - `properties.turn_detection.config.start_of_speech.mode` (string) - 对话开始检测模式,支持以下值: - `"vad"`:(默认)基于 VAD(语音活动检测)触发,使用音频信号检测。 - `"manual"`:手动 SoS 模式。关闭服务端自动 SoS 检测,由客户端通过 RTM 消息显式声明用户开始说话。 - `"keywords"`:已废弃,请改用 `properties.interruption.mode = "keywords"` 配置关键词打断。 - `"disabled"`:已废弃,请改用 `properties.interruption.enable = false` 配合 `properties.interruption.disabled_config.strategy` 配置关闭打断后的处理策略。 > [!CAUTION] > 使用 `"manual"` 时: > - 必须同时开启 `advanced_features.enable_rtm = true`。 > - 必须同时设置 `parameters.data_channel = "rtm"`。 > - 不支持传入 `manual_config`;该模式下无需公开配置项。 - `properties.turn_detection.config.start_of_speech.{mode}_config` (object, deprecated) - 对话开始检测配置参数。不同检测模式下该参数结构和支持的字段不同。 你需要根据 `mode` 传入对应的配置字段。例如 `mode` 为 `"vad"` 时,需传入 `vad_config`。不可同时传入多个模式配置。 当 `mode` 为 `"manual"` 时,无需传入任何 `manual_config`,且公开接口不支持该字段。 - `properties.turn_detection.config.start_of_speech.{mode}_config.interrupt_duration_ms` (integer) - 智能体空闲或倾听时的人声持续阈值 (ms),取值范围为 [120, 1200]。持续检测到人声信号的最小时间长度,避免误打断。 - Default: `160` - `properties.turn_detection.config.start_of_speech.{mode}_config.speaking_interrupt_duration_ms` (integer) - 智能体说话时的人声持续阈值 (ms),取值范围为 [120, 1200]。持续检测到人声信号的最小时间长度,避免误打断。通常设置得比 `interrupt_duration_ms` 更长,以避免智能体说话时被较短人声误打断。 - Default: `160` - `properties.turn_detection.config.start_of_speech.{mode}_config.prefix_padding_ms` (integer) - 前缀填充阈值 (ms),取值范围为 [0, 5000]。开始新的语音片段所需的最短语音持续时间,避免非常短的声音触发语音活动检测。 - Default: `800` - `properties.turn_detection.config.end_of_speech` (object) - 对话结束 (End of Speech, EoS) 检测配置,用于判定用户何时结束说话。 - `properties.turn_detection.config.end_of_speech.mode` (string) - 对话结束检测模式,支持以下值: - `"vad"`:(默认)基于 VAD(语音活动检测)触发,检测静音持续时间。 - `"semantic"`:优雅打断,基于语义触发,使用语义理解模块判定用户是否结束说话还是短暂停顿。该模式目前仅支持识别中文和英文文本。 - `"manual"`:手动 EoS 模式。关闭服务端自动 EoS 判停,由客户端通过 RTM 消息显式声明用户结束说话。 > [!CAUTION] > 使用 `"manual"` 时: > - 必须同时开启 `advanced_features.enable_rtm = true`。 > - 必须同时设置 `parameters.data_channel = "rtm"`。 > - 不支持传入 `manual_config`;该模式下无需公开配置项。 - `properties.turn_detection.config.end_of_speech.{mode}_config` (object) - 对话结束检测配置参数。不同检测模式下该参数结构和支持的字段不同。 你需要根据 `mode` 传入对应的配置字段。例如 `mode` 为 `"vad"` 时,需传入 `vad_config`。不可同时传入多个模式配置。 当 `mode` 为 `"manual"` 时,无需传入任何 `manual_config`,且公开接口不支持该字段。 - `properties.turn_detection.config.end_of_speech.{mode}_config.silence_duration_ms` (integer) - 静音持续阈值 (ms),取值范围为 [120, 2000]。语音结束时的最短静音持续时间,确保短暂的停顿不会过早结束语音片段。 - Default: `480` - `properties.turn_detection.config.end_of_speech.{mode}_config.max_wait_ms` (integer) - 最大等待时间 (ms),取值范围为 [500, 10000],传入 `-1` 表示永远等待。等待语义判定的最长时间,超时后将基于当前状态判定对话是否结束。 - Default: `3000` - `properties.turn_detection.config.end_of_speech.{mode}_config.pause_state_enabled` (boolean) - 是否判定用户有暂停对话的意图: - `true`:(默认)智能体会根据语义判断用户是否想要暂停对话。例如,当用户输入以“等一下”、“稍等”等词结束时,智能体可根据语义判断用户有暂停对话的意图并等待用户后续输入,而不是判断用户输入结束并直接发送给 LLM。 - `false`:智能体不判定用户是否想要暂停对话。 - Default: `true` - `properties.interruption` (object) - 智能打断控制配置,用于统一管理智能体被用户打断的行为策略。 - `properties.interruption.enable` (boolean) - 是否开启智能体打断功能: - `true`:(默认)开启。 - `false`:关闭。关闭后,智能体不会被中途打断。 - Default: `true` - `properties.interruption.mode` (string) - 打断触发方式,支持以下值: - `"start_of_speech"`:(默认)用户开始说话时触发打断。 - `"keywords"`:用户说出指定关键词时触发打断,在 `keywords_config` 字段中配置触发关键词。 - Default: `start_of_speech` - `properties.interruption.keywords_config` (object) - 基于关键词触发打断的配置。仅在 `mode = "keywords"` 时生效。 - `properties.interruption.keywords_config.trigger_keywords` (array) - 触发打断的关键词列表。最多支持设置 128 个关键词。 - `properties.interruption.keywords_config.trigger_keywords.items` (string) - `properties.interruption.disabled_config` (object) - 关闭打断功能后的处理策略。仅在 `interruption.enable` 为 `false` 时生效。 - `properties.interruption.disabled_config.strategy` (string) - 关闭打断功能后的处理策略,支持以下值: - `"append"`:追加模式,人声不打断智能体。智能体会在当前交互结束后处理刚才收到的人声请求。 - `"ignore"`:忽略模式,智能体忽略人声请求。如果智能体正在说话或思考中途收到人声,智能体会直接忽略并丢弃人声请求,不存入上下文。 - `properties.sal` (object) - 选择性注意力锁定(Selective Attention Locking, SAL)配置。 > [!NOTE] > 该功能目前处于 Beta 阶段。 - `properties.sal.sal_mode` (string) - 选择性注意力锁定模式,支持以下选项: - `"locking"`:(默认)主讲人锁定模式。智能体锁定主讲人,屏蔽 95% 的环境人声、噪声。该模式可通过两种方式启用: - 无感识别:用户在对话初期大声、清晰地说话,智能体即可自动将用户识别为主讲人。 - 预注册:创建智能体时,通过 `sample_urls` 字段预注册一名主讲人的声纹 URL,智能体将根据预注册的声纹 URL 锁定主讲人。 - `"recognition"`:声纹识别模式。你可以通过 `sample_urls` 字段预注册声纹 URL,目前仅支持单声纹注册。智能体将识别不同的说话人并抑制其他背景人声和环境噪音。识别到的说话人身份会通过 `metadata` 字段里的 `vpids` 字段标识并发送给 LLM,你需要将 `llm.vendor` 设置为 `"custom"`,并参考[自定义大模型](/zh-CN/ai/build/custom-model-integration/custom-llm)了解如何让 LLM 处理说话人信息。 - Default: `locking` - `properties.sal.sample_urls` (object) - 注册声纹 URL,为键值对形式,键为注册的声纹名称,值为对应说话者的声纹 URL 下载地址。 > [!CAUTION] > - 传入的声纹名称不可设置为 `"unknown"`,这是一个保留关键字,用于标识未知说话人。 > - 对于注册的声纹,需满足以下条件: > - 数量: 每个任务请求的注册声纹URL数量,目前仅支持单声纹,数量为 1 个。 > - 大小: 单个声纹文件不得超过 2 MB。 > - 时长:时长为 10 到 15 秒, 其中有效音频不小于 8 秒(不能有太多静音段)。 > - 格式: 必须为 16k 采样率、16bit 位深、单声道的 PCM 音频文件,文件名后缀必须为 `.pcm`。 - `properties.labels` (object) - 自定义标签,键值对形式,键为标签名,值为标签值。用于让智能体携带自定义业务信息。 这些自定义信息会与智能体绑定,并在对话式 AI 引擎所有类型消息通知回调的 `payload` 字段中返回,可用于实现自定义业务逻辑,例如标记活动 ID、客户分组、业务场景等。 - `properties.rtc` (object) - RTC 媒体内容加密配置。 - `properties.rtc.encryption_key` (string) - 字符串类型的加密密钥,长度不受限制。声网建议使用 32 字节的密钥。 > [!CAUTION] > 如果未设置加密密钥或将其设置为空,则无法使用内置加密。 - `properties.rtc.encryption_salt` (string) - 用于加密的盐值,Base64 编码的字符串,解码后长度为 32 字节。 > [!CAUTION] > 该参数仅在 `encryption_mode` 设为 `7`(AES_128_GCM2)或 `8`(AES_256_GCM2)时生效。在此情况下,请确保该参数不为空。 - `properties.rtc.encryption_mode` (integer) - 内置加密模式,支持以下值: - `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`)。 > [!TIP] > 声网建议使用 `7`(AES_128_GCM2)或 `8`(AES_256_GCM2)模式,这两种模式支持使用加密盐以提升安全性。 - `properties.filler_words` (object) - 承接词功能 (Beta) 配置,用于在 LLM 响应等待时播报承接词,缓解用户等待焦虑,提升对话流畅度。 承接词播报遵循以下规则: - **播报顺序**:当多个承接词或 LLM 响应等待播报时,按照文本到达的先后顺序进行播报。 - **打断控制**:继承全局配置中的打断模式设置 (`turn_detection.config`)。 - `properties.filler_words.enable` (boolean) - 是否启用承接词功能: - `true`:启用。 - `false`:(默认)不启用。 - Default: `false` - `properties.filler_words.trigger` (object) - 承接词触发配置,定义何时触发承接词播报。 - `properties.filler_words.trigger.fixed_time_config` (object) - 固定时间触发配置。省略时使用默认的 `1500` ms 等待阈值。 - `properties.filler_words.trigger.fixed_time_config.response_wait_ms` (integer) - LLM 响应等待阈值 (ms),取值范围为 [100, 10000]。当 LLM 处于等待状态(例如等待 RAG 检索结果、工具调用结果)的持续时间达到该阈值且未生成响应内容时,触发承接词播报。 - Default: `1500` - `properties.filler_words.content` (object) - 承接词内容配置,定义承接词的来源和选择规则。 - `properties.filler_words.content.mode` (string) - 承接词内容模式,支持以下值: - `"static"`:(默认)静态承接词。使用预定义的承接词列表。 - `"generated"`:生成承接词。由声网托管的生成能力根据当前上下文生成一句承接词;当生成结果不可用时,使用 `static_config` 中的静态承接词兜底。 - `properties.filler_words.content.static_config` (object) - 静态承接词配置。启用承接词时必需配置。`mode` 为 `"generated"` 时,该配置用于生成承接词不可用时的静态兜底。 - `properties.filler_words.content.static_config.phrases` (array) - 承接词短语列表。 - 支持 1 到 100 个非空字符串。 - 每个短语最多支持 20 个单词(拉丁文字)或 20 个字符(中文及其他非拉丁文字)。 - Min items: `1` - Max items: `100` - `properties.filler_words.content.static_config.phrases.items` (string) - `properties.filler_words.content.static_config.selection_rule` (string) - 承接词选择规则,支持以下值: - `"shuffle"`:随机打乱。在所有承接词都被使用完一轮前,已使用的承接词不会重复播报;只有所有承接词播报完后,才会重新随机打乱并开始新的一轮。 - `"round_robin"`:轮询。从承接词列表中顺序选取并播报,所有承接词播报完一轮后,开始新的循环播报。 - Allowed: `shuffle` | `round_robin` - Default: `shuffle` - `properties.filler_words.content.generated_config` (object) - 生成承接词配置。仅当 `mode` 为 `"generated"` 时生效。 - `properties.filler_words.content.generated_config.prompt` (string) - 生成承接词的 Prompt 指令。该字段为可选非空字符串;如果传入该字段,该 Prompt 会完整替换声网默认 Prompt,并对相同的对话上下文窗口生效。 - `properties.filler_words.content.generated_config.context_message_limit` (integer) - 动态承接词使用的对话消息数量上限,包含触发当前回合的用户消息。 - `1`:(默认)仅使用当前用户消息。 - `2` 到 `6`:除当前用户消息外,还会按时间顺序使用符合上限的近期用户和智能体文本消息。 - Default: `1` - Range: `[1, 6]` - `properties.filler_words.content.generated_config.history_character_limit` (integer) - 动态承接词使用的历史消息文本字符数上限,仅统计历史消息的 Unicode code points,不包含当前用户消息。 - `0`:不限制历史消息文本字符数,但完整输入仍受托管模型的有效输入容量限制。 - `1` 到 `10000`:超过上限时,从最旧的历史消息开始整条移除,不截断消息。 - Default: `1000` - Range: `[0, 10000]` - `properties.parameters` (object) - 智能体参数配置。 - `properties.parameters.silence_config` (object) - 智能体静默设置。 - `properties.parameters.silence_config.timeout_ms` (integer) - 智能体最大静默时间 (ms),取值范围为 [0,60000]。智能体创建成功,且用户加入频道后,智能体不处于倾听、思考或说话状态的持续时间称为智能体静默时间。静默时间达到设定值后,智能体将播报静默提示消息。该功能可用于在用户不活跃时让智能体提醒用户。 - 设置为 `0`(默认值):表示不启用该功能。 - 设置为 `(0,60000]` 时,必须同时设置 `content` 才能正常播报静默提示,否则设置无效。 - `properties.parameters.silence_config.action` (string) - 静默时间达到设定值后,智能体采取的行为,可设为以下值: - `"speak"`:(默认)使用 TTS 模块播报静默提示内容 (`content`)。 - `"think"`:将静默提示内容 (`content`) 追加在上下文的最后,并传递给 LLM。 - `properties.parameters.silence_config.content` (string) - 静默提示消息的内容。设置的内容会根据 `action` 中的设置以不同的方式使用。 - `properties.parameters.farewell_config` (object) - 智能体优雅挂断设置。 - `properties.parameters.farewell_config.graceful_enabled` (boolean) - 是否启用优雅退出(Graceful Leave)功能: - `true`:启用。开启后,调用 [POST 停止对话式智能体](/zh-CN/api-reference/api-ref/conversational-ai/leave)接口,让智能体退出频道时,会确保智能体处于静默状态(`IDLE`)后再离开频道。 - `false`:(默认)不启用。 - Default: `false` - `properties.parameters.farewell_config.graceful_timeout_seconds` (integer) - 优雅退出超时时间 (s),表示在退出频道前等待智能体进入静默状态(`IDLE`)的最长时间,超出该时间后,即便智能体不处于静默状态,也会立即退出频道。该字段仅在 `graceful_enabled` 为 `true` 时生效,取值范围为 [0,120]。 - Default: `30` - `properties.parameters.data_channel` (string) - 智能体数据传输通道,可选以下值: - `rtm`:使用 RTM 传输。该配置仅在 `advanced_features.enable_rtm` 为 `true` 时生效。 - `datastream`:(默认)使用 RTC 的 [`DataStream`](/zh-CN/api-reference/rtc/android/metadata/datastream#callback_irtcengineeventhandler_onstreammessage) 传输。 > [!CAUTION] > 如果 `turn_detection.config.start_of_speech.mode` 或 `turn_detection.config.end_of_speech.mode` 为 `manual`,则必须同时开启 `advanced_features.enable_rtm = true`,并将该字段设为 `rtm`。 - `properties.parameters.enable_metrics` (boolean) - 是否接收智能体性能数据: - `true`:接收。 - `false`:(默认)不接收。 该配置仅在 `advanced_features.enable_rtm` 为 `true` 时生效。你可以参考[监听智能体事件](/zh-CN/ai/build/handle-runtime-events/event-notifications)了解如何使用客户端组件接收智能体性能数据,或参考[接收 Webhook 事件](/zh-CN/ai/build/handle-runtime-events/webhooks)了解如何使用 Webhook 接收智能体性能数据。 - Default: `false` - `properties.parameters.enable_error_message` (boolean) - 是否接收智能体错误事件: - `true`:接收。 - `false`:(默认)不接收。 该配置仅在 `advanced_features.enable_rtm` 为 `true` 时生效。你可以参考[监听智能体事件](/zh-CN/ai/build/handle-runtime-events/event-notifications)了解如何使用客户端组件接收智能体错误事件。 - Default: `false` - `properties.parameters.opt_out` (boolean) - 是否关闭当前会话的数据留存: - `false`:(默认)不关闭。 - `true`:关闭会话数据留存。关闭后将无法依托历史内容开展故障排查、效果复盘与智能体优化。 > [!CAUTION] > 为保障服务运行、智能体迭代调优与故障排查,默认在最短必要周期内临时留存会话交互文本、音频。若您的业务对数据存储有严格的安全或合规要求,建议启用该字段,关闭当前会话的数据留存。 - Default: `false` ### Request body example ```json { "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 } } } } } ``` ## Responses ### 200 - 若返回的状态码为 `200` 则表示请求成功。响应包体中包含本次请求的结果。 - 若返回的状态码不为 `200` 则表示请求失败。响应包体中包含错误的类别和描述,你可以参考[响应状态码](/zh-CN/api-reference/conversational-ai/rest-api/api/response-code)了解可能的原因。 - `agent_id` (string) - 智能体唯一标识。 - `create_ts` (integer) - 智能体创建时间戳。 - `status` (string) - 智能体运行状态: - `IDLE` (0):空闲状态的智能体。 - `STARTING` (1):正在启动的智能体。 - `RUNNING` (2):正在运行的智能体。 - `STOPPING` (3):正在停止的智能体。 - `STOPPED` (4):已完成退出的智能体。 - `FAILED` (6):执行失败的智能体。 ## Response examples ### 200 ```json { "agent_id": "1NT29X10YHxxxxxWJOXLYHNYB", "create_ts": 1737111452, "status": "RUNNING" } ```