跳转到主要内容
使用这些接口向 Session 提交一个任务、恢复查询结果、观察持久事件并请求取消。以下路径均包含 /v1。Owner 和应用 Token 可以访问这些路由,但仍须通过租户归属和状态检查。本文描述当前源码契约。下文限定范围的 HTTP 检查使用隔离数据库验证提交、观察与取消接口,不代表完成模型或实云执行验收。

提交 Run

POST /v1/sessions/{session_id}/runs 返回 202 和 Run 对象。{session_id} 必须是当前认证租户拥有的 UUID。 请求体和 origin 中的未知字段会被拒绝。输入与编译后初始化上下文还必须满足合计 120,000 UTF-8 字节的限制,不能只检查字符长度。省略或传入空 origin 时保存为 {}。 发送前持久化 Session ID、精确请求体和幂等键。已有 Session 和可信后端 Token 时,将以下内容保存为 run-request.json:
使用事先保存的幂等键发送:
HEXAGON_API_URL 是不带 /v1 的控制平面 origin。这些 shell 变量是示例输入,不是服务器配置项;不要在录制的 shell 跟踪中暴露 Token。开始观察前先保存响应 ID。202 只说明任务被接受,不代表执行完成、Sandbox 已就绪、测试通过或产物已经导出。

幂等与状态规则

查找键由租户、Session 和幂等键共同组成。请求哈希覆盖输入文本及非空的已解析 origin。恢复请求时原样发送保存的请求体;使用同一键修改 input 或 origin 会返回 409 idempotency_conflict。查找既有提交先于新任务状态检查,因此即使 Session 后来关闭,匹配的旧请求也能返回原 Run 的当前状态。这不允许在已关闭 Session 中创建新任务。 新键允许的 Session 状态是 open、paused、pausing、resuming,由 worker 执行唤醒或对账。同一 Session 只允许一个非终态 Run,繁忙时拒绝提交,不会自动排到当前任务之后。Sandbox 和模型连接仍需启用、ready 且未删除;引用的上下文文件在接受任务前核对上传内容。Run 与初始 run.queued 事件在同一事务提交。 提交接口 HTTP 记录包含真实本机 HTTP 与 PostgreSQL 上的 27 项检查。两个并发相同提交返回同一 Run,且只产生一条 queued 事件;两个不同键竞争空闲 Session 时,一个被接受,另一个返回 session_busy。Session 关闭且连接禁用后,匹配的重放仍以 HTTP 202 返回原已完成 Run。这些观察验证提交事务,不证明 worker 执行或全部并发交错情况。 输入同时受两层限制。例如,40,001 个 界 符合 100,000 个 JavaScript 码元的限制,但占 120,003 个 UTF-8 字节,即使没有额外上下文也会返回 413 input_too_large。提交记录应保留精确的目标文本,不能在重试时静默截断。上下文文件与编译后上下文分支仍须满足上述独立要求,不在这份 HTTP 记录的验证范围内。 响应丢失不同于上表中的明确错误。使用相同请求体和幂等键重发原提交以恢复 Run,不要为网络重试生成新键。通用响应形状见错误参考。

恢复提交,避免创建第二个任务

提交 handler 对新 Run 和匹配的重放都返回 202。因此重放响应中的状态可以已经是 completed、failed 或 cancelled。不能仅凭 HTTP 状态码判断本次是否创建任务;应将返回的 Run ID 与持久化提交记录关联,再判断当前状态。 幂等判断基于解析后的请求值,不是 JSON 文件的原始字节。JSON 缩进和属性排列不会创建新任务;省略 origin 与传 {} 等价。输入文本原样保存,因此给 input 增加结尾换行会改变请求。origin.request_id 是参与哈希的关联元数据,不能替代请求头中的幂等键;保持键不变而修改它会冲突。实际恢复时保持已保存请求不变,避免依赖归一化细节。 查找范围是租户和 Session,不是某个应用用户或 Token。同租户重放不能证明你的应用终端用户拥有该任务;后端转发请求前仍须检查业务用户映射。提交去重也不保证外部 Tool 写入恰好执行一次;外部结果不确定时遵循 Tool 对账契约。

Run 响应对象

提交、GET /v1/runs/{id}、取消和单 Session Run 列表采用下列公开投影: 新提交的 execution_identity 包含 tenant_id、session_id、agent_id、agent_revision,以及认证流程提供时的 principal(可含 key_id 和 role)。直接创建的 Session 可能没有已保存 Agent 身份,历史行可能为 {}。不能用调用方提供的 origin 证明身份,也不能把身份快照当作独立访问凭据。Worker 租约字段、请求哈希、幂等键和 Runtime 游标不属于 publicRun。 Run 状态为 queued、provisioning、running、waiting_authorization、waiting_approval、cancelling、completed、failed、cancelled。只有最后三个是终态。Session 与 Runtime 状态另行定义,见事件和状态。 查询单个 Run 不需要请求体或查询参数:
成功返回 200。不存在或其他租户的 Run 返回 404 run_not_found。

公开响应示例与解读

以下响应由真实 GET handler 配合确定性数据库 fixture 生成。ID、时间和 assistant 问候语都是示意,不是模型执行回执。handler 检查还覆盖缺失 Run、无效 UUID 和未提供身份的响应。
需要结合字段判断:
  • state: completed 表示该 Run 结束,不会关闭父 Session。
  • output.artifacts: [] 是这个 fixture 的结果,不是导出文件,也不证明工作区任意文件可下载;已记录的导出应查询产物端点。
  • 直接创建的 Session 可以有 agent_id: null、agent_revision: null,不能要求每个 Run 都有模板。
  • origin.request_id 是调用方元数据,execution_identity.principal 是持久化的认证上下文;二者都不是可复用凭据。
  • 响应不包含 Idempotency-Key、请求哈希、租约或 Runtime cursor。保留自己的原始提交记录,GET 无法为你找回幂等键。
