
Claude-APIで実装するPlanner-Generator-Evaluator構成
Claude APIで実装するPlanner-Generator-Evaluator構成 — 本番LLMエージェントの役割分担パターン
LLMエージェントをPoCから本番に持ち上げると、ほぼ必ず同じ壁にぶつかります。「ループが終わらない」「中途半端な出力で完了扱いされる」「コンテキストが汚染されて精度が落ちる」。Anthropicが推奨する Planner-Generator-Evaluator(PGE)パターンは、これらを 構造で解く 設計です。本記事ではClaude APIで動く実装例とともに、設計判断のポイントを整理します。
Planner-Generator-Evaluator とは
PGEは、エージェントの仕事を3つの役割に分割するパターンです。
| 役割 | 推奨モデル | 担当 |
|---|---|---|
| Planner | Opus 4.7 | タスク分解、ゴール定義、成功条件の明文化 |
| Generator | Sonnet 4.6 | 計画に従った実行、ツール呼び出し |
| Evaluator | Sonnet 4.6 | 出力の独立評価、再実行の要否判定 |
ポイントは エージェント間の受け渡しを「共有コンテキスト」ではなく「構造化アーティファクト」で行う こと。Plannerが書いたJSONをGeneratorが読み、Generatorの成果物をEvaluatorが独立に評価します。共有コンテキストを使わないため、各エージェントは前段の思考過程に引きずられにくくなります。
実装してみた
環境構築
pip install "anthropic>=0.40"
export ANTHROPIC_API_KEY=sk-ant-...Python 3.11以上を想定。本記事では一般のClaude APIで実装しますが、ツール実行を含むGeneratorだけClaude Agent SDKに置き換える構成も可能です。
実装コード
import json
from anthropic import Anthropic
client = Anthropic()
PLANNER = "claude-opus-4-7"
WORKER = "claude-sonnet-4-6"
def plan(goal: str) -> dict:
"""Goalをサブタスクに分解し、成功条件付きの計画を返す"""
sys = (
"あなたはPlannerです。Goalを3〜5個のサブタスクに分解し、"
"各サブタスクの検証可能な成功条件を明文化してください。"
'出力は {"tasks": [{"id": int, "desc": str, "criteria": str}]} のJSONのみ。'
)
msg = client.messages.create(
model=PLANNER, max_tokens=1024, system=sys,
messages=[{"role": "user", "content": goal}],
)
return json.loads(msg.content[0].text)
def generate(task: dict) -> str:
"""サブタスクを実行する"""
sys = "あなたはGeneratorです。タスクの要求どおりの成果物だけを出力してください。"
msg = client.messages.create(
model=WORKER, max_tokens=2048, system=sys,
messages=[{"role": "user",
"content": json.dumps(task, ensure_ascii=False)}],
)
return msg.content[0].text
def evaluate(task: dict, output: str) -> dict:
"""成功条件に照らして独立評価する"""
sys = (
"あなたはEvaluatorです。criteriaに照らしoutputが合格かを判定。"
'出力は {"pass": bool, "reason": str} のJSONのみ。'
)
payload = {"criteria": task["criteria"], "output": output}
msg = client.messages.create(
model=WORKER, max_tokens=512, system=sys,
messages=[{"role": "user",
"content": json.dumps(payload, ensure_ascii=False)}],
)
return json.loads(msg.content[0].text)
def run(goal: str, max_retries: int = 2) -> list[dict]:
plan_obj = plan(goal)
results = []
for task in plan_obj["tasks"]:
verdict = {"pass": False, "reason": ""}
for _ in range(max_retries + 1):
output = generate(task)
verdict = evaluate(task, output)
if verdict["pass"]:
break
task["desc"] += f"\n[再試行ヒント] {verdict['reason']}"
results.append({"task": task, "output": output, "verdict": verdict})
return results動作確認
results = run("社内向けにLLMエージェント観測性のFAQを5問つくる")
for r in results:
print(r["task"]["id"], r["verdict"]["pass"])実行例: `1 True / 2 True / 3 False / 3 True`(タスク3が1回再試行で合格)。
設計判断のポイント
なぜモデルを使い分けるか
Plannerには推論深度が重要なので Opus 4.7。GeneratorとEvaluatorはレイテンシ・コストとのバランスで Sonnet 4.6 が無難です。Evaluatorを Haiku 4.5 に下げる手もありますが、評価精度とのトレードオフ。本番投入前にA/Bで測ることを推奨します。
なぜ評価を独立に走らせるか
同一プロンプト内で「生成して自己評価」させると、生成側のロジックに引きずられて合格判定が緩みます。別systemプロンプト・別messages履歴 で評価を走らせるのは、レビュアを変えるのと同じ効果があります。
ハマりどころ
1. Evaluatorが甘くなる問題
`criteria` を抽象的に書くと評価が緩みます。「丁寧な文体」ではなく「敬体(です・ます調)で統一・1問100字以上」のように 検証可能な記述 に落とすことが必須。Plannerのsystemプロンプトに「検証可能な」と明示するのも有効です。
2. JSONパース失敗
`max_tokens` を絞ると末尾が切れて `json.loads` が落ちます。本番では `try/except json.JSONDecodeError` で1回だけ再試行するか、ストリームの完了通知を確認するロジックを入れてください。
3. 無限再試行
`max_retries` ガードは必須。Claude API・Claude Agent SDK ともにループ保護は組み込まれていないため、自前で打つ必要があります。回数だけでなく、前回と同一出力が続いた場合は強制終了 する重複検知も合わせて実装すると安全です。
まとめ
PGEパターンの本質は 「共有コンテキストではなくアーティファクトで状態を渡す」 ことにあります。エージェントの責務が分離され、各層を独立にデバッグ・差し替えできます。本番投入時は、上記コードに加えてLangfuseやLangSmithでステップ単位のトレースを取ることを推奨します。
本番LLMエージェントは「賢いプロンプト」ではなく「明確な役割分担」で安定する。
次のステップは、各役割をキュー経由で非同期化し、複数Goalを並列実行する構成です。
この記事を書いた人:IT engineer。現場で実装しながら得た知見を、技術者目線で発信しています。
#システム設計 #AI上級者向け #エンジニア向け #ClaudeAgentSDK #LLMエージェント #PlannerGeneratorEvaluator #Anthropic #毎日note #AI #システム開発