协议版本与兼容 - 智谱AI开放文档

当前新接入请直接复制下面这组请求头；不要把日期改成“看起来更新”的值。只有平台发布新的兼容组合时，才按兼容说明一起升级。

BASE_URL=https://agent-api.bigmodel.cn/api/agent/managed
curl -sS "$BASE_URL/v1/agents?limit=20" \
  -H "Authorization: Bearer $ZHIPUAI_API_KEY" \
  -H "zai-version: 2026-05-26" \
  -H "zai-beta: managed-agents-2026-09-22"

为什么两个头的日期不一样

它们不是同一个“最新版本”字段，而是两层兼容控制：

请求头	当前值	负责什么	能不能互相替代
`zai-version`	`2026-05-26`	API 入口要求的基础协议标识，当前固定为此值	不能
`zai-beta`	`managed-agents-2026-09-22`	声明 Managed Agents Beta 协议，并选择返回字段与兼容行为的版本	不能

因此，新接入必须同时携带两个头：zai-version 满足基础协议校验，zai-beta 选择 Beta 协议的兼容形态。只写其中一个，不能通过另一项替代。旧客户端也可使用 2026-05-26 与 managed-agents-2026-05-26 这组已支持的组合。当前推荐组合是 zai-version: 2026-05-26 + zai-beta: managed-agents-2026-09-22。存量客户端可以在兼容期继续使用旧 Beta 值，但新代码应按本文示例接入。

两种 Beta 协议有什么区别

项目	2026-05-26	2026-09-22
`agent.thinking`	进度信号，不含思考文本	可含 `content` 文本块；订阅后可收到 Thinking delta
`model.effort` 响应	`"max"` 等字符串	`{"type":"max"}` 等对象
Skill 对象	`display_title`、字符串 `source`、`latest_version`	`display_name`、`source:{type}`、`latest_version_id`
SkillVersion 对象	含 `version`、`directory`	`id` 是版本 ID；`name` 是目录名，省略旧字段
Skill `latest`	会话每次启动时解析	创建 Session 时固定；Deployment 每次触发时固定
Agent 列表	缺省包含已归档 Agent	缺省排除；可显式传 `include_archived=true`
Files 列表	`data/has_more/first_id/last_id`	`data/next_page`
File 对象	无 `expires_at`	`expires_at:null`，当前不设文件过期
Thread	`stats/usage` 按旧形态输出	尚未运行的 `stats/usage` 可为 null；`workflow_run_id:null`
Idle 事件	无 `stop_details`	`stop_details:null`
创建成功状态码	使用 201 的创建接口仍回 201	这些接口回 200；按 2xx 判断成功
Memory 冲突错误	通用 `conflict_error`	可为 `memory_path_conflict_error` / `memory_precondition_failed_error`

输入仍兼容字符串 effort，也接受 {"type":"max"}。新协议里 web_fetch 的 url_sources:null 是响应字段，不代表支持配置 URL 来源限制。

升级客户端

将 zai-beta 切换为 managed-agents-2026-09-22。zai-version 保持 2026-05-26。
按上表更新读取字段；列表循环使用 next_page，不要只读取第一页。
对新字段与尚无用量的 null 值采用可选解析。创建请求按 2xx 判断成功。
使用一个小 Session 验证事件、审批、产物与用量，再切换实际业务。

同时声明两种可识别的 beta 值时取较新版本。存量事件不会被重写；加密历史中的密文不能按旧版本删字段，解密后的客户端应容忍未知字段。版本兼容不改变 Agent 的版本快照，也不等于获得账号尚未开放的能力。可用模型与计费资格仍按账号判断。