# 创建对话式智能体 (/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。
    - `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
- `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.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.<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 中的变量值只能是字符串、数字或布尔值。

> [!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.<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 字节。
            - Min length: `1`
            - Max length: `2048`
            - Pattern: `^https://`
          - `properties.llm.tools.items.server.headers` (object) - 自定义工具请求携带的自定义 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。
          - `properties.llm.tools.items.server.body` (unknown) - 自定义工具的 HTTP 请求体，仅支持用于 `POST`。为 `GET` 配置该字段会导致请求校验失败。

请求体支持 object、array、string、number、boolean 和 `null`，并可使用任意层级的 JSON 结构。请求体中的叶子值可以是：
- JSON 常量。
- 完整的 `{{args.<name>}}` 占位符。
- 完整的 `{{template_variables.<name>}}` 占位符。
- 完整的 `{{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"
}
```