런타임 플로우 완전 해부

A호출 체인 — cli 한 줄이 run_stream에 닿기까지

평가의 본체는 runner._execute_run() 안의 단 두 줄: 팀을 빌드하고, team.run_stream()을 TraceLogger.log_stream()에 먹인다.

핵심 12줄 (runner.py:237–299)

# 모델 클라이언트는 run마다 새로 — 동시성에서 공유 상태를 피한다
client = model_client_factory()
team, _ = build_registered_team(team_id, settings, client)   # registry: team_id → 빌더, AC9 가드
run_message = build_run_message(team_id, task, settings)      # v2/v3/v4/v5만 첨부경로 주입, 그 외 task.question
async with pool.acquire() as conn:
    trace_result = await TraceLogger(conn).log_stream(        #  ← 스트림 소비 + events 적재
        run_id,
        team.run_stream(task=run_message),                   # ← AutoGen 라이브러리 진입점
    )
    is_open_ended = task.benchmark in _OPEN_ENDED            # gaia=False → 한 줄 답
    answer_text = (trace_result.final_answer_full if is_open_ended
                   else trace_result.final_answer)
    score_fn = score                                         # benchmark별 분기, gaia는 gaia.scorer.score
    score_result = score_fn(answer_text, task.gold_answer)
    await conn.execute("UPDATE runs SET status='completed', …")  # ← 결과 확정

팀은 어떻게 생겼나 (v1_baseline.build_team, v2~v6 공유 골격)

SelectorGroupChat(
    [planner, executor, critic],                # 3 AssistantAgent
    model_client=model_client,
    termination_condition = TextMentionTermination("APPROVE", sources=["critic"])
                            | MaxMessageTermination(settings.max_messages),
    selector_prompt = SELECTOR_PROMPT,           # selector가 JSON {next,reason_code,summary} 출력하도록 강제
    allow_repeated_speaker = False,              # 같은 에이전트 연속 발화 금지 → 자연스러운 P→E→P→C 교대
    max_selector_attempts = 3,
    emit_team_events = True,                     # ← SelectorEvent를 스트림에 흘려보냄(이게 없으면 라우팅 근거 미기록)
    model_client_streaming = True,              # ← ModelClientStreamingChunkEvent 발생 → logger가 조용히 스킵
)

• termination: critic이 APPROVE를 말하면 종료. 못 하면 max_messages(예: 30)에서 강제 종료 → terminated_by='max_messages'.
• allow_repeated_speaker=False 때문에 executor가 파일읽기→집계를 한 턴에 몰아 못 한다. 그래서 trace가 P→E→P→E→P→C 처럼 교대한다(§E의 핵심 구조).
• emit_team_events=True 가 만드는 SelectorEvent 가 selector_decision 행의 원천 — “왜 이 에이전트가 다음인가”를 JSONB로 남긴다.

B예제 태스크 + run_stream 원시 이벤트 18개

GAIA L1, 첨부 xlsx 1개. 이 한 건이 아래 §C~§H를 관통한다.

입력 (tasks 행 + build_run_message 결과)

# tasks 테이블 행
task_id     = "c61d22de-…-5e9707bd3466"
benchmark   = "gaia"        level = 1        requires_web = false
file_name   = "cafe_sales.xlsx"
question    = "첨부 엑셀은 한 카페의 지난주 판매 내역이다. 음료(drink)를 제외한
               음식(food) 매출 합계는 USD로 얼마인가? 소수점 2자리로 답하라."
gold_answer = "89706.00"

# build_run_message("v5-multitool", task, settings) → registry._RUN_MESSAGE_BUILDERS[v5]
run_message = question + "\n\n[첨부파일 경로: /srv/data/gaia/validation/cafe_sales.xlsx] "
                       + "이 파일이 필요하면 read_attached_file 도구에 이 경로를 그대로 전달하라."

run_stream이 yield하는 객체 순서 (스트리밍 청크 제외)

