文档中心

火山方舟

委派任务给 Agent

管理 Session

Session 创建后，你可以查询状态、筛选列表、更新标题和标签、升级运行配置，以及在任务结束后归档或永久删除 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 资源的状态值是 rescheduling；对应的 SSE 状态事件名是 session.status_rescheduled。调用查询接口或使用 status 参数过滤时，应传 rescheduling，不要传事件名中的 rescheduled。

选择获取方式

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

需要获取的内容	使用接口	返回内容和限制
实时接收 Agent 回复和状态；按需接收累计用量	GET /sessions/{session_id}/events/stream	通过 SSE（Server-Sent Events）协议订阅会话主线程收到的实时事件。请建立 SSE 并等待 : ready 后，再发送事件。
已持久化的完整事件	GET /sessions/{session_id}/events	用于查询会话主线程中已经产生的事件，主要用于历史事件查询和断线补查，返回信息不包含预览帧。
最新状态、累计用量和配置快照	GET /sessions/{session_id}	查询指定会话的详细信息，包括智能体、会话运行环境、资源、状态和标签等，不返回 Agent 回复或完整事件历史

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

检索 Session

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

Curl

响应示例：

响应主要字段：

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

更新与升级 Session

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

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

注意

不要通过更新会话接口修改 Agent、Environment、tools 或 mcp_servers。该接口只更新标题和标签，运行配置变更必须调用升级会话接口。archived_at 已有值（已归档）或 status 为 terminated（已终止）的 Session 不能更新或升级。

归档 Session

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

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

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

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

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

删除 Session

注意

删除 Session 操作不可逆。删除会永久移除 Session 记录、所有事件和关联沙箱。status 为 idle（空闲）或 terminated（已终止）的 Session 可以直接删除。其他状态会返回 InvalidAction。如果 status 为 running（运行中），先发送中断事件，等待 status 恢复为 idle 后再删除。

Curl

数据保留与删除影响

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 中的对象不受影响

数据保留提示

独立资源不受 Session 删除影响：删除 Session 时，方舟不会删除 Agent、Environment、Memory、Vaults、技能，也不会删除通过 Files API 独立上传的输入文件。这些对象是独立资源，需要按各自的生命周期管理。

长期保存 Agent 产物：如果需要长期保留 Agent 产物，在方舟默认存储中的关联产物被清理前，将产物写入自有 TOS Bucket；如果还需要保留事件记录，也要在事件到期前保存到自己的存储。产物存储的配置方法，详情请参见配置产物存储。

延长沙箱状态保留期：如果需要继续保留沙箱状态，在当前 14 天保留期到期前发送一条 content 非空的 user.message。Session 完成本轮任务并再次进入 idle 后，平台重新计算 14 天保留期。省略 content 或传入空数组不会刷新保留期。

最近更新时间：2026.10.30 21:22:46

这个页面对您有帮助吗？

有用

无用