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

​

ループの概要

1. プロンプトを受け取る。 Claude はプロンプト、システムプロンプト、ツール定義、および会話履歴とともにプロンプトを受け取ります。SDK はセッションメタデータを含むサブタイプ "init" のSystemMessageを生成します。
2. 評価して応答する。 Claude は現在の状態を評価し、どのように進めるかを決定します。テキストで応答したり、1 つ以上のツール呼び出しをリクエストしたり、その両方を行ったりできます。SDK はテキストブロックやツール呼び出しリクエストなどのコンテンツブロックごとに 1 つずつ、1 つ以上の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 はツール呼び出しのないテキストのみの応答を生成します。「Fixed the auth bug, all three tests pass now.」SDK はこのテキストを含む最終 AssistantMessage を生成し、その後、同じテキストとコストおよび使用量を含むResultMessageを生成します。

​

メッセージタイプ

• SystemMessage： セッションライフサイクルイベント。subtype フィールドはそれらを区別します。
  • "init"：実行のセッションメタデータ。セッション起動中に SessionStart または Setup フックが実行される場合、そのフックライフサイクルメッセージは init メッセージの前に到着します
  • "compact_boundary"：圧縮後に発火します
  • "informational"：ループからのプレーンテキストステータスバナー
  • "worker_shutting_down"：ホストが終了しているか Remote Control が切断されました
  TypeScript では、"init" 以外の各サブタイプは SDKSystemMessage のサブタイプではなく、SDKMessage ユニオン内の独自のタイプです。
• AssistantMessage： 最終テキストのみの応答を含む、Claude の各応答のコンテンツブロックごとに生成されます。各メッセージは、テキストやツール呼び出しなどの単一のコンテンツブロックを持ち、1 つの応答からのメッセージは同じメッセージ ID を共有します。
• 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 にあります。

import asyncio
from claude_agent_sdk import query, AssistantMessage, ResultMessage, TextBlock, ToolUseBlock


async def main():
    try:
        async for message in query(prompt="Summarize this project"):
            if isinstance(message, AssistantMessage):
                # Each AssistantMessage carries one content block
                for block in message.content:
                    if isinstance(block, TextBlock):
                        print(f"Claude: {block.text}")
                    elif isinstance(block, ToolUseBlock):
                        print(f"Tool call: {block.name}")
            if isinstance(message, ResultMessage):
                if message.subtype == "success":
                    print(message.result)
                else:
                    print(f"Stopped: {message.subtype}")
    except Exception as error:
        # A single-shot query() raises after yielding an error result. If the
        # failure was an error result, the error subtype branches above have
        # already run; connection or process failures yield no result message.
        print(f"Session ended with an error: {error}")


asyncio.run(main())

import { query } from "@anthropic-ai/claude-agent-sdk";

try {
  for await (const message of query({ prompt: "Summarize this project" })) {
    if (message.type === "assistant") {
      // Each assistant message carries one content block
      for (const block of message.message.content) {
        if (block.type === "text") {
          console.log(`Claude: ${block.text}`);
        } else if (block.type === "tool_use") {
          console.log(`Tool call: ${block.name}`);
        }
      }
    }
    if (message.type === "result") {
      if (message.subtype === "success") {
        console.log(message.result);
      } else {
        console.log(`Stopped: ${message.subtype}`);
      }
    }
  }
} catch (error) {
  // A single-shot query() throws after yielding an error result. If the
  // failure was an error result, the error subtype branches above have
  // already run; connection or process failures yield no result message.
  console.log(`Session ended with an error: ${error}`);
}

​

ツール実行

​

組み込みツール

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

​

ツール権限

• allowed_tools / allowedTools リストされたツールを自動承認します。許可されたツールリストに ["Read", "Glob", "Grep"] がある読み取り専用エージェントは、ネットワークパスからの読み取りを除き、プロンプトなしでそれらのツールを実行します。リストされていないツールは引き続き利用可能ですが、それらへの呼び出しで承認が必要な場合は、権限モードと canUseTool にフォールスルーします。
• disallowed_tools / disallowedTools リストされたツールをブロックします。他の設定に関係なく。ツールが実行される前にルールがチェックされる順序については、権限を参照してください。
• permission_mode / permissionMode 必要な人間の監視の量を制御します。SDK は有効なモードと許可および拒否ルールを固定順序で評価します。詳細については、権限がどのように評価されるかを参照してください。利用可能なモードについては、権限モードを参照してください。