Cmapping.py — 이벤트 → message_type (순수 함수)

tracing/mapping.py는 IO가 없는 순수 변환표다. AutoGen .type 리터럴(또는 클래스명)을 받아 DB message_types.code를 돌려준다.

• ⚠ 유일한 의도적 None 두 종류가 다르다. ToolCallExecutionEvent의 None은 “기록하지 마라”가 아니라 “이벤트 레벨이 아니라 항목 레벨에서 분기하라”는 신호 — logger가 별도 분기(is_tool_execution_event)로 직접 잡는다. 진짜 “버려라”는 마지막 줄 None이다.
• † EvaluatorScoreEvent는 AutoGen 표준이 아니라 FabricMAS 교차검증 워커가 yield하는 duck-typed 이벤트다. mapping/logger 모두 클래스를 import하지 않고 getattr로만 읽는다.
• parse_selector_reason(): ```json … ``` 래핑 해제 → json.loads → 실패 시 본문에서 첫 {~마지막 } 재시도 → 그래도 실패면 ("PARSE_FAILED", {"summary": text[:500]}). 절대 예외를 올리지 않는다.

Dlogger.log_stream — 디스패치 사다리 + 상태 누산기

async for event in stream: 루프가 이벤트마다 위에서부터 아래 사다리를 타고 첫 매칭에서 continue. 그 사이 seq와 누산기들이 갱신된다.

분기 순서 (먼저 걸리는 게 이긴다 · logger.py:549–669)

1. type 이름이 ...TaskResult           → final_answer 1행, 토큰합산 안 함
2. is_tool_execution_event(event)     → tool_result/tool_error N행 (항목별)
3. type == "ToolCallRequestEvent"     → tool_call N행 + 토큰합산
4. type == "SelectorEvent"            → selector_decision 1행
5. type == "SelectSpeakerEvent"       → selector_decision 1행
6. type == "EvaluatorScoreEvent"      → evaluator_score 1행
7. get_message_type==agent_message    → agent_message 1행 + 토큰합산 + turns++ + FINAL ANSWER 캡처
8. get_message_type==handoff          → handoff 1행
9. (그 외)                            → continue (스킵)

run 1건 동안 살아있는 상태 (RunResult로 귀결)

E이벤트별 완전 변환 — E1 → E18, 행 17개가 만들어지는 과정

각 카드: 원시 객체 → 탄 분기 → 빌더가 만든 record dict → events INSERT 한 행. seq는 0부터, 누산기 변화도 함께.

F변환 규칙 5종 — 값이 어떻게 “가공”되나

위 워크스루에서 스쳐 지난 가공들. 전부 logger.py 모듈 함수 + 상수.

① 비밀 마스킹 _mask_secrets (절대규칙 5, 단일 지점)

dict/list 재귀 순회. 키가 정규식 (password|token|secret|api_key|authorization)(대소문자 무관)에 매칭되면 값을 ***로. tool_args 저장 전 반드시 통과.

# 가령 모델이 이런 인자를 넘겼다면(예시)
arguments = '{"url":"https://x","api_key":"sk-live-9f...","headers":{"Authorization":"Bearer abc"}}'
# → 저장되는 tool_args (JSONB)
{"url":"https://x","api_key":"***","headers":{"Authorization":"***"}}   # 중첩도 마스킹

우리 예제(read_attached_file/python_exec)엔 민감키가 없어 원본 그대로 통과했다. DSN/토큰이 예외·로그·커밋에 새지 않게 하는 게 목적.

② 절단 + 해시 (content 8192 / tool_result 2048)

E6이 이 케이스: 3,914자 → 2048 저장 + 해시. 절단된 JSON이 invalid가 될 수 있어, 절단본은 문자열로 저장(다시 파싱 실패 시).

③ tool_args 파싱 _parse_tool_args

