API 参考

Managed Agents API 的速查页：请求约定、全部端点与错误码。点击下表中的接口链接进入对应 API 页面，查看字段、示例与 Playground。

请求约定

Base URL 与协议头

https://agent-api.bigmodel.cn/api/agent/managed

路径以 /v1 开头，例如 POST /v1/agents。所有请求携带三个头。Authorization 使用智谱开放平台 API Key：

-H "Authorization: Bearer $ZHIPUAI_API_KEY"
-H "zai-version: 2026-05-26"
-H "zai-beta: managed-agents-2026-09-22"

写请求另加 content-type: application/json。上传文件或 Skill 时改用表单（multipart/form-data），不要发 JSON。需要把会话里的对话和工具内容加密落库时，创建会话再加 x-events-encrypted: true（只能是小写 true / false）。详见会话事件数据加密。 /mnt/session/outputs 始终跨轮保留。要跨轮保留沙箱系统盘（如 /workspace、/tmp 和运行期安装的软件包），创建会话再加 x-checkpoint: true（可选 x-checkpoint-ttl，1–30 天，默认 30）。详见跨轮保留沙箱文件。

ID 与时间戳

资源 ID 带类型前缀，例如 agent_、env_、sess_、sevt_（事件）、file_、sesrsc_（会话资源）、memstore_、vlt_（Vault）、vcrd_（凭据）、skill_、depl_、drun_。错误响应中的 request_id 以 req_ 开头，联系支持时请附上。时间戳统一为 RFC 3339 UTC 格式。

分页

大多数列表接口使用不透明游标：响应含 next_page，把它作为 page 参数传入下一次请求；limit 控制页大小（各接口默认值不同）。新版 Files 列表同样返回 next_page，page 优先；before_id/after_id 为兼容入口。事件列表支持 order（asc / desc）。

metadata

多数资源支持 metadata：最多 16 个键值对，键 ≤64 字符、值 ≤512 字符，均为字符串。更新时按键级 patch：传字符串写入、传 null 删除该键、整个 metadata 传 null 清空。

限流

默认按组织区分读写请求：读请求突发容量 100、每秒恢复 50；写请求突发容量 20、每秒恢复 10。以下高频写接口默认使用更高的容量 100、每秒恢复 50：

POST /v1/sessions/:sessionId/events
POST /v1/deployments/:deploymentId/run
POST /v1/sessions/:sessionId

平台可能按账号或接口调整限流值。收到 429 时，以响应头为准：ratelimit-limit、ratelimit-remaining、ratelimit-reset 和 retry-after；若 x-ratelimit-scope: global，表示平台全局容量已满。客户端应等待 retry-after 后重试。

端点总表

按资源列出全部接口。名称可点进对应页面看字段、示例与 Playground。

Agents

概念说明见定义 Agent。

方法	路径	名称	说明
POST	/v1/agents	创建 Agent	创建可复用的 Agent 配置
GET	/v1/agents	列出 Agent	列出你的 Agent
GET	/v1/agents/:agentId	获取 Agent	获取当前配置
POST	/v1/agents/:agentId	更新 Agent	更新配置，有变化时生成新版本
GET	/v1/agents/:agentId/versions	列出 Agent 版本	列出历史版本
POST	/v1/agents/:agentId/archive	归档 Agent	已有会话继续，不能再开新会话

Environments

概念说明见配置运行环境。

方法	路径	名称	说明
POST	/v1/environments	创建 Environment	创建运行环境（软件包、网络策略）
GET	/v1/environments	列出 Environment	列出运行环境
GET	/v1/environments/:environmentId	获取 Environment	获取单个环境
POST	/v1/environments/:environmentId	更新 Environment	只影响之后新建的会话
POST	/v1/environments/:environmentId/archive	归档 Environment	已有会话继续，不能再绑新会话
DELETE	/v1/environments/:environmentId	删除 Environment	删除环境

Sessions

概念说明见创建会话、管理会话、事件与流式输出。

方法	路径	名称	说明
POST	/v1/sessions	创建 Session	引用 Agent 与 Environment 创建会话
GET	/v1/sessions	列出 Session	按条件列出会话
GET	/v1/sessions/:sessionId	获取 Session	获取状态、用量与配置快照
POST	/v1/sessions/:sessionId	更新 Session	更新标题或 metadata；idle 时也可换工具
POST	/v1/sessions/:sessionId/archive	归档 Session	终止并只读
DELETE	/v1/sessions/:sessionId	删除 Session	删除会话
POST	/v1/sessions/:sessionId/events	发送事件	发送用户消息、工具结果或打断
GET	/v1/sessions/:sessionId/events	列出事件	分页拉取事件历史
GET	/v1/sessions/:sessionId/events/stream	订阅实时事件	用 SSE 订阅实时事件
POST	/v1/sessions/:sessionId/resources	新增会话资源	会话创建后追加挂载文件等资源
GET	/v1/sessions/:sessionId/resources	列出会话资源	列出已挂载资源
GET	/v1/sessions/:sessionId/resources/:resourceId	获取会话资源	获取单个挂载资源
DELETE	/v1/sessions/:sessionId/resources/:resourceId	删除会话资源	移除挂载资源

