> This is a page from the ElevenLabs documentation. For a complete page index, fetch https://elevenlabs.io/docs/llms.txt. For the full documentation in a single file, fetch https://elevenlabs.io/docs/llms-full.txt.

# 创建新分支

POST https://api.elevenlabs.io/v1/convai/agents/{agent_id}/branches
Content-Type: application/json

从任意分支的指定版本创建新分支

Reference: https://elevenlabs.io/docs/eleven-agents/api-reference/agents/branches/create

## Servers

- `https://api.elevenlabs.io` (Production, default)
- `https://api.us.elevenlabs.io` (Production US)
- `https://api.eu.residency.elevenlabs.io` (Production EU)
- `https://api.in.residency.elevenlabs.io` (Production India)
- `https://api.sg.residency.elevenlabs.io` (Production Singapore)

## Request

### Path parameters

- `agent_id` (string, required) — 智能体 ID。创建智能体时返回此值。

### Body (application/json)

This endpoint expects an object.

- `parent_version_id` (string, required) — 要创建分支的源版本 ID
- `name` (string, required) — 分支名称。在该智能体内唯一。
- `description` (string, required) — 分支说明
- `conversation_config` (map from string to any, optional) — Changes to apply to conversation config
- `platform_settings` (map from string to any, optional) — Changes to apply to platform settings
- `workflow` (AgentWorkflowRequestModel, optional) — 更新后的 workflow 定义。
- `include_draft` (boolean, optional, default: false) — 设为 true 时，新分支使用调用方的流程草稿集，而非分支顶端版本。要求 parent_version_id 为分支顶端版本。

## Response

### 200

成功响应

- `created_branch_id` (string, required) — 已创建分支的 ID
- `created_version_id` (string, required) — 已创建分支上首个版本的 ID

## Errors

### 422 Branches Create Request Unprocessable Entity Error

验证错误。

- `detail` (list of ValidationError, optional)

## Types

### AgentWorkflowRequestModel

- `edges` (map from string to WorkflowEdgeModelInput, optional)
- `nodes` (map from string to AgentWorkflowRequestModelNodesValue, optional)
- `prevent_subagent_loops` (boolean, optional, default: false) — 是否防止 workflow 执行中出现循环。

### ValidationError

- `loc` (list of ValidationErrorLocItem, required)
- `msg` (string, required)
- `type` (string, required)

### WorkflowEdgeModelInput

- `source` (string, required) — 源节点 ID。
- `target` (string, required) — 目标节点 ID。
- `forward_condition` (WorkflowEdgeModelInputForwardCondition, optional) — Condition that must be met for the edge to be traversed in the forward direction (source to target).
- `backward_condition` (WorkflowEdgeModelInputBackwardCondition, optional) — Condition that must be met for the edge to be traversed in the backward direction (target to source).

### AgentWorkflowRequestModelNodesValue

- `type`: `end`
  - `edge_order` (list of string, optional) — 出边的 ID，按应评估的顺序排列。
  - `outcome` (enum, optional, default: success) — 到达此结束节点时，是以成功还是失败结束对话。
    - Allowed values: `success`, `failure`
  - `position` (PositionInput, optional) — 节点在 workflow 中的位置。
- `type`: `override_agent`
  - `label` (string, required) — 整个 UI 中使用的人类可读节点标签。
  - `additional_knowledge_base` (list of KnowledgeBaseLocator, optional) — 子智能体可访问的其他知识库文档。这些文档会与主智能体的文档一同使用。
  - `additional_prompt` (string, optional) — 此子智能体的具体目标。该目标会添加到系统提示词中，可用于进一步优化智能体在此特定上下文中的行为。
  - `additional_tool_ids` (list of string, optional) — 子智能体可访问的其他工具 ID。将与主智能体的工具一同使用。
  - `conversation_config` (ConversationalConfigApiModelWorkflowOverrideInput, optional) — Configuration overrides applied while the subagent is conducting the conversation.
  - `edge_order` (list of string, optional) — 出边的 ID，按应评估的顺序排列。
  - `entry_behavior` (enum, optional, default: auto) — 决定此节点进入后应立即生成响应，还是等待用户输入。设为 "auto" 时，将根据前一节点的类型决定行为：在 "say" 和 "start" 节点后使用 "wait_for_user"，其他情况使用 "generate_immediately"。
    - Allowed values: `generate_immediately`, `wait_for_user`, `auto`
  - `position` (PositionInput, optional) — 节点在 workflow 中的位置。
- `type`: `phone_number`
  - `transfer_destination` (WorkflowPhoneNumberNodeModelInputTransferDestination, required)
  - `custom_sip_headers` (list of WorkflowPhoneNumberNodeModelInputCustomSipHeadersItem, optional) — 转接通话时包含的自定义 SIP 请求头。每个请求头可以是静态值或动态变量引用。
  - `edge_order` (list of string, optional) — 出边的 ID，按应评估的顺序排列。
  - `position` (PositionInput, optional) — 节点在 workflow 中的位置。
  - `post_dial_digits` (WorkflowPhoneNumberNodeModelInputPostDialDigits, optional) — 通话接通后发送的 DTMF 按键（例如，分机号使用 'ww1234'）。可以是静态值或动态变量引用。使用 'w' 表示暂停 0.5 秒。仅支持 Twilio 转接。
  - `sip_refer_play_dialtone` (boolean, optional, default: true) — 设为 True 时，在 SIP REFER 转接完成期间，原始通话线路会播放回铃音。该音调会通过 RTP 传输给执行 REFER 的 SIP 对端，因此如果接收系统（如 SBC 或呼叫中心）不应听到该音调，请禁用此项。禁用后，呼叫方在转接完成前将听到静音。仅适用于 SIP REFER 转接。
  - `transfer_type` (enum, optional, default: conference)
    - Allowed values: `blind`, `conference`, `sip_refer`
  - `uui` (UuiTransferConfig, optional) — 附加到 SIP REFER 转接的用户间信息（User-to-User Information，RFC 7433）。可在转接过程中携带 CRM 标识符或升级原因等通话上下文。
- `type`: `standalone_agent`
  - `agent_id` (string, optional) — 要将对话转接至的智能体 ID。None 表示在当前智能体内转接。
  - `branch_id` (string, optional) — 目标智能体的可选分支 ID。设为 None 时，沿用目标智能体的流量部署；若设置了 node_id，则使用其主分支。
  - `delay_ms` (integer, optional, default: 0) — Artificial delay in milliseconds applied before transferring the conversation.
  - `edge_order` (list of string, optional) — 出边的 ID，按应评估的顺序排列。
  - `enable_transferred_agent_first_message` (boolean, optional, default: false) — 是否允许转接后的智能体在转接后发送其配置的首条消息。
  - `node_id` (string, optional) — 目标智能体 workflow 中的可选目标节点 ID。设置后，转接将从该节点开始，而非默认入口节点。
  - `position` (PositionInput, optional) — 节点在 workflow 中的位置。
  - `preserve_client_tts_overrides` (boolean, optional, default: false) — 定义是否将 TTS 客户端覆盖设置沿用至被转接的智能体。
  - `preserve_voice_settings` (boolean, optional, default: false) — 定义是否将基础音色、TTS 模型和音色设置沿用至被转接的智能体。
  - `transfer_message` (string, optional) — 开始转接前发送给用户的可选消息。
- `type`: `start`
  - `edge_order` (list of string, optional) — 出边的 ID，按应评估的顺序排列。
  - `position` (PositionInput, optional) — 节点在 workflow 中的位置。
- `type`: `tool`
  - `edge_order` (list of string, optional) — 出边的 ID，按应评估的顺序排列。
  - `position` (PositionInput, optional) — 节点在 workflow 中的位置。
  - `tools` (list of WorkflowToolLocator, optional) — 要并行执行的工具列表。所有工具均成功执行时，整个节点才视为成功。
- `type`: `say`
  - `label` (string, required) — 整个 UI 中使用的人类可读节点标签。
  - `message` (WorkflowSayNodeModelInputMessage, required) — 此节点朗读的消息。使用 `literal` 指定精确文本，或使用 `prompt` 让 LLM 根据描述生成消息。
  - `additional_knowledge_base` (list of KnowledgeBaseLocator, optional) — 除智能体文档外，此节点生成消息时可供 LLM 使用的知识库文档。
  - `additional_prompt` (string, optional) — 为与子智能体节点保持一致而接受此项，但不会使用。请在 `message.prompt` 中描述消息，或通过 `conversation_config.agent.prompt.prompt` 替换系统提示词。
  - `additional_tool_ids` (list of string, optional) — 为与子智能体节点保持一致而接受此项，但不会使用。say 节点无法调用工具。
  - `conversation_config` (ConversationalConfigApiModelWorkflowOverrideInput, optional) — 此节点说话时应用的配置覆盖项，例如音色；对于提示词消息，还包括 LLM 和系统提示词。
  - `edge_order` (list of string, optional) — 出边的 ID，按应评估的顺序排列。
  - `position` (PositionInput, optional) — 节点在 workflow 中的位置。
  - `wait_for_speech_completion` (boolean, optional, default: false) — 设为 true 时，只有在消息完整朗读后，workflow 才会进入下一个节点。
  - `wait_for_user_response` (boolean, optional, default: false) — 设为 true 时，节点会先朗读消息，再等待用户回复，然后评估出边，以便根据回复进行分支。如果用户保持沉默，workflow 会在轮次超时后继续。
- `type`: `update_state`
  - `label` (string, required) — 整个 UI 中使用的人类可读节点标签。
  - `updates` (list of WorkflowStateUpdateInput, required) — workflow 到达此节点时应用的状态更新。每个节点最多接受 50 项更新。
  - `edge_order` (list of string, optional) — 出边的 ID，按应评估的顺序排列。
  - `position` (PositionInput, optional) — 节点在 workflow 中的位置。

### ValidationErrorLocItem

- string
- integer

### WorkflowEdgeModelInputForwardCondition

- `type`: `expression`
  - `expression` (AstNodeInput, required) — 要评估的表达式。
  - `label` (string, optional) — 可选的易读条件标签，供整个 UI 使用。
- `type`: `llm`
  - `condition` (string, required) — Condition to evaluate
  - `label` (string, optional) — 可选的易读条件标签，供整个 UI 使用。
- `type`: `result`
  - `successful` (boolean, required) — 先前执行的工具节点中所有工具是否均执行成功。
  - `label` (string, optional) — 可选的易读条件标签，供整个 UI 使用。
- `type`: `unconditional`
  - `label` (string, optional) — 可选的易读条件标签，供整个 UI 使用。

### WorkflowEdgeModelInputBackwardCondition

- `type`: `expression`
  - `expression` (AstNodeInput, required) — 要评估的表达式。
  - `label` (string, optional) — 可选的易读条件标签，供整个 UI 使用。
- `type`: `llm`
  - `condition` (string, required) — Condition to evaluate
  - `label` (string, optional) — 可选的易读条件标签，供整个 UI 使用。
- `type`: `result`
  - `successful` (boolean, required) — 先前执行的工具节点中所有工具是否均执行成功。
  - `label` (string, optional) — 可选的易读条件标签，供整个 UI 使用。
- `type`: `unconditional`
  - `label` (string, optional) — 可选的易读条件标签，供整个 UI 使用。

### PositionInput

- `x` (double, optional, default: 0)
- `y` (double, optional, default: 0)

### KnowledgeBaseLocator

- `type` (enum, required) — 知识库类型
  - Allowed values: `file`, `url`, `text`, `folder`
- `name` (string, required) — 知识库名称
- `id` (string, required) — 知识库的 ID
- `usage_mode` (enum, optional, default: auto) — 知识库使用模式
  - Allowed values: `prompt`, `auto`

