AI エージェント開発実践 #3 計画と自己修正

AI LLM Claude
読了 5分

第2回までで、ループとツールがそろいました。短い仕事ならすでにうまく回ります。ところが「先月の注文データを整理して、レポートの下書きまで作って」のように段階が多い仕事を任せると、エージェントが途中で道に迷ったり、同じ失敗を繰り返したりすることがあります。今回は、エージェントに計画を立てさせ、途中の結果を検証させ、失敗を自分で立て直させる方法を扱います。

システムプロンプトで行動ルールを与える #

これまでは目標だけを user メッセージで渡していました。複数の段階がある仕事では、タスクごとに変わる目標とは別に、常に守るべき行動ルールをシステムプロンプトに置きます。

agent_system_prompt.py 
SYSTEM = """あなたは注文データを扱う運用補助エージェントです。

ルール:
- 作業を始める前に、段階ごとの計画を先に立て、計画を一行ずつ列挙する。
- 各段階を終えるたびに、結果を一文で確認してから次の段階に進む。
- データを変更する作業は、変更前に現在の値を先に照会して確認する。
- 同じツールが同じ入力で2回連続して失敗したら、別の方法を探すか、作業を止めて状況を報告する。
"""

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=16000,
    system=SYSTEM,
    tools=tools,
    messages=messages,
)

ルールは抽象的な心構えより、行動として書くほうが効果的です。「慎重に行動する」より「変更前に現在の値を先に照会する」のほうがはるかによく守られます。

計画を先に立てさせる #

上のルールの一つ目が核心です。複雑な仕事ほど、いきなりツールを呼ぶより、計画を先にテキストで列挙させるほうが結果が良くなります。計画が会話に残っていると、Claude が各段階でその計画を見返しながら進めるため、長い仕事でも最初の目標を忘れません。

計画は一度立てたら終わりではありません。途中の結果が予想と違えば、計画を直す必要があります。これもルールとして書けます。「途中の結果が計画と違ったら、残りの計画を修正して再び列挙してから進める」のようにです。

途中の検証を作業に組み込む #

複数の段階がある仕事で最も危険なのは、途中の段階の失敗に気づかないまま次の段階を積み上げることです。防ぐ方法は単純です。確認する段階を作業の一部にすることです。

  • データを変更したら、変更後にもう一度照会して、意図どおりに変わったか確認します。
  • ファイルを作ったら、読み直して内容が正しいか確認します。
  • コードを直したら、テストを実行して通るか確認します。

検証に使うツールはたいていすでにあります。照会ツールがそのまま検証ツールです。必要なのはシステムプロンプトのルール一行です。「変更作業の後は必ず結果をもう一度照会して確認する」と書きます。

検証が失敗すると、その結果がツール結果として会話に入り、Claude は失敗を見て修正を試みます。これが自己修正の基本回路です。検証の段階がなければ、この回路自体が生まれません。

同じ失敗の繰り返しを止める #

自己修正には副作用が一つあります。ときどき、同じ方法を少しずつ変えながら際限なく再試行し続けることです。第1回の max_steps が最後の安全装置ですが、その前にループ側で繰り返しを検知して断ち切れます。

repeat_guard.py 
from collections import Counter

failure_count = Counter()

def execute_tool(block) -> dict:
    result = try_run_tool(block)
    if result.get("is_error"):
        key = (block.name, str(block.input))
        failure_count[key] += 1
        if failure_count[key] >= 3:
            result["content"] += (
                " この方法は3回失敗しました。同じ試行を繰り返さず、"
                "別の方法を探すか、これまでの状況を整理して報告してください。"
            )
    return result

同じツール・同じ入力の失敗回数を数え、上限に達したらエラーメッセージに指示を書き足します。第2回で見た原則そのままです。エラーメッセージは Claude が読んで従う文書なので、ループが把握した状況をその中に書いてあげればよいのです。

adaptive thinking で思考の深さを調節する #

計画と自己修正は、結局のところ推論の品質の問題でもあります。Claude には応答の前に内部で考える thinking 機能があり、最新モデルでは adaptive で有効にします。いつどれだけ考えるかを、Claude が仕事の難易度に合わせて自分で決める方式です。

adaptive_thinking.py 
response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=16000,
    thinking={"type": "adaptive"},
    output_config={"effort": "high"},
    system=SYSTEM,
    tools=tools,
    messages=messages,
)

effort は全体的な努力の水準を決めるパラメータです。low、medium、high、max があり、エージェントの仕事には high 以上を推奨します。深く考えるほどトークンを多く使いますが、エージェントでは計画が良くなって全体の段階数が減るため、総コストがむしろ下がる場合が多いです。

なお claude-opus-4-8 では temperature のようなサンプリングパラメータが削除されており、送ると 400 エラーになります。動作の調節はシステムプロンプトと effort で行います。

よくつまずくところ #

  • ルールを user メッセージに入れる — 行動ルールを毎回目標と一緒に送ると、会話が長くなるほど埋もれてしまいます。常に守るルールはシステムプロンプトに置きます。
  • 検証なしに段階を積み上げる — 3段階目で狂った作業が7段階目で見つかると、巻き戻すものが多くなります。変更直後の検証が最も安上がりです。
  • 再試行に上限を設けない — 自己修正を信じて無制限に回すと、同じ失敗にトークンを燃やすだけです。失敗回数を数え、上限で方向転換を指示します。

まとめ #

今回は、複数の段階がある仕事に耐えるエージェントの行動設計を扱いました。

  • 行動ルールはシステムプロンプトに、具体的な行動として書きます。計画を先に列挙させるルールが特に効果的です。
  • 変更後の再照会のような検証の段階を作業に組み込んでこそ、自己修正の回路が回り始めます。
  • 同じ失敗の繰り返しはループで検知して断ち切り、adaptive thinking と effort で思考の深さを仕事に合わせます。

ところが段階が増えると、別の問題が現れます。会話が長くなり、コンテキストが限界に近づくことです。次回の「AI エージェント開発実践 #4 長い作業を支えるコンテキスト管理」で扱います。

X