JamJet으로 재현 가능한 멀티 에이전트 실험 실행 — 스캐폴드부터 출판 가능한 결과까지.

JamJet을 활용한 멀티 에이전트 연구

JamJet은 연구자에게 즉시 사용 가능한 완전한 실험 인프라를 제공합니다: 재현성을 위한 내구성 있는 실행, 제거 연구를 위한 6가지 추론 전략, 파라미터 스윕을 위한 실험 그리드, 커스텀 스코어러가 포함된 내장 평가, 그리고 통계적 검정이 포함된 논문 출판 내보내기(LaTeX, CSV, JSON)를 지원합니다.

이 가이드는 프로젝트 스캐폴드부터 논문 수준의 결과까지 완전한 연구 워크플로를 안내합니다.

팁: JamJet에 이미 익숙하신가요? 실험 실행 또는 출판용 내보내기로 바로 이동하세요.

설정

JamJet 설치
```
pip install jamjet
```

연구 프로젝트 스캐폴드

jamjet init my-study --template research
cd my-study

스캐폴드된 구조 확인

my-study/
├── agents/
│   └── researcher.py       # 도구가 포함된 에이전트 정의
├── baselines/
│   └── baseline.py         # 베이스라인 비교 스텁
├── experiments/
│   ├── config.yaml          # 모델, 시드, 전략 설정
│   └── runner.py            # 실험 루프
├── evals/
│   ├── dataset.jsonl        # 평가 데이터셋
│   └── scorers.py           # 커스텀 스코어러 정의
├── results/                 # 출력 디렉토리 (.gitkeep)
├── workflow.yaml            # 워크플로 정의
└── README.md

에이전트 정의

에이전트는 @task 데코레이터가 적용된 Python 함수입니다. 각 에이전트는 서로 다른 추론 전략을 사용할 수 있습니다.

from jamjet import task, tool

@tool
async def web_search(query: str) -> str:
    """현재 정보를 웹에서 검색합니다."""
    ...

@task(model="claude-sonnet-4-6", tools=[web_search])
async def researcher(question: str) -> str:
    """웹 검색을 사용하여 질문을 조사합니다."""

6가지 내장 전략

JamJet은 고수준 전략 이름을 명시적인 IR 서브 DAG로 컴파일합니다. 단일 파라미터로 전환 — 동일한 에이전트, 다른 추론:

전략	패턴	최적 용도
`react`	추론 → 행동 → 관찰 루프	도구 집약적 작업
`plan_and_execute`	단계 계획 → 각 단계 실행 → 종합	다단계 분해
`critic`	생성 → 비평 → 수정	품질 민감 출력
`reflection`	실행 → 반성 → 게이트 → 수정 루프	자기 개선 에이전트
`consensus`	N개 에이전트 → 투표 → 판정 → 최종화	분산 감소
`debate`	제안 → 반론 → 판정 → 해결 루프	적대적 추론


# workflow.yaml — 전략을 compare로 변경

agents:
  researcher:
    model: claude-sonnet-4-6
    strategy: debate        # 다음으로 변경: react, reflection, consensus...
    tools: [web_search]
    max_iterations: 6

실험 실행

ExperimentGrid는 모든 조건과 시드의 조합을 영속적 워크플로 실행으로 처리합니다. 실행이 중단되면 체크포인트부터 재개되며 이전 단계를 다시 실행하지 않습니다.

from jamjet.eval import ExperimentGrid

grid = ExperimentGrid(
    conditions={
        "strategy": ["react", "plan_and_execute", "critic",
                      "reflection", "consensus", "debate"],
        "model": ["claude-sonnet-4-6", "gpt-4o"],
    },
    seeds=[42, 123, 456],
    dataset="evals/dataset.jsonl",
    scorers=["llm_judge", "factuality"],
)

results = await grid.run()
results.summary()  # 터미널에서 리치 테이블 출력

이는 6개 전략 x 2개 모델 x 3개 시드 = 36개의 영속적 실행을 수행하며, 각각 완전한 이벤트 추적과 체크포인트를 포함합니다.

참고: 모든 실행은 이벤트 소싱됩니다. 실험이 36개 중 22번째 실행에서 중단되면 22번째부터 재개되어 완료된 조건을 다시 실행하는 데 토큰을 낭비하지 않습니다.

결과 평가

기본 제공 스코어러

JamJet에는 기본적으로 4가지 스코어러 유형이 포함되어 있습니다:

llm_judge — LLM이 루브릭에 따라 출력을 평가 (0-5 척도)
assertion — 출력 구조 또는 콘텐츠에 대한 불린 검사
latency — 임계값 대비 실행 시간을 기준으로 점수 산정
cost — 예산 대비 토큰 비용을 기준으로 점수 산정

커스텀 스코어러

@scorer 데코레이터로 도메인별 스코어러를 등록하세요:

from jamjet import scorer
from jamjet.eval import ScorerResult

@scorer(name="factuality", description="사실 정확성 검증")
async def factuality_scorer(input: dict, output: dict, context: dict) -> ScorerResult:
    # 여기에 커스텀 채점 로직 작성
    return ScorerResult(
        score=0.85,
        passed=True,
        reason="모든 주장이 소스와 대조 검증됨",
    )