### ConversationalConfigApiModelWorkflowOverrideInput

- `asr` (AsrConversationalConfigWorkflowOverride, optional) — Configuration for conversational transcription
- `turn` (TurnConfigWorkflowOverride, optional) — Configuration for turn detection
- `tts` (TtsConversationalConfigWorkflowOverrideInput, optional) — Configuration for conversational text to speech
- `conversation` (ConversationConfigWorkflowOverrideInput, optional) — Configuration for conversational events
- `language_presets` (map from string to LanguagePresetInput, optional) — 对话语言预设
- `vad` (VadConfigWorkflowOverride, optional) — Configuration for voice activity detection
- `agent` (AgentConfigApiModelWorkflowOverrideInput, optional) — 智能体专属配置

### WorkflowPhoneNumberNodeModelInputTransferDestination

- `type`: `phone`
  - `phone_number` (string, required)
- `type`: `phone_dynamic_variable`
  - `phone_number` (string, required)
- `type`: `sip_uri`
  - `sip_uri` (string, required)
- `type`: `sip_uri_dynamic_variable`
  - `sip_uri` (string, required)

### WorkflowPhoneNumberNodeModelInputCustomSipHeadersItem

- `type`: `dynamic`
  - `key` (string, required) — SIP 请求头名称（例如 'X-Customer-ID'）
  - `value` (string, required) — 要解析的动态变量名称
- `type`: `static`
  - `key` (string, required) — SIP 请求头名称（例如 'X-Customer-ID'）
  - `value` (string, required) — 标头值

### WorkflowPhoneNumberNodeModelInputPostDialDigits

- `type`: `dynamic`
  - `value` (string, required) — 要解析的动态变量名称
- `type`: `static`
  - `value` (string, required) — 通话接通后发送的 DTMF 按键（例如，分机号使用 'ww1234'）

### UuiTransferConfig

用于 SIP REFER 转接的用户间信息（User-to-User Information）封装（RFC 7433）。 出站载荷采用十六进制编码（RFC 7433 唯一规定的编码）。协议判别维度允许通过配置表达各平台格式（Talkdesk、Genesys 等），而非分散使用转接标记。还可在此添加更多维度（ASCII 编码、标头名称、用途/内容参数），无需修改转接模型。

- `data` (string, required) — 在 SIP REFER 转接中发送的 UUI 载荷。支持内联动态变量，并会在转接时进行十六进制编码。
- `protocol_discriminator` (string, optional) — 可选的单八位组协议区分符（2 个十六进制数字，例如 '00'）。Genesys Cloud 等平台需要此项，否则会剥离有效负载的第一个八位组。对于需要纯十六进制有效负载的 Talkdesk 等平台，请留空。
- `protocol_discriminator_mode` (enum, optional, default: prefix) — 如何附加 protocol\_discriminator。'prefix' 会将该字节前置到十六进制载荷（User-to-User=XX\<hex>;encoding=hex）；'pd\_parameter' 会将其作为单独参数发送（User-to-User=\<hex>;pd=XX;encoding=hex）。未设置 protocol\_discriminator 时将忽略此项。
  - Allowed values: `prefix`, `pd_parameter`

### WorkflowToolLocator

- `tool_id` (string, required)
- `schema_overrides` (map from string to WorkflowToolLocatorSchemaOverridesValue, optional) — 在工具自身配置基础上应用的每节点参数覆盖选项。键为带点的参数路径（webhook 工具的键以前缀 path_params./query_params./request_body. 开头）。其优先级高于工具自身已定义的任何覆盖选项。

### WorkflowSayNodeModelInputMessage

此节点朗读的消息。使用 `literal` 指定精确文本，或使用 `prompt` 让 LLM 根据描述生成消息。

- `type`: `literal`
  - `text` (string, required) — 智能体朗读的精确文本。支持 `{{variable_name}}` 动态变量占位符。
  - `text_translations` (map from string to TranslatedString, optional) — `text` 的翻译，以语言代码为键。当对话语言存在对应条目时，将朗读其值而非 `text`。
- `type`: `prompt`
  - `prompt` (string, required) — LLM 应生成消息的描述。此节点处于活动状态时，会附加到智能体的系统提示词中。

### WorkflowStateUpdateInput

- `variable_name` (string, required) — 要赋值的动态变量名称。
- `expression` (AstNodeInput, required) — 其结果将赋给变量的表达式。可组合常量、其他动态变量、LLM 提取的值和运算符。
- `type` ("dynamic_variable", optional)
- `required` (boolean, optional, default: true) — 设为 false 时，LLM 可能省略此更新所依赖的值。此更新将被跳过，变量保留当前值。

### AstNodeInput

- `type`: `add_operator`
  - `left` (AstNodeInput, required) — 二元运算符的左操作数。
  - `right` (AstNodeInput, required) — 二元运算符的右操作数。
- `type`: `and_operator`
  - `children` (list of AstNodeInput, required) — Child nodes of the logical operator.
- `type`: `boolean_literal`
  - `value` (boolean, required) — 此字面量的值。
- `type`: `conditional_operator`
  - `condition` (AstNodeInput, required) — Condition deciding which expression should be selected.
  - `falseExpression` (AstNodeInput, required) — 条件为 false 时选择的表达式。
  - `trueExpression` (AstNodeInput, required) — 条件为 true 时选择的表达式。
- `type`: `div_operator`
  - `left` (AstNodeInput, required) — 二元运算符的左操作数。
  - `right` (AstNodeInput, required) — 二元运算符的右操作数。
- `type`: `dynamic_variable`
  - `name` (string, required) — 动态变量名称。
- `type`: `eq_operator`
  - `left` (AstNodeInput, required) — 二元运算符的左操作数。
  - `right` (AstNodeInput, required) — 二元运算符的右操作数。
- `type`: `gt_operator`
  - `left` (AstNodeInput, required) — 二元运算符的左操作数。
  - `right` (AstNodeInput, required) — 二元运算符的右操作数。
- `type`: `gte_operator`
  - `left` (AstNodeInput, required) — 二元运算符的左操作数。
  - `right` (AstNodeInput, required) — 二元运算符的右操作数。
- `type`: `llm`
  - `value_schema` (LlmLiteralJsonSchemaProperty, optional) — 描述 LLM 应提取值的 JSON Schema。
  - `prompt` (string, optional, deprecated) — 用于评估为布尔值的提示词。已弃用，请改用布尔模式。
- `type`: `lt_operator`
  - `left` (AstNodeInput, required) — 二元运算符的左操作数。
  - `right` (AstNodeInput, required) — 二元运算符的右操作数。
- `type`: `lte_operator`
  - `left` (AstNodeInput, required) — 二元运算符的左操作数。
  - `right` (AstNodeInput, required) — 二元运算符的右操作数。
- `type`: `mul_operator`
  - `left` (AstNodeInput, required) — 二元运算符的左操作数。
  - `right` (AstNodeInput, required) — 二元运算符的右操作数。
- `type`: `neq_operator`
  - `left` (AstNodeInput, required) — 二元运算符的左操作数。
  - `right` (AstNodeInput, required) — 二元运算符的右操作数。
- `type`: `null_literal`
- `type`: `number_literal`
  - `value` (AstNumberNodeInputValue, required) — 此字面量的值。
- `type`: `or_operator`
  - `children` (list of AstNodeInput, required) — Child nodes of the logical operator.
- `type`: `string_literal`
  - `value` (string, required) — 此字面量的值。
- `type`: `sub_operator`
  - `left` (AstNodeInput, required) — 二元运算符的左操作数。
  - `right` (AstNodeInput, required) — 二元运算符的右操作数。

### AsrConversationalConfigWorkflowOverride

- `quality` ("high", optional) — 转录质量
- `provider` (enum, optional, default: scribe_realtime) — 转录服务提供商
  - Allowed values: `elevenlabs`, `scribe_realtime`, `scribe_v2_turbo`
- `user_input_audio_format` (enum, optional, default: pcm_16000) — 要转录音频的格式
  - Allowed values: `pcm_8000`, `pcm_16000`, `pcm_22050`, `pcm_24000`, `pcm_44100`, `pcm_48000`, `ulaw_8000`
- `keywords` (list of string, optional) — 用于提高预测概率的关键词

### TurnConfigWorkflowOverride

- `turn_timeout` (double, optional) — 再次联系用户前等待用户回复的最长时间
- `initial_wait_time` (double, optional) — How long the agent will wait for the user to start the conversation if the first message is empty. If not set, uses the regular turn_timeout.
- `silence_end_call_timeout` (double, optional) — 用户最后一次说话后终止通话前的最长等待时间
- `turn_eagerness` (enum, optional, default: normal) — 控制智能体的响应积极程度。Low = 较不积极（等待更久），Standard = 默认积极程度，High = 更积极（响应更快）。
  - Allowed values: `patient`, `normal`, `eager`
- `spelling_patience` (enum, optional, default: auto) — 控制用户逐个拼读数字和命名实体时，智能体是否应更耐心等待。Auto = 基于模型判断，Off = 不额外等待。
  - Allowed values: `auto`, `off`
- `speculative_turn` (boolean, optional) — 启用后，在达到完整轮次置信度前的静音期间开始生成 LLM 回复，以降低感知延迟。可能增加 LLM 成本。
- `retranscribe_on_turn_timeout` (boolean, optional) — 启用后，如果 VAD 未检测到语音，会在轮次超时时尝试重新转录累计音频。为当前智能体或 workflow 节点启用期间，将停用静音折扣计费。
- `turn_model` (enum, optional, default: turn_v3) — 要使用的轮次检测模型版本。
  - Allowed values: `turn_v2`, `turn_v3`
- `interruption_ignore_terms` (list of string, optional) — 用户说出时不应触发打断的词条列表（例如“gotcha”“understood”）。使用不区分大小写的精确匹配。
- `interruption_ignore_term_languages` (list of string, optional) — 已启用预设忽略词类别的语言代码。明确存储，避免根据词条重叠推断显示内容。
- `merge_with_default_ignore_terms` (boolean, optional) — 启用后，除 interruption_ignore_terms 外，还会使用为 interruption_ignore_term_languages 精选的默认词条。
- `transcribe_on_disabled_interruptions` (boolean, optional) — 禁用打断时，仍会转写用户所说内容，以便带入下一轮。关闭后，不可打断轮次期间的用户语音将被忽略，且不会触发新一轮。
- `soft_timeout_config` (SoftTimeoutConfigWorkflowOverride, optional) — Configuration for soft timeout functionality. Provides immediate feedback during longer LLM responses.

### TtsConversationalConfigWorkflowOverrideInput

- `model_id` (enum, optional, default: eleven_v4_turbo) — 用于 TTS 的模型
  - Allowed values: `eleven_turbo_v2`, `eleven_turbo_v2_5`, `eleven_flash_v2`, `eleven_flash_v2_5`, `eleven_multilingual_v2`, `eleven_v3_conversational`, `eleven_v4`, `eleven_v4_turbo`
- `voice_id` (string, optional) — 用于 TTS 的音色 ID。
- `supported_voices` (list of SupportedVoice, optional) — 智能体额外支持的音色
- `expressive_mode` (boolean, optional) — 启用后，应用富表现力音频标签提示词。非 v3 模型会自动禁用。
- `suggested_audio_tags` (list of SuggestedAudioTag, optional) — 用于增强富有表现力语音的建议音频标签（适用于 eleven_v3 和 eleven_v3_conversational 模型）。智能体仍可使用此处未列出的其他标签。
- `agent_output_audio_format` (enum, optional, default: pcm_16000) — TTS 使用的音频格式
  - Allowed values: `pcm_8000`, `pcm_16000`, `pcm_22050`, `pcm_24000`, `pcm_44100`, `pcm_48000`, `ulaw_8000`
