agent-eval-gate

Codex、OpenAI互換エージェント、MCPクライアント向けのTrace Inspector + Eval Gate。 これは独立したMITライセンスの実装であり、制限されたソースコードを複製したり、公式のOpenAI/Codexプラグインであると主張したりするものではありません。

Install

Python 3.11+が必要です。

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

Related MCP server: agent-eval-mcp

CLI

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 schema

1行に1つの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）、レイテンシ、トークン合計、エラータイプ、正規化された失敗クラス、最終ステータス、コンテキスト予算の使用量をカウントします。コンテキスト予算は入力トークンと出力トークンの合計と比較されます。トークン化はプロデューサーに委任されるため、このツールは隠れたトークンを推定しません。

失敗クラスには、schema_error、permission_denied、timeout、tool_error、duplicate_operation、unknown_side_effect、model_error、unknownが含まれます。

Golden cases

ケースJSONはトレースとオプションの制約を指定します：expected_tools、forbidden_tools、max_tokens、max_steps、expected_final_status、context_budget。このリポジトリのフィクスチャは合成データであり、公開されています。

MCP

オプションのSDKをpip install -e '.[mcp]'でインストールし、python -m agent_eval_gate.mcp_serverを実行します。構造化JSONを返す読み取り専用のinspect_traceとevaluate_case_fileツールを公開します。MCPクライアントがこのコマンドを起動するように設定してください。公式プラグインとの関係は暗示されていません。

Codex integration

CLIはCodexスキルまたはプラグインから直接呼び出せます。最小限のスキルでagent-eval-gate inspect <trace>とagent-eval-gate gate <case>を呼び出せます。MCPサーバーはローカルのstdioサーバーとして登録できます。トレースとケースは呼び出し元のワークスペースに置いてください。

Architecture and development

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

pytest、ruff check .、mypy agent_eval_gateを実行します。GitHub Actionsはプッシュとプルリクエストでこれらのチェックを実行します。既知の制限：ベンダー固有のトレースアダプタなし、確率的スコアリングなし、生のプロンプトからのトークン再カウントなし。

中国語の説明

これは、Codex、OpenAI互換エージェント、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をサポートします。オプションフィールドには、ツール名、引数、レイテンシ、トークン、再試行回数、エラータイプが含まれます。メトリクスのトークンはプロデューサーが提供するtokens.inputとtokens.outputを使用し、本ツールは隠れたトークンを推測しません。

リポジトリのfixturesとcaseはすべて自作の公開データです。MCP SDKはオプションの依存関係であり、サービスはローカルのtraceとcaseを読み取り専用で分析します。現在の制限には、ベンダー固有のアダプタがないこと、確率的スコアリングがないこと、元のプロンプトからの再トークン化カウントがないことが含まれます。