管理会话

本页涵盖会话的日常运维操作：查看状态、更新配置、检索、列表、归档与删除。发送事件与流式接收见事件与流式输出。

会话状态

状态	含义
idle	等待输入。刚创建、或 Agent 完成本轮工作后处于此状态；发送新事件即可继续。
running	Agent 正在执行。可以追加消息引导它，或发送 user.interrupt 打断。
rescheduling	平台正在重新调度会话的沙箱（恢复或迁移），随后自动回到执行。
terminated	会话已终止，不再接受交互（例如所引用的 Environment 被归档后触发的准入终止）。

归档是独立于状态的生命周期标记（archived_at），见下文。

更新会话

POST /v1/sessions/:sessionId 支持更新四类内容，规则不同：

字段	规则
title	任意状态可更新；null 清空。
metadata	任意状态可更新；键级合并，限制与创建相同（16 键、key ≤64、value ≤512）。
agent.tools	仅 idle 状态可更新（否则 409 session_not_idle，需先发送 user.interrupt）；整体替换。
agent.mcp_servers	仅 idle 状态可更新；整体替换，与 agent.tools 的 mcp_toolset 引用保持一致。

model、system、skills、vault_ids 不支持会话中更新——它们在创建时冻结。已归档会话的任何更新返回 409 session_archived；空请求体返回 400。

curl -sS "$BASE_URL/v1/sessions/$SESSION_ID" \
  -H "Authorization: Bearer $ZHIPUAI_API_KEY" \
  -H "zai-version: 2026-05-26" \
  -H "zai-beta: managed-agents-2026-05-26" \
  -H "content-type: application/json" \
  -d '{
    "agent": {
      "tools": [
        {
          "type": "agent_toolset_20260601",
          "configs": [{"name": "bash", "permission_policy": {"type": "always_ask"}}]
        }
      ]
    }
  }'

获取会话

curl -sS "$BASE_URL/v1/sessions/$SESSION_ID" \
  -H "Authorization: Bearer $ZHIPUAI_API_KEY" \
  -H "zai-version: 2026-05-26" \
  -H "zai-beta: managed-agents-2026-05-26"

响应中值得关注的运行时字段：status（当前真实状态）、usage（累计 input / output / cache_read token）、resources（挂载的 Memory Store 与 File，含实际 mount_path）、agent（解析后的配置快照）。

列出会话

GET /v1/sessions 支持丰富的过滤条件：

curl -sS "$BASE_URL/v1/sessions?agent_id=$AGENT_ID&statuses[]=running&limit=20" \
  -H "Authorization: Bearer $ZHIPUAI_API_KEY" \
  -H "zai-version: 2026-05-26" \
  -H "zai-beta: managed-agents-2026-05-26"

参数	说明
agent_id / agent_version	按 Agent 过滤；agent_version 必须与 agent_id 同用。
memory_store_id	按挂载的 Memory Store 过滤。
statuses[]	可重复传入的状态过滤，如 statuses[]=idle&statuses[]=running。
created_at[gt] / [gte] / [lt] / [lte]	按创建时间过滤，值为 RFC 3339。例如 `created_at[gte]=2026-01-01T00:00:00Z`。四个参数可组合。
include_archived	默认 false；true 时包含已归档会话。
limit / order / page	分页：limit 默认 20，order 默认 desc；用响应中的 page 游标向后翻页、prev_page 游标向前翻页。

归档会话

归档把会话标记为已完成并使其只读。会话必须处于非 running 状态（否则 409，需先发送 user.interrupt）：

curl -sS -X POST "$BASE_URL/v1/sessions/$SESSION_ID/archive" \
  -H "Authorization: Bearer $ZHIPUAI_API_KEY" \
  -H "zai-version: 2026-05-26" \
  -H "zai-beta: managed-agents-2026-05-26"

注意与其他资源不同：对已归档会话重复归档返回 409 session_archived（不是幂等成功）。另外，非 API 创建的会话（例如 IM 渠道会话，可能出现在列表中）不可归档，返回 409 operation_not_supported。

删除会话

删除会永久移除会话及其事件历史，不可恢复：

curl -sS -X DELETE "$BASE_URL/v1/sessions/$SESSION_ID" \
  -H "Authorization: Bearer $ZHIPUAI_API_KEY" \
  -H "zai-version: 2026-05-26" \
  -H "zai-beta: managed-agents-2026-05-26"

{ "id": "sess_xxxxxxxxxxxx", "type": "session_deleted" }

规则：running 状态不可删除（409，先 interrupt）；已归档会话允许删除；非 API 创建的会话不可删除。会话挂载的 File 与 Memory Store 是独立资源，不随会话删除。

下一步

事件与流式输出

发送事件、打断、恢复空闲会话

文件

列出并下载会话产出文件

本页对应 OpenAPI

Session：获取、更新、归档、删除

开始使用

定义 Agent

配置运行环境

运行会话

上下文与记忆

自动化

参考

会话状态

更新会话

获取会话

列出会话

归档会话

删除会话

下一步

事件与流式输出

文件

本页对应 OpenAPI

​会话状态

​更新会话

​获取会话

​列出会话

​归档会话

​删除会话

​下一步

事件与流式输出

文件

本页对应 OpenAPI

会话状态

更新会话

获取会话

列出会话

归档会话

删除会话

下一步