---
title: "更新 Deployment"
method: POST
path: "/agent/managed/v1/deployments/{deploymentId}"
tags: ["Managed Agents - Deployment"]
---

# 更新 Deployment

`POST /agent/managed/v1/deployments/{deploymentId}`

## Request

- Base URL: `https://agent-api.bigmodel.cn/api`
- URL: `https://agent-api.bigmodel.cn/api/agent/managed/v1/deployments/{deploymentId}`
- Auth: HTTP bearer

更新 Deployment 的配置、任务输入与调度，或重新固定同一 Agent 的版本。

<Accordion title="使用说明">

更新指定 Deployment 的可变配置。支持 `name`、`description`、`metadata`、`initial_events`、`environment_id`、`vault_ids`、`resources`、`schedule` 和 `agent`；`agent` 只能重新固定同一个 Agent 的版本或覆盖配置，不能切换 Agent ID。`schedule: null` 会改为仅手动触发，`resources: null` 和 `metadata: null` 会清空对应配置，`environment_id: null` 会保留原值。已归档 Deployment 不可更新。

</Accordion>

## Path parameters

- `deploymentId` string, required

## Headers

- `zai-version` '2026-05-26', required
- `zai-beta` string, required

## Request body

- ManagedDeploymentUpdateRequest
  - `name` string: 替换名称；trim 后不能为空，省略时保持不变。
  - `agent` union: 可传 Agent ID 字符串、固定版本引用，或带会话级覆盖的 Agent 引用。
    - string
    - object
      - `type` 'agent', required: 固定为 agent。
      - `id` string, required: Agent ID。
      - `version` integer: 固定使用的 Agent 版本；省略时固定创建请求时的当前版本。
    - object
      - `type` 'agent_with_overrides', required: 固定为 agent_with_overrides。
      - `id` string, required: Agent ID。
      - `version` integer: 基准 Agent 版本；省略时固定创建请求时的当前版本。
      - `model` union: 模型 ID，或包含推理强度与速度的模型配置。当前支持 glm-5.3、glm-5.3-flash 与 glm-5.3-flashx。使用字符串简写时，服务端按模型补齐默认 effort，并将 speed 补为 standard。
        - 'glm-5.3' | 'glm-5.3-flash' | 'glm-5.3-flashx'
        - object
          - `id` 'glm-5.3' | 'glm-5.3-flash' | 'glm-5.3-flashx', required
          - `effort` union: 输入兼容字符串/对象/null；glm-5.3 默认 max，flash/flashx 默认 high。
            - 'low' | 'high' | 'max'
            - object
              - …
          - `speed` 'standard', nullable: 当前仅支持 standard；省略或传 null 时也使用 standard。
      - `system` string, nullable: 覆盖系统提示词；null 表示清空，省略时继承 Agent 版本。
      - `tools` ManagedAgentToolsetInput[], nullable: 整体覆盖工具列表；null 或空数组表示清空，省略时继承 Agent 版本。MCP 映射约束在合并后的最终配置上校验。
        - union
          - object
            - `type` 'agent_toolset_20260601', required
            - `default_config` ManagedToolDefaultConfigInput
              - …
            - `configs` ManagedBuiltinToolConfigInput[]: 逐工具覆盖；省略时为空，name 不得重复。
              - …
          - object
            - `type` 'mcp_toolset', required
            - `mcp_server_name` string, required: 必须精确匹配 mcp_servers 中唯一一个 Server 的 name。
            - `default_config` ManagedToolDefaultConfigInput
              - …
            - `configs` ManagedMcpToolConfigInput[]: 逐 MCP 工具覆盖；省略时为空，name 不得重复。
              - …
          - object
            - `type` 'custom', required
            - `name` string, required: 自定义工具名；仅允许字母、数字、下划线和连字符，不得以 mcp__ 开头，且同一配置内不得重复。
            - `description` string, required
            - `input_schema` ManagedCustomToolInputSchema, required
              - …
      - `skills` ManagedSkillReference[], nullable: 整体覆盖 Skill 列表；null 或空数组表示清空，省略时继承 Agent 版本。最终配置含 Skill 时必须含 agent_toolset_20260601。
        - `type` 'custom' | 'zai', required: custom 表示当前所有者创建的 Skill；zai 表示平台内置 Skill。
        - `skill_id` string, required: Skill ID；必须存在且当前身份可访问。
        - `version` string, nullable: 可省略/null/latest。新协议在 Session 创建/Deployment 触发时固定，旧协议每次沙箱启动解析；具体 ID 固定对应版本。
      - `mcp_servers` ManagedMcpServer[], nullable: 整体覆盖 MCP Server；null 或空数组表示清空，省略时继承 Agent 版本。最终配置必须与 mcp_toolset 一一对应。
        - `type` 'url', required: 当前只支持 url。
        - `name` string, required: Server 名称，长度 1–255；同一 mcp_servers 数组内不得重复。
        - `url` string, uri, required: 公开 HTTPS Streamable HTTP URL；不得包含凭据、fragment、空 query 或旧式 SSE 路径。
  - `environment_id` string, nullable: 重新绑定 Environment。字符串值必须指向 Agent 所有者名下未归档的 Environment；传 `null` 会保留原值。
  - `schedule` ManagedScheduleInput: Cron 调度配置。表达式必须是合法的五段 cron，且相邻执行时间需满足平台配置的最小间隔；当前仅支持 Asia/Shanghai 时区。
    - `type` 'cron', required: 固定为 cron。
    - `expression` string, required: 五段 cron 表达式；trim 后不能为空，必须存在未来触发时间，且相邻触发间隔不得小于平台配置值。
    - `timezone` 'Asia/Shanghai', nullable: 当前仅支持 Asia/Shanghai；省略或传 null 时使用该值。
  - `initial_events` ManagedDeploymentInitialEvent[]: 整体替换每次运行的初始消息；必须含 1–50 条 user.message。
    - `type` 'user.message', required: 固定为 user.message。
    - `content` ManagedInitialContentBlock[], required: 非空内容块数组；初始消息允许 text/image，普通消息还允许 document。图片最多 50 张；总量受请求体限制。
      - union
        - object
          - `type` 'text', required: 固定为 text。
          - `text` string, required: 非空文本内容。
        - object
          - `type` 'image', required: 固定为 image。
          - `source` union, required: 图片来源为 base64、url 或 file。每事件最多 50 张，单张最多 50 MiB；1–20 张时宽高各不超过 8000 px，21–50 张时各不超过 2000 px。图片 Base64 总量最多 112 MiB，带图请求体最多 128 MiB。
            - object
              - …
            - object
              - …
            - object
              - …
  - `description` string, nullable: 替换用途说明；非字符串值（包括 null）会清空，省略时保持不变。
  - `metadata` object, nullable: 整体替换 metadata；null 表示清空，省略时保持不变。键名不超过 64 字符，值为不超过 512 字符的字符串。
  - `vault_ids` string[]: 整体替换 Vault ID；省略时保持不变。
  - `resources` ManagedDeploymentResourceInput[], nullable: 整体替换资源；null 表示清空，省略时保持不变。
    - union
      - object
        - `type` 'memory_store', required: 固定为 memory_store。
        - `memory_store_id` string, required: Agent 所有者名下处于 active 状态的 Memory Store ID。
        - `access` 'read_only' | 'read_write': 挂载权限；省略时由 Memory 服务按 read_write 处理。
        - `instructions` string: 提供给 Agent 的使用说明；省略时不设置。
      - object
        - `type` 'file', required: 固定为 file。
        - `file_id` string, required: 已存在且归当前资源所有者所有的 File ID。
        - `mount_path` string, nullable: 沙箱内挂载路径；省略或传 null 时默认为 /mnt/session/uploads/{file_id}。路径会归一化到 /mnt/session/uploads 下，不能逃逸该目录，UTF-8 总长度不超过 1024 字节。