Files

概念说明见文件。

方法	路径	名称	说明
POST	/v1/files	上传 File	上传文件，供会话挂载给 Agent 读
GET	/v1/files	列出 File	列出已上传和会话产出的文件
GET	/v1/files/:fileId	获取 File	获取文件元数据
GET	/v1/files/:fileId/content	下载 File 内容	下载文件内容
DELETE	/v1/files/:fileId	删除 File	删除文件

Memory Stores

概念说明见记忆。

方法	路径	名称	说明
POST	/v1/memory_stores	创建 Memory Store	创建跨会话的记忆库
GET	/v1/memory_stores	列出 Memory Store	列出记忆库
GET	/v1/memory_stores/:storeId	获取 Memory Store	获取记忆库
POST	/v1/memory_stores/:storeId	更新 Memory Store	更新名称、说明或 metadata
POST	/v1/memory_stores/:storeId/archive	归档 Memory Store	归档后不能再挂到新会话
DELETE	/v1/memory_stores/:storeId	删除 Memory Store	删除记忆库及其中全部记忆
POST	/v1/memory_stores/:storeId/memories	创建 Memory	写入一条记忆
GET	/v1/memory_stores/:storeId/memories	列出 Memory	按路径前缀浏览记忆
GET	/v1/memory_stores/:storeId/memories/:memoryId	获取 Memory	读取一条记忆
POST	/v1/memory_stores/:storeId/memories/:memoryId	更新 Memory	更新路径或内容
DELETE	/v1/memory_stores/:storeId/memories/:memoryId	删除 Memory	删除一条记忆
GET	/v1/memory_stores/:storeId/memory_versions	列出 Memory Version	列出记忆的变更记录
GET	/v1/memory_stores/:storeId/memory_versions/:versionId	获取 Memory Version	获取某次变更
POST	/v1/memory_stores/:storeId/memory_versions/:versionId/redact	脱敏 Memory Version	抹除该版本中的敏感内容，保留审计轨迹

Vaults

概念说明见凭据管理。

方法	路径	名称	说明
POST	/v1/vaults	创建 Vault	创建凭据集合
GET	/v1/vaults	列出 Vault	列出 Vault
GET	/v1/vaults/:vaultId	获取 Vault	获取 Vault
POST	/v1/vaults/:vaultId	更新 Vault	更新展示名或 metadata
POST	/v1/vaults/:vaultId/archive	归档 Vault	归档 Vault
DELETE	/v1/vaults/:vaultId	删除 Vault	删除 Vault
POST	/v1/vaults/:vaultId/credentials	创建 Credential	添加一条凭据
GET	/v1/vaults/:vaultId/credentials	列出 Credential	列出凭据，不含密钥原文
GET	/v1/vaults/:vaultId/credentials/:credentialId	获取 Credential	获取凭据元数据
POST	/v1/vaults/:vaultId/credentials/:credentialId	更新 Credential	轮换 token 等密钥
POST	/v1/vaults/:vaultId/credentials/:credentialId/mcp_oauth_validate	验证 MCP OAuth	探测 MCP OAuth 凭据是否仍有效
POST	/v1/vaults/:vaultId/credentials/:credentialId/archive	归档 Credential	归档凭据
DELETE	/v1/vaults/:vaultId/credentials/:credentialId	删除 Credential	删除凭据

Skills

概念说明见 Skills。

方法	路径	名称	说明
POST	/v1/skills	创建 Skill	上传自定义 Skill
GET	/v1/skills	列出 Skill	列出 Skill
GET	/v1/skills/:skillId	获取 Skill	获取 Skill
DELETE	/v1/skills/:skillId	删除 Skill	删除 Skill
POST	/v1/skills/:skillId/versions	创建 Skill Version	上传新版本
GET	/v1/skills/:skillId/versions	列出 Skill Version	列出版本
GET	/v1/skills/:skillId/versions/:version	获取 Skill Version	获取某个版本
GET	/v1/skills/:skillId/versions/:version/content	下载 Skill ZIP	下载该版本的 ZIP
DELETE	/v1/skills/:skillId/versions/:version	删除 Skill Version	删除某个版本

Deployments

概念说明见定时任务。

