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。 - 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 的详细信息,包括智能体、会话运行环境、资源、状态、累计用量和标签等:
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 列表。
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(运行中)的工具任务时,也会拒绝归档;请等待工具任务结束或取消工具任务后重试。
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#
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 中的对象不受影响 |