FunctionCall.arguments(JSON 문자열) → json.loads → 실패하면 {"_raw": 원본문자열}로 감쌈(절대 예외 안 냄) → 마스킹 → 다시 json.dumps(ensure_ascii=False).

④ 토큰 추출 _extract_tokens

event.models_usage.(prompt_tokens, completion_tokens). 없으면 (0,0). 행에는 x or None으로 0을 NULL화. 합산은 agent_message·tool_call 분기에서만 → tool_result·selector·TaskResult의 LLM 비용은 합계에 안 들어간다.

⑤ latency 두 종류

• 행별 events.latency_ms = 이 이벤트 ts − prev_ts(직전 이벤트). 멀티행 이벤트는 i==0 행만 값, 나머지는 NULL. prev_ts는 행이 아니라 이벤트 단위로 갱신.
• run 전체 runs.latency_ms = last_ts − first_ts. 벽시계(이벤트 도착 시각) 기준이라 모델 추론·도구 실행·DB INSERT가 모두 포함된 end-to-end다.

FINAL ANSWER 추출이 “두 군데”인 이유

runner 경로에선 logger가 이미 추출해 한 줄 답을 넘기므로, gaia.scorer는 재추출 없이 normalize+비교만 한다(→ §H). critic 제외·planner 한정·플레이스홀더 가드는 critic의 검수 CoT가 정답을 덮어쓰는 오염을 막기 위함.

Gevents 테이블 최종 덤프 — 이 run이 남긴 18행

한 run_id 아래 seq 0~17. (event_id BIGSERIAL·ts·run_id 생략. 빈 칸=NULL.)

* 26900은 행별 latency 합이 아니라 last−first 벽시계다(seq0의 NULL 때문에 행 합과는 다름). tool_call/result/selector/final_answer 행은 토큰 합산에 안 들어간다.

HTaskResult → scorer → runs 한 행

logger가 RunResult를 돌려주면, runner가 채점기를 골라 돌리고 runs를 completed로 확정한다.

① 답 텍스트 선택 (open-ended 분기, runner.py:258–261)

is_open_ended = task.benchmark in _OPEN_ENDED   # {analysis,cppx,extract,sql,meeting,ocrproxy,coding,codetest}
# gaia는 _OPEN_ENDED 밖 → 한 줄 답 사용
answer_text = trace_result.final_answer          # = "89706.00"
# (개방형이면 final_answer_full 전문을 써서 출처/본문까지 채점)

② 채점기 분기 → gaia.scorer.score("89706.00", "89706.00")

format_valid = predicted is not None             # "89706.00" → True
norm_pred = normalize("89706.00")                # 통화·콤마·% 제거 → "89706.00" → float → "89706"
norm_gold = normalize("89706.00")                # → "89706"
success = _compare_normalized("89706","89706")   # 둘 다 float 파싱 → abs(a−b)<1e-6
# ScoreResult(success=True, format_valid=True)

③ runs UPDATE — 이 run의 최종 행

I집계 — events/runs → materialized view

배치가 끝나면 run_batch 말미에 db.refresh_views(conn). report/Grafana는 원본 테이블이 아니라 이 뷰를 읽는다(상세는 코드맵 §6·§9).

우리 run 1건은 mv_tool_summary에 read_attached_file ×1, python_exec ×1(에러 0)로, mv_batch_summary에 v5-multitool의 성공 1건/토큰 5670/latency 26900으로 집계된다.

Jv1 → v6 계보 — 같은 파이프라인, 정확히 어디 1곳만 바뀌나

위 §A~§H의 골격(SelectorGroupChat P-E-C, logger, scorer)은 v1~v6 전부 동일하다. 각 버전은 단 하나의 변수만 바꿔, 그 효과를 격리 측정한다(experiments 원장). 먼저 요약표, 그 다음 모든 프롬프트·코드·레지스트리 변경의 실제 unified diff(git diff 그대로)를 전수 수록한다.

v1 → v2-attach-path · 입력층

