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

​

ループの概要

1. プロンプトを受け取る。 Claude はプロンプト、システムプロンプト、ツール定義、および会話履歴とともにプロンプトを受け取ります。SDK はセッションメタデータを含むサブタイプ "init" のSystemMessageを生成します。
2. 評価して応答する。 Claude は現在の状態を評価し、どのように進めるかを決定します。テキストで応答したり、1 つ以上のツール呼び出しをリクエストしたり、その両方を行ったりできます。SDK はテキストとツール呼び出しリクエストを含むAssistantMessageを生成します。
3. ツールを実行する。 SDK は要求された各ツールを実行し、結果を収集します。ツール結果の各セットは次の決定のために Claude にフィードバックされます。hooksを使用して、ツール呼び出しを実行前に傍受、変更、またはブロックできます。
4. 繰り返す。 ステップ 2 と 3 がサイクルとして繰り返されます。各完全なサイクルは 1 ターンです。Claude はツール呼び出しと結果の処理を続け、ツール呼び出しのない応答を生成するまで続きます。
5. 結果を返す。 SDK は最終的なAssistantMessage（テキスト応答、ツール呼び出しなし）を生成し、その後に最終テキスト、トークン使用量、コスト、およびセッション ID を含むResultMessageを生成します。

​

ターンとメッセージ

1. ターン 1： Claude は Bash を呼び出して npm test を実行します。SDK はAssistantMessageとツール呼び出しを生成し、コマンドを実行し、出力（3 つの失敗）を含むUserMessageを生成します。
2. ターン 2： Claude は Read を呼び出して auth.ts と auth.test.ts を読み取ります。SDK はファイルの内容を返し、AssistantMessage を生成します。
3. ターン 3： Claude は Edit を呼び出して auth.ts を修正し、Bash を呼び出して npm test を再実行します。3 つのテストすべてが成功します。SDK は AssistantMessage を生成します。
4. 最終ターン： Claude はツール呼び出しのないテキストのみの応答を生成します。「認証バグを修正し、3 つのテストすべてが成功しました。」SDK はこのテキストを含む最終 AssistantMessage を生成し、その後、同じテキストとコストおよび使用量を含むResultMessageを生成します。

​

メッセージタイプ

• SystemMessage： セッションライフサイクルイベント。subtype フィールドはそれらを区別します。"init" は最初のメッセージ（セッションメタデータ）で、"compact_boundary" は圧縮後に発火します。TypeScript では、圧縮境界は SDKSystemMessage のサブタイプではなく、独自のSDKCompactBoundaryMessageタイプです。
• AssistantMessage： 最終テキストのみの応答を含む、各 Claude 応答の後に生成されます。そのターンからのテキストコンテンツブロックとツール呼び出しブロックを含みます。
• UserMessage： 各ツール実行後、Claude に送り返されるツール結果コンテンツとともに生成されます。ループ中盤でストリーミングするユーザー入力に対しても生成されます。
• StreamEvent： 部分メッセージが有効な場合のみ生成されます。生のAPI ストリーミングイベント（テキストデルタ、ツール入力チャンク）を含みます。ストリーム応答を参照してください。
• ResultMessage： エージェントループの終了をマークします。最終テキスト結果、トークン使用量、コスト、およびセッション ID を含みます。subtype フィールドをチェックして、タスクが成功したか制限に達したかを判断します。prompt_suggestion などの少数の末尾システムイベントはその後に到着する可能性があるため、結果で中断するのではなく、ストリームを完了まで反復処理します。結果を処理するを参照してください。

​

メッセージを処理する

• 最終結果のみ： ResultMessage を処理して、出力、コスト、およびタスクが成功したか制限に達したかを取得します。
• 進捗更新： AssistantMessage を処理して、Claude が各ターンで何をしているか、どのツールを呼び出したかを確認します。
• ライブストリーミング： 部分メッセージを有効にする（Python では include_partial_messages、TypeScript では includePartialMessages）して、リアルタイムで StreamEvent メッセージを取得します。リアルタイムでストリーム応答を参照してください。

• Python： claude_agent_sdk からインポートされたクラスに対して isinstance() でメッセージタイプをチェックします（たとえば、isinstance(message, ResultMessage)）。
• TypeScript： type 文字列フィールドをチェックします（たとえば、message.type === "result"）。AssistantMessage と UserMessage は生の API メッセージを .message フィールドでラップするため、コンテンツブロックは message.content ではなく message.message.content にあります。

from claude_agent_sdk import query, AssistantMessage, ResultMessage

async for message in query(prompt="Summarize this project"):
    if isinstance(message, AssistantMessage):
        print(f"Turn completed: {len(message.content)} content blocks")
    if isinstance(message, ResultMessage):
        if message.subtype == "success":
            print(message.result)
        else:
            print(f"Stopped: {message.subtype}")

​

ツール実行

​

組み込みツール

• 外部サービスを接続する MCP サーバー（データベース、ブラウザ、API）
• カスタムツールを定義する カスタムツールハンドラー
• プロジェクトスキルをロードする 設定ソース経由で再利用可能なワークフロー

​

ツール権限

