マルチエージェントコラボレーション · 第 6 回 / 全 6 回

レッスン6: ハンズオン: 2エージェントレビューパイプラインの構築

学習目標:

Claude API を使用して本当に実行可能なプロデューサー・レビュアーの2エージェントパイプラインを書く

レビュアーに包括的な「良さそうだ」ではなく、構造化されたチェック可能なレビュー結果を返させる

プロデューサーとレビュアーが永遠に磨き合わないように、ループに安全弁を設置する

前提: レッスン1〜5を完了し、基本的な JavaScript/Node.js を読むことができ、動作する Claude API キーを持っていること | 前: レッスン5 <<

まず、結果: 1回の完全な実行

これはレッスンの終わりまでに実行できるようになるものです。ターミナルにタスクを渡すと、2つのエージェントがレビューが通るかラウンド制限に達するまで交代します。

$ node review-pipeline.js "Write an API change announcement for developers: the v2 endpoint changes the user_id field from a number to a string"
[Producer v1]The v2 endpoint is here! Hugely improved experience — please switch to the new version soon.
[Reviewer round 1] Rejected. Issues:- Doesn't spell out the specific field this change affects (never mentions that user_id goes from number to string)- Gives no migration advice; developers don't know how to update their code- "Hugely improved experience" is an unverifiable, exaggerated claim with no concrete basis
[Producer v2]v2 API change notice: the user_id field type changes from number to string.Check every piece of code that parses this field and switch the read logic from numeric to string,to avoid parse failures caused by the type mismatch. This change takes effect in v2.1.0.
[Reviewer round 2] Approved
Final draft (approved in round 2):v2 API change notice: the user_id field type changes from number to string.Check every piece of code that parses this field and switch the read logic from numeric to string,to avoid parse failures caused by the type mismatch. This change takes effect in v2.1.0.

$ node review-pipeline.js "Write an API change announcement for developers: the v2 endpoint changes the user_id field from a number to a string"
[Producer v1]The v2 endpoint is here! Hugely improved experience — please switch to the new version soon.
[Reviewer round 1] Rejected. Issues:- Doesn't spell out the specific field this change affects (never mentions that user_id goes from number to string)- Gives no migration advice; developers don't know how to update their code- "Hugely improved experience" is an unverifiable, exaggerated claim with no concrete basis
[Producer v2]v2 API change notice: the user_id field type changes from number to string.Check every piece of code that parses this field and switch the read logic from numeric to string,to avoid parse failures caused by the type mismatch. This change takes effect in v2.1.0.
[Reviewer round 2] Approved
Final draft (approved in round 2):v2 API change notice: the user_id field type changes from number to string.Check every piece of code that parses this field and switch the read logic from numeric to string,to avoid parse failures caused by the type mismatch. This change takes effect in v2.1.0.

最初のバージョンはレビュアーによって跳ね返され、各具体的な基準に紐付いた理由が示されます。プロデューサーは2番目のバージョンに修正し、レビュアーは再度確認し、今回は通ります。これはレッスン4のプロデューサー・レビュアーパターンをコードに変えたものです。"one LLM call generates a response while another provides evaluation and feedback in a loop."¹

全体的な形: 実行ループと同じ骨格

このシリーズでAgent Tool Calling: Getting Agents to Actually Do Thingsコースを受けた場合、このパイプラインの骨格は馴染みがあるでしょう。ループ、ラウンドごとの1つの判定、続けるかどうかを決定する結果、さらに無限ループに対する安全弁です。唯一の違いは判定が何を判定するかです。そのコースのツール実行ループは「モデルはまだツールを呼び出したいか」を判定します（ループのセマンティクスはそのコースのレッスンThe Full Round-Trip of a Tool Callとその公式ソースにあります）。ここでは「レビュアーは合格と言ったか」を判定します。同じ骨格、ループ本体の内容が異なります。

パイプライン全体は3つの関数をつなぎ合わせたものです。runProducerはテキストを生成または修正し、runReviewerは基準に対してスコアを付けて具体的なメモを提供し、runPipelineは2つをループに結び付け、安全弁としてラウンドの上限を設定します。

ステップ1: プロデューサー — タスクを受け取り、テキストを生成する

最初の実行では、プロデューサーはタスクそのものしか持っていません。却下後の2回目の実行では、完全な前のバージョンとレビューメモも運びます。そのため、プロデューサーはゼロから自由にスタイリングするのではなく、メモに従って最後のバージョンの上に修正します。

JAVASCRIPT

import Anthropic from "@anthropic-ai/sdk";

const anthropic = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });
const MODEL = "claude-sonnet-5"; // アカウントが呼び出せるモデルに交換
const MAX_ROUNDS = 3; // 安全弁: プロデューサー・レビュアーは最大3ラウンド磨き、無限ループを避ける

