文档中心

火山方舟

委派任务给 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 运行配置

状态迁移规律：

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 资源的状态值是 rescheduling；对应的 SSE 状态事件名是 session.status_rescheduled。调用查询接口或使用 status 参数过滤时，应传 rescheduling，不要传事件名中的 rescheduled。

检索 Session

通过 GET /sessions/{session_id} 拿到 Session 的最新状态、用量统计、配置快照：

Curl

curl 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 配过结果评估，响应中还会出现 outcome_evaluations 字段；该字段的解读详情请参见定义结果，本文不展开。

列出 Session

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

Curl

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 表示升级流程已结束。

注意

不要通过更新会话接口修改 Agent、Environment、tools 或 mcp_servers。该接口只更新标题和标签。运行配置变更必须调用升级会话接口，否则请求字段不在该接口的契约中。

删除 Session

注意

不可逆。删除会永久移除 Session 记录、所有事件和关联沙箱。删除接口只接受 idle 或 terminated 状态；其他状态会返回 InvalidAction。如果 Session 正在 running，先发送中断事件，等待状态回到 idle 后再删除。

Curl

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

Agent、Environment、Memory、Vaults、技能，以及通过 Files API 独立上传的输入文件，都是独立资源，不受 Session 删除影响。Agent 生成的产物按存储位置采用不同的清理策略：

你的存储方式	删除 Session 后
方舟公共 TOS	平台清理该 Session 在默认存储中的关联产物。
自己的 TOS Bucket	平台不删除 Bucket 中的对象。你需要在 TOS 中管理对象生命周期。

产物存储的配置方法，详情请参见配置产物存储。

沙箱状态保留期

Session 进入 idle 时，平台会保存一份沙箱状态快照，其中包括：

文件系统状态。

已安装的软件包。

Agent 在沙箱中创建的产物文件。

这让客户端能从非活动状态干净恢复，给 Session 发新的 user.message 就能继续之前的工作（详情请参见 Session 事件流 § 恢复空闲 Session）。

说明

保留期差异：

Session 历史：除非显式删除，永久保留。

沙箱状态快照：Session 连续处于 idle 状态时，从最后活动时间起保留 14 天。

自有 TOS 产物：不跟随沙箱状态快照过期。你需要在 TOS 中配置和管理 Bucket 生命周期。

如果需要保留沙箱状态快照超过 14 天，请在快照过期前发送一条包含有效 content 的 user.message。Session 完成本轮任务并再次进入 idle 后，平台会重新计算 14 天保留期。省略 content 或传入空数组不会刷新保留期。

最近更新时间：2026.09.14 20:02:04

这个页面对您有帮助吗？

有用

无用