- `optimize_streaming_latency` (integer, optional) — 已弃用：此字段无效，将被忽略。
- `stability` (double, optional) — 生成语音的稳定性
- `speed` (double, optional) — 生成语音的速度
- `similarity_boost` (double, optional) — 生成语音的相似度增强
- `text_normalisation_type` (enum, optional, default: system_prompt) — 将文本转为语音前把数字转换为文字的方法。设为 SYSTEM_PROMPT 时，系统提示词会更新为包含规范化说明。设为 ELEVENLABS 时，文本会在生成后规范化，这会略微增加延迟。
  - Allowed values: `system_prompt`, `elevenlabs`
- `pronunciation_dictionary_locators` (list of PydanticPronunciationDictionaryVersionLocator, optional) — 发音词典定位器
- `enable_phoneme_tags` (boolean, optional) — 选择为 V3 模型启用 SSML 音素标签处理。启用后，音素标签（内联及来自发音词典的标签）会先解析为内联 IPA，再发送给模型。
- `audio_effects` (EffectsSpecInput, optional) — 可选的 TTS 效果规格：滤镜预设、距离（近讲 EQ）和环境（卷积混响）。

### ConversationConfigWorkflowOverrideInput

- `text_only` (boolean, optional) — 启用后将不处理音频，仅使用文本，可避免音频计费。
- `max_duration_seconds` (integer, optional) — 单次对话的最长时长，单位为秒
- `client_events` (list of enum, optional) — 将发送至客户端的事件
  - Allowed values: `conversation_initiation_metadata`, `asr_initiation_metadata`, `ping`, `audio`, `interruption`, `user_transcript`, `tentative_user_transcript`, `agent_response`, `agent_response_correction`, `client_tool_call`, `mcp_tool_call`, `mcp_connection_status`, `agent_tool_request`, `agent_tool_response`, `agent_tool_response_full_payload`, `agent_response_metadata`, `vad_score`, `agent_chat_response_part`, `client_error`, `guardrail_triggered`, `dtmf_request`, `agent_response_complete`, `context_usage`, `internal_turn_probability`, `internal_tentative_agent_response`
- `file_input` (FileInputConfigWorkflowOverride, optional) — Configuration for file input (image/PDF uploads) during conversations.
- `monitoring_enabled` (boolean, optional) — 通过 WebSocket 启用对话实时监控
- `monitoring_events` (list of enum, optional) — 将发送至监控连接的事件。
  - Allowed values: `conversation_initiation_metadata`, `asr_initiation_metadata`, `ping`, `audio`, `interruption`, `user_transcript`, `tentative_user_transcript`, `agent_response`, `agent_response_correction`, `client_tool_call`, `mcp_tool_call`, `mcp_connection_status`, `agent_tool_request`, `agent_tool_response`, `agent_tool_response_full_payload`, `agent_response_metadata`, `vad_score`, `agent_chat_response_part`, `client_error`, `guardrail_triggered`, `dtmf_request`, `agent_response_complete`, `context_usage`, `internal_turn_probability`, `internal_tentative_agent_response`
- `dtmf_input_settings` (DtmfInputConfig, optional) — Configure DTMF (keypad) input collection during phone calls
- `background_sound` (BackgroundSoundConfigWorkflowOverride, optional) — Configuration for background sound during conversations.
- `source_attribution` (boolean, optional) — 启用后，若存在知识库内容，将要求 LLM 报告所使用的来源。

### LanguagePresetInput

- `overrides` (ConversationConfigClientOverrideInput, required) — 语言预设的覆盖设置
- `first_message_translation` (LanguagePresetTranslation, optional) — 第一条消息的翻译
- `soft_timeout_translation` (LanguagePresetTranslation, optional) — 软超时消息的翻译

### VadConfigWorkflowOverride

### AgentConfigApiModelWorkflowOverrideInput

- `first_message` (string, optional) — 非空时，为智能体首先说出的消息。为空时，智能体会等待用户发起对话。
- `language` (string, optional) — 智能体语言，用于 ASR 和 TTS
- `hinglish_mode` (boolean, optional) — 启用后，智能体会在印地语、马拉雅拉姆语、泰卢固语或卡纳达语回复中混用英语单词和短语。
- `dynamic_variables` (DynamicVariablesConfigWorkflowOverride, optional) — Configuration for dynamic variables
- `disable_first_message_interruptions` (boolean, optional) — 如果为 true，在发送第一条消息期间，用户无法打断智能体。
- `max_conversation_duration_message` (string, optional) — 非空时，为达到最长对话时长后智能体发送的消息。
- `text_behavior_overrides` (map from string to BehaviorOverride, optional) — 文本对话的每个渠道响应行为覆盖选项。未设置时使用内置渠道默认值。
- `prompt` (PromptAgentApiModelWorkflowOverrideInput, optional) — 智能体的提示词

### WorkflowToolLocatorSchemaOverridesValue

- `source`: `constant`
  - `constant_value` (ConstantSchemaOverrideConstantValue, optional) — 要使用的常量值
- `source`: `dynamic_variable`
  - `dynamic_variable` (string, required) — 要使用的动态变量名称
- `source`: `llm`
  - `prompt` (string, optional) — LLM 的提示词覆盖内容。未提供时，使用原始架构描述。
- `source`: `omit`

### TranslatedString

- `value` (string, required)

### LlmLiteralJsonSchemaProperty

- `type` (LlmLiteralJsonSchemaPropertyType, required)
- `description` (string, required)
- `enum` (list of string, optional) — List of allowed string values for string type parameters

### AstNumberNodeInputValue

此字面量的值。

- double
- integer

### SoftTimeoutConfigWorkflowOverride

- `timeout_seconds` (double, optional) — 等待 LLM 响应时显示预定义消息前的秒数。设为 -1 可禁用。
- `message` (string, optional) — 等待 LLM 响应时，首次达到软超时时显示的消息。支持动态变量（例如 \{\{system\_\_time}}、\{\{custom\_variable}}）。
- `additional_soft_timeout_messages` (list of string, optional) — 同一次 LLM 生成中后续软超时时使用的额外静态填充消息。首次超时使用 `message`。如果配置的消息少于 `max_soft_timeouts_per_generation`，会重复最后一条配置的消息；否则使用内置填充消息。
- `use_llm_generated_message` (boolean, optional) — 启用后，将动态生成软超时消息，而非使用静态消息。
- `randomize_fillers` (boolean, optional) — 启用后，在每轮开始时随机打乱静态软超时消息的顺序。仅在 use_llm_generated_message 为 false 时适用。
- `max_soft_timeouts_per_generation` (integer, optional) — 等待单次 LLM 响应期间允许发送的最大填充消息数。每隔 timeout_seconds 触发一次，直到 LLM 开始流式返回内容或达到此限制。
- `llm_generated_message_prompt_override` (string, optional) — 启用 use\_llm\_generated\_message 时，用于生成软超时填充消息的自定义提示词。最近的对话上下文将作为单独的用户消息提供。未设置时将使用默认提示词。支持动态变量（例如 \{\{system\_\_time}}、\{\{custom\_variable}}）。
- `disable_until_first_user_message` (boolean, optional) — 设为 true 时，在对话至少包含一条真实用户消息前，将不使用软超时填充语。避免在智能体开场轮次中使用填充语（例如 workflow 立即生成，或用户说话前调用工具）。

### SupportedVoice

- `label` (string, required)
- `voice_id` (string, required)
- `description` (string, optional)
- `language` (string, optional)
- `model_family` (enum, optional)
  - Allowed values: `turbo`, `flash`, `multilingual`, `v3_conversational`, `v4`, `v4_turbo`
- `optimize_streaming_latency` (integer, optional)
- `stability` (double, optional)
- `speed` (double, optional)
- `similarity_boost` (double, optional)

### SuggestedAudioTag

- `tag` (string, required) — Audio tag to use (for best performance, 1-2 words, e.g., 'happy', 'excited')
- `description` (string, optional) — 何时使用此标签的可选说明

### PydanticPronunciationDictionaryVersionLocator

供其他文档引用特定词典及其版本的定位符。 这是 PronunciationDictionaryVersionLocatorDBModel 的 pydantic 版本。 用于确保与其他智能体数据模型兼容。

- `pronunciation_dictionary_id` (string, required) — 发音词典的 ID
- `version_id` (string, optional) — 发音词典版本的 ID

### EffectsSpecInput

应用于生成语音的音频效果：滤镜预设、感知距离、混响 环境、背景噪声底音和立体声声像。将所有字段保留为默认值， 即可获得未经处理的音频。

- `filter_preset_id` (string, optional) — 为语音增添音色特征的滤镜预设 ID，例如 `phone` 或 `old_radio`。使用 `GET /v1/audio-effects/catalog` 列出有效 ID。
- `distance` (double, optional, default: 0) — 说话者听起来与麦克风的距离，范围为 0（近，不变）至 1（远）。值越高，低频和高频衰减越多；设置环境后，干声与混响之间的平衡会更偏向混响。
- `environment_id` (string, optional) — 将语音置于特定空间中的混响环境 ID，例如 `small_room` 或 `hall`。使用 `GET /v1/audio-effects/catalog` 列出有效 ID。混响以立体声渲染，并会在语音结束后添加最长数秒的余响。
- `background_noise_id` (string, optional) — 在语音下方循环播放的背景噪声底音 ID，例如 `cafe` 或 `keyboard`。使用 `GET /v1/audio-effects/catalog` 列出有效 ID。
- `send_level` (double, optional, default: 1) — 输入混响的语音比例，范围为 0（无）至 1（全部）。仅在设置 `environment_id` 时生效；0 会关闭混响。
- `pan` (double, optional, default: 0) — 音色的立体声位置，范围从 -1（最左）经 0（居中）到 1（最右）。仅音色会进行声像定位；混响和背景噪声保持居中。

### FileInputConfigWorkflowOverride

- `enabled` (boolean, optional) — 启用后，如果 LLM 支持多模态输入，用户可在聊天中附加图片、PDF 或文本文件。
- `max_files_in_memory` (integer, optional) — 对话期间保留在内存中的最新文件数量。较旧文件会被总结并释放其字节数据。
- `max_files_per_conversation` (integer, optional) — 用户在一次对话中可上传的文件总数。上传按文件计费。使用 -1 表示不限，或设为大于等于 max_files_in_memory 的值。

### DtmfInputConfig

Configuration for DTMF (keypad) input collection during phone calls.

- `dtmf_input_timeout` (double, optional, default: 2) — 等待额外 DTMF 按键的超时时间（秒）。
- `hash_terminator` (boolean, optional, default: true) — 如果为 true，按下 # 会立即完成 DTMF 输入。
- `redact_input` (boolean, optional, default: false) — 如果为 true，将在转录文本、对话日志和分析中用脱敏标记替换来电者的 DTMF（键盘）输入。智能体复述或传递给工具的数字不受影响。

### BackgroundSoundConfigWorkflowOverride

- `source_type` ("preset", optional) — 背景声音源类型。
- `source_id` (enum, optional) — 声音源标识符。
  - Allowed values: `office2`, `office1`, `restaurant`, `city`, `typing`, `elevator1`, `elevator2`, `elevator3`, `elevator4`
- `volume` (double, optional) — 背景音量级别（0.01 至 1.0）。
- `crossfade_loop` (boolean, optional) — 在循环边界应用交叉淡化，避免声音循环时出现爆音。

### ConversationConfigClientOverrideInput

