Runs、状态与用量

区分 Agent 生命周期与单轮执行状态，追加任务并读取结果和 token 统计。

This page has not been translated into English yet. The original Chinese version is shown below.

Agent 保留对话和 workspace，Run 对应一轮提示的执行。读取 Agent 的 latestRunId 后再查 Run，不能用 Agent 是否 ACTIVE 判断任务是否成功。

查询与分页

方法与路径	用途
`GET /v1/agents`	当前认证用户的 Agent，新建优先
`GET /v1/agents/{id}`	完整持久元数据及 latestRunId
`GET /v1/agents/{id}/runs`	某 Agent 的 Run，新建优先
`GET /v1/agents/{id}/runs/{runId}`	指定轮状态、结果与耗时
`GET /v1/agents/{id}/usage`	按轮拆分的 token 用量

Agent 与 Run 列表的 limit 默认 20、最大 100，使用 nextCursor 继续。Agent 列表还支持 prUrl 和默认 true 的 includeArchived。末页省略 nextCursor，不是返回 null；列表项只提供概要，需要详情时另查单个资源。

Agent 状态

ACTIVE：正在执行、等待后台工作或即将启动，应保持 worker 可用。
IDLE：上一轮结束，可接受后续提示；可恢复错误也会回到 IDLE，错误细节在 Run。
ARCHIVED：归档或到期，claim 结束，workspace 状态可清理。

归档 Agent 可通过 unarchive 恢复接收新 Run；不要把调度层面的终止状态理解为资源永远无法恢复。生命周期操作见产物与归档。

追加提示与取消

POST /v1/agents/{id}/runs 至少传 prompt.text。同一 Agent 同时只允许一个活跃 Run；已有 CREATING 或 RUNNING 时返回 409 agent_busy，等待其结束或取消后再发送。

追加时省略 mode 保留对话当前模式；提供 mcpServers 会替换本轮的创建时 inline MCP 配置，省略则保留当前配置。图像限制与创建时相同。

POST /v1/agents/{id}/runs/{runId}/cancel 把活跃轮变为 CANCELLED，不能恢复这一轮；继续对话要新建 Run。已终止或从未活跃的轮返回 409 run_not_cancellable。

最终结果与 Git 状态

FINISHED、ERROR、CANCELLED、EXPIRED 属于终止状态。终止后 durationMs 表示墙钟毫秒，result 提供最终助手文本。以具体状态判断结果，不能把有 result 当作成功。

git.branches[] 的每项包含 repoUrl、可选 branch 和 prUrl。这里的 Git 快照属于整个 Agent，同一 Agent 的不同 Run 可返回相同当前快照；它不是每轮独立改动记录。需要归因时结合 latestRunId 或 SSE。响应 repoUrl 不带 https://，请求 repos[].url 则保留协议。

Token 用量

usage 响应包含 totalUsage 和 runs，每轮可带 usageUuid。usage 包括 inputTokens、outputTokens、cacheWriteTokens、cacheReadTokens，totalTokens 为四者之和。

可用 ?runId=... 限定一轮，未知 ID 返回 404 run_not_found。尚无统计的轮仍会出现且各计数为 0，这不是最终零成本结论。该接口的 token 统计与团队 usage events 对应，不应自行把 token 总数当成美元账单。