agent-eval-gate

Trace Inspector + Eval Gate для Codex, OpenAI-совместимых агентов и MCP-клиентов. Это независимая реализация под лицензией MIT; она не копирует ограниченный исходный код и не претендует на статус официального плагина OpenAI/Codex.

Установка

Требуется 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 и возвращает ненулевой код при ошибке.

Схема трассировки

Один 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.

Золотые кейсы

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. Он предоставляет инструменты только для чтения inspect_trace и evaluate_case_file, возвращающие структурированный JSON. Настройте ваш MCP-клиент на запуск этой команды; никакой связи с официальным плагином не подразумевается.

Интеграция с Codex

CLI можно напрямую вызывать из навыка или плагина Codex. Минимальный навык может вызывать agent-eval-gate inspect <trace> и agent-eval-gate gate <case>; MCP-сервер можно зарегистрировать как локальный stdio-сервер. Храните трассировки и кейсы в рабочей области, из которой осуществляется вызов.

Архитектура и разработка

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

Запускайте pytest, ruff check . и mypy agent_eval_gate. GitHub Actions выполняет эти проверки при пушах и pull request. Известные ограничения: отсутствуют адаптеры трассировок для конкретных вендоров, отсутствует вероятностная оценка и отсутствует повторный подсчёт токенов по исходным промптам.

Китайское описание

Это независимая реализация Trace Inspector + Eval Gate для Codex, агентов, совместимых с OpenAI, и MCP-клиентов, распространяемая под лицензией MIT; это не официальный плагин OpenAI или Codex, и она не копирует код из ограниченных репозиториев.

Для установки требуется Python 3.11+: python -m pip install -e .. inspect выводит метрики в JSON, eval выполняет и показывает проверки золотых кейсов, а gate возвращает ненулевой код выхода при нарушении ограничений и подходит для интеграции в CI. В JSONL событий type поддерживает run, model_call, tool_call, tool_result, error; необязательные поля включают имя инструмента, аргументы, задержку, токены, количество повторных попыток и тип ошибки. Для токенов в метриках используются tokens.input и tokens.output, предоставленные производителем; этот инструмент не угадывает скрытые токены.

Фикстуры и кейсы в репозитории являются синтетическими и публичными данными. MCP SDK является опциональной зависимостью; сервис анализирует локальные трассировки и кейсы в режиме только для чтения. Текущие ограничения включают отсутствие адаптеров для конкретных вендоров, отсутствие вероятностной оценки и отсутствие повторного подсчёта токенов по исходным промптам.