- `asr` (AsrConversationalConfigOverride, optional) — Configuration for conversational transcription
- `turn` (TurnConfigOverride, optional) — Configuration for turn detection
- `tts` (TtsConversationalConfigOverride, optional) — Configuration for conversational text to speech
- `conversation` (ConversationConfigOverride, optional) — Configuration for conversational events
- `agent` (AgentConfigOverrideInput, optional) — 智能体专属配置

### LanguagePresetTranslation

- `source_hash` (string, required)
- `text` (string, required)

### DynamicVariablesConfigWorkflowOverride

- `dynamic_variable_placeholders` (map from string to any, optional) — 动态变量占位符及其值的字典。

### BehaviorOverride

- `verbosity` (enum, optional) — 详细程度覆盖设置。未设置时使用底层默认值。
  - Allowed values: `auto`, `concise`, `thorough`
- `output_format` (enum, optional) — 输出格式覆盖值。未设置时使用底层默认值。
  - Allowed values: `mp3_22050_32`, `mp3_44100_32`, `mp3_44100_64`, `mp3_44100_96`, `mp3_44100_128`, `mp3_44100_192`, `pcm_16000`, `pcm_22050`, `pcm_24000`, `pcm_44100`, `ulaw_8000`
- `interaction_budget` (enum, optional) — 交互预算覆盖设置。未设置时使用底层默认值。
  - Allowed values: `realtime`, `5_minutes`, `10_minutes`, `1_hour`

### PromptAgentApiModelWorkflowOverrideInput

- `prompt` (string, optional) — 智能体的提示词
- `llm` (enum, optional) — 用于结合提示词和聊天记录进行查询的 LLM。使用数据驻留时，该 LLM 必须受数据驻留环境支持
  - Allowed values: `gpt-4o-mini`, `gpt-4o`, `gpt-4`, `gpt-4-turbo`, `gpt-4.1`, `gpt-4.1-mini`, `gpt-4.1-nano`, `gpt-5`, `gpt-5.1`, `gpt-5.2`, `gpt-5.2-chat-latest`, `gpt-5.4`, `gpt-5.4-mini`, `gpt-5.4-nano`, `gpt-5.5`, `gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-5.6-luna`, `gpt-6-astra`, `gpt-6-sol`, `gpt-6-luna`, `gpt-6.1-sol`, `gpt-5-mini`, `gpt-5-nano`, `gpt-3.5-turbo`, `gemini-1.5-pro`, `gemini-1.5-flash`, `gemini-2.0-flash`, `gemini-2.0-flash-lite`, `gemini-2.5-flash-lite`, `gemini-2.5-flash`, `gemini-3-pro-preview`, `gemini-3-flash-preview`, `gemini-3.1-pro-preview`, `gemini-3.1-flash-lite-preview`, `gemini-3.1-flash-lite`, `gemini-3.5-flash`, `gemini-3.5-flash-lite`, `gemini-3.6-flash`, `gemini-3.7-flash`, `gemini-3.8-flash`, `gemini-4-argon`, `claude-sonnet-4-5`, `claude-opus-4-6`, `claude-opus-4-7`, `claude-opus-4-8`, `claude-opus-5`, `claude-opus-5-5`, `claude-sonnet-4-6`, `claude-sonnet-5`, `claude-sonnet-5-5`, `claude-sonnet-4`, `claude-haiku-4-5`, `claude-haiku-5-5`, `claude-3-7-sonnet`, `claude-3-5-sonnet`, `claude-3-5-sonnet-v1`, `claude-3-haiku`, `grok-beta`, `custom-llm`, `qwen3-4b`, `qwen3-30b-a3b`, `qwen36-35b-a3b`, `qwen35-397b-a17b`, `gpt-oss-20b`, `gpt-oss-120b`, `glm-45-air-fp8`, `glm-52`, `deepseek-v41-flash`, `nemotron-35-super-vl-nvfp4`, `gemini-2.5-flash-preview-09-2025`, `gemini-2.5-flash-lite-preview-09-2025`, `gemini-2.5-flash-preview-05-20`, `gemini-2.5-flash-preview-04-17`, `gemini-2.5-flash-lite-preview-06-17`, `gemini-2.0-flash-lite-001`, `gemini-2.0-flash-001`, `gemini-1.5-flash-002`, `gemini-1.5-flash-001`, `gemini-1.5-pro-002`, `gemini-1.5-pro-001`, `claude-sonnet-4@20250514`, `claude-sonnet-4-5@20250929`, `claude-haiku-4-5@20251001`, `claude-3-7-sonnet@20250219`, `claude-3-5-sonnet@20240620`, `claude-3-5-sonnet-v2@20241022`, `claude-3-haiku@20240307`, `gpt-5-2025-08-07`, `gpt-5.1-2025-11-13`, `gpt-5.2-2025-12-11`, `gpt-5.4-2026-03-05`, `gpt-5.4-mini-2026-03-17`, `gpt-5.4-nano-2026-03-17`, `gpt-5.5-2026-04-23`, `gpt-5-mini-2025-08-07`, `gpt-5-nano-2025-08-07`, `gpt-4.1-2025-04-14`, `gpt-4.1-mini-2025-04-14`, `gpt-4.1-nano-2025-04-14`, `gpt-4o-mini-2024-07-18`, `gpt-4o-2024-11-20`, `gpt-4o-2024-08-06`, `gpt-4o-2024-05-13`, `gpt-4-0613`, `gpt-4-0314`, `gpt-4-turbo-2024-04-09`, `gpt-3.5-turbo-0125`, `gpt-3.5-turbo-1106`, `watt-tool-8b`, `watt-tool-70b`
- `reasoning_effort` (enum, optional) — 模型的推理强度。仅部分模型支持。
  - Allowed values: `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`
- `thinking_budget` (integer, optional) — 用于思考的最大 token 数。模型支持时，设为 0 可关闭。
- `enable_reasoning_summary` (boolean, optional) — 启用模型推理摘要。禁用后，如可行，将不向提供商请求摘要，以加快 TTFB。不兼容 ZRM。
- `temperature` (double, optional) — LLM 的 temperature。默认为 0。设为 null 可从 LLM 请求中完全省略此参数（适用于拒绝 temperature 字段的自定义 LLM）。
- `max_tokens` (integer, optional) — 若大于 0，则为 LLM 可预测的最大 token 数
- `tool_ids` (list of string, optional) — 智能体使用的工具 ID 列表。
- `tool_ids_strict` (boolean, optional) — 仅作为对话覆盖项生效，在允许覆盖 tool_ids 时均可使用。为 true 时，覆盖后的 tool_ids 是对话中允许使用的完整工具列表，包括 workflow 节点上的工具。在智能体上设置时会被忽略。
- `built_in_tools` (BuiltInToolsWorkflowOverrideInput, optional) — Built-in system tools to be used by the agent
- `enable_parallel_tool_calls` (boolean, optional) — 启用并行工具调用。启用后，智能体可在单个轮次中并行执行多个工具。并非所有模型都支持。
- `mcp_server_ids` (list of string, optional) — 供智能体使用的 MCP 服务器 ID 列表
- `native_mcp_server_ids` (list of string, optional) — 供智能体使用的原生 MCP 服务器 ID 列表
- `knowledge_base` (list of KnowledgeBaseLocator, optional) — 供智能体使用的知识库列表
- `custom_llm` (CustomLlm, optional) — 当 LLM 字段设为 'CUSTOM_LLM' 时，自定义 LLM 的定义
- `ignore_default_personality` (boolean, optional) — 是否从系统提示词中移除默认人格描述
- `rag` (RagConfigWorkflowOverrideInput, optional) — Configuration for RAG
- `timezone` (string, optional) — 用于在系统提示词中显示当前时间的时区。设置后，系统提示词会按此时区包含当前时间。必须是有效的时区名称（如 'America/New_York'、'Europe/London'、'UTC'）。建议设置以获得准确的时间感知回复；否则，除非通过动态变量或工具提供，智能体不会知道当前日期和时间，可能导致时间引用错误或幻觉。
- `backup_llm_config` (PromptAgentApiModelWorkflowOverrideInputBackupLlmConfig, optional) — Configuration for backup LLM cascading. Can be disabled, use system defaults, or specify custom order.
- `cascade_timeout_seconds` (double, optional) — 切换至备用 LLM 前等待的秒数。必须介于 2 至 15 秒。
- `tools` (list of PromptAgentApiModelWorkflowOverrideInputToolsItem, optional) — 智能体在对话过程中可使用的工具列表，请改用 tool_ids。

### ConstantSchemaOverrideConstantValue

要使用的常量值

- string
- integer
- double
- boolean
- list of any
- map from string to any

### LlmLiteralJsonSchemaPropertyType

- "boolean"
- "string"
- "integer"
- "number"
- list of string

### AsrConversationalConfigOverride

- `keywords` (list of string, optional) — 用于提高预测概率的关键词

### TurnConfigOverride

- `soft_timeout_config` (SoftTimeoutConfigOverride, optional) — Configuration for soft timeout functionality. Provides immediate feedback during longer LLM responses.

### TtsConversationalConfigOverride

- `model_id` (enum, optional, default: eleven_v4_turbo) — 用于 TTS 的模型
  - Allowed values: `eleven_turbo_v2`, `eleven_turbo_v2_5`, `eleven_flash_v2`, `eleven_flash_v2_5`, `eleven_multilingual_v2`, `eleven_v3_conversational`, `eleven_v4`, `eleven_v4_turbo`
- `voice_id` (string, optional) — 用于 TTS 的音色 ID。
- `supported_voices` (list of SupportedVoice, optional) — 智能体额外支持的音色
- `stability` (double, optional) — 生成语音的稳定性
- `speed` (double, optional) — 生成语音的速度
- `similarity_boost` (double, optional) — 生成语音的相似度增强
- `pronunciation_dictionary_locators` (list of PydanticPronunciationDictionaryVersionLocator, optional) — 发音词典定位器

### ConversationConfigOverride

- `text_only` (boolean, optional) — 启用后将不处理音频，仅使用文本，可避免音频计费。
- `max_duration_seconds` (integer, optional) — 单次对话的最长时长，单位为秒

### AgentConfigOverrideInput

- `first_message` (string, optional) — 非空时，为智能体首先说出的消息。为空时，智能体会等待用户发起对话。
- `language` (string, optional) — 智能体语言，用于 ASR 和 TTS
- `max_conversation_duration_message` (string, optional) — 非空时，为达到最长对话时长后智能体发送的消息。
- `prompt` (PromptAgentApiModelOverrideInput, optional) — 智能体的提示词

### BuiltInToolsWorkflowOverrideInput

- `transfer_to_agent` (SystemToolConfigInput, optional) — 转接至智能体工具
- `end_call` (SystemToolConfigInput, optional) — 结束通话工具
- `language_detection` (SystemToolConfigInput, optional) — 语言检测工具
- `transfer_to_number` (SystemToolConfigInput, optional) — 转接至号码工具
- `skip_turn` (SystemToolConfigInput, optional) — 跳过回合工具
- `play_keypad_touch_tone` (SystemToolConfigInput, optional) — 播放 DTMF 工具
- `voicemail_detection` (SystemToolConfigInput, optional) — 语音信箱检测工具。

### CustomLlm

