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

# 创建 Session

`POST /agent/managed/v1/sessions`

## Request

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

基于指定 Agent 和 Environment 创建 Session。可选择固定 Agent 版本或提供会话级覆盖，并可附带初始用户消息、File 或 Memory Store 资源及 Vault。

## Headers

- `zai-version` '2026-05-26', required
- `zai-beta` string, required
- `x-events-encrypted` 'true' | 'false'
- `x-checkpoint` 'true' | 'false'
- `x-checkpoint-ttl` integer

## Request body

- union: 必须提供 agent 与 environment_id。未传 agent 时，服务端仍接受兼容字段 agent_id。
  - object
    - `agent` union, required: 可传 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。
              - …
            - `speed` 'standard', nullable: 当前仅支持 standard；省略或传 null 时也使用 standard。
        - `system` string, nullable: 覆盖系统提示词；null 表示清空，省略时继承 Agent 版本。
        - `tools` ManagedAgentToolsetInput[], nullable: 整体覆盖工具列表；null 或空数组表示清空，省略时继承 Agent 版本。MCP 映射约束在合并后的最终配置上校验。
          - union
            - object
              - …
            - object
              - …
            - object
              - …
        - `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 路径。
    - `agent_id` string: 兼容字段；agent 缺失时使用。
    - `environment_id` string, required: 必填的 Environment ID；必须存在、未归档并可由当前 Agent 使用。
    - `title` string, nullable: 会话标题；省略或传 null 时不设置。
    - `metadata` ManagedMetadata: 客户端自定义元数据；省略时默认为空对象。最多 16 个键，键名长度不超过 64 字符，值必须是长度不超过 512 字符的字符串。
    - `initial_events` ManagedInitialUserMessageEventInput[]: 创建后立即写入并唤醒执行的 user.message 事件；省略时为空。仅允许文本与图片（base64、url 或 file 来源），图片要求生效模型支持图片输入。
      - `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。
              - …
    - `resources` ManagedSessionResourceInput[]: file ≤500、memory_store ≤8；github_repository 只在创建 Session 时声明。仓库凭据可轮换，不支持后续新增或删除仓库。
      - union
        - object
          - `type` 'memory_store', required: 固定为 memory_store。
          - `memory_store_id` string, required: 已存在且可访问的 Memory Store ID。
          - `access` 'read_only' | 'read_write', nullable: 挂载权限；省略或传 null 时由 Memory 服务按 read_write 处理。
          - `instructions` string, nullable: 提供给 Agent 的使用说明；省略或传 null 时不设置。
        - 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 字节。
        - ManagedGithubRepositoryInput
          - `type` 'github_repository', required
          - `url` string, required: 不含 .git 后缀
          - `authorization_token` string, required
          - `mount_path` string, nullable: 在 /workspace 下，默认 /workspace/仓库名
          - `checkout` union
            - object
              - …
            - object
              - …
    - `vault_ids` string[]: 挂载的 Vault ID；省略时为空，最多 20 个且不得重复。
  - object
    - `agent` union, required: 可传 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。
              - …
            - `speed` 'standard', nullable: 当前仅支持 standard；省略或传 null 时也使用 standard。
        - `system` string, nullable: 覆盖系统提示词；null 表示清空，省略时继承 Agent 版本。
        - `tools` ManagedAgentToolsetInput[], nullable: 整体覆盖工具列表；null 或空数组表示清空，省略时继承 Agent 版本。MCP 映射约束在合并后的最终配置上校验。
          - union
            - object
              - …
            - object
              - …
            - object
              - …
        - `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 路径。
    - `agent_id` string, required: 兼容字段；agent 缺失时使用。
    - `environment_id` string, required: 必填的 Environment ID；必须存在、未归档并可由当前 Agent 使用。
    - `title` string, nullable: 会话标题；省略或传 null 时不设置。
    - `metadata` ManagedMetadata: 客户端自定义元数据；省略时默认为空对象。最多 16 个键，键名长度不超过 64 字符，值必须是长度不超过 512 字符的字符串。
    - `initial_events` ManagedInitialUserMessageEventInput[]: 创建后立即写入并唤醒执行的 user.message 事件；省略时为空。仅允许文本与图片（base64、url 或 file 来源），图片要求生效模型支持图片输入。
      - `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。
              - …
    - `resources` ManagedSessionResourceInput[]: file ≤500、memory_store ≤8；github_repository 只在创建 Session 时声明。仓库凭据可轮换，不支持后续新增或删除仓库。
      - union
        - object
          - `type` 'memory_store', required: 固定为 memory_store。
          - `memory_store_id` string, required: 已存在且可访问的 Memory Store ID。
          - `access` 'read_only' | 'read_write', nullable: 挂载权限；省略或传 null 时由 Memory 服务按 read_write 处理。
          - `instructions` string, nullable: 提供给 Agent 的使用说明；省略或传 null 时不设置。
        - 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 字节。
        - ManagedGithubRepositoryInput
          - `type` 'github_repository', required
          - `url` string, required: 不含 .git 后缀
          - `authorization_token` string, required
          - `mount_path` string, nullable: 在 /workspace 下，默认 /workspace/仓库名
          - `checkout` union
            - object
              - …
            - object
              - …
    - `vault_ids` string[]: 挂载的 Vault ID；省略时为空，最多 20 个且不得重复。

