agent-eval-gate

Codex, OpenAI 호환 에이전트 및 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

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 친화적이며 실패 시 0이 아닌 값을 반환합니다.

트레이스 스키마

각 줄에 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를 실행합니다. 구조화된 JSON을 반환하는 읽기 전용 inspect_trace 및 evaluate_case_file 도구를 제공합니다. 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는 푸시와 풀 리퀘스트에서 이러한 검사를 실행합니다. 알려진 제한 사항: 공급업체별 트레이스 어댑터 없음, 확률적 점수 계산 없음, 원시 프롬프트에서 토큰 재계산 없음.

중국어 설명

이것은 Codex, OpenAI 호환 에이전트 및 MCP 클라이언트를 위한 Trace Inspector + Eval Gate 독립 구현체이며, MIT 라이선스를 사용하고, OpenAI 또는 Codex 공식 플러그인이 아니며, 제한된 저장소 코드를 복사하지 않습니다.

설치에는 Python 3.11+가 필요합니다: python -m pip install -e .. inspect는 JSON 메트릭을 출력하고, eval은 골든 케이스 검사를 실행하고 표시하며, gate는 제약 조건 실패 시 0이 아닌 종료 코드를 반환하여 CI에 적합합니다.

이벤트 JSONL의 type은 run, model_call, tool_call, tool_result, error를 지원합니다. 선택 필드에는 도구 이름, 매개변수, 지연 시간, 토큰, 재시도 횟수 및 오류 유형이 포함됩니다. 메트릭의 토큰은 생성자가 제공한 tokens.input 및 tokens.output을 사용하며, 이 도구는 숨겨진 토큰을 추측하지 않습니다.

저장소의 픽스처와 케이스는 모두 자체 제작한 공개 데이터입니다. MCP SDK는 선택적 종속성이며, 서비스는 로컬 트레이스와 케이스를 읽기 전용으로 분석합니다. 현재 제한 사항에는 공급업체별 어댑터 없음, 확률적 점수 계산 없음, 원시 프롬프트에서 토큰 재계산 없음이 포함됩니다.