- `url` (string, required) — 兼容 Chat Completions 的端点 URL
- `model_id` (string, optional) — 当 URL 提供多个模型时使用的模型 ID
- `api_key` (CustomLlmApiKey, optional) — 用于身份验证的 API 密钥。可以是工作区密钥引用 \{'secret\_id': '...'}，也可以是环境变量引用 \{'env\_var\_label': '...'}。
- `auth_connection` (CustomLlmAuthConnection, optional) — 用于认证的可选工作区身份验证连接。仅支持生成 Authorization Bearer 令牌的身份验证连接；不支持 Basic 认证、mTLS、自定义标头和 URL 密钥认证连接。
- `request_headers` (map from string to CustomLlmRequestHeadersValue, optional) — 请求中应包含的请求头
- `api_version` (string, optional) — 请求使用的 API 版本
- `api_type` (enum, optional, default: chat_completions) — 要使用的 API 类型（chat_completions、responses 或 websocket）
  - Allowed values: `chat_completions`, `responses`, `websocket`

### RagConfigWorkflowOverrideInput

- `enabled` (boolean, optional)
- `embedding_model` (enum, optional, default: e5_mistral_7b_instruct)
  - Allowed values: `e5_mistral_7b_instruct`, `multilingual_e5_large_instruct`
- `max_vector_distance` (double, optional) — 检索文档块的最大向量距离。
- `max_documents_length` (integer, optional) — 从 RAG 检索的文档块最大总长度。
- `max_retrieved_rag_chunks_count` (integer, optional) — 初始从向量存储中检索的最大 RAG 文档块数。随后会按向量距离和总长度进一步筛选。
- `num_candidates` (integer, optional) — ANN 向量搜索中评估的候选项数量。数值越高，结果越好，但延迟也越高。建议最小值为 100。禁用时使用默认值。
- `query_rewrite_prompt_override` (string, optional) — 在 RAG 检索前改写用户查询的自定义提示词。对话历史将自动附加在末尾。未设置时将使用默认提示词。
- `knowledge_base_tool_info` (KnowledgeBaseToolInfo, optional) — 设置后，智能体将使用 knowledge_base 工具，而非旧版 knowledge_base_rag 工具。None 表示智能体未启用此功能。

### PromptAgentApiModelWorkflowOverrideInputBackupLlmConfig

Configuration for backup LLM cascading. Can be disabled, use system defaults, or specify custom order.

- Backup Llm Default: BackupLlmDefault
- Backup Llm Disabled: BackupLlmDisabled
- Backup Llm Override: BackupLlmOverride

### PromptAgentApiModelWorkflowOverrideInputToolsItem

工具类型

- `type`: `api_integration_webhook`
  - `api_integration_connection_id` (string, required)
  - `api_integration_id` (string, required)
  - `description` (string, required) — 说明何时应使用该工具及其功能。
  - `name` (string, required)
  - `api_schema_overrides` (ApiIntegrationWebhookOverrides, optional) — 应用于基础 api_schema 之上的用户覆盖项。
  - `assignments` (list of DynamicVariableAssignment, optional) — Configuration for extracting values from tool responses and assigning them to dynamic variables
  - `dynamic_variables` (DynamicVariablesConfig, optional) — Configuration for dynamic variables
  - `execution_mode` (enum, optional, default: immediate) — 决定工具的执行时机和方式：'immediate' 会在 LLM 请求时立即执行工具；'post_tool_speech' 会等待智能体说完后再执行；'async' 会在后台运行工具且不阻塞，最适合耗时较长的操作。
    - Allowed values: `immediate`, `post_tool_speech`, `async`
  - `interruption_mode` (enum, optional, default: allow) — 控制用户在此次工具调用前后能否打断智能体。'allow'（默认）允许用户随时打断，'disable_during_tool' 仅在工具运行期间禁止打断，'disable_during_tool_and_turn' 会在工具运行期间及其后的智能体响应期间禁止打断。
    - Allowed values: `allow`, `disable_during_tool`, `disable_during_tool_and_turn`
  - `pre_tool_speech` (enum, optional, default: auto) — 控制调用此工具前智能体是否说话。'auto'（默认）会根据近期工具延迟决定，'force' 始终要求智能体说话，'off' 无论延迟如何都完全禁用。
    - Allowed values: `auto`, `force`, `off`
  - `response_timeout_secs` (integer, optional, default: 20) — 等待工具调用完成的最长时间，单位为秒。必须介于 5 秒和 300 秒之间（含）。
  - `tool_call_sound` (enum, optional) — 工具执行期间播放的预定义工具调用音效类型。未指定时，不播放工具调用音效。
    - Allowed values: `typing`, `elevator1`, `elevator2`, `elevator3`, `elevator4`
  - `tool_call_sound_behavior` (enum, optional, default: auto) — 决定工具调用提示音何时播放。'auto' 仅在工具调用前有语音时播放，'always' 会在每次工具调用时播放。
    - Allowed values: `auto`, `always`
  - `tool_error_handling_mode` (enum, optional, default: auto) — 控制工具错误在共享给智能体前的处理方式。'auto' 会根据工具类型决定处理方式（原生集成会生成摘要，其他工具会隐藏），'summarized' 会发送由 LLM 生成的摘要，'passthrough' 会发送原始错误，'hide' 不会向智能体共享错误。
    - Allowed values: `auto`, `summarized`, `passthrough`, `hide`
  - `tool_version` (string, optional, default: 1.0.0) — API 集成工具的版本。
  - `disable_interruptions` (boolean, optional, default: false, deprecated) — 已弃用：请改用 `interruption_mode`。如果为 true，当此工具运行时，用户无法打断智能体。
  - `force_pre_tool_speech` (boolean, optional, default: false, deprecated) — 已弃用：请改用 `pre_tool_speech`。如果为 true，智能体会在调用工具前发言。
- `type`: `client`
  - `description` (string, required) — 说明何时应使用该工具及其功能。
  - `name` (string, required)
  - `assignments` (list of DynamicVariableAssignment, optional) — Configuration for extracting values from tool responses and assigning them to dynamic variables
  - `dynamic_variables` (DynamicVariablesConfig, optional) — Configuration for dynamic variables
  - `execution_mode` (enum, optional, default: immediate) — 决定工具的执行时机和方式：'immediate' 会在 LLM 请求时立即执行工具；'post_tool_speech' 会等待智能体说完后再执行；'async' 会在后台运行工具且不阻塞，最适合耗时较长的操作。
    - Allowed values: `immediate`, `post_tool_speech`, `async`
  - `expects_response` (boolean, optional, default: false) — 如果为 true，调用此工具会阻塞对话，直到客户端返回响应并传递给 llm。如果为 false，则不会等待客户端响应，而是继续对话。这适合向用户展示内容而不阻塞对话。
  - `interruption_mode` (enum, optional, default: allow) — 控制用户在此次工具调用前后能否打断智能体。'allow'（默认）允许用户随时打断，'disable_during_tool' 仅在工具运行期间禁止打断，'disable_during_tool_and_turn' 会在工具运行期间及其后的智能体响应期间禁止打断。
    - Allowed values: `allow`, `disable_during_tool`, `disable_during_tool_and_turn`
  - `parameters` (ObjectJsonSchemaPropertyInput, optional) — 传递给客户端的所有参数的 Schema
  - `pre_tool_speech` (enum, optional, default: auto) — 控制调用此工具前智能体是否说话。'auto'（默认）会根据近期工具延迟决定，'force' 始终要求智能体说话，'off' 无论延迟如何都完全禁用。
    - Allowed values: `auto`, `force`, `off`
  - `response_timeout_secs` (integer, optional, default: 20) — 等待工具调用完成的最长时间（秒）。必须介于 1 到 120 秒之间（含），或设为 -1 以无限期等待客户端响应（需要 expects_response）。
  - `tool_call_sound` (enum, optional) — 工具执行期间播放的预定义工具调用音效类型。未指定时，不播放工具调用音效。
    - Allowed values: `typing`, `elevator1`, `elevator2`, `elevator3`, `elevator4`
  - `tool_call_sound_behavior` (enum, optional, default: auto) — 决定工具调用提示音何时播放。'auto' 仅在工具调用前有语音时播放，'always' 会在每次工具调用时播放。
    - Allowed values: `auto`, `always`
  - `tool_error_handling_mode` (enum, optional, default: auto) — 控制工具错误在共享给智能体前的处理方式。'auto' 会根据工具类型决定处理方式（原生集成会生成摘要，其他工具会隐藏），'summarized' 会发送由 LLM 生成的摘要，'passthrough' 会发送原始错误，'hide' 不会向智能体共享错误。
    - Allowed values: `auto`, `summarized`, `passthrough`, `hide`
  - `disable_interruptions` (boolean, optional, default: false, deprecated) — 已弃用：请改用 `interruption_mode`。如果为 true，当此工具运行时，用户无法打断智能体。
  - `force_pre_tool_speech` (boolean, optional, default: false, deprecated) — 已弃用：请改用 `pre_tool_speech`。如果为 true，智能体会在调用工具前发言。
- `type`: `mcp`
  - `value` (any, required)
- `type`: `smb`
  - `value` (any, required)
- `type`: `system`
  - `name` (string, required)
  - `params` (SystemToolConfigInputParams, required)
  - `assignments` (list of DynamicVariableAssignment, optional) — Configuration for extracting values from tool responses and assigning them to dynamic variables
  - `description` (string, optional, default: ) — 说明何时应使用该工具及其功能。留空则使用针对该工具类型优化的默认说明。
  - `interruption_mode` (enum, optional, default: allow) — 控制用户在此次工具调用前后能否打断智能体。'allow'（默认）允许用户随时打断，'disable_during_tool' 仅在工具运行期间禁止打断，'disable_during_tool_and_turn' 会在工具运行期间及其后的智能体响应期间禁止打断。
    - Allowed values: `allow`, `disable_during_tool`, `disable_during_tool_and_turn`
  - `pre_tool_speech` (enum, optional, default: auto) — 控制调用此工具前智能体是否说话。'auto'（默认）会根据近期工具延迟决定，'force' 始终要求智能体说话，'off' 无论延迟如何都完全禁用。
    - Allowed values: `auto`, `force`, `off`
  - `response_timeout_secs` (integer, optional, default: 20) — 等待工具调用完成的最长时间，单位为秒。
  - `tool_call_sound` (enum, optional) — 工具执行期间播放的预定义工具调用音效类型。未指定时，不播放工具调用音效。
    - Allowed values: `typing`, `elevator1`, `elevator2`, `elevator3`, `elevator4`
  - `tool_call_sound_behavior` (enum, optional, default: auto) — 决定工具调用提示音何时播放。'auto' 仅在工具调用前有语音时播放，'always' 会在每次工具调用时播放。
    - Allowed values: `auto`, `always`
  - `tool_error_handling_mode` (enum, optional, default: auto) — 控制工具错误在共享给智能体前的处理方式。'auto' 会根据工具类型决定处理方式（原生集成会生成摘要，其他工具会隐藏），'summarized' 会发送由 LLM 生成的摘要，'passthrough' 会发送原始错误，'hide' 不会向智能体共享错误。
    - Allowed values: `auto`, `summarized`, `passthrough`, `hide`
  - `disable_interruptions` (boolean, optional, default: false, deprecated) — 已弃用：请改用 `interruption_mode`。如果为 true，当此工具运行时，用户无法打断智能体。
  - `force_pre_tool_speech` (boolean, optional, default: false, deprecated) — 已弃用：请改用 `pre_tool_speech`。如果为 true，智能体会在调用工具前发言。
