Metric LibraryVibectl-optimizer사전 설계 초안

Optimizer가 소비할 메트릭 스펙(정의·수식·trajectory) + "프롬프트가 아니라 도구를 고쳐라"는 개입 레버의 근거 · 갱신 2026-07-01
📄 소스: eval-metrics 특이점 레이더 · 메트릭 레시피 · 원장 experiments(~40건) · migrations/*.sql
핵심 주장. 에이전트 성능 개선의 큰 몫은 system prompt 재작성이 아니라 도구 자체를 고치는 것 — 정확한 파라미터 설명, 반환 규약 문서화, 백엔드 신뢰성, 통합 설정 — 에서 나온다. 우리 실측(§3)과 업계·논문(§2)이 같은 방향을 가리킨다. 그래서 optimizer의 개입 표면에 tool-doc / tool-schema / tool-backend 레버를 프롬프트 레버와 동급으로 넣는다.
×3
EXP-153: 되는 검색도구 추가 → pass@1 0.1→0.3
100→0%
read_attached_file 도구 에러율 (파서 교체)
+67%
EXP-124: validator 도구 → field_accuracy
90→57%
pass^k 붕괴 (k=8, τ-bench) — 다중턴 도구호출
40
experiments 원장 실험 수
1 근거 — Tool-calling은 어렵고, 도구 설명/스키마가 성능을 좌우한다
#주장등급출처 · 핵심 수치
E1도구 설명이 도구 성능의 "가장 중요한 단일 요인". 설명 정밀화만으로 SWE-bench Verified SOTA·에러율 급감. 권고: 도구당 3–4문장+, "새 팀원 온보딩하듯".벤더 공식Anthropic, Writing effective tools for AI agents · Advanced tool use
E2파라미터 이름/값을 정확·명확·비모호하게 쓰는 것이 별도 성능 레버(도구 검색이 이름·설명에 매칭).벤더 공식Anthropic 위 문서(파라미터 설계 원칙)
E3최상위 모델도 함수호출이 불안정(AST 평가). 단일턴 OK, 다중턴·메모리·장기추론에서 붕괴.논문Berkeley Function Calling Leaderboard, ICML 2025
E4다중턴 신뢰도 지수 붕괴: pass^k=p^k → pass@1 90%도 k=8에서 57%. GPT-4o τ-bench retail 성공 <50%, pass^8 <25%.논문τ-bench 2406.12045 · τ²-bench 2506.07982
E5도구 인자 취약성: 인자 약간 변화·누락·오호출만으로 결과가 크게 달라짐.논문Stability of Tool-Integrated LLM Agents 2506.21967
E6오류가 체계적: ① 파라미터 값 환각 ② 도구 관련성 환각 ③ JSON 형식 오류.논문ToolScan 2411.13547 · Tool-Hallucination 2412.04141
E7멀티에이전트 실패의 큰 몫이 도구/검증/조정(MAST FC3=21.3%).논문MAST 2503.13657 (022_verification_quality.sql에 인용)
2 개선 내역 원장 — 40건이 말하는 메타패턴
원장 자신의 결론 (EXP-64 lesson, verbatim): "세션 전체 패턴 확정: promoted는 전부 도구/입력 수정, rejected는 전부 프롬프트/구조 추가. 좋은 베이스라인엔 surgical 데이터/도구 레버가 프롬프트 튜닝보다 신뢰롭다."  정밀한 축은 "수정(fix)/제거 vs 추가(add)" — 도구 구현·입력 주입·형식/종료 배선은 promote, 프롬프트·에이전트·토폴로지·제약 추가는 reject.

✅ PROMOTED — 도구·입력·배선 수정T·W

레버표면: T 도구 W 배선
EXP개입(1변수)표면메트릭 이동
40첨부 절대경로 주입Tpass@1 0.42→0.48
42멀티포맷 파서 + python_execTread 에러 87→15%, exec 100→0%
64status-aware 검색(프롬프트 불변)Tpass@1 0.80→0.87, 지연 −38%
65web_search groundingTgrounded 0→100%
66과검색 제거(1라운드)W토큰 −82%, grounded 유지
124validator 정규화 도구Tfield_acc 0.75→0.906, pass@1 +67%
144형식 규율 1단락Wformat_invalid 1.0→0.0
147종료조건 1개Wloop_rate 1.0→0.0, 토큰 반감
153web_search(firecrawl)Tgrounded 0→1.0, pass@1 ×3
159출력폭주 방지(길이·형식)WOCR 폭주 17→8%, pass@1 0.83→0.92
173검색·작성 역할 분리Wformat_valid 0→1.0

❌ REJECTED — 프롬프트·구조·제약 추가P·X

레버표면: P 프롬프트 X 토폴로지
EXP개입(1변수)표면메트릭 이동
45max_messages 캡 축소W토큰−38%이나 fmt_invalid 0→0.21
60RoundRobin 토폴로지Xpass@1 97%→7% 붕괴
63decoy 방지 프롬프트 강화Ppass@1 80%→27%
67synthesizer '전부 인용' 강제Pgrounded 100→67%, 토큰 +61%
134value-linking 프로빙 강제Pexec_acc 0.9→0.8, 토큰 3×
154전담 retriever 분업 추가Xpass@1 0.3→0.0, 깊이 4.3→1.3
169검색검증 critic 추가P토큰 +114%, p95 573→1315s
221SOURCES 인용 강제Pentail F1 flat, EM −3.3pp
관통 결론. promoted 레버는 압도적으로 T(도구)·W(배선), rejected는 압도적으로 P(프롬프트)·X(토폴로지) 추가다. → Optimizer는 신호를 받으면 T·W 수정 레버부터 탐색하고, P·X 추가는 정확도 가드와 함께 마지막에. rejected의 절반은 "메트릭이 즉시 붕괴를 포착해 출시를 막은" 사례 — 하니스의 가치가 이 매핑에 있다.
3 Metric Library — 마스터 표 (Metric · 수식 · Trajectory)
집합 크기는 count(...), 논리곱/합은 ∧/∨. mv_*=materialized(REFRESH 필요), v_*=live. 파일:라인은 근거 위치.
4.1 정확도 (Outcome)
Metric수식Trajectory (원천 → 메트릭)
pass_at_1AVG(success::int); success = format_valid ∧ match(pred,gold)events → 최종답 추출 → 벤치 scorer → runs.success → mv_batch_summary (002:8)
pass_any / pass_allBOOL_OR(success) / BOOL_AND(success)runs(같은 task 다회) → mv_passk (002:21)
format_invalid_rateAVG((NOT format_valid)::int) FILTER(completed)FINAL ANSWER 패턴 존재? → runs.format_valid → mv (002:9)
GAIA matchnormalize(pred)==normalize(gold) (숫자 1e-6, 리스트 순서보존)extract → normalize → compare (gaia/scorer.py:121)
cover-EM (hotpot)norm(gold)가 norm(pred)의 연속 부분열SQuAD 정규화 → 부분열 검사 (hotpot/scorer.py:45)
field_accuracycount(k∈gold: k∈pred ∧ norm매치) / count(gold)JSON 파싱 → 필드별 비교 (extract/scorer.py:69)
meeting_coveragematched / count(gold_items), item hit=키워드적중≥0.6액션아이템 분리 → 키워드매칭 (roles/scorer.py:32)
ocr_cerLevenshtein(pred,gold)/len(gold); success=CER≤0.15편집거리 (roles/scorer.py:65)
test kill_ratekilled/count(mutants); success=valid ∧ ≥0.5뮤턴트 실행 (roles/code_scorer.py:45)
4.2 비용 · 효율 (Cost / Efficiency)
Metric수식Trajectory
avg_tokensAVG(total_tokens); total = input + outputmodels_usage → logger → runs → mv (002:13)
tokens_per_success ⭐SUM(total_tokens) / NULLIF(SUM(success::int),0)배치 토큰합 ÷ 성공수 (002:14)
overhead_tokensclient.total_usage() − sum(events 토큰)selector 미포착 비용 → runs.overhead_tokens (020)
loop_rateAVG((terminated_by='max_messages')::int)stop_reason → runs.terminated_by → mv (002:11)
p95_latency ⭐PERCENTILE_CONT(0.95) WITHIN GROUP(ORDER BY latency_ms)latency_ms=last_ev−first_ev → mv (002:16)
4.3 도구 (Tool usage) — optimizer 최우선 축
Metric수식Trajectory
calls / errors / avg_latencyerrors=count(tool_error); avg_latency=AVG(latency_ms) FILTER(tool_result)events group by tool_name → mv_tool_summary (002:29)
any_tool_errcount(tool_error) > 0v_run_features (019:52)
truncated_resultscount(tool_result WHERE tool_result_hash NOT NULL)v_run_features (019:24)
errored / recoveredrecovered = errored ∧ last_result_seq > first_error_seqtool_error/result seq 윈도우 → v_run_recovery (021:29)
4.4 근거 · 인용 (Grounding / Citation)
Metric수식Trajectory
grounded_pct ⭐AVG((n_search_ok>0)::int); n_search_ok=count(tool_result NOT LIKE '(%')events(tool~search) → v_analysis_grounded → _summary (010)
recency_scoremean(as_of_date, current_year_ratio, url_current_ratio)리포트 텍스트 연도/URL 파싱(파생) (recency.py:49)
hallucination_riskrecency≥0.5 ∧ n_search_ok=0 ∧ ¬simulatedrecency × grounding 교차 (grounding_guard.py:54)
cite_f1 (overlap)p=count(cited∩gold)/count(cited); r=/count(gold); f1=2pr/(p+r)SOURCES doc_id → gold 교집합 → research_grounding (scorer.py:45, 006)
cite_f1_entail (NLI)recall=1(전체 cited가 claim 함의); precision=necessary/checked(LOO)verify_fn(이종 claude -p) NLI → entail 컬럼 (scorer.py:61, 023)
sources_present_rateAVG(sources_present::int)SOURCES 줄 존재? → v_research_grounding_summary (006)
cppx ground_ration_grounded / n_facts문제사실 문자열 인용 → cppx_grounding (008)
4.5 검증 · 신뢰 (Verification)
Metric수식Trajectory
revisionscount(selector_reason.reason_code = 'NEEDS_REVISION')selector_decision JSON → v_run_features (019)
false_approval (FM-3.3)terminated_by='approve' ∧ success IS FALSEv_verification_quality (022:32)
useful_rejectionrevisions>0 ∧ success IS TRUEv_verification_quality (022:33)
verify_absent_fail (FM-3.2)success IS FALSE ∧ ¬critic_engagedv_verification_quality (022:35)
claim_verified_ratecount(eval_meta.supported=true) / count(evaluator_score)이종 검증기 → events.eval_meta JSONB → 집계 (009)
4 Metric → Lever 매핑 (Optimizer 페이로드)
메트릭 신호진단1순위 레버(표면)선례
format_invalid_rate ↑출력 규율 없음형식 지시 1단락 WEXP-144
loop_rate ↑종료 배선 누락종료조건 1개 WEXP-147
grounded_pct ↓검색이 호출은 되나 결과 0백엔드 교체+반환규약 TEXP-153
errors ↑도구 구현/스키마 결함구현·파라미터 설명 수정 Tread 100→0%
avg_search_ok↓ & grounded=1이진지표가 품질하락 은폐깊이 메트릭+핸드오프 축소 XEXP-154
tokens_per_success ↑중복 에이전트solo/duo 가지치기 XSQL solo 챔피언
cite_f1 ↓ (정답은 맞음)근거 부실/후행합리화NLI 채점 병행 TEXP-221
false_approval truecritic이 오답 승인검증 게이트 강화 WMAST FM-3.3
ROI 순서 가설. 대개 T·W(도구·배관)를 P(프롬프트)보다 먼저. "더 똑똑한 프롬프트/더 많은 에이전트"는 배관·근거가 정직해진 뒤의 레버다.
5 Insight — 반복해 부딪힌 문제 (optimizer가 늘 유념)
  1. 호출 ≠ 성공. 도구가 불려도 빈손(rate-limit/403)이면 모델이 지어낸다 → 메트릭은 출력 계약(실패="(…)")을 읽는다. presence 기반 지표는 환각을 grounded 100%로 둔갑시킴(실측 205/205 실패).
  2. 파라미터 환각·형식 오류(E6). 파라미터 설명을 "온보딩"급으로 + format_valid로 구조위반을 조용한 오답과 분리.
  3. 빈 결과 크래시. reflect_on_tool_use=True가 빈 도구결과에 RuntimeError → 8+팀이 False로 우회. 도구 통합 설정도 레버(T).
  4. 핸드오프 정보 손실(EXP-154). 요약 경유로 정확 값 유실(pass@1 0.3→0). 비병렬 단일맥락엔 에이전트 추가 금지, 결과는 raw로 전달.
  5. 배관이 능력보다 먼저(EXP-144/147). 첫 진단은 능력이 아니라 format_invalid_rate / loop_rate.
  6. pass^k 지수 붕괴(E4). 단발 A/B는 flaky를 능력으로 오인 → attempts≥3, pass_any/pass_all gap.
  7. 이진 지표의 은폐. grounded(≥1)는 품질하락을 숨김 → 연속 깊이/함의 지표를 얹어 읽는다.
  8. 1변수 규율 + 재현성 가드. 바뀐 건 레버 하나, 프롬프트/도구 한 글자라도 바뀌면 새 team_id.
방향 한 줄. Optimizer는 "프롬프트 옵티마이저"가 아니라 "에이전트 시스템 옵티마이저"여야 한다 — 도구(T)·배관(W)·토폴로지(X)를 프롬프트(P)와 동급으로 놓고, T·W부터 훑는다.