---
title: "更新 Agent"
method: POST
path: "/agent/managed/v1/agents/{agentId}"
tags: ["Managed Agents - Agent"]
---

# 更新 Agent

`POST /agent/managed/v1/agents/{agentId}`

## Request

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

更新 Agent 配置并生成新版本，支持通过 `version` 防止并发覆盖。

<Accordion title="使用说明">

更新指定 Agent 并生成新的不可变版本。可带当前 `version`；不一致时返回 409，避免覆盖刚发生的改动。仅所有者可更新，已归档 Agent 不可更新。MCP Server 与 `mcp_toolset` 必须按名称一一对应。

</Accordion>

## Path parameters

- `agentId` string, required

## Headers

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

## Request body

- ManagedAgentUpdateRequest
  - `version` number: 可选。带上当前版本号时，若期间配置已被他人改过则返回 409；省略则按本次提交覆盖。须为正整数。
  - `name` string: 替换 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
          - `type` 'low' | 'high' | 'max', required
      - `speed` 'standard', nullable: 当前仅支持 standard；省略或传 null 时也使用 standard。
  - `system` string, nullable: 替换系统提示词；null 表示清空，省略时保持不变。
  - `description` string, nullable: 替换用途说明；null 表示清空，省略时保持不变。
  - `tools` ManagedAgentToolsetInput[], nullable: 整体替换工具列表；null 或空数组表示清空，省略时保持不变。若包含 mcp_toolset，必须同时提交 mcp_servers。
    - union
      - object
        - `type` 'agent_toolset_20260601', required
        - `default_config` ManagedToolDefaultConfigInput
          - `enabled` boolean, nullable: 工具集默认是否启用；省略或传 null 时为 true。
          - `permission_policy` ManagedPermissionPolicy
            - `type` 'always_allow' | 'always_ask', required: 工具调用权限策略。always_allow 表示无需确认；always_ask 表示每次调用前请求确认。
        - `configs` ManagedBuiltinToolConfigInput[]: 逐工具覆盖；省略时为空，name 不得重复。
          - union
            - object: type/name 若同时提供必须相等。
              - …
            - object: allowed_domains/blocked_domains 暂不接受：配置时 400，不是静默失效。
              - …
            - object: allowed_domains/blocked_domains 暂不接受：配置时 400，不是静默失效。
              - …
      - object
        - `type` 'mcp_toolset', required
        - `mcp_server_name` string, required: 必须精确匹配 mcp_servers 中唯一一个 Server 的 name。
        - `default_config` ManagedToolDefaultConfigInput
          - `enabled` boolean, nullable: 工具集默认是否启用；省略或传 null 时为 true。
          - `permission_policy` ManagedPermissionPolicy
            - `type` 'always_allow' | 'always_ask', required: 工具调用权限策略。always_allow 表示无需确认；always_ask 表示每次调用前请求确认。
        - `configs` ManagedMcpToolConfigInput[]: 逐 MCP 工具覆盖；省略时为空，name 不得重复。
          - `name` string, required: MCP Server 实际公开的工具名；同一 configs 数组内不得重复。
          - `enabled` boolean, nullable: 覆盖当前 MCP 工具的 enabled；省略或传 null 时继承 default_config。
          - `permission_policy` ManagedPermissionPolicy
            - `type` 'always_allow' | 'always_ask', required: 工具调用权限策略。always_allow 表示无需确认；always_ask 表示每次调用前请求确认。
      - object
        - `type` 'custom', required
        - `name` string, required: 自定义工具名；仅允许字母、数字、下划线和连字符，不得以 mcp__ 开头，且同一配置内不得重复。
        - `description` string, required
        - `input_schema` ManagedCustomToolInputSchema, required
          - `type` 'object', required: 固定为 object。
          - `properties` object: 工具输入字段的 JSON Schema；省略时表示未声明属性。
          - `required` string[]: 必填输入字段名；省略时无必填字段。
  - `skills` ManagedSkillReference[], nullable: 整体替换 Skill 列表；null 或空数组表示清空，省略时保持不变。有效配置必须包含 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 列表；仅能与 tools 同时提交，null 或空数组表示清空。最终配置必须与 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 路径。
  - `metadata` ManagedMetadataPatch, nullable: 元数据补丁；省略整个字段时保持不变，键值为 null 时删除对应键。最多 16 个键，键名长度不超过 64 字符，字符串值不超过 512 字符。
  - `multiagent` ManagedMultiagent, nullable: 可选，Multi Agent 主配置。null 清空，创建/更新时固定成员版本；Session override 不支持改 Agent 列表。
    - `type` 'coordinator', required
    - `agents` ManagedMultiagentEntry[], required: 按 Agent ID 计最多 20 个唯一成员；Advisor 至多一个；成员不得携带自己的 Agent 列表。
      - union
        - object
          - `type` 'agent', required
          - `id` string, required
          - `version` integer
        - object
          - `type` 'self', required
        - object
          - `type` 'advisor', required
          - `model` string, required