- `type`: `webhook`
  - `api_schema` (WebhookToolApiSchemaConfigInput, required) — 出站 webhook 的架构，包括参数和 URL 规范。
  - `description` (string, required) — 说明何时应使用该工具及其功能。
  - `name` (string, required)
  - `assignments` (list of DynamicVariableAssignment, optional) — Configuration for extracting values from tool responses and assigning them to dynamic variables
  - `dynamic_variables` (DynamicVariablesConfig, optional) — Configuration for dynamic variables
  - `execution_mode` (enum, optional, default: immediate) — 决定工具的执行时机和方式：'immediate' 会在 LLM 请求时立即执行工具；'post_tool_speech' 会等待智能体说完后再执行；'async' 会在后台运行工具且不阻塞，最适合耗时较长的操作。
    - Allowed values: `immediate`, `post_tool_speech`, `async`
  - `follow_redirects` (boolean, optional, default: false) — 是否解析端点重定向并返回最终响应。会跟随 1 次重定向，并以不带请求体的 GET 请求访问；此工具中配置的任何内容（标头、身份验证、客户端证书）都不会发送到重定向目标。端点和重定向目标均必须使用 HTTPS。不支持 API 集成工具。
  - `follow_redirects_allowed_domains` (list of string, optional) — 重定向可能指向的域名，例如 'test.example.com'。跟随重定向时必填，列表外的目标将被拒绝。
  - `interruption_mode` (enum, optional, default: allow) — 控制用户在此次工具调用前后能否打断智能体。'allow'（默认）允许用户随时打断，'disable_during_tool' 仅在工具运行期间禁止打断，'disable_during_tool_and_turn' 会在工具运行期间及其后的智能体响应期间禁止打断。
    - Allowed values: `allow`, `disable_during_tool`, `disable_during_tool_and_turn`
  - `pre_tool_speech` (enum, optional, default: auto) — 控制调用此工具前智能体是否说话。'auto'（默认）会根据近期工具延迟决定，'force' 始终要求智能体说话，'off' 无论延迟如何都完全禁用。
    - Allowed values: `auto`, `force`, `off`
  - `response_timeout_secs` (integer, optional, default: 20) — 等待工具调用完成的最长时间，单位为秒。必须介于 5 秒和 300 秒之间（含）。
  - `tool_call_sound` (enum, optional) — 工具执行期间播放的预定义工具调用音效类型。未指定时，不播放工具调用音效。
    - Allowed values: `typing`, `elevator1`, `elevator2`, `elevator3`, `elevator4`
  - `tool_call_sound_behavior` (enum, optional, default: auto) — 决定工具调用提示音何时播放。'auto' 仅在工具调用前有语音时播放，'always' 会在每次工具调用时播放。
    - Allowed values: `auto`, `always`
  - `tool_error_handling_mode` (enum, optional, default: auto) — 控制工具错误在共享给智能体前的处理方式。'auto' 会根据工具类型决定处理方式（原生集成会生成摘要，其他工具会隐藏），'summarized' 会发送由 LLM 生成的摘要，'passthrough' 会发送原始错误，'hide' 不会向智能体共享错误。
    - Allowed values: `auto`, `summarized`, `passthrough`, `hide`
  - `disable_interruptions` (boolean, optional, default: false, deprecated) — 已弃用：请改用 `interruption_mode`。如果为 true，当此工具运行时，用户无法打断智能体。
  - `force_pre_tool_speech` (boolean, optional, default: false, deprecated) — 已弃用：请改用 `pre_tool_speech`。如果为 true，智能体会在调用工具前发言。

### SoftTimeoutConfigOverride

- `message` (string, optional) — 等待 LLM 响应时，首次达到软超时时显示的消息。支持动态变量（例如 \{\{system\_\_time}}、\{\{custom\_variable}}）。
- `additional_soft_timeout_messages` (list of string, optional) — 同一次 LLM 生成中后续软超时时使用的额外静态填充消息。首次超时使用 `message`。如果配置的消息少于 `max_soft_timeouts_per_generation`，会重复最后一条配置的消息；否则使用内置填充消息。

### PromptAgentApiModelOverrideInput

- `prompt` (string, optional) — 智能体的提示词
- `llm` (enum, optional) — 用于结合提示词和聊天记录进行查询的 LLM。使用数据驻留时，该 LLM 必须受数据驻留环境支持
  - Allowed values: `gpt-4o-mini`, `gpt-4o`, `gpt-4`, `gpt-4-turbo`, `gpt-4.1`, `gpt-4.1-mini`, `gpt-4.1-nano`, `gpt-5`, `gpt-5.1`, `gpt-5.2`, `gpt-5.2-chat-latest`, `gpt-5.4`, `gpt-5.4-mini`, `gpt-5.4-nano`, `gpt-5.5`, `gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-5.6-luna`, `gpt-6-astra`, `gpt-6-sol`, `gpt-6-luna`, `gpt-6.1-sol`, `gpt-5-mini`, `gpt-5-nano`, `gpt-3.5-turbo`, `gemini-1.5-pro`, `gemini-1.5-flash`, `gemini-2.0-flash`, `gemini-2.0-flash-lite`, `gemini-2.5-flash-lite`, `gemini-2.5-flash`, `gemini-3-pro-preview`, `gemini-3-flash-preview`, `gemini-3.1-pro-preview`, `gemini-3.1-flash-lite-preview`, `gemini-3.1-flash-lite`, `gemini-3.5-flash`, `gemini-3.5-flash-lite`, `gemini-3.6-flash`, `gemini-3.7-flash`, `gemini-3.8-flash`, `gemini-4-argon`, `claude-sonnet-4-5`, `claude-opus-4-6`, `claude-opus-4-7`, `claude-opus-4-8`, `claude-opus-5`, `claude-opus-5-5`, `claude-sonnet-4-6`, `claude-sonnet-5`, `claude-sonnet-5-5`, `claude-sonnet-4`, `claude-haiku-4-5`, `claude-haiku-5-5`, `claude-3-7-sonnet`, `claude-3-5-sonnet`, `claude-3-5-sonnet-v1`, `claude-3-haiku`, `grok-beta`, `custom-llm`, `qwen3-4b`, `qwen3-30b-a3b`, `qwen36-35b-a3b`, `qwen35-397b-a17b`, `gpt-oss-20b`, `gpt-oss-120b`, `glm-45-air-fp8`, `glm-52`, `deepseek-v41-flash`, `nemotron-35-super-vl-nvfp4`, `gemini-2.5-flash-preview-09-2025`, `gemini-2.5-flash-lite-preview-09-2025`, `gemini-2.5-flash-preview-05-20`, `gemini-2.5-flash-preview-04-17`, `gemini-2.5-flash-lite-preview-06-17`, `gemini-2.0-flash-lite-001`, `gemini-2.0-flash-001`, `gemini-1.5-flash-002`, `gemini-1.5-flash-001`, `gemini-1.5-pro-002`, `gemini-1.5-pro-001`, `claude-sonnet-4@20250514`, `claude-sonnet-4-5@20250929`, `claude-haiku-4-5@20251001`, `claude-3-7-sonnet@20250219`, `claude-3-5-sonnet@20240620`, `claude-3-5-sonnet-v2@20241022`, `claude-3-haiku@20240307`, `gpt-5-2025-08-07`, `gpt-5.1-2025-11-13`, `gpt-5.2-2025-12-11`, `gpt-5.4-2026-03-05`, `gpt-5.4-mini-2026-03-17`, `gpt-5.4-nano-2026-03-17`, `gpt-5.5-2026-04-23`, `gpt-5-mini-2025-08-07`, `gpt-5-nano-2025-08-07`, `gpt-4.1-2025-04-14`, `gpt-4.1-mini-2025-04-14`, `gpt-4.1-nano-2025-04-14`, `gpt-4o-mini-2024-07-18`, `gpt-4o-2024-11-20`, `gpt-4o-2024-08-06`, `gpt-4o-2024-05-13`, `gpt-4-0613`, `gpt-4-0314`, `gpt-4-turbo-2024-04-09`, `gpt-3.5-turbo-0125`, `gpt-3.5-turbo-1106`, `watt-tool-8b`, `watt-tool-70b`
- `tool_ids` (list of string, optional) — 智能体使用的工具 ID 列表。
- `tool_ids_strict` (boolean, optional) — 仅作为对话覆盖项生效，在允许覆盖 tool_ids 时均可使用。为 true 时，覆盖后的 tool_ids 是对话中允许使用的完整工具列表，包括 workflow 节点上的工具。在智能体上设置时会被忽略。
- `native_mcp_server_ids` (list of string, optional) — 供智能体使用的原生 MCP 服务器 ID 列表
- `knowledge_base` (list of KnowledgeBaseLocator, optional) — 供智能体使用的知识库列表

### SystemToolConfigInput

系统工具是用于调用服务器系统方法的工具

- `name` (string, required)
- `params` (SystemToolConfigInputParams, required)
- `type` ("system", optional) — 工具类型
- `description` (string, optional, default: ) — 说明何时应使用该工具及其功能。留空则使用针对该工具类型优化的默认说明。
- `response_timeout_secs` (integer, optional, default: 20) — 等待工具调用完成的最长时间，单位为秒。
- `interruption_mode` (enum, optional, default: allow) — 控制用户在此次工具调用前后能否打断智能体。'allow'（默认）允许用户随时打断，'disable_during_tool' 仅在工具运行期间禁止打断，'disable_during_tool_and_turn' 会在工具运行期间及其后的智能体响应期间禁止打断。
  - Allowed values: `allow`, `disable_during_tool`, `disable_during_tool_and_turn`
- `pre_tool_speech` (enum, optional, default: auto) — 控制调用此工具前智能体是否说话。'auto'（默认）会根据近期工具延迟决定，'force' 始终要求智能体说话，'off' 无论延迟如何都完全禁用。
  - Allowed values: `auto`, `force`, `off`
- `assignments` (list of DynamicVariableAssignment, optional) — Configuration for extracting values from tool responses and assigning them to dynamic variables
- `tool_call_sound` (enum, optional) — 工具执行期间播放的预定义工具调用音效类型。未指定时，不播放工具调用音效。
  - Allowed values: `typing`, `elevator1`, `elevator2`, `elevator3`, `elevator4`
- `tool_call_sound_behavior` (enum, optional, default: auto) — 决定工具调用提示音何时播放。'auto' 仅在工具调用前有语音时播放，'always' 会在每次工具调用时播放。
  - Allowed values: `auto`, `always`
- `tool_error_handling_mode` (enum, optional, default: auto) — 控制工具错误在共享给智能体前的处理方式。'auto' 会根据工具类型决定处理方式（原生集成会生成摘要，其他工具会隐藏），'summarized' 会发送由 LLM 生成的摘要，'passthrough' 会发送原始错误，'hide' 不会向智能体共享错误。
  - Allowed values: `auto`, `summarized`, `passthrough`, `hide`
- `disable_interruptions` (boolean, optional, default: false, deprecated) — 已弃用：请改用 `interruption_mode`。如果为 true，当此工具运行时，用户无法打断智能体。
- `force_pre_tool_speech` (boolean, optional, default: false, deprecated) — 已弃用：请改用 `pre_tool_speech`。如果为 true，智能体会在调用工具前发言。

### CustomLlmApiKey

用于身份验证的 API 密钥。可以是工作区密钥引用 \{'secret\_id': '...'}，也可以是环境变量引用 \{'env\_var\_label': '...'}。

- Conv AI Secret Locator: ConvAiSecretLocator
- Conv AI Env Var Locator: ConvAiEnvVarLocator

### CustomLlmAuthConnection

用于认证的可选工作区身份验证连接。仅支持生成 Authorization Bearer 令牌的身份验证连接；不支持 Basic 认证、mTLS、自定义标头和 URL 密钥认证连接。

- Auth Connection Locator: AuthConnectionLocator
- Environment Auth Connection Locator: EnvironmentAuthConnectionLocator

### CustomLlmRequestHeadersValue

- string
- Conv AI Secret Locator: ConvAiSecretLocator
- Conv AI Dynamic Variable: ConvAiDynamicVariable
- Conv AI Env Var Locator: ConvAiEnvVarLocator

