agent-eval-gate

Trace Inspector + Eval Gate für Codex, OpenAI-kompatible Agenten und MCP-Clients. Dies ist eine unabhängige, unter MIT-Lizenz stehende Implementierung; sie kopiert keinen eingeschränkten Quellcode und erhebt keinen Anspruch auf ein offizielles OpenAI-/Codex-Plugin.

Installation

Erfordert 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 gibt JSON aus und dient der Information; gate ist CI-freundlich und liefert bei Fehlern einen Nicht-Null-Exit-Code.

Trace-Schema

Ein JSON-Objekt pro Zeile. type ist eines von run, model_call, tool_call, tool_result oder error. Optionale Felder umfassen id, parent_id, timestamp, status, tool, arguments, latency_ms, attempt, tokens: {input, output} und error_type.

Die Metriken zählen Tool-Aufrufe, eindeutige Tools, wiederholte (tool, arguments)-Signaturen, Wiederholungen (attempt > 1), Latenz, Token-Summen, Fehlertypen, normalisierte Fehlerklassen, Endstatus und die Nutzung des Kontextbudgets. Ein Kontextbudget wird mit Eingabe- plus Ausgabe-Tokens verglichen; die Tokenisierung wird dem Produzenten überlassen, sodass dieses Tool keine versteckten Tokens schätzt.

Zu den Fehlerklassen gehören schema_error, permission_denied, timeout, tool_error, duplicate_operation, unknown_side_effect, model_error und unknown.

Golden Cases

Case-JSON benennt einen Trace und optionale Einschränkungen: expected_tools, forbidden_tools, max_tokens, max_steps, expected_final_status und context_budget. Die Fixtures in diesem Repository sind synthetisch und öffentlich.

MCP

Installieren Sie das optionale SDK mit pip install -e '.[mcp]' und führen Sie dann python -m agent_eval_gate.mcp_server aus. Es stellt die schreibgeschützten Tools inspect_trace und evaluate_case_file bereit, die strukturiertes JSON zurückgeben. Konfigurieren Sie Ihren MCP-Client so, dass er diesen Befehl startet; es wird keine offizielle Plugin-Beziehung impliziert.

Codex-Integration

Die CLI ist direkt aus einem Codex-Skill oder -Plugin aufrufbar. Ein minimaler Skill kann agent-eval-gate inspect <trace> und agent-eval-gate gate <case> aufrufen; der MCP-Server kann als lokaler stdio-Server registriert werden. Bewahren Sie Traces und Cases im aufrufenden Workspace auf.

Architektur und Entwicklung

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

Führen Sie pytest, ruff check . und mypy agent_eval_gate aus. GitHub Actions führt diese Prüfungen bei Pushes und Pull Requests aus. Bekannte Grenzen: keine herstellerspezifischen Trace-Adapter, keine probabilistische Bewertung und kein erneutes Zählen von Tokens aus rohen Prompts.

Chinesische Erläuterung

Dies ist eine unabhängige Implementierung von Trace Inspector + Eval Gate für Codex, OpenAI-kompatible Agenten und MCP-Clients, lizenziert unter MIT. Sie ist kein offizielles OpenAI- oder Codex-Plugin und kopiert keinen Code aus eingeschränkten Repositories.

Für die Installation ist Python 3.11+ erforderlich: python -m pip install -e .. inspect gibt JSON-Metriken aus, eval führt Golden-Case-Prüfungen aus und zeigt sie an, gate liefert bei fehlgeschlagenen Einschränkungen einen Nicht-Null-Exit-Code und eignet sich für die CI-Integration. Der type der Ereignis-JSONL unterstützt run, model_call, tool_call, tool_result, error; optionale Felder umfassen Tool-Name, Argumente, Latenz, Tokens, Anzahl der Wiederholungen und Fehlertyp. Die Tokens in den Metriken verwenden die vom Produzenten bereitgestellten tokens.input und tokens.output; dieses Tool errät keine versteckten Tokens.

Die Fixtures und Cases im Repository sind selbst erstellte öffentliche Daten. Das MCP-SDK ist eine optionale Abhängigkeit; der Dienst analysiert lokale Traces und Cases nur lesend. Zu den aktuellen Einschränkungen gehören das Fehlen herstellerspezifischer Adapter, keine probabilistische Bewertung und kein erneutes Zählen von Tokens aus rohen Prompts.