管理 Session

Session 创建后，你可以查询状态、列出 Session、更新标题和标签、升级运行配置，以及永久删除 Session。

准备工作#

开始前你需要：

• 已创建的 API Key：配置为环境变量 ARK_API_KEY，详情请参见 API Key 管理。
• 已创建的 Agent：详情请参见 定义 Agent。
• 已创建的 Environment：详情请参见 配置云环境。

本章节示例的 Base URL 与鉴权方式详情请参见 Base URL 及鉴权。

Session 状态机#

这些状态及主要迁移关系如下：

状态迁移规律：

• initializing → idle：Session 初始化或资源恢复完成。
• initializing → failed：Session 初始化或资源恢复失败。
• idle → running：收到 user.message 或 user.tool_confirmation 等用户事件。
• running → idle：Agent 一轮工作结束（end_turn）或需要等用户输入（requires_action，详情请参见 Session 事件流）。
• running → rescheduling → running：框架遇到暂时性错误后自动重试，你无需介入。
• idle → upgrading → idle：服务端受理运行配置升级，升级完成或回滚后恢复为空闲状态。
• 任意状态 → terminated：Session 终止。终止后不再接收事件，但记录与事件历史保留。

选择获取方式#

Session 详情接口只返回资源的最新状态、用量统计和配置快照。实时回复和历史事件由 Session Events API 承载：

正常交互时，通过 SSE 实时接收 Agent 回复和状态。GET /sessions/{session_id}/events 仅用于历史事件查询和断线补查。不要只根据 status=idle 判断本轮成功。发送任务、接收回复和判断 stop_reason 的完整流程，详情请参见 Session 事件流。

检索 Session#

通过 GET /sessions/{session_id} 查询 Session 的详细信息，包括智能体、会话运行环境、资源、状态和标签等：

1
2curl https://ark.cn-beijing.volces.com/api/v3/sessions/sesn-20260701120100-klmno \
  -H "Authorization: Bearer $ARK_API_KEY"

响应主要字段：

• id：Session ID。
• status：当前状态（见上表）。
• usage：累计 token 用量（详情请参见 Session 事件流 § 跟踪用量）。
• agent：绑定的 Agent 对象，内含 id、version 等字段。
• environment_id：绑定的云环境。

列出 Session#

GET /sessions 支持按 agent_id 过滤、按创建时间倒序分页，响应以 data 数组形式返回 Session 列表：

1
2curl "https://ark.cn-beijing.volces.com/api/v3/sessions?agent_id=agent-20260701120000-abcde&limit=20" \
  -H "Authorization: Bearer $ARK_API_KEY"

更新与升级 Session#

升级接口保持原 session_id 不变，也不支持换绑其他 Agent 或 Environment。发起升级前，Session 必须处于 idle，并且上一轮任务以 end_turn 结束。接口返回 upgrading 后，轮询 GET /sessions/{session_id}；状态恢复为 idle 表示升级流程已结束。

删除 Session#

1
2
3curl https://ark.cn-beijing.volces.com/api/v3/sessions/sesn-20260701120100-klmno \
  -X DELETE \
  -H "Authorization: Bearer $ARK_API_KEY"

数据保留与删除影响#

Session 资源记录、完整事件、沙箱状态和 Agent 产物使用独立的保留策略：