### KnowledgeBaseToolInfo

- `enabled_strategies` (list of enum, optional) — 向模型公开的搜索策略。不能为空。
  - Allowed values: `cat`, `keyword`, `semantic`, `ls`

### BackupLlmDefault

- `preference` ("default", optional)

### BackupLlmDisabled

- `preference` ("disabled", optional)

### BackupLlmOverride

- `order` (list of enum, required)
  - Allowed values: `gpt-4o-mini`, `gpt-4o`, `gpt-4`, `gpt-4-turbo`, `gpt-4.1`, `gpt-4.1-mini`, `gpt-4.1-nano`, `gpt-5`, `gpt-5.1`, `gpt-5.2`, `gpt-5.2-chat-latest`, `gpt-5.4`, `gpt-5.4-mini`, `gpt-5.4-nano`, `gpt-5.5`, `gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-5.6-luna`, `gpt-6-astra`, `gpt-6-sol`, `gpt-6-luna`, `gpt-6.1-sol`, `gpt-5-mini`, `gpt-5-nano`, `gpt-3.5-turbo`, `gemini-1.5-pro`, `gemini-1.5-flash`, `gemini-2.0-flash`, `gemini-2.0-flash-lite`, `gemini-2.5-flash-lite`, `gemini-2.5-flash`, `gemini-3-pro-preview`, `gemini-3-flash-preview`, `gemini-3.1-pro-preview`, `gemini-3.1-flash-lite-preview`, `gemini-3.1-flash-lite`, `gemini-3.5-flash`, `gemini-3.5-flash-lite`, `gemini-3.6-flash`, `gemini-3.7-flash`, `gemini-3.8-flash`, `gemini-4-argon`, `claude-sonnet-4-5`, `claude-opus-4-6`, `claude-opus-4-7`, `claude-opus-4-8`, `claude-opus-5`, `claude-opus-5-5`, `claude-sonnet-4-6`, `claude-sonnet-5`, `claude-sonnet-5-5`, `claude-sonnet-4`, `claude-haiku-4-5`, `claude-haiku-5-5`, `claude-3-7-sonnet`, `claude-3-5-sonnet`, `claude-3-5-sonnet-v1`, `claude-3-haiku`, `grok-beta`, `custom-llm`, `qwen3-4b`, `qwen3-30b-a3b`, `qwen36-35b-a3b`, `qwen35-397b-a17b`, `gpt-oss-20b`, `gpt-oss-120b`, `glm-45-air-fp8`, `glm-52`, `deepseek-v41-flash`, `nemotron-35-super-vl-nvfp4`, `gemini-2.5-flash-preview-09-2025`, `gemini-2.5-flash-lite-preview-09-2025`, `gemini-2.5-flash-preview-05-20`, `gemini-2.5-flash-preview-04-17`, `gemini-2.5-flash-lite-preview-06-17`, `gemini-2.0-flash-lite-001`, `gemini-2.0-flash-001`, `gemini-1.5-flash-002`, `gemini-1.5-flash-001`, `gemini-1.5-pro-002`, `gemini-1.5-pro-001`, `claude-sonnet-4@20250514`, `claude-sonnet-4-5@20250929`, `claude-haiku-4-5@20251001`, `claude-3-7-sonnet@20250219`, `claude-3-5-sonnet@20240620`, `claude-3-5-sonnet-v2@20241022`, `claude-3-haiku@20240307`, `gpt-5-2025-08-07`, `gpt-5.1-2025-11-13`, `gpt-5.2-2025-12-11`, `gpt-5.4-2026-03-05`, `gpt-5.4-mini-2026-03-17`, `gpt-5.4-nano-2026-03-17`, `gpt-5.5-2026-04-23`, `gpt-5-mini-2025-08-07`, `gpt-5-nano-2025-08-07`, `gpt-4.1-2025-04-14`, `gpt-4.1-mini-2025-04-14`, `gpt-4.1-nano-2025-04-14`, `gpt-4o-mini-2024-07-18`, `gpt-4o-2024-11-20`, `gpt-4o-2024-08-06`, `gpt-4o-2024-05-13`, `gpt-4-0613`, `gpt-4-0314`, `gpt-4-turbo-2024-04-09`, `gpt-3.5-turbo-0125`, `gpt-3.5-turbo-1106`, `watt-tool-8b`, `watt-tool-70b`
- `preference` ("override", optional)

### ApiIntegrationWebhookOverrides

- `schema_overrides` (map from string to ApiIntegrationWebhookOverridesSchemaOverridesValue, optional)
- `response_filter_mode` (enum, optional, default: all) — 控制工具响应在对智能体可见前的过滤方式。
  - Allowed values: `all`, `allow`, `hide_all`
- `response_filters` (list of string, optional)
- `request_headers` (map from string to ApiIntegrationWebhookOverridesRequestHeadersValue, optional)

### DynamicVariableAssignment

Configuration for extracting values from tool responses and assigning them to dynamic variables.

- `dynamic_variable` (string, required) — 要分配提取值的动态变量名称
- `value_path` (string, required) — 用于从源中提取值的点表示法路径（例如 'user.name' 或 'data.0.id'）
- `source` ("response", optional) — 提取值的来源。目前仅支持 'response'。
- `sanitize` (boolean, optional, default: false) — 如果为 true，此赋值的值会在发送给 LLM 和转录文本前从工具响应中移除，但仍会用于变量赋值处理。
- `preserve_native_type` (boolean, optional, default: false) — 如果为 true，从工具响应中提取的非标量值（列表、对象）将以原生类型存储，而非转换为 JSON 字符串。启用后，可将提取的数组直接用作列表动态变量。

### DynamicVariablesConfig

- `dynamic_variable_placeholders` (map from string to any, optional) — 动态变量占位符及其值的字典。

### ObjectJsonSchemaPropertyInput

- `property_kind` (enum, optional, default: object)
  - Allowed values: `array`, `object`
- `description` (string, optional, default: )
- `dynamic_variable` (string, optional, default: ) — 设置后，整个参数将在运行时从此动态变量填充。与 description（由 LLM 提供的值）、constant_value 和 is_omitted 互斥。
- `constant_value` (map from string to any, optional) — 设置后，整个对象将在运行时使用此常量 JSON 值。与 description（由 LLM 提供的对象）、dynamic_variable 和 is_omitted 互斥。
- `is_omitted` (boolean, optional, default: false) — 如果为 true，此参数将完全从请求中省略。仅对可选参数有效。与 description、dynamic_variable 和 constant_value 互斥。
- `type` ("object", optional)
- `required` (list of string, optional)
- `properties` (map from string to ObjectJsonSchemaPropertyInputPropertiesValue, optional)
- `required_constraints` (RequiredConstraints, optional) — 适用于必填字段的 anyOf/allOf 组合约束包装器。

### SystemToolConfigInputParams

- `system_tool_type`: `end_call`
- `system_tool_type`: `end_procedure`
  - `procedures` (map from string to EndProcedureToolConfigProceduresValue, optional)
- `system_tool_type`: `knowledge_base`
  - `enabled_strategies` (list of enum, optional)
    - Allowed values: `cat`, `keyword`, `semantic`, `ls`
- `system_tool_type`: `knowledge_base_rag`
- `system_tool_type`: `language_detection`
  - `only_at_conversation_start` (boolean, optional, default: false) — 如果前 2 轮用户发言未发生语言切换，之后的切换尝试将失败，对话将保持当前语言。如果在这几轮中发生语言切换，之后仍可切换。启用此项可降低错误切换的可能性。
- `system_tool_type`: `play_keypad_touch_tone`
  - `suppress_turn_after_dtmf` (boolean, optional, default: false) — 如果为 true，智能体播放 DTMF 音后不会继续生成语音。这可防止智能体语音干扰 IVR 系统。
  - `use_out_of_band_dtmf` (boolean, optional, default: true) — 将 DTMF 音作为带外 RTP 事件（RFC 4733）发送，而非带内音频。仅对通过 SIP 中继导入的号码生效。
- `system_tool_type`: `skip_turn`
  - `wait_timeout_secs` (double, optional, default: -1) — 调用 skip_turn 后，智能体生成上下文跟进前的等待秒数。等待期间，"静默后结束对话"计时器会暂停。-1 可禁用等待：调用 skip_turn 后，智能体会保持静默，直到调用方发言，且该计时器会继续运行。仅适用于语音对话。
- `system_tool_type`: `start_procedure`
  - `procedures` (map from string to StartProcedureToolConfigProceduresValue, optional)
- `system_tool_type`: `transfer_to_agent`
  - `transfers` (list of AgentTransferInput, required)
- `system_tool_type`: `transfer_to_number`
  - `transfers` (list of PhoneNumberTransfer, required)
  - `enable_client_message` (boolean, optional, default: true) — 是否在客户等待转接时播放消息。为保持向后兼容，默认为 true。
- `system_tool_type`: `voicemail_detection`
  - `voicemail_message` (string, optional) — 检测到语音信箱时留下的可选消息。未提供时，检测到语音信箱后将立即结束通话。支持动态变量（例如 \{\{system\_\_time}}、\{\{system\_\_call\_duration\_secs}}、\{\{custom\_variable}}）。

### WebhookToolApiSchemaConfigInput

