Sessions 与 Tasks
Session 是一个运行时容器——它持有浏览器、profile（cookies / 登录态）、workspace（文件系统）。Task 是跑在 session 里的一条 instruction。同一 session 可以接连跑多个 task，它们共享前一个 task 留下的状态。
资源形态
text
project
└── session id: sess_…
├── browser, profile, workspace
└── task id: task_…
├── instructions "搜 Hacker News..."
├── status running | done | …
└── events (SSE) task.status_changed, task.message, …生命周期（7 态）
mermaid
stateDiagram-v2
[*] --> pending
pending --> running
running --> awaiting_input : task.input_request
awaiting_input --> running : POST /intervene
running --> paused : POST /pause
paused --> running : POST /resume
running --> done
running --> failed
pending --> canceled
running --> canceled : POST /cancel
awaiting_input --> canceled
paused --> canceled| 状态 | 含义 | 下一步 |
|---|---|---|
pending | 已接收，等 agent slot | → running、canceled |
running | agent 在跑 | → done、failed、awaiting_input、paused、canceled |
awaiting_input | agent 自己暂停了，等你回应 | → running（通过 intervene） |
paused | 你手动暂停 | → running（resume）、canceled |
done | 成功完成；output 已落 | 终态 |
failed | 报错；error.code error.detail 已落 | 终态 |
canceled | 你取消（或 max_duration 触发） | 终态 |
非终态都占 session 资源。用 max_duration_minutes 兜底。
提交一个 task
python
from web_agent import Client
from web_agent.v1.types import CreateSessionRequest, RecordingConfigRequest
session = await client.sessions.create(CreateSessionRequest(
instructions="找出 24 小时内 Show HN 上 Top 5 的帖子。",
model="claude-sonnet-4.6",
max_cost_usd="0.50",
max_duration_minutes=10,
recording=RecordingConfigRequest(enabled=True),
keep_alive=True,
))
task = session.tasks[0]| 字段 | 类型 | 说明 |
|---|---|---|
instructions | string | 一段中文 / 英文。最多 10 000 字符 |
model | string | 模型 id，如 claude-sonnet-4.6 / gemini-3-flash |
max_cost_usd | string | decimal-as-string；硬上限 |
max_duration_minutes | int | 1–10 080（一周） |
recording | object | {enabled, quality, capture_during_take_control}；不传 = 关 |
keep_alive | bool | task 结束后保持 session 热度，方便接 follow-up task |
allowed_actions | string[] | 允许 agent 调的工具白名单。空数组 = 全允许 |
profile_id | string | 复用 profile 的 cookies / 登录态 |
完整 schema 见 OpenAPI spec。
Follow-up task
python
from web_agent.v1.types import CreateTaskRequest
followup = await client.sessions.create_task(
session.id,
CreateTaskRequest(instructions="点进第一篇帖子，总结一下评论区。"),
)跑在同一个浏览器里，cookies 与上一条 task 留下的 DOM 都在。
事件
每个 task 有一条 SSE 流：
http
GET /v1/projects/{pid}/do_anything/sessions/{sid}/tasks/{tid}/events
Authorization: Bearer wa_…11 种事件类型（envelope 一致；data 内容不同）：
| 类型 | 何时 emit |
|---|---|
task.status_changed | 状态切换 |
task.message | chat 里多一条（agent 或 user） |
task.action.started | agent 调用某工具 |
task.action.completed | 工具返回 |
task.action.failed | 工具抛错 |
task.screenshot | 浏览器新 frame（url 短期签名） |
task.input_request | agent 暂停，需要你回应 |
task.input_request_resolved | 你的 intervene 已采纳 |
task.cost_update | 一步的 cost 增量 |
task.completed | 终态；output 已落 |
stream.heartbeat | 约 15 s 一次；可忽略 |
断线干净续传：
http
GET …/events
Last-Event-ID: 142server 会重放 id > 142 的事件，不漏。
Input request（人在回路）
agent 撞到 captcha、2FA、判断不准的事，会发 task.input_request：
json
{
"type": "task.input_request",
"data": {
"input_request_id": "ir_01HXX…",
"prompt": "我看到一个 'Verify you're human' 挑战，你帮我点过去？",
"schema": { "type": "object", "properties": { "solved": { "type": "boolean" } } }
}
}你 POST /intervene 回：
python
await client.messages.intervene(
session.id, task.id,
input_request_id="ir_01HXX…",
response={"solved": True},
)task 切回 running。整轮一次往返，无 polling。
Profiles
Profile = 可复用的浏览器身份：cookies、localStorage、登录态。create session 时引用：
python
await client.sessions.create(CreateSessionRequest(
instructions="打开 LinkedIn 收件箱，回复最新一条消息。",
profile_id="prof_linkedin_main",
))第一次在 Console 里手动设置 profile（登录、点 cookies、做你想做的）。后续 session 直接复用。
Workspaces
Workspace = 持久文件系统。agent 可读可写；task 跑完后用签名 URL 取文件。"抓这个站，写 CSV，丢回来"这种场景常用。
接下来
- API 参考 —— 每个字段
- 鉴权 —— key、scope、轮换
- Vibecoding —— 怎么把这些喂给 IDE