火山方舟
火山方舟
文档指南
请输入
- 文档首页
火山方舟Managed Agents委派任务给 Agent启动 Session
复制全文
下载 pdf启动 Session
文档反馈
问问助手Session 是托管 Agent 在某个 Environment 中跑某个 Agent 的一次实例。一个 Session 在多次交互中维护对话历史、保留沙箱状态，允许 Agent 跨轮次记住之前做过的事情。
启动一个 Session 分两步：
- 创建 Session：配置沙箱、绑定 Agent 与 Environment，此时 Agent 不开始任何工作。
- 发送首个事件：通过 user.message 事件把任务交给 Agent，Session 进入 running 状态开始执行。
准备工作
开始前你需要：
- 已创建的 API Key：配置为环境变量 ARK_API_KEY，详情请参见 API Key 管理。
- 已创建的 Agent：详情请参见 定义 Agent。
- 已创建的 Environment：详情请参见 配置云环境。
创建 Session
创建 Session 必需两个上游资源 ID：
- Agent ID：由 定义 Agent 创建后获得，形如 agent-20260701120000-xxxxx。
- Environment ID：由 配置云环境 创建后获得，形如 env-20260701120000-xxxxx。
使用 Agent 最新版本（推荐入门）
Agent 是带版本的资源，以字符串形式传入 agent ID 时，Session 会用该 Agent 的最新版本启动。
curl https://ark.cn-beijing.volces.com/api/v3/sessions \
-H "Authorization: Bearer $ARK_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"agent": "agent-20260701120000-abcde",
"environment_id": "env-20260701120000-fghij"
}'
响应返回完整的 Session 记录，其中 id 字段（形如 sesn-20260701120100-xxxxx）是后续所有操作的入口：
{
"id": "sesn-20260701120100-xxxxx",
"type": "session",
"status": "idle",
"environment_id": "env-20260701120000-xxxxx",
"agent": {
"id": "agent-20260701120000-xxxxx",
"type": "agent",
"version": 3
},
"created_at": "2026-06-29T10:00:00Z",
"updated_at": "2026-06-29T10:00:00Z",
"resources": [],
"vault_ids": null
}
响应中 status 为 idle，表示 Session 已就绪等待首个事件。Session 会经历 idle → running → idle/terminated 等状态迁移；进入 idle 时，平台会保存沙箱状态快照，便于后续恢复。状态机与沙箱状态保留期详情请参见 沙箱状态保留期。
固定 Agent 版本（灰度发布场景）
当你需要把 Session 锁定到 Agent 的某个具体版本（用于回滚、灰度对比、产品定版）时，以对象形式传入 agent，显式指定 version：
curl https://ark.cn-beijing.volces.com/api/v3/sessions \
-H "Authorization: Bearer $ARK_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"agent": {"type": "agent", "id": "agent-20260701120000-abcde", "version": 1},
"environment_id": "env-20260701120000-fghij"
}'
固定版本后，即使该 Agent 后续发布了新版本，本 Session 仍按 version: 1 的行为运行。这让你可以分阶段灰度推出新版本，而不影响存量 Session 的行为一致性。
覆写产物存储（可选）
需要沿用 Environment 的产物存储配置时，在创建 Session 时传入 environment_id：
- Environment 未配置 config.tos：产物使用方舟公共 TOS。你需要在平台 TTL 到期前下载所需文件。
- Environment 已配置 config.tos：产物写入你配置的 TOS Bucket，完整对象路径为 {prefix}outputs/{env-id}/{session-id}/{file}。
只有当前任务需要使用不同的 Bucket 或 prefix 时，改用 environment 对象创建 Session，并通过 environment_with_overrides 临时覆写 config.tos：
session=$(
curl -sS --fail-with-body "https://ark.cn-beijing.volces.com/api/v3/sessions" \
-H "Authorization: Bearer $ARK_API_KEY" \
-H "Content-Type: application/json" \
-d @- <<EOF
{
"agent": "$AGENT_ID",
"environment": {
"type": "environment_with_overrides",
"id": "$ENVIRONMENT_ID",
"config": {
"type": "cloud",
"tos": {
"bucket": "<TOS_BUCKET>",
"prefix": "session-outputs/"
}
}
},
"title": "Session with output storage override"
}
EOF
)
SESSION_ID=$(jq -er '.id' <<<"$session")
echo "Session ID: $SESSION_ID"
Environment 覆写遵循以下规则：
- environment_id 与 environment 二选一，不能同时传入。
- environment.id 指向作为基础配置的 Environment。
- config.tos 是原子配置。传非空对象时，bucket 和 prefix 必须同时提供。
- 省略 config.tos 时，产物使用 Environment 中配置的存储位置；传空对象 {} 时，本次 Session 的产物存入方舟公共 TOS。
- 覆写只对当前 Session 生效，不会修改原 Environment，也不会影响之后创建的其他 Session。
注意
无论沿用还是覆写存储配置，都让 Agent 将交付物写入 /mnt/session/outputs/。Environment 覆写不会改变 Agent 使用的沙箱目录。
通过 Vaults 注入终端用户凭据（可选）
最简示例，把 Vaults（凭据保管库）挂到 Session：
curl https://ark.cn-beijing.volces.com/api/v3/sessions \
-H "Authorization: Bearer $ARK_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"agent": "agent-20260701120000-abcde",
"environment_id": "env-20260701120000-fghij",
"vault_ids": ["vlt-20260701120000-pqrst"]
}'
启动 Session：发送第一个事件
注意
创建 Session 仅完成沙箱配置，不会启动任何工作。 必须发送 user.message 事件，Agent 才会开始执行。
这种解耦设计让客户端可以先注入 Vaults 凭据、检查沙箱环境，再发送首个事件启动 Agent。
向 Session 的事件入口 POST /sessions/{session_id}/events 提交一条 user.message 事件，Session 状态会从 idle 切换到 running，Agent 进入工作。
curl https://ark.cn-beijing.volces.com/api/v3/sessions/sesn-20260701120100-klmno/events \
-H "Authorization: Bearer $ARK_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"events": [
{
"type": "user.message",
"content": [
{"type": "text", "text": "List the files in the working directory."}
]
}
]
}'
响应模型与下一步
发送事件后，Session 进入 running 状态。要实时看到 Agent 的进度（消息、工具调用、思考过程），请配合 Session 事件流 打开 SSE 流接收 agent.* 事件；若仅需轮询状态，可周期性 GET Session 详情，详情请参见 管理 Session。
最近更新时间：2026.08.27 11:36:07
这个页面对您有帮助吗？
有用
有用
无用
无用