読み込み中

エージェントループの仕組み

レッスン 47 分
読み込み中

エージェントループの仕組み

これまでAPI呼び出しを行ってきましたが、1回の呼び出しでは1つの応答しか返ってきません。ワークフローを自動化したい場合、Claudeは行動し、結果を確認し、次に何をすべきかを判断し、それを続ける必要があります。このパターンこそが、人々がエージェンティックワークフローと呼ぶものです。

エージェントとは実際に何なのか

エージェントとは、人間を介さずにメッセージングループの両側を実行する、Claudeの自律バージョンです。エージェントはタスクを受け取り、ツールを選び、Claudeがタスクの完了を判断するまでループ内でコードを実行します。

エージェントループを実装する最も簡単な方法は、次のようになります。

  1. ツールを利用可能な状態でClaudeにメッセージを送信します。
  2. Claudeは最終的な回答を返すか、あなたが定義したツールの使用を要求します。
  3. あなたのコードがそのツールを実行します。
  4. 結果をClaudeに送り返します。
  5. stop reason(停止理由) が tool_use である限り繰り返します。end_turn はClaudeが完了したことを意味し、それ以外の停止理由もループを終了させます。

これをターンが交互に入れ替わる会話として考えてみてください。ユーザーが最初に行動を起こし、エージェントがツールを呼び出し、ツールが結果を返し、エージェントは回答が得られるまでこれを続けます。

最小限の動作例

データベースやUIを持ち出さずにこのループを最初から最後まで実行する様子を見るために、get_weather という偽のツールを用意し、Claudeに今日オースティンで何を着るべきか尋ねてみましょう。Claudeは自力で天気を知る術がないため、ツールを呼び出し、結果を読み取ってから、あなたに回答を返す必要があります。

スクリプト全体はこちらです。

python
import anthropic

client = anthropic.Anthropic()

# tools配列は、Claudeが使用できるものを示します:
# 名前、説明、そして入力用のJSONスキーマです。
tools = [
    {
        "name": "get_weather",
        "description": "Get the current weather for a city.",
        "input_schema": {
            "type": "object",
            "properties": {
                "city": {
                    "type": "string",
                    "description": "The city to get weather for",
                }
            },
            "required": ["city"],
        },
    }
]

# run_toolは単なるハードコードされたルックアップです。
# 実際のアプリでは、データベースやAPIなど何かにアクセスすることになります。
def run_tool(name, tool_input):
    if name == "get_weather":
        return f"Weather in {tool_input['city']}: 95F, sunny"
    raise ValueError(f"Unknown tool: {name}")

messages = [
    {"role": "user", "content": "What should I wear in Austin today?"}
]

# エージェントループです。各イテレーションでClaudeにメッセージを送信し、
# レスポンスのstop reasonで分岐します。
while True:
    response = client.messages.create(
        model="claude-sonnet-5",
        max_tokens=1024,
        tools=tools,
        messages=messages,
    )

    if response.stop_reason == "end_turn":
        # Claudeの処理が完了しました。最終的なテキストを出力してbreakします。
        for block in response.content:
            if block.type == "text":
                print(block.text)
        break

    elif response.stop_reason == "tool_use":
        # レスポンス内のtool useブロックを見つけ、それぞれを実行します。
        tool_results = []
        for block in response.content:
            if block.type == "tool_use":
                result = run_tool(block.name, block.input)
                tool_results.append(
                    {
                        "type": "tool_result",
                        "tool_use_id": block.id,
                        "content": result,
                    }
                )

        # assistantのレスポンスとこちらのツール結果をmessagesに追加し、
        # その後再びループすることで、Claudeが回答できるようにします。
        messages.append({"role": "assistant", "content": response.content})
        messages.append({"role": "user", "content": tool_results})

    else:
        # max_tokensや拒否応答など、それ以外のstop reasonです。
        # messagesには何も変化がないため、ここで停止します。再度ループすると、
        # 同じリクエストに対して何度も料金が発生してしまいます。
        print(f"Stopped early: {response.stop_reason}")
        break

注目すべき3つのポイントがあります。

  • tools配列は、Claudeが利用できるものを伝えます。名前、説明、そして入力のためのJSONスキーマです。
  • run_tool は単なるハードコードされたルックアップです。実際のアプリケーションでは、これはデータベースやAPIなど、何らかのものにアクセスすることになるでしょう。
  • ループがエージェントループです。各イテレーションでメッセージをClaudeに送信し、応答のstop reasonに応じて分岐します。end_turn の場合、Claudeは完了しているので、最終的なテキストを表示してループを抜けます。tool_use の場合、tool useブロックを見つけ、それぞれを実行し、assistantの応答とツールの結果を messages に戻してから、Claudeが回答できるよう再びループします。それ以外の場合は、stop reasonを表示してループを抜けます。

その最後の分岐を省略しないでください。それがないと、max_tokens で打ち切られた応答は messages に何も追加されないため、ループは同じリクエストを再度送信し続け、そのたびに料金が発生してしまいます。ドキュメントにはすべての停止理由とその対処法が一覧になっています。

実行してみる

スクリプトを実行すると、2回のターンが見られます。

  1. ターン1: 停止理由は tool_use です。Claudeはオースティンの get_weather を要求し、あなたのコードが気温と天候を返します。
  2. ターン2: 停止理由は end_turn で、Claudeは軽くて通気性の良いものを着るよう教えてくれます。

エージェントループの端末出力: ターン1はtool_useで停止しオースティンのget_weatherを呼び出し、ターン2はend_turnで停止しClaudeが最終的な服装の推奨を表示する

2回のAPI呼び出し、1回のツール実行、1回の最終回答。これがループのすべてです。Claude APIで構築するものはすべて、これと似たものになります。

本番環境における同じループ

実際の環境では、この同じループが、構造報告書を読み取り、関連する建築基準をツール経由で調べ、作業を進めながらリスクの所見を1件ずつデータベースに書き戻す、コンプライアンスエージェントのような自動レビューエンドポイントを動かします。

アップロードされた構造報告書を一覧表示するコンプライアンスレビューダッシュボード。それぞれにエージェントを起動する「Run auto-review」ボタンがある

ループの形は、あなたがたった今実行したものと同一です。異なるのは次の点です。

  • モックの天気検索の代わりに実際のツールを使用する。
  • 結果がサーバー送信イベントとしてUIにストリーミングで返される。
  • 所見がリスク所見テーブルに永続化される。

実行中のコンプライアンスエージェントのレビュー トレース: ループが繰り返される中、建築基準ライブラリを検索し特定の条項を調べる何十回ものツール呼び出し

まとめ

  • エージェントとはループの中のClaudeです。観察し、判断し、行動し、繰り返します。
  • ループはシンプルです。ツール付きでメッセージを送信し、Claudeが要求するツールを実行し、結果を送り返し、停止理由が tool_use 以外になったら止めます。
  • ループとツールを所有するのはあなたです。推論を所有するのはClaudeです。
  • 同じループの形は、モックの天気デモから本番のコンプライアンスエージェントまで拡張できます。変わるのはツールと配線部分だけです。
  • ループを自分で所有したくない場合は、managed agentsがAnthropicのインフラ上でこの同じループをあなたの代わりに実行します。