非终态响应的 error 可以包含恢复诊断;应按 state 判断终态,不只看 error 或 output 是否存在。轮询与新事件发生竞争时,继续观察原 Run,不另行制造一次提交。

两种不同的 Run 列表契约

单 Session 的 Runs

GET /v1/sessions/{session_id}/runs 返回 200 和 { "runs": [...] },每项为完整公开 Run 对象。可选 before 必须通过 datetime 校验,比较条件是严格的 created_at < before。每页最多 100 项,按创建时间倒序,不返回 next_offset 或 has_more。
第一页省略 before。当前只有时间戳游标,没有 ID 辅助排序;页边界时间戳相同的记录可能被跳过,因此不能承诺通过该游标无遗漏导出所有历史。Session 不存在或属于其他租户时返回 404 session_not_found。

全租户 Run 摘要

GET /v1/runs 返回 200,形状为 { "runs": [...], "offset": 0, "next_offset": null },存在下一页时 next_offset 为数字。 搜索对 Run ID、Session ID、输入文本和 Session definition 名称做不区分大小写的子串匹配。结果按 created_at DESC, id DESC 排序。每项包含 id、session_id、state、created_at、updated_at、error、input_preview(数据库文本前 240 字符)和 agent_name。这是摘要,不是完整 Run 响应。并发插入可能移动 offset,不构成快照导出。

选择正确的分页游标

这些游标不能混用。例如,101 个 Run 共享同一时间戳时,Session 列表可能先返回 100 条,再以该时间戳作为 before 得到空页。相对地,501 条持久事件可以先读取 500 条,再使用最后一个事件 ID 读取剩余一条。提交任务时保存业务请求和 Run ID,不要依赖事后扫描列表重建完整业务账本。

查询或订阅持久事件

GET /v1/runs/{id}/events?after=0 返回 200 和 { "events": [...] }。每项包含字符串 id、字符串 type、JSON data 和 created_at。after 默认 "0",只能包含十进制数字,且不包含游标对应事件。每页最多 500 项,按序号递增。保存最后处理的 ID,序号有间隔是正常情况;继续查询至无返回项,Run 仍活动时继续观察。没有事件不等于完成。 将服务端返回的游标作为十进制字符串保存,并与对应 Run 关联。初次从 "0" 开始;不要转换为 JavaScript Number、自行加一或从时间戳推导 ID。当前查询使用 PostgreSQL 有符号 64 位序列范围,而请求校验仅要求字符串全部为数字。超出范围的数字游标在 JSON 事件接口上目前返回 500 internal_error,不能保证返回明确的 400 参数错误。发现游标损坏时从持久化检查点恢复,不要反复重试同一个超大值。
GET /v1/runs/{id}/stream 返回 200 和 text/event-stream。游标优先级为显式 after、Last-Event-ID、"0"。持久事件通过 SSE 的 id、event、JSON data 输出,不携带 JSON 列表中的时间戳字段。心跳使用注释帧 : keepalive,约 15 秒检查发送;没有新页面时服务端每 500 毫秒检查数据。
服务端观察到 Run 终态后会再次检查持久事件,再发送不带编号的 stream.end,其数据形如 { "state": "completed" },也可能为 failed/cancelled。此处是响应形状,不是执行记录。不要把 stream.end 保存为新游标。意外 EOF 后使用最后已提交游标重新查询或连接;关闭客户端流不会取消 Run。Run 不存在或属于其他租户时在建立流之前返回 404;发送响应头之后的异常则可能体现为断流。

取消 Run

POST /v1/runs/{id}/cancel 无必需请求体,返回 200 和公开 Run 对象:
queued Run 变为 cancelled,其他非终态 Run 变为 cancelling。待处理审批在同一事务过期,并持久化相应状态事件。已终态或已 cancelling 的 Run 返回当前对象,不重复产生取消转换。继续查询到终态;此操作不承诺立即终止进程、撤销已派发 Tool 写入或清理 Session 资源。工作结束后另行关闭 Session。Run 不存在或属于其他租户时返回 404 run_not_found。

取消可能与完成发生竞争

返回对象反映获取 Run 锁时观察到的状态。若完成先提交,取消返回 completed,不会把结果改为 cancelled。若在 queued 时取得锁,则返回 cancelled;其他活动状态会请求转入 cancelling,还需要等待 worker 收尾。200 说明取消端点处理了请求,不保证最终状态一定为 cancelled。 对 cancelling 或终态 Run 重复取消不会追加另一个取消事件;这条直接返回路径也不会重新执行待处理审批清理。审批过期、进程收尾、外部写入对账和 Session 关闭各有自己的契约,不能仅凭取消的 HTTP 状态推断它们全部完成。

验证范围

Run 观察接口 HTTP 检查记录 包含 40 项检查:使用当前服务端、本机 HTTP、真实 PostgreSQL 和已迁移的隔离 schema,覆盖两个列表接口、单 Run 查询、JSON 事件、SSE 与取消。检查包括租户边界、应用 Token 访问、分页、游标优先级、真实客户端断开与重连,以及取消的状态、事件和审批事务。检查结束后已移除临时 schema。 该检查中的 Run 完成由受控数据库状态变更产生,没有运行模型、Harness 或取消 worker,没有验证浏览器与代理,也没有提交真实任务。单独的实云执行旅程见首个 Session 教程;上述 HTTP 检查不会扩大教程中已验证的 Provider 和模型范围。 来源:HTTP 路由与公开投影、提交、事件和取消、集合查询。下一步:HTTP 总览、事件参考、故障恢复。