async function runProducer(task, feedback, prevDraft) {
  const prompt = feedback
    ? `Task: ${task}\n\nYour previous version was:\n"""\n${prevDraft}\n"""\n\nThe reviewer rejected it with these notes:\n${feedback}\n\nRevise your previous version according to these notes. Return the full revised text only, with no extra explanation.`
    : `Task: ${task}\n\nReturn the text only, with no extra explanation.`;

  const response = await anthropic.messages.create({
    model: MODEL,
    max_tokens: 512,
    messages: [{ role: "user", content: prompt }],
  });
  const block = response.content.find((b) => b.type === "text");
  return block ? block.text.trim() : "";
}

プロデューサーのプロンプトは独立しています。レッスン3でカバーしたように、サブエージェントはオーケストレーター側で何が起こったかを見ることができず、前回どうレビューされたかも見ることができません²。そのため、すべての呼び出しは「タスクが何か」「前のバージョンが何と言ったか」「（もしあれば）前のラウンドの問題が何だったか」をこの呼び出しのプロンプトに逐語的に書き込みます。プロデューサー自身の以前の下書きでさえ明示的に戻す必要があることに注意してください。これは独立性の原則の中で最も見逃しやすい半分です。Messages API はステートレスで、すべてのリクエストは必要な完全な履歴を運ばなければならず、サーバーはリクエスト間で何も保持しません³。「前のバージョンを修正する」は、前のバージョンが実際にこのプロンプトに書き込まれたときにのみ意味があります。

ステップ2: レビュアー — 具体的な基準に対してスコアを付け、曖昧な評決をしない

レビュアーはモデルに「これは良いか」と尋ねるだけではありません。レッスン5でカバーしたように、検証は印象ベースのスコアではなく、具体的でチェック可能な基準に着地しなければなりません⁴。ここでレビュアーは明示的なチェックリストを取得し、固定された JSON フォーマットで返信することを要求されます。

JAVASCRIPT

const REVIEW_CRITERIA = [
  "Does it clearly state the specific field or endpoint this change affects (not just 'something changed' or 'better experience')?",
  "Does it give concrete migration advice, telling developers how to update their code?",
  "Is the whole announcement kept under 150 words?",
  "Are there any unverifiable, exaggerated claims (like 'hugely improved' with no concrete basis)?",
];

async function runReviewer(task, draft) {
  const prompt = `You are the reviewer. You only find problems; you do not rewrite. Task requirements: ${task}

Review criteria (check each one; do not give a vague verdict):
${REVIEW_CRITERIA.map((c, i) => `${i + 1}. ${c}`).join("\n")}

Text to review:
"""
${draft}
"""

Reply strictly in the JSON format below, with no text outside the JSON:
{"approved": true or false, "issues": ["list each criterion that failed, with the specific problem for each; if all pass, give an empty array"]}`;

  const response = await anthropic.messages.create({
    model: MODEL,
    max_tokens: 512,
    messages: [{ role: "user", content: prompt }],
  });
  const block = response.content.find((b) => b.type === "text");
  return block ? block.text.trim() : "{}";
}

approvedとissuesフィールドが一緒になって構造化されたレビュー結果を構成します。単一の「大丈夫だ」ではなく、「合格か不合格か」プラス「失敗した各基準の背後にある具体的な問題」です。プロデューサーがissuesを持っていると、曖昧な評決からどこに行くかを推測するのではなく、それらの具体的な問題を修正します。

ステップ3: レビュー結果を盲目的に信頼しない — パース失敗を却下として扱う

runReviewerは文字列を返し、実際の JSON オブジェクトではないので、まだパースする必要があります。レビュアーが「厳密に JSON で返信する」ように言われていても、構造化出力の制約がなければ、モデルは依然として構文的に無効な JSON を生成したり、フィールドをドロップしたり、JSON をコードブロックで囲み、その周りにいくつかの説明行を追加したりする可能性があります⁵。ここでの罠は、パースが失敗したときに何が起こるかです。怠惰なルートを取る（パース失敗時にデフォルトで通す）と、「レビュアーが仕事をしなかった」失敗を静かに「レビュー合格」に変えます。それはまさにレッスン5が指摘したポイントです。「見える」完了した出力は実際に正しい出力と同じではなく、検証できないものは出荷すべきではありません⁶。ここでは逆を行います。パース失敗は常に却下としてカウントし、決して合格としてはカウントしません。

JAVASCRIPT

function extractJson(raw) {
  // モデルは時々 JSON をコードブロックで囲む。最初にフェンスを剥がそうとする
  const fenced = raw.match(/```(?:json)?\s*([\s\S]*?)```/);
  return fenced ? fenced[1].trim() : raw.trim();
}