① build_team — v1을 team_id만 바꿔 그대로 호출(프롬프트 재생성 없음)

+++ b/teams/v2_attach_path.py
+def build_team(settings, model_client):
+    """v1-baseline 구성을 team_id만 바꿔 그대로 빌드한다."""
+    return v1_baseline.build_team(settings, model_client, team_id="v2-attach-path")

② build_run_message — v1엔 없던 함수가 새로 생김(첨부 절대경로 주입)

+++ b/teams/v2_attach_path.py
+def build_run_message(task, settings):
+    file_name = getattr(task, "file_name", None)
+    if not file_name:
+        return task.question                       # 첨부 없으면 v1과 동일
+    abs_path = Path(settings.gaia_dir).expanduser().resolve() / file_name
+    return (f"{task.question}\n\n"
+            f"[첨부파일 경로: {abs_path}] "
+            f"이 파일이 필요하면 read_attached_file 도구에 이 경로를 그대로 전달하라.")

③ registry.py — run 메시지 빌더 등록(v1은 미등록 → 기본 task.question)

--- a/teams/registry.py
+++ b/teams/registry.py
 _RUN_MESSAGE_BUILDERS: dict[str, Callable] = {
+    _V2_TEAM_ID: _v2_build_run_message,
 }

v2 → v3-prompt-fix · 프롬프트층

PLANNER_PROMPT

--- a/PLANNER_PROMPT (v1=v2)
+++ b/PLANNER_PROMPT (v3)
@@ -2,5 +2,11 @@
 - 태스크를 단계로 분해하고 executor에게 필요한 계산/파일 작업을 지시한다.
 - 직접 도구를 실행하지 않는다.
-- 모든 필요 정보가 모이면 critic 검증을 받을 최종 답변 초안을 작성한다.
-- 최종 답변은 반드시 `FINAL ANSWER: <answer>` 한 줄이어야 한다.
-- 숫자는 콤마/단위 없이, 문자열은 관사 없이, 리스트는 콤마 구분으로 작성한다.
+- 모든 필요 정보가 모이면 critic 검증을 받을 최종 답변을 아래 형식으로 한 줄만 출력한다.
+
+  숫자:    FINAL ANSWER: 42
+  문자열:  FINAL ANSWER: Paris
+  리스트:  FINAL ANSWER: cat, dog, fish
+
+- <answer> 같은 플레이스홀더는 절대 출력하지 않는다. 반드시 실제 값을 적는다.
+- 숫자는 콤마·단위 없이, 문자열은 관사 없이, 리스트는 쉼표 구분으로 작성한다.
+- executor의 python_calc는 산술식 전용(예: 3*4+2)이다. import/print 코드는 전달하지 않는다.

CRITIC_PROMPT

--- a/CRITIC_PROMPT (v1=v2)    +++ b/CRITIC_PROMPT (v3)
@@ -1,4 +1,5 @@
 당신은 GAIA 평가용 critic이다.
 - 최종 답변이 질문에 정확히 답하는지 검토한다.
-- `FINAL ANSWER: <answer>` 형식을 지키는지 확인한다.
+- `FINAL ANSWER: 42` 또는 `FINAL ANSWER: Paris` 처럼 실제 값이 들어간 형식인지 확인한다.
+- `FINAL ANSWER: <answer>` 처럼 꺾쇠 플레이스홀더가 남아 있으면 반드시 반려한다.
 - 통과하면 APPROVE 만 단독 출력하고, 아니면 구체적 반려 사유를 출력한다.

v3 → v4-prompt-fix · 프롬프트층

PLANNER_PROMPT

--- a/PLANNER_PROMPT (v3)    +++ b/PLANNER_PROMPT (v4)
@@ -8,4 +8,5 @@
   리스트:  FINAL ANSWER: cat, dog, fish