​

並列ツール実行

​

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

​

ターンと予算

​

予算の余裕

​

努力レベル

​

権限モード

​

モデル

​

コンテキストウィンドウ

​

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

​

自動圧縮

• CLAUDE.md の要約指示： 圧縮機は他のコンテキストと同様に CLAUDE.md を読むため、要約時に保持する内容を指示するセクションを含めることができます。圧縮機は意図に基づいて一致するため、セクションヘッダーは自由形式です。
• PreCompact フック： 圧縮が発生する前にカスタムロジックを実行します。たとえば、完全なトランスクリプトをアーカイブします。フックは trigger フィールド（manual または auto）を受け取ります。hooksを参照してください。
• 手動圧縮： /compact をプロンプト文字列として送信して、オンデマンドで圧縮をトリガーします。この方法で送信されるコマンドは 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 ツールスキーマを遅延させ、オンデマンドでロードします。ツール検索がオフの場合またはサポートされていないモデルと特定のプラットフォームでアップフロントロードにフォールバックした場合、各 MCP サーバーはすべてのツールスキーマをすべてのリクエストに追加するため、多くのツールを持つ少数のサーバーは、エージェントが何か作業を行う前に大量のコンテキストを消費できます。完全な構成については、ツール検索を構成を参照してください。
• ルーチンタスクに低い努力を使用します。 ファイルを読み取るか、ディレクトリをリストするだけで済むエージェント用に努力を "low" に設定します。これはトークン使用量とコストを削減します。

​

セッションと継続性

​

結果を処理する

• セッションクラッシュ後、最終結果は error_during_execution であり、そのコストフィールドはゼロになる可能性があり、その stop_reason は null です。プロセスはそれを発行した後に終了します。セッションクラッシュ後に合計を復旧するを参照してください。
• Python では、total_cost_usd、usage、および model_usage はオプションとして型付けされているため、読み取る前に None でないことを確認してください。

​

Hooks

​

すべてをまとめる

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage


async def run_agent():
    session_id = None

    try:
        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}")
    except Exception as error:
        # A single-shot query() raises after yielding an error result. If the
        # failure was an error result, the error subtype branches above have
        # already run; connection or process failures yield no result message.
        print(f"Session ended with an error: {error}")


asyncio.run(run_agent())

import { query } from "@anthropic-ai/claude-agent-sdk";

let sessionId: string | undefined;

try {
  for await (const message of query({
    prompt: "Find and fix the bug causing test failures in the auth module",
    options: {
      allowedTools: ["Read", "Edit", "Bash", "Glob", "Grep"], // Listing tools here auto-approves them (no prompting)
      settingSources: ["project"], // Load CLAUDE.md, skills, hooks from current directory
      maxTurns: 30, // Prevent runaway sessions
      effort: "high" // Thorough reasoning for complex debugging
    }
  })) {
    // Save the session ID to resume later if needed
    if (message.type === "system" && message.subtype === "init") {
      sessionId = message.session_id;
    }

    // Handle the final result
    if (message.type === "result") {
      if (message.subtype === "success") {
        console.log(`Done: ${message.result}`);
      } else if (message.subtype === "error_max_turns") {
        // Agent ran out of turns. Resume with a higher limit.
        console.log(`Hit turn limit. Resume session ${sessionId} to continue.`);
      } else if (message.subtype === "error_max_budget_usd") {
        console.log("Hit budget limit.");
      } else {
        console.log(`Stopped: ${message.subtype}`);
      }
      console.log(`Cost: $${message.total_cost_usd.toFixed(4)}`);
    }
  }
} catch (error) {
  // A single-shot query() throws after yielding an error result. If the
  // failure was an error result, the error subtype branches above have
  // already run; connection or process failures yield no result message.
  console.log(`Session ended with an error: ${error}`);
}

​

次のステップ

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