## Response `200`

请求成功。

- ManagedAgent
  - `id` string, required: Agent ID。
  - `type` 'agent', required
  - `name` string, required
  - `description` string, nullable, required: 用途说明。
  - `model` ManagedModelResponse, required
    - `id` string, required
    - `effort` union: 新协议返回 {type:档位}，旧协议返回字符串。
      - object
        - `type` 'low' | 'high' | 'max', required
      - 'low' | 'high' | 'max'
    - `speed` 'standard', required
  - `system` string, nullable, required: 系统提示词。
  - `tools` ManagedAgentToolsetResponse[], required
    - union
      - object
        - `type` 'agent_toolset_20260601', required
        - `default_config` ManagedToolDefaultConfigResponse, required
          - `enabled` boolean, required
          - `permission_policy` ManagedPermissionPolicy, required
            - `type` 'always_allow' | 'always_ask', required: 工具调用权限策略。always_allow 表示无需确认；always_ask 表示每次调用前请求确认。
        - `configs` ManagedBuiltinToolConfigResponse[], required
          - union
            - object: type/name 若同时提供必须相等。
              - …
            - object: allowed_domains/blocked_domains 暂不接受：配置时 400，不是静默失效。
              - …
            - object: allowed_domains/blocked_domains 暂不接受：配置时 400，不是静默失效。
              - …
      - object
        - `type` 'mcp_toolset', required
        - `mcp_server_name` string, required
        - `default_config` ManagedToolDefaultConfigResponse, required
          - `enabled` boolean, required
          - `permission_policy` ManagedPermissionPolicy, required
            - `type` 'always_allow' | 'always_ask', required: 工具调用权限策略。always_allow 表示无需确认；always_ask 表示每次调用前请求确认。
        - `configs` ManagedMcpToolConfigResponse[], required
          - `name` string, required
          - `enabled` boolean, required
          - `permission_policy` ManagedPermissionPolicy, required
            - `type` 'always_allow' | 'always_ask', required: 工具调用权限策略。always_allow 表示无需确认；always_ask 表示每次调用前请求确认。
      - object
        - `type` 'custom', required
        - `name` string, required
        - `description` string, required
        - `input_schema` ManagedCustomToolInputSchema, required
          - `type` 'object', required: 固定为 object。
          - `properties` object: 工具输入字段的 JSON Schema；省略时表示未声明属性。
          - `required` string[]: 必填输入字段名；省略时无必填字段。
  - `skills` ManagedSkillReference[], required
    - `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[], required
    - `type` 'url', required: 当前只支持 url。
    - `name` string, required: Server 名称，长度 1–255；同一 mcp_servers 数组内不得重复。
    - `url` string, uri, required: 公开 HTTPS Streamable HTTP URL；不得包含凭据、fragment、空 query 或旧式 SSE 路径。
  - `metadata` ManagedMetadata, required: 客户端自定义元数据；省略时默认为空对象。最多 16 个键，键名长度不超过 64 字符，值必须是长度不超过 512 字符的字符串。
  - `version` integer, required
  - `created_at` string, date-time, required: 创建时间。
  - `updated_at` string, date-time, required: 更新时间。
  - `multiagent` ManagedMultiagent, nullable: 可选，Multi Agent 主配置。null 清空，创建/更新时固定成员版本；Session override 不支持改 Agent 列表。
    - `type` 'coordinator', required
    - `agents` ManagedMultiagentEntry[], required: 按 Agent ID 计最多 20 个唯一成员；Advisor 至多一个；成员不得携带自己的 Agent 列表。
      - union
        - object
          - `type` 'agent', required
          - `id` string, required
          - `version` integer
        - object
          - `type` 'self', required
        - object
          - `type` 'advisor', required
          - `model` string, required
  - `archived_at` string, nullable, required: 归档时间；未归档时为 null。

## 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/agents/:agentId/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)