+- 답이 한 단어 또는 한 글자여도 반드시 `FINAL ANSWER:` 형식을 사용한다. 절대 생략하지 않는다.
 - <answer> 같은 플레이스홀더는 절대 출력하지 않는다. 반드시 실제 값을 적는다.
 - 숫자는 콤마·단위 없이, 문자열은 관사 없이, 리스트는 쉼표 구분으로 작성한다.

CRITIC_PROMPT

--- a/CRITIC_PROMPT (v3)    +++ b/CRITIC_PROMPT (v4)
@@ -2,4 +2,5 @@
 - 최종 답변이 질문에 정확히 답하는지 검토한다.
 - `FINAL ANSWER: 42` 또는 `FINAL ANSWER: Paris` 처럼 실제 값이 들어간 형식인지 확인한다.
+- `FINAL ANSWER:` 행이 없으면 답변 길이에 관계없이 반드시 반려한다.
 - `FINAL ANSWER: <answer>` 처럼 꺾쇠 플레이스홀더가 남아 있으면 반드시 반려한다.
 - 통과하면 APPROVE 만 단독 출력하고, 아니면 구체적 반려 사유를 출력한다.

v4 → v5-multitool · 도구층 + 프롬프트 예제 run

① 도구 교체 — build_team import + tools 리스트

--- a/teams/v5_multitool.py    +++ b/teams/v5_multitool.py
-from agent_eval.teams.v1_baseline import (… python_calc, read_attached_file)
+from agent_eval.teams.tools_v5 import python_exec, read_attached_file
 ...
-        tools=[read_attached_file, python_calc],
+        tools=[read_attached_file, python_exec],

② read_attached_file — UTF-8 단일 리더 → 확장자별 멀티포맷 파서

- def read_attached_file(path):                          # v1~v4 (teams/v1_baseline.py)
-     p = Path(path).expanduser().resolve()
-     if not p.is_file(): raise FileNotFoundError(str(p))
-     return p.read_text(encoding="utf-8")               # ← 바이너리에서 UnicodeDecodeError로 전수 실패
+ def read_attached_file(path):                          # v5 (teams/tools_v5.py)
+     ext = p.suffix.lower()
+     if   ext in _TEXT_EXTS:        content = _read_text(p)     # errors="replace"
+     elif ext in (".xlsx",".xls"):  content = _read_xlsx(p)     # openpyxl 시트→탭 텍스트
+     elif ext == ".docx":           content = _read_docx(p)     # python-docx
+     elif ext == ".pptx":           content = _read_pptx(p)     # python-pptx
+     elif ext == ".pdf":            content = _read_pdf(p)      # pdfplumber
+     elif ext in _IMAGE_EXTS:       return "[이미지 …텍스트 추출 불가…]"   # 크래시 대신 안내문
+     elif ext in _AUDIO_EXTS:       return "[오디오 …전사 불가…]"
+     return _truncate(content, 20_000)

③ python_calc(AST 산술 전용) → python_exec(격리 subprocess)

- def python_calc(expression):                  # v1~v4 — AST allowlist, 산술만
-     parsed = ast.parse(expression, mode="eval")  # 파일 파싱 코드 넘기면 SyntaxError
-     return str(_eval_numeric(parsed))
+ def python_exec(code):                         # v5 — 모델이 쓴 파이썬을 실행
+     proc = subprocess.run([sys.executable, "-c", code],
+                           capture_output=True, text=True,
+                           timeout=20, cwd=tempdir)   # 20s 타임아웃 · 8KB 출력 가드 · 폐쇄망
+     return _truncate(proc.stdout, 8_000)

④ PLANNER_PROMPT

--- a/PLANNER_PROMPT (v4)    +++ b/PLANNER_PROMPT (v5)
@@ -1,4 +1,4 @@
 당신은 GAIA 평가용 planner다.
-- 태스크를 단계로 분해하고 executor에게 필요한 계산/파일 작업을 지시한다.
+- 태스크를 단계로 분해하고 executor에게 필요한 파일 작업/계산을 지시한다.
 - 직접 도구를 실행하지 않는다.
 - 모든 필요 정보가 모이면 critic 검증을 받을 최종 답변을 아래 형식으로 한 줄만 출력한다.
