jq。这些示例将 AgentEye 的可观测性数据转化为终端用户或 AI 代码 Agent（Claude Code、Cursor）可查询和自动化处理的形式，无需点击仪表板。
以下模式可直接复制粘贴用于 AgentEye 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成功 ·2参数错误 ·3无法连接仪表板 ·4未登录或已过期 ·5权限不足。 - 使用
-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 命令——将事件记录与会话评估结合使用：
获取所有数据（分页）
结果按最新优先排列，使用游标分页。使用 —fields 精简输出
限制返回的字段（在表格和--json 中均生效），减少 Agent 需要读取的内容。
2），并列出有效字段，这也是探索字段名的便捷方式。
发现有效的过滤器值
选择组织（多租户）
如果你属于多个组织，可在登录时选择当前租户（会被保存）：--org 时会以非零退出码退出，并打印可选择的组织列表。
为 SDK/采集器创建 API 密钥
运行已保存或临时查询
非交互式处理告警事件
在--json模式下或 stdin 非 TTY 时，变更操作会自动跳过确认提示，因此 Agent 不会挂起；在其他情况下可显式传入--yes/-y跳过确认。
脚本中的退出码处理
JSON 输出结构
| 命令 | stdout JSON（使用 --json） |
|---|---|
whoami | {"logged_in": true, "id", "email", "is_instance_admin", "active_org", "permissions": [...], "memberships": [...]} 或 {"logged_in": false} |
orgs list | {"active_org", "orgs": [{"org_slug","org_name","permission_set","permissions"}]} |
events | {"events": [...], "next_cursor": <cursor or null>} |
evals | {"evaluations": [...], "next_cursor": <cursor or null>} |
sessions | {"sessions": [...], "next_cursor": <cursor or null>} |
errors | {"errors": [...], "next_cursor": <cursor or null>} |
list <kind> | {"kind", "values": [...]} |
keys list / keys create | {"keys": [...]} / {id, name, permissions, created_at, key}（key 仅显示一次） |
query run | {columns: [{name,type}], rows: [[...]], truncated, elapsed_ms} |
users list / settings list | {"users": [...]} / {"settings": [...]} |
alerts list / incidents list | {"alerts": [...]} / {"incidents": [...]} |
| create/update/delete（任意） | 资源对象，或删除时返回 {"deleted": true, "id"} |
失败（任意，使用 --json） | stdout 输出 {"error": "...", "exit_code": <n>, "status"?: <http>, "hint"?: "..."} |
- 每个 event 条目（
events）：id, session_id, agent_id, event_type, ts, payload, environment。 - 每个 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 的字段集不同，因此对一个命令有效的字段名可能被另一个命令拒绝。