面向 AI 助手:本页的 Markdown 版本位于 https://ark.volcengine.com/region:cn-beijing/docs/manage-session.md,全部文档索引见 https://ark.volcengine.com/llms.txt。

管理 Session

Session 创建后,你可以查询状态、筛选列表、更新标题和标签、升级运行配置,以及在任务结束后归档或永久删除 Session。需要释放运行资源但保留可查询记录时选择归档;确定不再需要记录时再删除。

准备工作#

开始前你需要:

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

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

Session 状态机#

状态 说明
idle Agent 正在等待输入,例如用户消息或工具确认。普通新建的 Session 以该状态启动
running Agent 正在执行任务
terminated Session 已终止,不再接收新事件
rescheduling 发生暂时性错误后,系统正在重新调度 Session
initializing Session 正在初始化运行环境或恢复资源
failed Session 初始化或运行失败
upgrading Session 正在升级 Agent 或 Environment 运行配置

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

Session 资源在 initializing、idle、running、upgrading、rescheduling、failed 和 terminated 之间的迁移关系

状态迁移规律:

  • Session 初始化或资源恢复完成后,状态从 initializing 变为 idle。
  • Session 初始化或资源恢复失败后,状态从 initializing 变为 failed。
  • 收到 user.message 或 user.tool_confirmation 等用户事件后,状态从 idle 变为 running。
  • Agent 一轮工作结束(end_turn)或需要等用户输入时,状态从 running 变为 idle(requires_action,详情请参见 Session 事件流)。
  • Session 运行期间出现暂时性错误时,状态从 running 变为 rescheduling。方舟会自动恢复并重新调度 Session。恢复完成后,状态变回 running,你无需介入。
  • 服务端受理运行配置升级后,状态从 idle 变为 upgrading。升级完成或回滚后,状态恢复为 idle。
  • Session 可以从任意状态变为 terminated。终止后不再接收事件,但记录与事件历史保留。

选择获取方式#

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

需要获取的内容 使用接口 返回内容和限制
实时接收 Agent 回复和状态;按需接收累计用量 流式获取会话事件 通过 SSE(Server-Sent Events)协议订阅 Session 实时事件。建立连接并等待 : ready 后,再发送事件。
已持久化的完整事件 查询会话事件列表 用于历史事件查询和断线补查,不包含预览帧。子线程内部的完整执行过程通过 查询线程事件列表 获取。
最新状态、累计用量和配置快照 查询会话详情 返回智能体、运行环境、资源、状态和标签等信息,不包含 Agent 回复或完整事件历史。

正常交互时,通过 SSE 实时接收 Agent 回复和状态;如需展示用量或记账,可读取 session.usage 累计用量快照。GET /sessions/{session_id}/events 仅用于历史事件查询和断线补查。不要只根据 status=idle 判断本轮成功。发送任务、接收回复和判断 stop_reason 的完整流程,详情请参见 Session 事件流。

检索 Session#

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

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

响应示例:

{
  "id": "<SESSION_ID>",
  "status": "idle",
  "usage": {
    "active_seconds": 147.661,
    "cache_read_input_tokens": 271227,
    "input_tokens": 34,
    "output_tokens": 7774,
    "server_tool_use": {
      "general_search_requests": 1,
      "visual_search_requests": 1,
      "web_fetch_requests": 0,
      "web_search_requests": 2
    }
  },
  "stats": {
    "active_seconds": 147.661,
    "duration_seconds": 1788.0
  },
  "agent": {
    "id": "<AGENT_ID>",
    "version": 1
  },
  "environment_id": "<ENVIRONMENT_ID>"
}

