/v1 路由要求认证和租户归属。Health、Run 集合与 Session 列表/活动允许应用 Token;overview、pending、Fleet 要求 owner。
健康检查
GET /v1/health 查询数据库,返回 process_id、布尔 active_runs、api/database 就绪、credentials、credential_access、execution。可选健康服务可能返回 not_configured。Credentials.state=unavailable 时返回 503,其他正常响应为 200;数据库异常进入服务器错误处理。必须检查字段,不能只看状态码:处理器不会把每一种 execution/access 降级情况都转换成 503。
GET /health/live 是独立的未认证存活检查,返回 {status:"alive"},不查询依赖。运维决策应使用就绪和生命周期诊断,不能以存活代替完整健康。
Session 集合
GET /v1/sessions 返回 200、{sessions:[...],offset,next_offset}。Limit 默认 25,整数 1–100;offset 默认 0,非负整数;search 默认空,最多 200 字符;state 默认空,最多 40 字符。非空 state 精确过滤 Session 状态;search 对 Session ID、Agent ID、definition 名称做不区分大小写的子串匹配。排序为 created_at DESC、id DESC;观测到末页时 next_offset 为 null,并发插入可能移动页面。
任务活动
GET /v1/sessions/activity 接受 period=24h(默认)或 7d,返回 200,包含 active_sessions、idle_sessions、paused_sessions、period、buckets、checked_at。
分类未必互斥:刚提交工作但仍 paused 的 Session 可以同时算 active 和 paused。每个 bucket 包含 start、active_sessions。24h 使用逐小时滚动区间,7d 使用逐日滚动区间,以查询时间为基准,不是自然日零点。终态 Run 的重叠截止 updated_at,非终态延伸到当前时间。统计覆盖租户完整数据,不受当前 Session 列表页影响。它衡量任务活动,不是 CPU、HTTP 流量或计费计算量。
总览
GET /v1/overview 返回 200,包含 checked_at 和以下计数:
- ready_connections:未删除、已启用、ready 的连接。
- open_sessions:仅 open,不是全部未关闭 Session。
- active_runs:全部非终态 Run。
- pending_approvals:pending 审批。
- pending_authorizations:waiting_authorization 的 Tool calls。
- unknown_operations:全部 unknown 资源操作,包括已 acknowledged 的项。
- active_agents:未归档模板。
待处理工作
GET /v1/pending 返回 200、{items:[...],offset,next_offset},limit/offset 与集合查询相同。共享解析器虽然接受 search/state,但当前 SQL 不应用这两个过滤条件,因此不能将它们宣传为此接口的筛选功能。
Fleet 快照
GET /v1/fleet 返回 200、{sessions:[...]},最多最近 200 个 Session,无分页契约。每项包含 id、agent_id、definition、env_names、state、sandbox、created_at、updated_at、runtime_state、latest_run、resource_operations。
400 invalid_request;应用 Token 访问 owner 路由返回 403 owner_token_required;未认证返回 401。具体调查使用资源操作与 Runs。来源:查询实现、Fleet 投影、HTTP 路由。监控契约审阅通过当前处理器和真实 PostgreSQL,在新建并迁移的隔离 schema 中完成 36 项检查,覆盖角色、租户隔离、分页、search/state 语义、pending 分类、活动重叠、Fleet 上限与就绪响应。测试后已删除 schema。这些是受控的持久状态 fixture,不是云监控或网络传输验收。
SDK 示例:分别读取运维视图
使用已初始化的 owner 客户端,因为 overview 和 pending 仅限 owner。这些函数只读,并保留各集合的响应外层,包括各自的next_offset。仅定义函数不会请求接口。TypeScript 片段使用 SDK 初始化时导入的 Hexagon。
read_operations_page / readOperationsPage 返回四次独立查询的观察,不是一个一致快照。Session 页的 next_offset 用作下一次 session_offset / sessionOffset,pending 页的游标则单独用作 pending_offset / pendingOffset。null 表示对应集合已到本次观察的末尾;不要把 Session offset 用于 pending,也不要由单页推断租户总量。并发变化可能移动 offset 分页。
示例只选 open Session,不包含所有未关闭 Session。overview 的未知操作计数可能包含已 acknowledged、因而不在 pending 队列中的操作;activity 类别也可能重叠,不能直接相加得到总资源数。pending 行用于提示调查:行动前读取对应审批、Tool 调用或资源操作,并重新核对当前状态。不要把这个只读函数扩展为自动批准循环。
通用 request 接收 /health,SDK 会补 /v1;传 /v1/health 会重复前缀。成功时返回 JSON,health 的 503 会成为 SDK 异常,不会由该函数作为普通状态对象返回。200 中仍可能有降级的执行或访问状态。读取结果不证明实时 Provider 状态或全局资源清理。鉴权、角色、校验、网络和解码错误向调用方传播;组合函数在首次失败时停止,没有内置部分结果恢复。
比较不同视图,不拼出虚假的总数
考虑这样一组持久状态:A 为 open,存在 running Run;B 为 paused,存在 queued Run;C 为 open,没有活动 Run;D 已 closed,但其 completed Run 曾在最近一小时执行。另有两条 unknown 资源操作,其中一条已 acknowledged,另一条仍待检查。
不要把 active、idle、paused 相加当作 Session 总数,也不要直接用历史桶与当前 active 数量比较。Acknowledgement 改变的是调查队列,不代表已消除记录中的不确定性或确认远程资源状态。决定动作前先读取底层记录。
理解空结果与不健康响应
- 集合查询的
state是有长度限制的文本,不按 enum 校验。未知状态可以返回200与空列表,不能据此证明没有任务。相反,activity 的period=30d等非法值返回400 invalid_request。 - Search 是不区分大小写的字面子串匹配,
%、_在这里不是 SQL 通配符。使用 URL 编码,确保服务端收到预期文本。 - 集合的
next_offset: null只描述本次查询观察到的末尾。Fleet 没有下一页游标,最多返回 200 个 Session;这些观察都不能证明全局资源已清理。 - 已关闭 Session 在 Fleet 中的
runtime_state被投影为stopped,Session 集合则暴露记录中的 Runtime binding 状态。字段不同前先确认各投影定义,不要将差异当作新的实时观察。 - 凭据不可用时,Health 返回
503,响应体仍为包含credentials.state的健康对象,而不是通常的{error:{code}}。curl --fail-with-body返回失败时仍保留该响应体。当前 SDK 的通用 request 将它转换为 status 503、codehttp_error的异常,上文 helper 不会返回其中的健康字段。独立 liveness 返回200不能抵消 readiness 失败。