POST https://ark.cn-beijing.volces.com/api/v3/deployments/{deployment_id}
调整 Deployment 的运行配置，例如更换 Agent、修改定时计划、增减挂载资源或标签。
更新后，接下来创建的 Run 使用新配置；已经受理的 Run 和已创建的 Session 继续使用更新前的配置，不受本次更新影响。请求中省略的字段保持原值；数组字段（如挂载资源、标签、Vault ID）整体替换为请求中的新列表。
鉴权#
本接口支持鉴权方式如下，详情请参见 Base URL 及鉴权。
- API Key 鉴权，请在 API Key 管理 页面，获取长效 API Key。
请求参数#
Path 参数#
deployment_id string 必选 | Deployment ID
要更新的 Deployment ID。
Body 参数#
name string | 名称
替换 Deployment 名称，用于识别这份重复运行配置。不能传空字符串。
description string | 描述
替换 Deployment 描述。传 null 或空字符串时清空描述。
agent string / object | Agent 引用
替换后续 Run 使用的 Agent。可直接传入 Agent ID；需要固定 Agent 版本时，传入 Agent 引用对象并设置 id 和 version。已受理的 Run 继续使用原快照。
Agent ID string
直接传入 Agent ID，Deployment 会固定请求受理时的当前有效版本。
Agent 引用 object
Agent 引用对象。通过 id 指定 Agent，通过 version 固定每次运行使用的 Agent 版本；省略 version 时固定当前有效版本。
id string 必选 | Agent ID
agent.id
要用于创建或更新 Deployment 的 Agent ID。
type string 必选 | 引用类型
agent.type
引用类型，固定为 agent。
version integer | Agent 版本
agent.version
每次运行使用的 Agent 版本号；省略时固定当前有效版本。
environment_id string | Environment ID
替换后续 Run 使用的 Environment ID。不能传 null 或空字符串。
initial_events object[] | 初始事件
整体替换每次运行创建新 Session 后发送的启动事件模板。支持 user.message 事件，字段结构请参见 会话事件结构参考。
不能传 null 或空数组；已受理的 Run 继续使用原快照。
用户消息 object
用户消息事件。每次运行创建 Session 后，平台会把该消息作为启动任务的第一条用户输入发送给 Agent。
content object[] 必选 | 消息内容
type string 必选 | 事件类型
initial_events.type
事件类型，固定为 user.message。
schedule object | 定时计划
整体替换定时计划。传 null 时移除计划，保留手动运行能力。
expression string 必选 | Cron 表达式
schedule.expression
五段式 cron 表达式，格式为 分钟 小时 日期 月份 星期。例如 0 9 * * 1-5 表示在配置时区的工作日 09:00 触发；不支持秒、年份和 @daily 等快捷写法。星期字段支持数字 0-7（0 和 7 均表示周日）及英文简写 SUN~SAT。
timezone string 必选 | 时区
schedule.timezone
cron 表达式使用的 IANA 时区，例如 Asia/Shanghai、UTC 或 America/New_York。平台按该时区计算计划触发时间。
type string 必选 | 计划类型
schedule.type
计划类型，固定为 cron。
resources object[] | 挂载资源
整体替换挂载资源。传 null 或空数组时清空资源。
type string 必选 | 资源类型
resources.type
资源类型。file 表示通过 Files API 上传并挂载到 Session 的文件；memory_store 表示挂载到 Session 的记忆库；tos 表示挂载到 Session 的 TOS 对象目录。
access string | 访问权限
resources.access
每次运行创建的 Session 对该资源的访问权限。read_only 表示智能体只能读取资源；read_write 表示智能体可以读取和修改支持写入的资源。
file_id string | 文件 ID
resources.file_id
当 type 为 file 时，表示要挂载到 Session 的文件 ID，通过 Files API 上传文件后获得。
memory_store_id string | 记忆库 ID
resources.memory_store_id
当 type 为 memory_store 时，表示要挂载到 Session 的记忆库 ID。
mount_path string | 挂载路径
resources.mount_path
该资源在每次运行创建的 Session 运行环境中的挂载路径。
tos_bucket string | TOS 存储桶
resources.tos_bucket
当 type 为 tos 时，表示待挂载目录所在的 TOS 存储桶名称。
tos_key string | TOS 目录前缀
resources.tos_key
当 type 为 tos 时，表示 TOS 中待挂载目录的对象前缀。前缀必须以 / 结尾。
tos_region string | TOS 地域
resources.tos_region
当 type 为 tos 时，表示源存储桶所在地域的 Region ID。
vault_ids string[] | 保管库 ID
整体替换 Vault ID 列表。传 null 或空数组时清空列表。
tags object[] | 标签
整体替换标签。传 null 或空数组时清空标签。
key string 必选 | 标签键
tags.key
标签键，用于标识分类维度。
value string | 标签值
tags.value
标签值，用于记录该分类维度的具体内容。
响应参数#
agent object | Agent 引用
Deployment 固定使用的 Agent 和版本。
id string | Agent ID
agent.id
Deployment 使用的 Agent ID。
type string | 对象类型
agent.type
Agent 引用类型，固定为 agent。
version integer | Agent 版本
agent.version
Deployment 固定使用的 Agent 版本号。
created_at string | 创建时间
Deployment 创建时间，采用 RFC 3339 格式。
environment_id string | Environment ID
每次运行使用的 Environment ID。
id string | Deployment ID
Deployment 的唯一标识符，以 depl- 开头，形如 depl-<14位时间戳>-<10位随机字符>。
initial_events object[] | 初始事件
每次运行创建新 Session 后发送的启动事件模板。
用户消息 object
用户消息事件。每次运行创建 Session 后，平台会把该消息作为启动任务的第一条用户输入发送给 Agent。
content object[] | 消息内容
type string | 事件类型
initial_events.type
事件类型，固定为 user.message。
name string | 名称
Deployment 名称。
resources object[] | 挂载资源
每次运行创建 Session 时使用的资源配置。
type string | 资源类型
resources.type
资源类型。file 表示通过 Files API 上传并挂载到 Session 的文件；memory_store 表示挂载到 Session 的记忆库；tos 表示挂载到 Session 的 TOS 对象目录。
access string | 访问权限
resources.access
每次运行创建的 Session 对该资源的访问权限。read_only 表示智能体只能读取资源；read_write 表示智能体可以读取和修改支持写入的资源。
file_id string | 文件 ID
resources.file_id
当 type 为 file 时，表示要挂载到 Session 的文件 ID，通过 Files API 上传文件后获得。
memory_store_id string | 记忆库 ID
resources.memory_store_id
当 type 为 memory_store 时，表示要挂载到 Session 的记忆库 ID。
mount_path string | 挂载路径
resources.mount_path
该资源在每次运行创建的 Session 运行环境中的挂载路径。
tos_bucket string | TOS 存储桶
resources.tos_bucket
当 type 为 tos 时，表示待挂载目录所在的 TOS 存储桶名称。
tos_key string | TOS 目录前缀
resources.tos_key
当 type 为 tos 时，表示 TOS 中待挂载目录的对象前缀。前缀必须以 / 结尾。
tos_region string | TOS 地域
resources.tos_region
当 type 为 tos 时，表示源存储桶所在地域的 Region ID。
status string | 运行状态
Deployment 的调度状态。paused 不接受定时触发，但仍允许手动运行；archived_at 有值时已归档，无论该字段取值如何都不再接受任何触发。取值：active / paused。
tags object[] | 标签
Deployment 标签列表。
key string | 标签键
tags.key
标签键，用于标识分类维度。
value string | 标签值
tags.value
标签值，用于记录该分类维度的具体内容。
type string | 对象类型
对象类型，固定为 deployment。
updated_at string | 更新时间
Deployment 最近更新时间，采用 RFC 3339 格式。
vault_ids string[] | 保管库 ID
每次运行创建 Session 时绑定的 Vault ID 列表。
archived_at string | 归档时间
Deployment 归档时间，采用 RFC 3339 格式。未归档时不返回该字段。
description string | 描述
Deployment 描述。未设置时不返回该字段。
paused_reason object | 暂停原因
Deployment 暂停的原因。status 为 active 时不返回该字段。
type string | 暂停类型
paused_reason.type
暂停原因类型。manual 表示调用暂停接口；error 表示 Run 遇到不可恢复错误后自动暂停。
error object | 暂停错误
paused_reason.error
自动暂停时的错误信息。type 为 manual 时不返回该字段。
message string | 错误信息
paused_reason.error.message
用于定位失败原因的可读信息。
type string | 错误类型
paused_reason.error.type
错误分类。
schedule object | 定时计划
定时触发计划。仅支持手动运行时不返回该字段。
expression string | Cron 表达式
schedule.expression
五段式 cron 表达式，格式为 分钟 小时 日期 月份 星期。例如 0 9 * * 1-5 表示在配置时区的工作日 09:00 触发；不支持秒、年份和 @daily 等快捷写法。星期字段支持数字 0-7（0 和 7 均表示周日）及英文简写 SUN~SAT。
timezone string | 时区
schedule.timezone
cron 表达式使用的 IANA 时区，例如 Asia/Shanghai、UTC 或 America/New_York。平台按该时区计算计划触发时间。
type string | 计划类型
schedule.type
计划类型，固定为 cron。
upcoming_runs_at string[] | 后续计划时间
schedule.upcoming_runs_at
接下来最多 5 个理论计划时间，采用 RFC 3339 格式，不包含调度抖动。Deployment 暂停时仍返回按当前计划计算的时间；归档后返回空数组。
last_run_at string | 最近定时运行时间
schedule.last_run_at
最近一次定时 Run 的理论计划时间，采用 RFC 3339 格式。尚未定时触发时不返回该字段；手动 Run 不更新该字段。