@@ -11,3 +11,4 @@
 - <answer> 같은 플레이스홀더는 절대 출력하지 않는다. 반드시 실제 값을 적는다.
 - 숫자는 콤마·단위 없이, 문자열은 관사 없이, 리스트는 쉼표 구분으로 작성한다.
-- executor의 python_calc는 산술식 전용(예: 3*4+2)이다. import/print 코드는 전달하지 않는다.
+- 첨부파일이 주어지면 executor에게 read_attached_file로 내용을 먼저 추출하게 한다.
+- 표 합계·필터·정렬 등 산술 이상의 계산이 필요하면 executor에게 python_exec 코드를 지시한다.

⑤ EXECUTOR_PROMPT (v1~v4 → v5)

--- a/EXECUTOR_PROMPT (v1~v4)    +++ b/EXECUTOR_PROMPT (v5)
@@ -1,4 +1,10 @@
-당신은 GAIA 평가용 executor다.
-- planner가 요청한 로컬 첨부파일 읽기와 안전한 산술 계산만 수행한다.
-- 폐쇄망 전제이므로 웹/API 호출을 시도하지 않는다.
-- 도구 결과를 간결히 보고한다.
+당신은 GAIA 평가용 executor다. 두 가지 로컬 도구만 사용한다.
+1. read_attached_file(path): 첨부파일을 텍스트로 추출한다. 텍스트뿐 아니라
+   xlsx/docx/pptx/pdf도 지원한다. 이미지/오디오는 추출 불가 안내를 반환한다.
+   질문에 [첨부파일 경로: ...]가 있으면 그 절대경로를 그대로 전달한다.
+2. python_exec(code): 격리된 Python으로 코드를 실행하고 print 출력을 받는다.
+   파일 파싱·표 집계·정렬·날짜 계산 등 산술 이상의 작업에 사용한다.
+   첨부 파일은 절대경로로 open 한다. 결과는 반드시 print 한다.
+   pandas, openpyxl 등 표준 데이터 라이브러리를 import 할 수 있다.
+- 폐쇄망 전제이므로 웹/API 호출은 시도하지 않는다.
+- 도구 결과(추출 텍스트·실행 출력)를 간결히 보고한다.

v1 → v6-verify-gate · 라우팅층 (selector만)

SELECTOR_PROMPT — "검증 의무 경유" 블록 7줄 추가

--- a/SELECTOR_PROMPT (v1)    +++ b/SELECTOR_PROMPT (v6)
@@ -4,4 +4,11 @@
 Conversation:
 {history}
+
+Mandatory verification gate (do not violate):
+- A run may end ONLY after critic outputs APPROVE.
+- The moment planner produces a line starting with `FINAL ANSWER:`, you MUST select
+  critic next with reason_code NEEDS_VERIFICATION. Never route to planner or executor
+  to "finalize" a draft — only critic can clear a final answer.
+- If critic returned a rejection, route back to planner with reason_code NEEDS_REVISION.

 Return exactly one JSON object with this schema:

“1변수” 가드가 코드로 강제되는 지점

• 같은 골격, 다른 한 곳: v2는 v1_baseline.build_team(team_id="v2-attach-path")를 그대로 호출(프롬프트 재사용) → 그래서 hash가 v1과 같다. v6은 SELECTOR_PROMPT만 바꿔 hash가 달라진다. v3/v4/v5는 planner/critic/executor·도구를 건드려 hash가 달라진다.
• AC9 재현성 가드(registry.ensure_team_record): 같은 team_id인데 DB의 prompt_bundle_hash와 다르면 TeamConfigMismatchError로 즉시 중단. “프롬프트 한 글자라도 바꿨으면 새 team_id를 써라”를 DB가 집행한다.
• 입력 가공은 따로 등록: 첨부경로 주입은 프롬프트가 아니므로 hash에 안 잡힌다. 대신 registry._RUN_MESSAGE_BUILDERS에 v2~v5만 등록 — v1의 입력 재현성을 깨지 않으려고 “기본은 task.question 그대로”를 유지한다.