function parseReview(raw) {
  try {
    const parsed = JSON.parse(extractJson(raw));
    if (typeof parsed.approved !== "boolean" || !Array.isArray(parsed.issues)) {
      throw new Error("field shape is wrong");
    }
    return parsed;
  } catch (err) {
    return {
      approved: false,
      issues: [`Reviewer did not reply in the agreed format. Raw content: ${raw.slice(0, 200)}`],
    };
  }
}

typeof parsed.approved !== "boolean"と!Array.isArray(parsed.issues)の行は同じアイデアを拡張します。JSON.parseが成功しても、パースされたフィールドが正しい形を持っていることを確認し、間違ったフィールドタイプも却下としてカウントします。「少なくとも有効な JSON だ」からといって警戒を解かないでください。

一つの余談: レスポンスがスキーマに厳密に一致することをサンプリングレベルで保証する公式の構造化出力機能があります⁵。このレッスンは意図的に「素の呼び出しプラス自分の防御的なパース」スタイルを使用して、モデルの出力を盲目的に信頼できないことを直接感じるようにします。本番では構造化出力を使用してこの落とし穴を完全に取り除くことができます。

ステップ4: ループに配線し、安全弁を追加する

runProducer、runReviewer、parseReviewを手に入れたら、runPipelineは3つを一緒に配線し、MAX_ROUNDSはここでの唯一の安全弁です。プロデューサーとレビュアーは理論的には永遠に磨くことができるので、上限が必要です。

JAVASCRIPT

async function runPipeline(task) {
  let draft = await runProducer(task);
  console.log(`[Producer v1]\n${draft}\n`);

  for (let round = 1; round <= MAX_ROUNDS; round++) {
    const review = parseReview(await runReviewer(task, draft));

    if (review.approved) {
      console.log(`[Reviewer round ${round}] Approved`);
      return { draft, rounds: round, approved: true };
    }

    console.log(`[Reviewer round ${round}] Rejected. Issues:\n- ${review.issues.join("\n- ")}\n`);

    if (round === MAX_ROUNDS) {
      return { draft, rounds: round, approved: false, issues: review.issues };
    }

    draft = await runProducer(task, review.issues.join("\n"), draft);
    console.log(`[Producer v${round + 1}]\n${draft}\n`);
  }
}

const task =
  process.argv[2] ??
  "Write an API change announcement for developers: the v2 endpoint changes the user_id field from a number to a string";

runPipeline(task)
  .then((result) => {
    if (result.approved) {
      console.log(`Final draft (approved in round ${result.rounds}):\n${result.draft}`);
    } else {
      console.log(
        `Hit the max round count (${MAX_ROUNDS}) without passing review. Emitting the last version for human review:\n${result.draft}\n\n` +
          `Issues left unresolved in the last round:\n- ${result.issues.join("\n- ")}`
      );
    }
  })
  .catch((err) => {
    // API 呼び出し自体も失敗する可能性がある（ネットワーク、認証、レート制限）。それも静かに飲み込まない
    console.error(`Pipeline run failed: ${err.message}`);
    process.exitCode = 1;
  });

まだ合格せずにMAX_ROUNDSに達したとき、runPipelineは「合格」の評決を強制しません。最後の下書きとまだ解決されていない問題を人間のレビューのために正直に引き渡します。これもレッスン5のポイントをクロージングステップに適用したものです。結果統合段階が判断できないものに遭遇したとき、コードで自分で決定することでそれを覆い隠すべきではありません。

レビュアーが合意されたフォーマットで返信しなかった — 何をすべきか

このパイプラインを実行している間、レビュアーが1回厳密な JSON で返信せず、代わりに「さっと見たが、コンテンツは基本的に良い」という行を追加し、`JSON.parse` がスローします。パイプラインを実行し続けるために、このパース失敗を合格レビューとして扱うべきですか。

まとめ

プロデューサー・レビュアーパイプラインの骨格は実行ループと同じものです。ループ、ラウンドごとの1つの判定、続けるかどうかを決定する結果、さらに無限ループに対する安全弁です。このパターンの公式定義はまさに "one LLM call generates a response while another provides evaluation and feedback in a loop"¹ です。ここで判定は「ツールを呼び出すべきか」から「レビュアーは合格と言ったか」に切り替わります。
プロデューサーのプロンプトは独立しています。すべての呼び出しはタスク、完全な前のバージョン、（もしあれば）前のラウンドの具体的な問題をプロンプトに逐語的に書き込みます。Messages API はステートレスで、すべてのリクエストは完全な履歴を運ばなければならず、リクエスト間で何も保持されません³。そのため、モデルが前のラウンドで何が起こったかを自分で覚えていることを頼りにすることはできません²。
レビュアーは具体的でチェック可能な基準に対して項目ごとにスコアを付け、包括的な評決ではなく構造化された{approved, issues}を返します⁴。
レビュアーが返すものも盲目的に信頼できません。パース失敗または間違ったフィールド形状は静かな合格ではなく却下としてカウントすべきです⁶。この原則は「サブエージェントが言うことを信頼する」だけでなく、「サブエージェントが返すデータフォーマットを信頼する」にも適用されます。
まだ合格せずに最大ラウンド数に達したとき、パイプラインはコードで自分で合格を決定するのではなく、最後の下書きと未解決の問題を人間のレビューのために正直に引き渡すべきです。

