agent-eval-gate

Trace Inspector + Eval Gate para Codex, agentes compatibles con OpenAI y clientes MCP. Esta es una implementación independiente con licencia MIT; no copia código fuente restringido ni se presenta como un complemento oficial de OpenAI/Codex.

Instalación

Requiere 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 imprime JSON y es informativo; gate es compatible con CI y devuelve un valor distinto de cero en caso de error.

Esquema de trace

Un objeto JSON por línea. type es uno de run, model_call, tool_call, tool_result o error. Los campos opcionales incluyen id, parent_id, timestamp, status, tool, arguments, latency_ms, attempt, tokens: {input, output} y error_type.

Las métricas cuentan llamadas a herramientas, herramientas únicas, firmas repetidas (tool, arguments), reintentos (attempt > 1), latencia, totales de tokens, tipos de error, clases de fallo normalizadas, estado final y uso del presupuesto de contexto. Un presupuesto de contexto se compara con los tokens de entrada más los de salida; la tokenización se delega al productor, por lo que esta herramienta no estima tokens ocultos.

Las clases de fallo incluyen schema_error, permission_denied, timeout, tool_error, duplicate_operation, unknown_side_effect, model_error y unknown.

Casos golden

El JSON de un caso nombra un trace y restricciones opcionales: expected_tools, forbidden_tools, max_tokens, max_steps, expected_final_status y context_budget. Los fixtures de este repositorio son sintéticos y públicos.

MCP

Instale el SDK opcional con pip install -e '.[mcp]' y luego ejecute python -m agent_eval_gate.mcp_server. Expone las herramientas de solo lectura inspect_trace y evaluate_case_file que devuelven JSON estructurado. Configure su cliente MCP para lanzar este comando; no se implica ninguna relación oficial con complementos.

Integración con Codex

Se puede llamar directamente a la CLI desde una skill o complemento de Codex. Una skill mínima puede invocar agent-eval-gate inspect <trace> y agent-eval-gate gate <case>; el servidor MCP se puede registrar como servidor stdio local. Mantenga los traces y casos en el espacio de trabajo que realiza la llamada.

Arquitectura y desarrollo

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

Ejecute pytest, ruff check . y mypy agent_eval_gate. GitHub Actions ejecuta estas comprobaciones en cada push y pull request. Limitaciones conocidas: sin adaptadores de trace específicos de proveedores, sin puntuación probabilística y sin recuento de tokens a partir de prompts sin procesar.

Nota en chino

Esta es una implementación independiente de Trace Inspector + Eval Gate para Codex, agentes compatibles con OpenAI y clientes MCP, con licencia MIT. No es un complemento oficial de OpenAI o Codex ni copia código de repositorios restringidos.

La instalación requiere Python 3.11+: python -m pip install -e .. inspect genera métricas JSON, eval ejecuta y muestra las comprobaciones de casos golden, y gate devuelve un código de salida distinto de cero cuando fallan las restricciones, adecuado para integrarse en CI. El type del JSONL de eventos admite run, model_call, tool_call, tool_result y error; los campos opcionales incluyen nombre de la herramienta, argumentos, latencia, tokens, número de reintentos y tipo de error. Las métricas de tokens utilizan tokens.input y tokens.output proporcionados por el productor; esta herramienta no adivina tokens ocultos.

Los fixtures y casos del repositorio son datos públicos generados por nosotros. El SDK de MCP es una dependencia opcional; el servicio solo analiza traces y casos locales de forma de solo lectura. Las limitaciones actuales incluyen la ausencia de adaptadores de traces específicos de proveedores, sin puntuación probabilística y sin recontar tokens a partir del prompt original.