agent-eval-gate

面向 Codex、OpenAI-compatible Agent 和 MCP 客户端的 Trace Inspector + Eval Gate。 这是一个独立的 MIT 许可实现；它不复制受限源代码，也不声称是官方的 OpenAI/Codex 插件。

安装

需要 Python 3.11+。

python -m pip install -e .
python -m pip install -e '.[dev]'

Related MCP server: agent-eval-mcp

命令行

agent-eval-gate inspect fixtures/normal.jsonl
agent-eval-gate eval cases/safe_search.json
agent-eval-gate gate cases/budget_fail.json  # exits 1 when a check fails
agent-eval-gate schema fixtures/normal.jsonl

eval 输出 JSON 且仅作信息展示；gate 适合 CI 使用，失败时返回非零退出码。

Trace 结构

每行一个 JSON 对象。type 为 run、model_call、tool_call、tool_result 或 error 之一。 可选字段包括 id、parent_id、timestamp、status、tool、arguments、latency_ms、attempt、tokens: {input, output} 和 error_type。

指标统计工具调用次数、唯一工具、重复的 (tool, arguments) 签名、重试（attempt > 1）、延迟、token 总量、错误类型、归一化失败类别、最终状态和上下文预算使用情况。上下文预算与输入加输出 token 进行比较；分词由生产者负责，因此本工具不会估算隐藏 token。

失败类别包括 schema_error、permission_denied、timeout、tool_error、duplicate_operation、unknown_side_effect、model_error 和 unknown。

Golden cases

Case JSON 指定一个 trace 名称和可选的约束：expected_tools、forbidden_tools、max_tokens、max_steps、expected_final_status 和 context_budget。本仓库中的 fixtures 是合成的公开数据。

MCP

使用 pip install -e '.[mcp]' 安装可选 SDK，然后运行 python -m agent_eval_gate.mcp_server。它提供只读的 inspect_trace 和 evaluate_case_file 工具，返回结构化 JSON。配置你的 MCP 客户端以启动此命令；不暗示任何官方插件关系。

Codex 集成

CLI 可直接从 Codex skill 或插件调用。一个最小的 skill 可以调用 agent-eval-gate inspect <trace> 和 agent-eval-gate gate <case>；MCP 服务器可以注册为本地 stdio 服务器。将 traces 和 cases 放在调用工作区中。

架构与开发

JSONL -> parser -> typed events -> deterministic analysis -> eval checks -> CLI / MCP JSON

运行 pytest、ruff check . 和 mypy agent_eval_gate。GitHub Actions 在推送和拉取请求时运行这些检查。已知限制：没有厂商特定的 trace 适配器、没有概率评分，也不会从原始提示重新统计 token。

中文说明

这是一个面向 Codex、OpenAI-compatible Agent 和 MCP 客户端的 Trace Inspector + Eval Gate 独立实现，采用 MIT 许可证，不是 OpenAI 或 Codex 官方插件，也不复制受限仓库代码。

安装需要 Python 3.11+：python -m pip install -e .。inspect 输出 JSON 指标，eval 执行并展示 golden case 检查，gate 在约束失败时返回非零退出码，适合接入 CI。事件 JSONL 的 type 支持 run、model_call、tool_call、tool_result、error；可选字段包括工具名、参数、延迟、token、重试次数和错误类型。指标中的 token 使用生产者提供的 tokens.input 与 tokens.output，本工具不会猜测隐藏 token。

仓库 fixtures 和 case 都是自造公开数据。MCP SDK 是可选依赖，服务只读分析本地 trace 和 case。当前限制包括没有厂商专用适配器、没有概率评分，也不会从原始 prompt 重新分词计数。