このコースの6つのレッスンはすべてここまでです。「なぜ複数エージェントか」から始まり、オーケストレーターとサブエージェントがどう作業を分割するか、委任プロンプトをどう書くか、どのコラボレーションパターンがどのシナリオに適合するか、失敗をどう処理するかを経て、手作業で動作するプロデューサー・レビュアーパイプラインを構築することで終わります。次に最も価値のあることは説明を読み直すことではありません。手元にある小さな実際のタスクを選び、このパイプラインの骨格にドロップし、レビュー基準を調整し、実行して下書きが跳ね返されるかどうか、何回跳ね返されるかを確認することです。自分でレビュー基準を1回調整することは、理論を10回読み直すことに勝ります。

Building effective agents (Anthropic Engineering) — https://www.anthropic.com/engineering/building-effective-agents ↩ ↩²
Create custom subagents (Claude Code Docs) — https://code.claude.com/docs/en/sub-agents ↩ ↩²
Using the Messages API (Claude API) — https://platform.claude.com/docs/en/build-with-claude/working-with-messages ↩ ↩²
How we built our multi-agent research system (Anthropic Engineering) — https://www.anthropic.com/engineering/multi-agent-research-system ↩ ↩²
Structured outputs (Claude API) — https://platform.claude.com/docs/en/build-with-claude/structured-outputs ↩ ↩²
Best practices for Claude Code (Claude Code Docs) — https://code.claude.com/docs/en/best-practices ↩ ↩²

練習

このレッスンのコードをreview-pipeline.jsに組み立て、npm install @anthropic-ai/sdkを実行し、npm pkg set type=moduleを実行し、ANTHROPIC_API_KEYを設定し、このレッスンの例のタスクを1回実行します。「Approved」を見る前に少なくとも1回「Rejected」ラウンドを見ることを確認します。（プロデューサーの最初のバージョンがそのまま通過する場合、つまずきやすいタスクに交換します。例えば、意図的に「very short announcement」を求め、どれくらい短いかを言わないなど。）

レベル1: 実行してから、レビュー基準を追加する

実行したら、新しい基準をREVIEW_CRITERIAに追加します。「Does the text mention the specific version number where the change takes effect?」再度実行し、レビュアーのissuesにこの新しい基準に紐付いたメモが含まれていることを確認します。

完了基準 · ローカルでチェック

パイプラインが実際に実行され、ログにプロデューサーの最初のバージョンと少なくとも1ラウンドのレビューメモが表示される追加されたレビュー基準が本当にレビュー結果を変える — その情報が欠落している下書きがフラグされる決して合格せずに`MAX_ROUNDS`に達した場合、パイプラインが最終的に何を出力するかを説明できる（クラッシュではなく、最後のバージョンと未解決の問題を引き渡す）

以下のparseReviewのバージョンには問題があります。まず、本当にレビューされなかった下書きを「承認済み」として通す状況を説明し、次に修正されたコードを提供してください。

レベル2: わざと何かを壊してから修正する

JAVASCRIPT

// 壊れたバージョン
function parseReview(raw) {
  try {
    return JSON.parse(raw);
  } catch (err) {
    return { approved: true, issues: [] };
  }
}

完了基準 · ローカルでチェック

問題を正確に名前を付ける: パース失敗時に`approved: true`を返し、「レビュアーが合意されたフォーマットで返信しなかった」失敗を「レビュー合格」として扱うこれがもたらす具体的な結果を説明する（レッスン5の「盲目的に信頼できない」原則に結びつける）修正はパース失敗のフォールバックを`approved: false`に変更し、生のコンテンツを`issues`に記録してトリアージまたはプロデューサーの再試行のために

レッスン6: ハンズオン: 2エージェントレビューパイプラインの構築

まず、結果: 1回の完全な実行

全体的な形: 実行ループと同じ骨格

ステップ1: プロデューサー — タスクを受け取り、テキストを生成する

ステップ2: レビュアー — 具体的な基準に対してスコアを付け、曖昧な評決をしない

ステップ3: レビュー結果を盲目的に信頼しない — パース失敗を却下として扱う

ステップ4: ループに配線し、安全弁を追加する

まとめ

Footnotes

練習

以下のparseReviewのバージョンには問題があります。まず、本当にレビューされなかった下書きを「承認済み」として通す状況を説明し、次に修正されたコードを提供してください。