## Response `200`

请求成功。

- ManagedDeployment
  - `id` string, required
  - `type` 'deployment', required
  - `name` string, required
  - `agent` ManagedDeploymentAgent, required
    - `type` 'agent', required
    - `id` string, required
    - `version` integer, required
  - `environment_id` string, required: Deployment 绑定的 Environment ID。旧数据缺失该字段时可能返回内部兼容值 `env_default`。
  - `description` string, nullable, required: 用途说明。
  - `metadata` ManagedMetadata, required: 客户端自定义元数据；省略时默认为空对象。最多 16 个键，键名长度不超过 64 字符，值必须是长度不超过 512 字符的字符串。
  - `resources` ManagedDeploymentResourceInput[], required
    - union
      - object
        - `type` 'memory_store', required: 固定为 memory_store。
        - `memory_store_id` string, required: Agent 所有者名下处于 active 状态的 Memory Store ID。
        - `access` 'read_only' | 'read_write': 挂载权限；省略时由 Memory 服务按 read_write 处理。
        - `instructions` string: 提供给 Agent 的使用说明；省略时不设置。
      - object
        - `type` 'file', required: 固定为 file。
        - `file_id` string, required: 已存在且归当前资源所有者所有的 File ID。
        - `mount_path` string, nullable: 沙箱内挂载路径；省略或传 null 时默认为 /mnt/session/uploads/{file_id}。路径会归一化到 /mnt/session/uploads 下，不能逃逸该目录，UTF-8 总长度不超过 1024 字节。
  - `schedule` ManagedScheduleResponse, required
    - `type` 'cron', required
    - `expression` string, required
    - `timezone` 'Asia/Shanghai', required
    - `last_run_at` string, nullable, required: 上次运行时间。
    - `upcoming_runs_at` string[], required: 即将触发的计划时间。下次运行看数组第一项；manual-only 时整个 schedule 为 null。
  - `initial_events` ManagedDeploymentInitialEvent[], required
    - `type` 'user.message', required: 固定为 user.message。
    - `content` ManagedInitialContentBlock[], required: 非空内容块数组；初始消息允许 text/image，普通消息还允许 document。图片最多 50 张；总量受请求体限制。
      - union
        - object
          - `type` 'text', required: 固定为 text。
          - `text` string, required: 非空文本内容。
        - object
          - `type` 'image', required: 固定为 image。
          - `source` union, required: 图片来源为 base64、url 或 file。每事件最多 50 张，单张最多 50 MiB；1–20 张时宽高各不超过 8000 px，21–50 张时各不超过 2000 px。图片 Base64 总量最多 112 MiB，带图请求体最多 128 MiB。
            - object
              - …
            - object
              - …
            - object
              - …
  - `status` 'active' | 'paused', required
  - `paused_reason` union, required
    - object
      - `type` 'manual', required
    - object
      - `type` 'error', required
      - `error` object, required
        - `type` 'environment_archived_error' | 'environment_not_found_error' | 'file_not_found_error' | 'memory_store_archived_error' | 'vault_archived_error' | 'vault_not_found_error', required
  - `vault_ids` string[], required
  - `archived_at` string, nullable, required: 归档时间。
  - `created_at` string, date-time, required: 创建时间。
  - `updated_at` string, date-time, required: 更新时间。

## Other responses

- `default`: 请求失败。

## Changes

- **2026-11-03** `7fd61aa7f811`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/bigmodel/apis/zhipu-ai-api/changes/agent/managed/v1/deployments/:deploymentId/post.md)

---

[API](https://skmtc.dev/bigmodel/apis/zhipu-ai-api.md) - [All operations](https://skmtc.dev/bigmodel/apis/zhipu-ai-api/llms.txt) - [OpenAPI document](https://skmtc.dev/bigmodel/apis/zhipu-ai-api/revisions/f2be7c0fcbb9?raw)