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 — 戦略を変更して比較

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戦略 × 2モデル × 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で自動的に利用可能になります。

ワークフロー内のEvalノード

評価は、実行後ではなく実行中にワークフローノードとしてインラインで実行することもできます：

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")

統計的比較

組み込みの有意性検定で任意の2つの条件を比較：

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

以下を含むComparisonResultを返します：

フィールド	説明
`test_name`	使用された検定（welch、wilcoxon、mann_whitney）
`statistic`	検定統計量
`p_value`	p値
`effect_size`	コーエンのd
`ci_lower`、`ci_upper`	95%信頼区間
`significant`	p < alphaの場合`True`
`mean_a`、`mean_b`	グループ平均

利用可能な検定：

welch — ウェルチのt検定（デフォルト、独立サンプル）
wilcoxon — ウィルコクソンの符号付順位検定（対応サンプル）
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

ランタイムは元の実行イベントを取得し、ワークフローと入力を抽出して、同じパラメータで新しい実行を作成します。検証とデバッグに便利です。

アブレーション研究のためのフォーク

完了した実行から変更された入力でフォーク — 他のすべてを同一に保ちながら1つの変数を変更：

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

戦略対応エージェントの場合、以下が表示されます：

戦略名とタイプ
反復回数とプランステップ
クリティック判定（critic/debate戦略の場合）
反復ごとのコスト

例：完全な研究の午後

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 deliberationとLDP routingパターン
機能概要については/researchページを参照
より詳細な評価設定についてはevalハーネスドキュメントを参照
jamjet init my-study --template researchを試して開始する

研究ガイド