响应主要字段:

  • id:Session ID。
  • status:当前状态(见上表)。
  • usage:Session 运行期间累计的运行时长、模型 token 和服务端搜索请求次数(详情请参见 Session 事件流 § 跟踪用量)。
    • active_seconds 表示 Session 至少有一个线程处于 running 状态的累计时长。
    • cache_read_input_tokens、input_tokens 和 output_tokens 分别记录缓存读取、未缓存输入和输出 token。
    • server_tool_use 记录服务端托管工具累计发起的请求次数,具体字段请参见 查询会话详情 。
  • stats:Session 的累计运行时长和从创建到当前或终止时的总时长。
    • active_seconds 表示 Session 至少有一个线程处于 running 状态的累计时长,单位为秒。
    • duration_seconds 表示从创建到查询时刻的总时长;Session 终止后,该值固定为从创建到终止的时长。
  • agent:绑定的 Agent 对象,内含 id、version 等字段。
  • environment_id:绑定的云环境。

需要查看某个线程的时长和累计用量时,调用 查询线程详情 并读取该线程的 stats 和 usage。

列出 Session#

GET /sessions 支持按 agent_id、状态、标签和创建时间过滤,响应以 data 数组形式返回 Session 列表。

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

更新与升级 Session#

需求 接口 状态变化
修改标题或标签 更新 Session 标题和标签 不改变 Session 的运行状态
修改 Agent 或 Environment 运行配置 升级会话 先从 idle 变为 upgrading,结束后恢复为 idle

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

归档 Session#

任务已经结束,需要释放运行资源但仍要保留 Session 配置和历史记录供查询时,调用 归档会话。

归档前,确保 Session 处于 idle。如果 Session 正在运行,先发送中断事件,并等待当前任务结束。即使 Session 已经空闲,服务端检测到状态为 queued(排队中)或 running(运行中)的工具任务时,也会拒绝归档;请等待工具任务结束或取消工具任务后重试。

Bash
curl -sS --fail-with-body \
  "https://ark.cn-beijing.volces.com/api/v3/sessions/<SESSION_ID>/archive" \
  -H "Authorization: Bearer $ARK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

归档成功后,平台开始回收会话运行资源,但 Session 配置和历史记录仍可查询。

status 为 idle 的 Session 归档成功后,status 变为 terminated(已终止),archived_at 记录首次进入该状态的时间。归档后的 Session 不能再更新、升级或写入事件。

归档接口支持幂等调用。已终止 Session 重复归档时保留已有 archived_at;对于归档功能上线前已经终止且缺少 archived_at 的历史 Session,服务端不会用本次调用时间补写。重复归档也不会延长事件、Trace 记录以及图片、视频等媒体数据的保留期。需要长期保存时,应在对应数据到期前导出到自己的存储。

删除 Session#

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

数据保留与删除影响#

Session 资源记录、完整事件、Trace 记录、图片和视频等媒体数据、沙箱状态以及 Agent 产物使用独立的保留策略。归档只改变 Session 的可用性和运行资源状态,不会统一延长这些数据的保留期:

对象 默认保留与恢复规则 归档 Session 后 删除 Session 后
Session 资源记录 除非显式删除,否则持续保留 Session 配置记录仍可查询 资源记录不可再查询
Session 事件历史 每条已持久化的完整事件默认保留 6 个月;event_start 和 event_delta 预览帧不写入历史 继续按原保留期保存,不因归档延长 该 Session 的事件全部删除
Trace 记录和图片、视频等媒体数据 分别遵循对应功能的保留期限 继续按各自保留期限处理,归档不会将这些数据改为永久保留 删除 Session 不表示外部存储中的相关数据会立即清理,仍以对应功能的保留规则为准
沙箱状态 Session 处于 idle 且尚未终止时,可以恢复文件系统、已安装软件包和沙箱中的临时文件。Session 连续处于 idle 达到 14 天后进入 terminated Session 进入 terminated,平台开始回收运行资源 关联沙箱及其中的临时状态被清理
Agent 产物 方舟默认存储只用于临时保存关联产物;写入自有 TOS Bucket 的对象遵循你配置的 Bucket 生命周期 默认存储中的关联产物随运行资源回收;自有 TOS Bucket 中的对象不受影响 默认存储中的关联产物被清理;自有 TOS Bucket 中的对象不受影响