K불변식(CHECK) 대조 — 이 trace가 통과하는 제약들

스키마(001_init.sql)의 CHECK는 “정합성을 코드 검증만으로 끝내지 마라”(절대규칙 4)의 집행자. 위 18행+runs 1행이 실제로 통과하는지 대조.

L평가 실행 명령어 — 옵션별 완전 레퍼런스

진입점은 python cli.py <command> (typer). 모든 명령은 load_settings()로 .env의 EVAL_*를 읽는다. 비밀(DSN/키)은 로그·예외에 출력하지 않는다.

L.0 환경변수 (EVAL_*) — src/agent_eval/config.py

L.1 run — 평가 배치 실행 (핵심)

python cli.py run --batch <ID> [--team …] [--benchmark …] [--level N] [--exclude-web]
                  [--task-ids a,b] [--limit N] [--attempts N] [--concurrency N] [--retry-crashed]

• 재개(resume) 의미론(runner._prepare_run_row): 같은 (batch,task,attempt)가 completed면 skip · crashed면 --retry-crashed일 때만 삭제 후 재시도 · 그 외 신규 INSERT(status=running). → 같은 --batch로 다시 돌리면 멈춘 지점부터 이어진다.
• 종료 시 자동으로 materialized view를 REFRESH(db.refresh_views) → report/Grafana가 즉시 최신.
• 출력 한 줄: batch=… planned=… started=… completed=… crashed=… skipped=… retried=…

L.2 시나리오별 실행 레시피 (복붙)

# ① 오프라인 스모크 — 2문제만, 웹 불요, 끝까지 도는지 확인
python cli.py run --batch dev_smoke --team v1-baseline --limit 2 --exclude-web

# ② GAIA level-1 전체를 v5로 (첨부 멀티포맷 도구)
python cli.py run --batch gaia_l1_v5 --team v5-multitool --benchmark gaia --level 1 --concurrency 4

# ③ pass@3 (task별 3회 반복) — 변동성 측정
python cli.py run --batch gaia_l1_v5_k3 --team v5-multitool --level 1 --attempts 3

# ④ 1변수 비교쌍: 같은 task 셋을 v1 / v6 두 배치로
python cli.py run --batch cmp_v1 --team v1-baseline   --level 1
python cli.py run --batch cmp_v6 --team v6-verify-gate --level 1
python cli.py compare --batches cmp_v1,cmp_v6

# ⑤ 특정 실패 task만 골라 크래시 재수렴 (1개씩 독립 권장 — 아래 §M.4)
python cli.py run --batch gaia_l1_v5 --task-ids c61d22de-…,8f80a1b2-… --retry-crashed

L.3 데이터 적재 / DB

L.4 리포팅 (읽기 전용 — 뷰만 읽음)

L.5 채점 / grounding · L.6 기타

narrate(LLM 서사 리포트)는 SPEC §0.3대로 의도적 미구현.

M추가 평가(테스트) 돌리는 법 — 단계별 가이드

“새 실험을 하나 추가해서 돌리고 비교한다”의 전 과정. 핵심 규율: 1배치=1조건, 1팀=1변수, 비교는 같은 task 셋으로.

M.0 준비 (1회)

pip install -e ".[dev]"                 # 폐쇄망이면 사내 PyPI 미러
cp .env.example .env                    # EVAL_PG_DSN / EVAL_LLM_* 채우기
python cli.py init-db                   # 001+ 멱등 적용 (2회 돌려도 성공해야 정상)
python cli.py load-gaia                 # metadata.jsonl → tasks
python scripts/smoke_llm.py            # GLM function calling 왕복 (M2 전 필수)
python cli.py run --batch dev_smoke --team v1-baseline --limit 2 --exclude-web