## Response `200`

请求成功。

- ManagedSession
  - `id` string, required: Session ID。
  - `type` 'session', required
  - `agent` ManagedSessionAgentResponse, required
    - `id` string, required
    - `type` 'agent', required
    - `name` string, 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: 解析后的系统提示词。
    - `description` string, nullable, required: Agent 描述。
    - `tools` ManagedAgentToolsetResponse[], required
      - union
        - object
          - `type` 'agent_toolset_20260601', required
          - `default_config` ManagedToolDefaultConfigResponse, required
            - `enabled` boolean, required
            - `permission_policy` ManagedPermissionPolicy, required
              - …
          - `configs` ManagedBuiltinToolConfigResponse[], required
            - union
              - …
        - object
          - `type` 'mcp_toolset', required
          - `mcp_server_name` string, required
          - `default_config` ManagedToolDefaultConfigResponse, required
            - `enabled` boolean, required
            - `permission_policy` ManagedPermissionPolicy, required
              - …
          - `configs` ManagedMcpToolConfigResponse[], required
            - `name` string, required
            - `enabled` boolean, required
            - `permission_policy` ManagedPermissionPolicy, required
              - …
        - 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 路径。
    - `multiagent` null, nullable: Session 内嵌快照当前为 null，成员 Agent 列表 从对应 Agent 版本读取。
    - `version` integer, required
  - `environment_id` string, required
  - `status` 'idle' | 'running' | 'rescheduling' | 'terminated', required
  - `title` string, nullable, required: Session 标题。
  - `metadata` ManagedMetadata, required: 客户端自定义元数据；省略时默认为空对象。最多 16 个键，键名长度不超过 64 字符，值必须是长度不超过 512 字符的字符串。
  - `resources` ManagedSessionResourceResponse[], required
    - union
      - object
        - `type` 'memory_store', required
        - `memory_store_id` string, required
        - `name` string, required
        - `description` string, nullable, required
        - `access` 'read_only' | 'read_write', required
        - `instructions` string, nullable, required
        - `mount_path` string, required
      - object
        - `id` string, required
        - `type` 'file', required
        - `file_id` string, required
        - `mount_path` string, required
        - `created_at` string, date-time, required: 创建时间。
        - `updated_at` string, date-time, required: 更新时间。
      - ManagedGithubRepositoryResponse
        - `id` string, required
        - `type` 'github_repository', required
        - `url` string, required
        - `mount_path` string, required
        - `checkout` union
          - object
            - `type` 'branch', required
            - `name` string, required
          - object
            - `type` 'commit', required
            - `sha` string, required
        - `created_at` string, date-time, required
        - `updated_at` string, date-time, required
  - `vault_ids` string[], required
  - `outcome_evaluations` object[], required
  - `stats` object, required
    - `active_seconds` number
    - `duration_seconds` number, required
  - `usage` object, required
    - `input_tokens` integer, required
    - `output_tokens` integer, required
    - `cache_read_input_tokens` integer, required
    - `server_tool_use` object
      - `web_search_requests` integer, required
      - `web_fetch_requests` 0, required
  - `budget` null, nullable: 当前不支持会话级消费上限，固定为 null。
  - `created_at` string, date-time, required: 创建时间。
  - `updated_at` string, date-time, required: 更新时间。
  - `archived_at` string, nullable, 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/sessions/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)