メインコンテンツへスキップ
見出し画像

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 #システム開発

     
     
    中小企業の「人手が足りない」を仕組みで解決するITエンジニア。Excel手作業からn8n・Claude API自動化まで現場で動かした実装ノウハウを発信。 n8n Verified Creator/Make Lv5認定。 事例はこちら https://www.itdoor.jp

    あなたへのおすすめ