方法	路径	名称	说明
POST	/v1/deployments	创建 Deployment	创建定时或手动触发的任务
GET	/v1/deployments	列出 Deployment	列出定时任务
GET	/v1/deployments/:deploymentId	获取 Deployment	获取任务配置
POST	/v1/deployments/:deploymentId	更新 Deployment	更新名称、调度或初始事件
POST	/v1/deployments/:deploymentId/pause	暂停 Deployment	暂停定时触发；手动运行仍可用
POST	/v1/deployments/:deploymentId/unpause	恢复 Deployment	恢复定时触发
POST	/v1/deployments/:deploymentId/archive	归档 Deployment	归档后不再触发
POST	/v1/deployments/:deploymentId/run	手动运行 Deployment	立即触发一次运行
GET	/v1/deployment_runs	列出 Deployment Run	列出运行记录
GET	/v1/deployment_runs/:runId	获取 Deployment Run	获取单次运行结果

错误处理

错误响应使用统一信封，只包含 HTTP 状态码、error.type、error.message 与 request_id：

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "environment_id: value is required"
  },
  "request_id": "req_xxxxxxxxxxxx"
}

HTTP	error.type	典型场景
400 / 422	invalid_request_error	参数非法、字段不支持、缺少必填字段
401	authentication_error	缺少或无法解析凭据
403	permission_error	身份可识别但权限不足
404	not_found_error	资源不存在或对调用者不可见
409	invalid_request_error	版本冲突、资源状态冲突、唯一键冲突（无独立 conflict 类型，结合状态码与 message 区分）
413	request_too_large	请求体超限
429	rate_limit_error	配额或请求频率超限
500	api_error	内部错误
504	timeout_error	请求或上游处理超时
502 / 503 / 529	overloaded_error	上游不可用或服务过载

读取请求遇到 429 与 5xx 可按 Retry-After 或指数退避重试；400 类错误应先修正请求。创建资源、提交 Event 等写请求结果未知时，先核对已有资源或历史，不要直接重复提交。会话内的异步失败不走 HTTP 错误，而是以 session.error 事件送达，见事件与流式输出。

协议与补充资源

本页和 Playground 默认使用新 beta header。旧协议继续兼容；effort、Skill、Files、Thinking、创建成功状态码等差异见协议版本。

Threads

方法	路径	用途
GET	`/v1/sessions/:sessionId/threads` — 字段与示例	列出线程（含主线程），支持 statuses[]
GET	`/v1/sessions/:sessionId/threads/:threadId` — 字段与示例	线程详情
POST	`/v1/sessions/:sessionId/threads/:threadId/archive` — 字段与示例	归档 idle 子线程
GET	`/v1/sessions/:sessionId/threads/:threadId/events` — 字段与示例	分页读取完整历史
GET	`/v1/sessions/:sessionId/threads/:threadId/stream` — 字段与示例	独立 live-only SSE

Skill 与仓库补充端点

方法	路径	用途
GET	/v1/skills/:id/versions/latest	读取 head SkillVersion
POST	/v1/sessions/:sessionId/resources/:resourceId	仅轮换 github_repository authorization_token

完整用法见会话线程、Agent Skills、访问 GitHub 仓库。仓库不能后续追加/删除，Deployment 不接受仓库资源。

控制台接入边界

聊天渠道提供公开 Channel v0 的接入步骤；控制台 /v1/console/* 是另一套接口，不应替代公开 Channel API。创建普通 Session 不需要先启用所有可选能力。新客户端只按自己需要的页配置工具、Skills、仓库、Memory 或 Deployment。

Channel API

聊天渠道通过 Forward Channel v0 管理，使用独立 Base URL 和 Beta 请求头，不属于 /v1/sessions 的子资源。目前支持飞书，微信、企微等渠道近期支持。接入步骤见接入聊天渠道。

方法	接口	用途
POST	创建 Channel	绑定固定的 Agent 版本与飞书机器人
GET	列出 Channel	分页读取当前账号的渠道
GET	获取 Channel	查看连接状态、配置与错误
PATCH	更新 Channel	仅修改群聊 Prompt 模板
DELETE	删除 Channel	停止接入并清理机器人凭据

开始使用

定义 Agent

配置运行环境

运行会话

上下文与记忆

评测与优化

自动化

接入

参考

请求约定

Base URL 与协议头

ID 与时间戳

分页

metadata

限流

端点总表

Agents

Environments

Sessions

Files

Memory Stores

Vaults

Skills

Deployments

错误处理

协议与补充资源

Threads

Skill 与仓库补充端点

控制台接入边界

Channel API

​请求约定

​Base URL 与协议头

​ID 与时间戳

​分页

​metadata

​限流

​端点总表

​Agents

​Environments

​Sessions

​Files

​Memory Stores

​Vaults

​Skills

​Deployments

​错误处理

​协议与补充资源

​Threads

​Skill 与仓库补充端点

​控制台接入边界

​Channel API

请求约定

Base URL 与协议头

ID 与时间戳

分页

metadata

限流

端点总表

Agents

Environments

Sessions

Files

Memory Stores

Vaults

Skills

Deployments

错误处理

协议与补充资源

Threads

Skill 与仓库补充端点

控制台接入边界

Channel API