jq。这些脚本将 Failproof AI Observability 的数据转化为终端用户或 AI Coding Agent（Claude Code、Cursor）可以查询和自动化处理的格式，无需点击仪表盘。
以下模式均可直接复制粘贴，适用于 Failproof AI Observability CLI（agenteye）。安装、认证及完整选项列表请参阅 CLI；运行 agenteye -h 或 agenteye <command> -h 查看内置帮助。
基本规则
- 全局选项必须放在命令之前。
agenteye --json sessions是正确的；agenteye sessions --json则不对。全局选项包括--json、--base-url、--org、--token、--insecure/--secure、--timeout、--quiet、--no-color。 - 解析输出时始终传入
--json。 数据以 JSON 格式输出到 stdout；人类可读的状态和错误信息输出到 stderr，因此 stdout 保持干净，可直接通过管道传入jq。 - 根据退出码而非 stderr 文本做分支判断：
0正常 ·1意外错误 ·2参数有误 ·3无法连接仪表盘 ·4未登录或已过期 ·5缺少权限 ·6资源未找到。 - 通过
-h探索命令。 每个命令都会说明其过滤器、值格式和 JSON 结构。
一次性初始化
执行操作前确认认证状态
whoami 在会话缺失或过期时不会报错，而是返回 logged_in:false，因此 Agent 可以安全地探测认证状态。（如果未设置 base URL 或仪表盘不可达，仍可能以非零状态退出。）
查找失败或低分会话
evals 上进行，而非 sessions。--score KEY:MIN..MAX 可重复使用，多个条件取 AND；任意一端为可选（..0.5 表示 ≤ 0.5，0.9.. 表示 ≥ 0.9）。每次请求最多可传入 20 个评分过滤条件，超出则返回 HTTP 400。sessions 与 evals 共享 --env、--status、--agent-id、--session-id 以及时间范围过滤器，但不支持 --score。
端到端读取一个会话
没有单独的session show 命令，可将事件轨迹与会话评估结合使用：
注意： 默认情况下，events读取的是快速、无载荷的数据流。每个事件包含服务端计算的单行summary以及is_error、token 计数等标志，但payload返回为{}。若要获取原始载荷，请添加--full（或--fields payload）。完整数据流在数据量大时速度较慢，因此建议限制范围：将--full与单个--session-id配合使用。
获取全量数据（分页）
结果按最新优先排序，使用游标分页。通过 —fields 精简输出
限制字段（表格和--json 均适用），减少 Agent 需要读取的内容。
2）并附带有效字段列表，这也是探索字段名的便捷方式。
探索有效过滤器值
选择组织（多租户）
如果你属于多个组织，可在登录时选择当前租户（会保存选择）：--org，将以非零状态退出并列出可选择的组织。
为 SDK/collector 创建 API 密钥
运行已保存或临时查询
非交互式故障排查
注意： 在--json模式下或当 stdin 不是 TTY 时，变更操作会自动跳过确认提示，因此 Agent 不会挂起；在其他情况下可显式传入--yes/-y跳过确认。
脚本中的退出码处理
JSON 输出结构
- 每个 event 条目（
events）：id, session_id, agent_id, event_type, ts, payload, environment, summary, is_error, error_type, output_tokens, context_window, context_fill。注意：除非通过--full（或--fields payload）请求完整数据流，否则payload为{}。 - 每个 evaluation 条目（
evals）：id, session_id, agent_id, environment, status, scores, reasoning, summary, error, attempt_count, duration_ms, completed_at, created_at。 - 每个 session 条目（
sessions）：session_id, agent_id, environment, status, scores, event_count, started_at, last_event_at, first_event_id, last_event_id, latest_evaluation。
--fields 只接受其对应条目的字段名。sessions 和 evals 的字段集不同，因此对一个命令有效的字段名可能被另一个命令拒绝。
下一步
- CLI：安装、认证及每个命令的完整选项参考。
- CLI agent skill：将这些脚本打包为 AI Coding Agent 可加载的技能。
- API keys：创建并限定 CLI、SDK 和 collector 认证所用密钥的权限范围。
- Python SDK：向 Failproof AI Observability 发送事件，为上述脚本提供可查询的数据。