BIbigmodel
Managed Agents - Session

创建 Session

Changed on

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

post/agent/managed/v1/sessions

Request

  • Base URL
    https://agent-api.bigmodel.cn/api
  • Auth
    HTTP bearer

Headers

zai-version'2026-05-26' required
Example:2026-05-26

Managed Agents API 入口要求的基础协议标识，当前只接受 2026-05-26；响应兼容形态由 zai-beta 选择。两个头均需携带。

zai-betastring required
Example:managed-agents-2026-09-22

声明 Managed Agents Beta 协议并选择响应字段与兼容行为。新接入使用 managed-agents-2026-09-22；旧客户端仍可使用 managed-agents-2026-05-26。必须同时携带 zai-version: 2026-05-26。字段差异见 /cn/managed-agents/protocol-versions。

x-events-encrypted'true' | 'false'

仅创建 Session 时可用。精确传 true 时启用事件加密。详见 会话事件数据加密。

x-checkpoint'true' | 'false'

创建时固定。显式 true/false 优先；未声明时Multi Agent Agent 列表/仓库资源可推导默认开启。成功或合作式中断收尾尽力保存，失败/配额不足可能回退，不保证唯一持久存储。

x-checkpoint-ttlinteger

保留天数 1–30。通常须显式 x-checkpoint:true；仓库资源默认开启时也可设置；只依赖 Agent 列表 默认开启时单独 TTL 仍被拒绝。

Request body

OR

Response

请求成功。

idstring required

Session ID。

type'session' required
environment_idstring required
status'idle' | 'running' | 'rescheduling' | 'terminated' required
titlestring nullable required

Session 标题。

metadataManagedMetadata required

客户端自定义元数据；省略时默认为空对象。最多 16 个键，键名长度不超过 64 字符，值必须是长度不超过 512 字符的字符串。

vault_idsstring[] required
outcome_evaluationsobject[] required
budgetobject (null) nullable

当前不支持会话级消费上限，固定为 null。

created_atstring date-time required

创建时间。

updated_atstring date-time required

更新时间。

archived_atstring nullable required

归档时间。

Example response

{
  "id": "sess_01J...",
  "agent": {
    "model": {
      "id": "glm-5.3",
      "speed": "standard"
    },
    "skills": [
      {
        "version": "latest"
      }
    ],
    "mcp_servers": [
      {
        "type": "url",
        "name": "knowledge-base",
        "url": "https://mcp.example.com/mcp"
      }
    ]
  }
}

Changes