---
title: "创建 Agent"
method: POST
path: "/agent/managed/v1/agents"
tags: ["Managed Agents - Agent"]
---

# 创建 Agent

`POST /agent/managed/v1/agents`

## Request

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

创建 Agent 及其首个不可变版本，配置模型、系统提示词、工具、Skills 与 MCP。

<Accordion title="使用说明">

创建 Agent 及其首个不可变版本。可配置模型、系统提示词、内置或自定义工具、Skill 和 MCP Server；配置 MCP Server 时必须同时提供引用同名服务器的 `mcp_toolset`，不使用 MCP 时请省略这两个字段。

</Accordion>

## Headers

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

## Request body

- ManagedAgentCreateRequest
  - `name` string, required: Agent 名称，长度 1–256 个字符。
  - `model` union, required: 模型 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: Agent 用途说明；省略或传 null 时不设置。
  - `tools` ManagedAgentToolsetInput[]: 工具集列表；省略时为空。MCP Server 必须与 mcp_toolset 按名称一一对应；配置 Skill 时必须包含 agent_toolset_20260601。
    - 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[]: Skill 引用；省略时为空。version 省略或传 null 时跟随 latest，传具体版本号时固定版本；同一 skill_id 与生效 version 组合不得重复。配置 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[]: MCP Server 列表；省略时为空。名称必须唯一，并且每个 Server 必须恰好对应一个同名 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` ManagedMetadata: 客户端自定义元数据；省略时默认为空对象。最多 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`

新 beta header 的创建成功响应

- 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

- `201`: 旧 beta header 的创建成功响应
- `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/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)