M.1 시나리오 A — 기존 팀으로 새 배치

python cli.py run --batch <새 batch ID> --team v5-multitool --benchmark gaia --level 1
python cli.py report --batch <새 batch ID>          # pass@1·p50·도구

배치 ID는 의미를 담아 유일하게(예: gaia_l1_v5_20260623). 중간에 끊겨도 같은 ID로 다시 돌리면 이어서 채운다.

M.2 시나리오 B — 새 실험 팀 추가 (1변수 개입)

§J의 v2~v6이 바로 이 절차로 만들어졌다. “프롬프트 한 글자라도” 바꾸면 새 team_id(AC9).

레지스트리 등록 — 실제 편집 2곳 (teams/registry.py)

# ① import (파일 상단 v-시리즈 import 옆)
+from agent_eval.teams.v7_xxx import TEAM_ID as _V7_TEAM_ID
+from agent_eval.teams.v7_xxx import build_team as _build_team_v7

# ② 빌더 매핑에 한 줄
 TEAM_REGISTRY: dict[str, Callable] = {
     ...
+    _V7_TEAM_ID: _build_team_v7,
 }

# ③ (입력 가공팀일 때만) run 메시지 빌더 등록
 _RUN_MESSAGE_BUILDERS: dict[str, Callable] = {
     ...
+    _V7_TEAM_ID: _v7_build_run_message,
 }

M.3 시나리오 C — 단위 테스트(pytest)

pytest -x                       # 전체. LLM은 mock — 실 네트워크 호출 금지
pytest tests/test_scorer.py -x  # 채점 규칙(AC3: 최소 15케이스)
pytest tests/test_mapping.py -x # 이벤트→message_type 매핑

신규 코드엔 신규 테스트 동반(scorer/매핑/제약은 필수 대상). 동작을 바꾸면 해당 테스트부터 확인한다.

M.4 동시성 · 재개 · 크래시

• 재개: 끊긴 배치는 같은 --batch로 재실행 → 완료분 skip, 나머지만. crashed를 다시 돌리려면 --retry-crashed.
• AutoGen teardown 경합 크래시(동시성 1에서도 간헐 발생 가능): timeout 래퍼로 감싸지 말 것. 수렴법 — ⓐ --retry-crashed 반복, 또는 ⓑ 남은 것을 --task-ids로 1개씩 독립 프로세스로 실행.
• 동시성 vs z.ai: 같은 외부 백엔드를 동시에 두 배치로 두드리지 않기(콘텐츠필터/레이트리밋). 폐쇄망 vLLM이면 --concurrency를 올려도 됨.

# 크래시 1건씩 독립 재시도 (bash)
for t in $(

  
M.5 정합성 점검 SQL (Definition of Done)
  
스모크 후 아래가 모두 0행이어야 완료 선언:
-- 완료 run인데 success 누락
SELECT run_id FROM runs WHERE status='completed' AND success IS NULL;

-- tool_call인데 응답(result/error) 짝이 없는 이벤트
SELECT e.run_id, e.seq FROM events e
WHERE e.message_type='tool_call' AND NOT EXISTS (
  SELECT 1 FROM events r WHERE r.run_id=e.run_id
    AND r.tool_call_id=e.tool_call_id
    AND r.message_type IN ('tool_result','tool_error'));

  
M.6 한 배치의 체크리스트
  

  ① .env 고정값(temperature·seed·model) 확인 → ② pytest -x →
  ③ run --limit 2 스모크 + 정합성 SQL 0행 → ④ 전체 run(같은 batch로 재개 가능) →
  ⑤ report --batch / 1변수면 compare → ⑥ (research/cppx면) grounding-score →
  ⑦ Grafana/eval-metrics에서 확인. 검증 못 하면 완료 선언 안 함.