- `url` (string, required) — 将发送 webhook 的 URL。可包含路径参数，例如 [https://example.com/agents/\{agent\_id}](https://example.com/agents/\{agent_id})
- `request_headers` (map from string to WebhookToolApiSchemaConfigInputRequestHeadersValue, optional) — 请求中应包含的请求头
- `method` (enum, optional, default: GET) — webhook 使用的 HTTP 方法
  - Allowed values: `GET`, `POST`, `PUT`, `PATCH`, `DELETE`
- `path_params_schema` (map from string to LiteralJsonSchemaProperty, optional) — 路径参数的 Schema（如有）。键应与 URL 中的占位符匹配。
- `query_params_schema` (QueryParamsJsonSchemaInput, optional) — 查询参数的 Schema（如有）。这些参数将作为查询参数添加到 URL 末尾。注意：查询参数中的属性必须全部为字面量类型。
- `request_body_schema` (ObjectJsonSchemaPropertyInput, optional) — 请求正文参数的 Schema（如有）。用于 POST/PATCH/PUT 请求。该 Schema 应为作为 JSON 正文发送的对象。
- `response_body_schema` (ObjectJsonSchemaPropertyInput, optional) — 描述预期响应正文结构的 Schema。仅用于文档，不会提供给 LLM。
- `response_filter` (ResponseFilter, optional) — 在 LLM 查看回复前应用的可选允许列表过滤器，避免大型回复污染上下文。默认为完整回复。
- `content_type` (enum, optional, default: application/json) — Content type for the request body. Only applies to POST/PUT/PATCH requests.
  - Allowed values: `application/json`, `application/x-www-form-urlencoded`
- `auth_resolved_params` (list of string, optional) — 从身份验证连接而非 path_params_schema 解析的 URL 占位符（例如通过 UrlSecretAuthConnection 注入的密钥）。
- `auth_connection` (WebhookToolApiSchemaConfigInputAuthConnection, optional) — 用于向此 webhook 进行身份验证的可选认证连接

### ConvAiSecretLocator

用于引用智能体密钥存储中的密钥。

- `secret_id` (string, required)

### ConvAiEnvVarLocator

用于通过标签引用环境变量。

- `env_var_label` (string, required)

### AuthConnectionLocator

用于引用工作区身份验证连接存储中的身份验证连接。

- `auth_connection_id` (string, required)

### EnvironmentAuthConnectionLocator

通过标签引用类型为 'auth_connection' 的环境变量。 运行时会解析为当前环境的认证连接， 并回退到默认环境。

- `env_var_label` (string, required)

### ConvAiDynamicVariable

用于引用动态变量。

- `variable_name` (string, required)

### ApiIntegrationWebhookOverridesSchemaOverridesValue

- `source`: `constant`
  - `constant_value` (ConstantSchemaOverrideConstantValue, optional) — 要使用的常量值
- `source`: `dynamic_variable`
  - `dynamic_variable` (string, required) — 要使用的动态变量名称
- `source`: `llm`
  - `prompt` (string, optional) — LLM 的提示词覆盖内容。未提供时，使用原始架构描述。
- `source`: `omit`

### ApiIntegrationWebhookOverridesRequestHeadersValue

- string
- Conv AI Dynamic Variable: ConvAiDynamicVariable

### ObjectJsonSchemaPropertyInputPropertiesValue

- Literal JSON Schema Property: LiteralJsonSchemaProperty
- Object JSON Schema Property Input: ObjectJsonSchemaPropertyInput
- Array JSON Schema Property Input: ArrayJsonSchemaPropertyInput

### RequiredConstraints

适用于必填字段的 anyOf/allOf 组合约束包装器。

- `any_of` (list of RequiredConstraint, optional)
- `all_of` (list of RequiredConstraint, optional)

### EndProcedureToolConfigProceduresValue

- Procedure Version Ref: ProcedureVersionRef
- Procedure Draft Ref: ProcedureDraftRef

### StartProcedureToolConfigProceduresValue

- Procedure Version Ref: ProcedureVersionRef
- Procedure Draft Ref: ProcedureDraftRef

### AgentTransferInput

- `condition` (string, required)
- `agent_id` (string, optional)
- `branch_id` (string, optional)
- `node_id` (string, optional)
- `delay_ms` (integer, optional, default: 0)
- `transfer_message` (string, optional)
- `enable_transferred_agent_first_message` (boolean, optional, default: false)
- `is_workflow_node_transfer` (boolean, optional, default: false)
- `preserve_client_tts_overrides` (boolean, optional, default: false) — 定义是否将 TTS 客户端覆盖设置沿用至被转接的智能体。
- `preserve_voice_settings` (boolean, optional, default: false) — 定义是否将基础音色、TTS 模型和音色设置沿用至被转接的智能体。

### PhoneNumberTransfer

- `transfer_destination` (PhoneNumberTransferTransferDestination, required)
- `condition` (string, required)
- `custom_sip_headers` (list of PhoneNumberTransferCustomSipHeadersItem, optional) — 转接通话时包含的自定义 SIP 请求头。每个请求头可以是静态值或动态变量引用。
- `transfer_type` (enum, optional, default: conference)
  - Allowed values: `blind`, `conference`, `sip_refer`
- `sip_refer_play_dialtone` (boolean, optional, default: true) — 设为 True 时，在 SIP REFER 转接完成期间，原始通话线路会播放回铃音。该音调会通过 RTP 传输给执行 REFER 的 SIP 对端，因此如果接收系统（如 SBC 或呼叫中心）不应听到该音调，请禁用此项。禁用后，呼叫方在转接完成前将听到静音。仅适用于 SIP REFER 转接。
- `uui` (UuiTransferConfig, optional) — 附加到 SIP REFER 转接的用户间信息（User-to-User Information，RFC 7433）。可在转接过程中携带 CRM 标识符或升级原因等通话上下文。
- `post_dial_digits` (PhoneNumberTransferPostDialDigits, optional) — 通话接通后发送的 DTMF 按键（例如，分机号使用 'ww1234'）。可以是静态值或动态变量引用。使用 'w' 表示暂停 0.5 秒。仅支持 Twilio 转接。
- `phone_number` (string, optional, deprecated)

### WebhookToolApiSchemaConfigInputRequestHeadersValue

- string
- Conv AI Secret Locator: ConvAiSecretLocator
- Conv AI Dynamic Variable: ConvAiDynamicVariable
- Conv AI Env Var Locator: ConvAiEnvVarLocator

### LiteralJsonSchemaProperty

字面量 JSON 类型的 Schema 属性。重要提示：以下字段只能设置其中一个：description（LLM 提供值）、dynamic_variable（来自变量的值）、is_system_provided（系统提供值）、constant_value（固定值）或 is_omitted（省略参数）。这些字段互斥。

- `type` (LiteralJsonSchemaPropertyType, required)
- `description` (string, optional, default: ) — 属性描述。设置后，LLM 将根据此描述提供值。不能与 dynamic_variable、is_system_provided、constant_value 和 is_omitted 同时使用。
- `enum` (list of string, optional) — List of allowed string values for string type parameters
- `is_system_provided` (boolean, optional, default: false) — 如果为 true，该值将在运行时由系统填充。供 API Integration Webhook 工具用于模板化。与 description、dynamic_variable、constant_value 和 is_omitted 互斥。
- `dynamic_variable` (string, optional, default: ) — 用于此属性值的动态变量名称。不能与 description、is_system_provided、constant_value 和 is_omitted 同时使用。
- `allowed_values` (AllowedValues, optional) — 针对 LLM 提供值的服务端拒绝保护：运行时会拒绝此对象指定的允许集合以外的任何值，且不会将该集合以枚举形式提供给 LLM。仅当值来源为 `description` 时支持；与 dynamic_variable、is_system_provided、constant_value 或 is_omitted 结合使用会被拒绝。
- `constant_value` (LiteralJsonSchemaPropertyConstantValue, optional) — 用于此属性的常量值。与 description、dynamic_variable、is_system_provided 和 is_omitted 互斥。
- `is_omitted` (boolean, optional, default: false) — 如果为 true，此参数将完全从请求中省略。仅对可选参数有效。与 description、dynamic_variable、is_system_provided 和 constant_value 互斥。
- `allowed_values_dynamic_variable` (string, optional, default: , deprecated) — 已弃用：请改用 `allowed_values`。设置后，LLM 会提供值，但运行时会拒绝此动态变量持有的列表中不存在的任何值（必须是 JSON 数组，例如 ["ws_alpha", "ws_beta"]）。用于让 LLM 从服务器验证的集合中选择（例如当前用户允许访问的 ID）。需要 description；不能与 dynamic_variable、is_system_provided、constant_value 和 is_omitted 同时使用。

### QueryParamsJsonSchemaInput

- `properties` (map from string to LiteralJsonSchemaProperty, required)
- `required` (list of string, optional)

### ResponseFilter

Configuration for filtering tool responses before they are visible to the agent.

- `mode` (enum, optional, default: all) — 控制工具响应的过滤方式。'all' 返回完整响应，'allow' 仅返回指定路径，'hide_all' 隐藏整个响应。
  - Allowed values: `all`, `allow`, `hide_all`
- `filters` (list of string, optional) — 当 mode 为 'allow' 时要包含的点表示法路径（例如 ['ticket.id', 'ticket.status']）。
- `content_type` ("application/json", optional) — Content type for response filtering. Only 'application/json' responses are filtered.

### WebhookToolApiSchemaConfigInputAuthConnection

用于向此 webhook 进行身份验证的可选认证连接

- Auth Connection Locator: AuthConnectionLocator
- Environment Auth Connection Locator: EnvironmentAuthConnectionLocator

### ArrayJsonSchemaPropertyInput

- `property_kind` (enum, optional, default: array)
  - Allowed values: `array`, `object`
- `description` (string, optional, default: )
- `dynamic_variable` (string, optional, default: ) — 设置后，整个参数将在运行时从此动态变量填充。与 description（由 LLM 提供的值）、constant_value 和 is_omitted 互斥。
- `constant_value` (list of any, optional) — 设置后，整个数组将在运行时使用此常量值。与 description（由 LLM 提供的数组）、dynamic_variable 和 is_omitted 互斥。
- `is_omitted` (boolean, optional, default: false) — 如果为 true，此参数将完全从请求中省略。仅对可选参数有效。与 description、dynamic_variable 和 constant_value 互斥。
- `type` ("array", optional)
- `items` (ArrayJsonSchemaPropertyInputItems, optional) — 数组元素的 Schema。

### RequiredConstraint

必须全部存在才能满足此约束的一组字段。

- `required` (list of string, required)

### ProcedureVersionRef

- `procedure_id` (string, required) — 流程 ID
- `version_id` (string, required) — 过程版本的版本 ID。

### ProcedureDraftRef

- `procedure_id` (string, required) — 流程 ID
- `version_id` (any, optional)

### PhoneNumberTransferTransferDestination

- `type`: `phone`
  - `phone_number` (string, required)
- `type`: `phone_dynamic_variable`
  - `phone_number` (string, required)
- `type`: `sip_uri`
  - `sip_uri` (string, required)
- `type`: `sip_uri_dynamic_variable`
  - `sip_uri` (string, required)

### PhoneNumberTransferCustomSipHeadersItem

- `type`: `dynamic`
  - `key` (string, required) — SIP 请求头名称（例如 'X-Customer-ID'）
  - `value` (string, required) — 要解析的动态变量名称
- `type`: `static`
  - `key` (string, required) — SIP 请求头名称（例如 'X-Customer-ID'）
  - `value` (string, required) — 标头值

### PhoneNumberTransferPostDialDigits

- `type`: `dynamic`
  - `value` (string, required) — 要解析的动态变量名称
- `type`: `static`
  - `value` (string, required) — 通话接通后发送的 DTMF 按键（例如，分机号使用 'ww1234'）

### LiteralJsonSchemaPropertyType

- "boolean"
- "string"
- "integer"
- "number"
- list of string

### AllowedValues

- `dynamic_variable` (string, required) — 动态变量名称，必须解析为包含允许值的 JSON 数组，例如 ["ws_alpha", "ws_beta"]。系统变量仅在解析为列表时有效。

### LiteralJsonSchemaPropertyConstantValue

用于此属性的常量值。与 description、dynamic_variable、is_system_provided 和 is_omitted 互斥。

- string
- integer
- double
- boolean

### ArrayJsonSchemaPropertyInputItems

数组元素的 Schema。

- Literal JSON Schema Property: LiteralJsonSchemaProperty
- Object JSON Schema Property Input: ObjectJsonSchemaPropertyInput
- Array JSON Schema Property Input: ArrayJsonSchemaPropertyInput

## Examples

**Request**

```json
{
  "parent_version_id": "parent_version_id",
  "name": "name",
  "description": "description"
}
```

**Response**

```json
{
  "created_branch_id": "created_branch_id",
  "created_version_id": "created_version_id"
}
```

**SDK Code**

```python
import requests

url = "https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/branches"

payload = {
    "parent_version_id": "parent_version_id",
    "name": "name",
    "description": "description"
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/branches';
const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: '{"parent_version_id":"parent_version_id","name":"name","description":"description"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/branches"

	payload := strings.NewReader("{\n  \"parent_version_id\": \"parent_version_id\",\n  \"name\": \"name\",\n  \"description\": \"description\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/branches")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"parent_version_id\": \"parent_version_id\",\n  \"name\": \"name\",\n  \"description\": \"description\"\n}"

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/branches")
  .header("Content-Type", "application/json")
  .body("{\n  \"parent_version_id\": \"parent_version_id\",\n  \"name\": \"name\",\n  \"description\": \"description\"\n}")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/branches', [
  'body' => '{
  "parent_version_id": "parent_version_id",
  "name": "name",
  "description": "description"
}',
  'headers' => [
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/branches");
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"parent_version_id\": \"parent_version_id\",\n  \"name\": \"name\",\n  \"description\": \"description\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["Content-Type": "application/json"]
let parameters = [
  "parent_version_id": "parent_version_id",
  "name": "name",
  "description": "description"
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/branches")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```