• allowed_tools / allowedTools リストされたツールを自動承認します。許可されたツールリストに ["Read", "Glob", "Grep"] がある読み取り専用エージェントは、プロンプトなしでそれらのツールを実行します。リストされていないツールは引き続き利用可能ですが、権限が必要です。
• disallowed_tools / disallowedTools リストされたツールをブロックします。他の設定に関係なく。ツールが実行される前にルールがチェックされる順序については、権限を参照してください。
• permission_mode / permissionMode 許可または拒否ルールでカバーされていないツールに何が起こるかを制御します。利用可能なモードについては、権限モードを参照してください。

​

並列ツール実行

​

ループの実行方法を制御する

​

ターンと予算

​

努力レベル

​

権限モード

​

モデル

​

コンテキストウィンドウ

​

コンテキストを消費するもの

​

自動圧縮

• CLAUDE.md の要約指示： 圧縮機は他のコンテキストと同様に CLAUDE.md を読むため、要約時に保持する内容を指示するセクションを含めることができます。セクションヘッダーは自由形式です（マジック文字列ではありません）。圧縮機は意図に基づいて一致します。
• PreCompact フック： 圧縮が発生する前にカスタムロジックを実行します。たとえば、完全なトランスクリプトをアーカイブします。フックは trigger フィールド（manual または auto）を受け取ります。hooksを参照してください。
• 手動圧縮： /compact をプロンプト文字列として送信して、オンデマンドで圧縮をトリガーします。この方法で送信されるコマンドは SDK 入力であり、CLI のみのショートカットではありません。SDK のコマンドを参照してください。

# Summary instructions

When summarizing this conversation, always preserve:
- The current task objective and acceptance criteria
- File paths that have been read or modified
- Test results and error messages
- Decisions made and the reasoning behind them

​

コンテキストを効率的に保つ

• サブタスク用にサブエージェントを使用します。 各サブエージェントは新しい会話で開始されます（以前のメッセージ履歴はありませんが、独自のシステムプロンプトとプロジェクトレベルのコンテキスト（CLAUDE.md など）をロードします）。親のターンは表示されず、最終応答のみが親にツール結果として返されます。メインエージェントのコンテキストは完全なサブタスクトランスクリプトではなく、その要約で増加します。詳細については、サブエージェントが継承するものを参照してください。
• ツールを選別します。 すべてのツール定義はコンテキストスペースを取ります。AgentDefinitionの tools フィールドを使用してサブエージェントを必要な最小セットにスコープします。
• MCP サーバーコストを監視します。 MCP ツール検索はデフォルトで MCP ツールスキーマを遅延させ、オンデマンドでロードします。ツール検索がオフの場合、Vertex AI 上の場合、または非ファーストパーティの ANTHROPIC_BASE_URL の背後にある場合、各 MCP サーバーはすべてのツールスキーマをすべてのリクエストに追加するため、多くのツールを持つ少数のサーバーは、エージェントが何か作業を行う前に大量のコンテキストを消費できます。
• ルーチンタスクに低い努力を使用します。 ファイルを読み取るか、ディレクトリをリストするだけで済むエージェント用に努力を "low" に設定します。これはトークン使用量とコストを削減します。

​

セッションと継続性

​

結果を処理する

​

Hooks

​

すべてをまとめる

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage


async def run_agent():
    session_id = None

    async for message in query(
        prompt="Find and fix the bug causing test failures in the auth module",
        options=ClaudeAgentOptions(
            allowed_tools=[
                "Read",
                "Edit",
                "Bash",
                "Glob",
                "Grep",
            ],  # Listing tools here auto-approves them (no prompting)
            setting_sources=[
                "project"
            ],  # Load CLAUDE.md, skills, hooks from current directory
            max_turns=30,  # Prevent runaway sessions
            effort="high",  # Thorough reasoning for complex debugging
        ),
    ):
        # Handle the final result
        if isinstance(message, ResultMessage):
            session_id = message.session_id  # Save for potential resumption

            if message.subtype == "success":
                print(f"Done: {message.result}")
            elif message.subtype == "error_max_turns":
                # Agent ran out of turns. Resume with a higher limit.
                print(f"Hit turn limit. Resume session {session_id} to continue.")
            elif message.subtype == "error_max_budget_usd":
                print("Hit budget limit.")
            else:
                print(f"Stopped: {message.subtype}")
            if message.total_cost_usd is not None:
                print(f"Cost: ${message.total_cost_usd:.4f}")


asyncio.run(run_agent())

​

次のステップ

• まだエージェントを実行していませんか？ クイックスタートから始めて、SDK をインストールし、完全な例をエンドツーエンドで実行してください。
• プロジェクトにフックする準備ができていますか？ CLAUDE.md、スキル、ファイルシステムフックをロードして、エージェントがプロジェクト規約に自動的に従うようにします。
• インタラクティブ UI を構築していますか？ ストリーミングを有効にして、ループが実行されるときにライブテキストとツール呼び出しを表示します。
• エージェントが何をできるかについてより厳密な制御が必要ですか？ 権限でツールアクセスをロックダウンし、フックを使用して、実行前にツール呼び出しを監査、ブロック、または変換します。
• 長時間または高コストのタスクを実行していますか？ 隔離された作業をサブエージェントにオフロードして、メインコンテキストをリーンに保ちます。