Skip to main content
POST
创建 Session

Authorizations

Authorization
string
header
required

标准的 HTTP Bearer 认证方式,在 API Keys 页面获取密钥。

Headers

zai-version
enum<string>
default:2026-05-26
required

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

Available options:
2026-05-26
Example:

"2026-05-26"

zai-beta
string
default:managed-agents-2026-09-22
required

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

Example:

"managed-agents-2026-09-22"

x-events-encrypted
enum<string>
default:false

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

Available options:
true,
false
x-checkpoint
enum<string>

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

Available options:
true,
false
x-checkpoint-ttl
integer
default:30

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

Required range: 1 <= x <= 30

Body

application/json

必须提供 agent 与 environment_id。未传 agent 时,服务端仍接受兼容字段 agent_id。

agent
required

Agent 配置;必填。仅为兼容旧调用时可改用 agent_id。

Minimum string length: 1
environment_id
string
required

必填的 Environment ID;必须存在、未归档并可由当前 Agent 使用。

Required string length: 1 - 64
Pattern: ^env_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
Example:

"env_019e8f00-1ac2-7a6b-8000-3f2d5c8b9a01"

agent_id
string

兼容字段;agent 缺失时使用。

Minimum string length: 1
title
string | null

会话标题;省略或传 null 时不设置。

Maximum string length: 256
metadata
object

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

initial_events
object[]

创建后立即写入并唤醒执行的 user.message 事件;省略时为空。仅允许文本与 base64 图片,图片要求生效模型支持图片输入。

Maximum array length: 50
resources
(memory_store · object | file · object | github_repository · object)[]

file ≤500、memory_store ≤8;github_repository 只在创建 Session 时声明。仓库凭据可轮换,不支持后续新增或删除仓库。

vault_ids
string[]

挂载的 Vault ID;省略时为空,最多 20 个且不得重复。

Maximum array length: 20

Response

请求成功。

id
string
required

Session ID。

Example:

"sess_01J..."

type
enum<string>
required
Available options:
session
agent
object
required
environment_id
string
required
status
enum<string>
required
Available options:
idle,
running,
rescheduling,
terminated
title
string | null
required

Session 标题。

metadata
object
required

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

resources
(memory_store · object | file · object | github_repository · object)[]
required
vault_ids
string[]
required
outcome_evaluations
object[]
required
stats
object
required
usage
object
required
created_at
string<date-time>
required

创建时间。

updated_at
string<date-time>
required

更新时间。

archived_at
string | null
required

归档时间。

budget
object | null

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