128 lines
8.5 KiB
Markdown
128 lines
8.5 KiB
Markdown
---
|
|
spec_doc_type: spec
|
|
spec_id: testing/agent-comparison-benchmark
|
|
status: 구현됨
|
|
source_evidence:
|
|
- type: code
|
|
path: scripts/agent_comparison_benchmark.py
|
|
notes: validate, preflight, run, resume, status, score, report 공개 CLI
|
|
- type: code
|
|
path: scripts/agent_benchmark/manifest.py
|
|
notes: manifest 정규화, 경로 격리, fixture와 입력 digest 검증
|
|
- type: code
|
|
path: scripts/agent_benchmark/attempts.py
|
|
notes: append-only run/attempt 저장과 preflight, 실행, 재개 lifecycle
|
|
- type: code
|
|
path: scripts/agent_benchmark/connectivity.py
|
|
notes: caller capability, requested/effective binding과 blocker 분류
|
|
- type: code
|
|
path: scripts/agent_benchmark/measurement.py
|
|
notes: source-aware timing과 usage 정규화
|
|
- type: code
|
|
path: scripts/agent_benchmark/web_validation.py
|
|
notes: 정적 웹 산출물과 desktop/mobile 자동 gate 검증
|
|
- type: code
|
|
path: scripts/agent_benchmark/scoring.py
|
|
notes: 익명화 입력, fresh evaluator와 scoring attempt 처리
|
|
- type: code
|
|
path: scripts/agent_benchmark/reporting.py
|
|
notes: deterministic Markdown 보고서 생성
|
|
- type: test
|
|
path: scripts/agent_benchmark/connectivity_integration_test.py
|
|
notes: 세 caller의 IOP binding, lifecycle, 격리와 실패 경계 통합 검증
|
|
- type: test
|
|
path: scripts/agent_benchmark/scoring_test.py
|
|
notes: unscored, scoring_failed, 새 scoring attempt와 익명화 검증
|
|
- type: test
|
|
path: scripts/agent_benchmark/reporting_test.py
|
|
notes: all-status, 동점과 raw evidence 포인터 보고 검증
|
|
- type: test
|
|
path: scripts/agent_benchmark/skill_contract_test.py
|
|
notes: project-local skill과 공개 CLI 계약 검증
|
|
- type: contract
|
|
path: agent-contract/outer/openai-compatible-api.md
|
|
notes: agy와 Codex가 사용하는 IOP OpenAI-compatible ingress 계약
|
|
- type: contract
|
|
path: agent-contract/outer/anthropic-compatible-api.md
|
|
notes: Claude Code가 사용하는 IOP Anthropic-compatible ingress 계약
|
|
- type: contract
|
|
path: agent-contract/inner/edge-config-runtime-refresh.md
|
|
notes: model, route, execution preset과 protocol profile 설정 계약
|
|
- type: roadmap
|
|
path: agent-roadmap/archive/phase/knowledge-tool-optimization-extension/milestones/agent-comparison-benchmark-pipeline.md
|
|
notes: bench-01 완료 범위와 evidence 집계
|
|
- type: sdd
|
|
path: agent-roadmap/archive/sdd/knowledge-tool-optimization-extension/agent-comparison-benchmark-pipeline/SDD.md
|
|
notes: benchmark lifecycle, 실패 보존, 채점과 secret-safe evidence 결정
|
|
---
|
|
|
|
# 스펙: Agent 비교 벤치마크 파이프라인
|
|
|
|
## 목적
|
|
|
|
Claude Code, agy, Codex가 IOP를 경유해 수행하는 동일 과업을 설정만 바꿔 반복 실행하고, 연결 상태부터 실행·검증·채점·보고까지 재현 가능한 evidence로 남기는 현재 benchmark harness를 설명한다.
|
|
|
|
## 기능 목록
|
|
|
|
| 기능 | 설명 |
|
|
|------|------|
|
|
| manifest 검증 | caller, IOP direct/preset route, model, effort, fixture, 반복 횟수, timeout, evaluator와 `agent-test/runs/<output-id>` 경로를 검증하고 canonical digest를 만든다. |
|
|
| 연결 preflight | Claude Code, agy, Codex의 binary/config와 IOP endpoint·auth·model·effort·stream binding을 확인하고 `ready`, `registration_required`, `implementation_gap`으로 분류한다. |
|
|
| 격리 실행과 재개 | 각 cell/repetition을 동일 checksum의 clean workspace와 fresh caller session에서 실행하며, 종료·idle·timeout·cancel·cleanup을 bounded하게 처리한다. 실패한 attempt는 덮어쓰지 않고 명시적 재개 시 새 attempt로 남긴다. |
|
|
| 측정과 evidence | 제출, 첫 출력, 첫 파일 쓰기, model/tool/queue, finish/idle 시간을 관측 source와 함께 정규화한다. token은 보고 주체와 미제공 상태를 보존하며 임의 추정값을 authoritative 값과 섞지 않는다. |
|
|
| 웹 자동 검증 | 필수 HTML/CSS/JS와 로컬 이미지, 외부 asset 금지, desktop/mobile render, console/asset 오류, 반응형·접근성 gate와 screenshot을 확인한다. |
|
|
| 익명 품질 채점 | 필수 자동 gate를 통과한 결과만 identity를 가린 뒤 manifest에 고정된 fresh evaluator로 100점 rubric을 평가한다. 부적격 결과는 `unscored`, 평가 실패는 `scoring_failed`로 남기며 retry는 새 scoring attempt id를 사용한다. |
|
|
| 상태와 보고 | `validate`, `preflight`, `run`, `resume`, `status`, `score`, `report` CLI를 제공하고, 성공·실패·blocked·unscored·scoring_failed·동점을 raw evidence 포인터와 함께 deterministic Markdown으로 만든다. |
|
|
|
|
## 범위
|
|
|
|
- 포함: benchmark manifest, caller adapter binding, run/attempt 저장, 격리 workspace, source-aware timing/usage, 정적 웹 gate, 익명 채점, Markdown 보고.
|
|
- 제외: IOP runtime 자체 구현, provider credential 등록, 실제 9개 비교군 실행과 모델 우열 결론. 해당 실행과 결론은 `[bench-02]`가 소유한다.
|
|
|
|
## 주요 흐름
|
|
|
|
```mermaid
|
|
flowchart LR
|
|
Operator[사용자 또는 project skill] --> CLI[benchmark CLI]
|
|
CLI --> Manifest[manifest 검증]
|
|
Manifest --> Preflight[caller와 IOP preflight]
|
|
Preflight --> Store[append-only run store]
|
|
Store --> Attempt[clean workspace와 fresh session attempt]
|
|
Attempt --> Evidence[timing, usage와 web evidence]
|
|
Evidence --> Score[익명 evaluator scoring]
|
|
Score --> Report[deterministic Markdown report]
|
|
```
|
|
|
|
## 계약
|
|
|
|
- OpenAI-compatible caller ingress는 [OpenAI-Compatible API](../../agent-contract/outer/openai-compatible-api.md)를 따른다.
|
|
- Claude Code ingress는 [Anthropic-Compatible Messages API](../../agent-contract/outer/anthropic-compatible-api.md)를 따른다.
|
|
- model, direct/preset route와 protocol profile의 기준은 [Edge Config And Runtime Refresh](../../agent-contract/inner/edge-config-runtime-refresh.md)를 따른다.
|
|
- 사용자-facing orchestration과 안전한 실행 순서는 [IOP Agent Comparison Benchmark skill](../../agent-ops/skills/project/iop-agent-comparison-benchmark/SKILL.md)이 소유하고, 제품 호출과 evidence 생성은 deterministic Python pipeline이 소유한다.
|
|
|
|
## 설정/데이터/이벤트
|
|
|
|
- manifest의 matrix cell은 stable id, caller, IOP route kind, requested/effective model과 effort를 가진다. unsupported alias나 effort는 다른 값으로 대체하지 않고 fail-closed한다.
|
|
- run state는 `agent-test/runs/<output-id>/<run-id>/` 아래에 격리되며 manifest digest가 다른 상태를 재개하지 않는다.
|
|
- preflight는 scored attempt가 아니며, 실행 중 실패·timeout·cancel과 scoring 실패는 기존 attempt를 수정하지 않고 보존한다.
|
|
- raw credential과 private endpoint는 tracked manifest, event, log, screenshot과 report에 기록하지 않는다.
|
|
- report는 run state의 canonical evidence에서 생성되며 성공하지 않은 결과를 0점으로 변환하거나 동점에 임의 순위를 부여하지 않는다.
|
|
|
|
## 검증
|
|
|
|
- `python3 -m unittest discover -s scripts/agent_benchmark -p '*_test.py'` - 전체 benchmark unit/integration 계약이 통과한다.
|
|
- `python3 -m unittest scripts.agent_benchmark.reporting_test scripts.agent_benchmark.skill_contract_test` - 공개 보고 CLI와 project-local skill 계약이 통과한다.
|
|
- `python3 scripts/agent_comparison_benchmark.py validate --manifest scripts/fixtures/agent-comparison-benchmark-manifest.example.json` - 표준 manifest가 유효하다.
|
|
- `python3 scripts/agent_comparison_benchmark.py validate --manifest scripts/fixtures/agent-comparison-benchmark-supported-direct.example.json` - 지원 direct route fixture가 유효하다.
|
|
- `python3 scripts/agent_comparison_benchmark.py validate --manifest scripts/fixtures/agent-comparison-benchmark-direct-preflight.example.json` - direct preflight fixture가 유효하다.
|
|
|
|
## 한계와 주의사항
|
|
|
|
- example manifest와 fake adapter 테스트 통과는 실제 provider credential, endpoint 또는 preset의 live readiness를 의미하지 않는다. 실제 실행 전 redacted preflight가 필요하다.
|
|
- 현재 living spec은 비교 파이프라인의 구현 상태만 다룬다. 9개 scored cell 실행, 비교 결과와 결론은 후속 `[bench-02]` evidence로 관리한다.
|
|
- caller나 IOP가 제공하지 않은 usage는 `unavailable`로 남으며, 서로 다른 clock/source의 중첩 구간을 임의로 합산하지 않는다.
|
|
- benchmark 결과는 허용된 `agent-test/runs/` 경계 안에만 생성한다.
|
|
|
|
## 변경 기록
|
|
|
|
- 2026-08-12: `[bench-01]` 종료 감사에서 확인한 421개 benchmark test, manifest/CLI 계약과 구현 evidence를 기준으로 생성했다.
|