커스텀 스코어러는 이름으로 ExperimentGrid 및 EvalNode에서 자동으로 사용할 수 있습니다.

워크플로우에서 평가 노드 사용

평가는 실행 후가 아닌 실행 중에 워크플로우 노드로 인라인 실행될 수 있습니다:

nodes:
  check-quality:
    type: eval
    scorers:
      - type: llm_judge
        rubric: "Is the response accurate and well-sourced?"
        min_score: 4
    on_fail: retry_with_feedback
    max_retries: 2

점수가 너무 낮으면 retry_with_feedback이 평가자의 추론을 추가 컨텍스트로 사용하여 상위 노드를 재실행합니다.

출판용 내보내기

LaTeX 표

results.to_latex("table1.tex", caption="Strategy comparison across models")

논문에서 \input{}으로 바로 사용할 수 있도록 조건별 평균 +/- 표준편차가 포함된 booktabs 형식 표를 출력합니다.

R / pandas용 CSV

results.to_csv("results.csv")

추가 분석용 JSON

results.to_json("results.json")

통계적 비교

내장된 유의성 검정으로 두 조건을 비교합니다:

comparison = results.compare("debate", "react", test="auto", alpha=0.05)

다음 필드가 포함된 ComparisonResult를 반환합니다:

필드	설명
`test_name`	사용된 검정 (welch, wilcoxon, mann_whitney)
`statistic`	검정 통계량
`p_value`	p-값
`effect_size`	Cohen's d
`ci_lower`, `ci_upper`	95% 신뢰구간
`significant`	p < alpha이면 `True`
`mean_a`, `mean_b`	그룹 평균

사용 가능한 검정:

welch — Welch의 t-검정 (기본값, 독립 표본)
wilcoxon — Wilcoxon 부호순위 검정 (대응 표본)
mann_whitney — Mann-Whitney U (비모수, 독립)
auto — 표본 크기 및 대응 여부에 따라 자동 선택

CLI 내보내기

jamjet eval export results.json --format latex --caption "Table 1"
jamjet eval compare results.json --conditions "debate,react" --test auto

재실행 및 포크

정확한 재실행

체크포인트에서 모든 실행을 재현하세요 — 동일한 입력, 동일한 실행 경로:

jamjet replay exec_abc123

런타임이 원본 실행 이벤트를 가져와 워크플로우와 입력을 추출하고, 동일한 매개변수로 새로운 실행을 생성합니다. 검증 및 디버깅에 유용합니다.

절제 연구를 위한 포크

완료된 실행에서 수정된 입력으로 포크하세요 — 나머지는 모두 동일하게 유지하면서 하나의 변수만 변경:

jamjet fork exec_abc123 --override-input '{"model": "gpt-4o"}'

원본 입력은 보존되고 오버라이드가 병합됩니다. 절제 연구로 가는 가장 빠른 경로입니다 — 재구성도, 전체 그리드 재실행도 필요 없습니다.

출처

JamJet의 모든 노드 완료에는 ProvenanceMetadata가 포함됩니다:

필드	설명
`model_id`	이 출력을 생성한 모델
`model_version`	모델 버전 문자열
`confidence`	자체 보고된 신뢰도 (0.0–1.0)
`verified`	출력이 검증을 통과했는지 여부
`source`	출처 식별자

출처는 자동으로 첨부됩니다 — 추가 구성이 필요 없습니다. 이벤트 추적, 감사 로그, 내보낸 결과로 전달됩니다.

팁: 출처 메타데이터는 어떤 모델이 어떤 중간 결과를 생성했는지 귀속해야 하는 다중 모델 실험에서 특히 유용합니다.

워크플로우 검사

jamjet inspect를 사용하여 전략별 세부 정보를 포함한 컴파일된 워크플로우를 검사하세요:

jamjet inspect workflow.yaml

전략 인식 에이전트의 경우 다음을 표시합니다:

전략 이름 및 유형
반복 횟수 및 계획 단계
비평가 판정 (비평/토론 전략의 경우)
반복당 비용

예시: 완전한 리서치 오후

from jamjet.eval import ExperimentGrid

# 1. 그리드 정의

grid = ExperimentGrid(
    conditions={
        "strategy": ["react", "plan_and_execute", "critic",
                      "reflection", "consensus", "debate"],
    },
    seeds=[42, 123, 456],
    dataset="evals/dataset.jsonl",
    scorers=["llm_judge"],
)

# 2. 실행 (내구성 — 충돌 시 재개)

results = await grid.run()

# 3. LaTeX 테이블 내보내기

results.to_latex("table1.tex", caption="Strategy comparison")

# 4. 통계 검정

comp = results.compare("debate", "react")
print(f"p = {comp.p_value:.4f}, Cohen's d = {comp.effect_size:.2f}")

# 5. 특정 실행 재실행

# $ jamjet replay exec_debate_seed42

# 6. 절제 연구를 위한 분기

# $ jamjet fork exec_debate_seed42 --override-input '{"model":"gpt-4o"}'

다음 단계

연구 예제 둘러보기 — DCI 심의 및 LDP 라우팅 패턴
기능 개요는 /research 페이지 참고
심화 평가 설정은 평가 하네스 문서 읽기
jamjet init my-study --template research로 시작하기

연구 가이드