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

メッセージライフサイクル、ツール実行、コンテキストウィンドウ、および SDK エージェントを支える アーキテクチャを理解します。

Agent SDK を使用すると、Claude Code の自律型エージェントループを独自のアプリケーションに組み込むことができます。SDK はスタンドアロンパッケージで、ツール、権限、コスト制限、および出力をプログラムで制御できます。これを使用するために Claude Code CLI をインストールする必要はありません。

エージェントを開始すると、SDK は Claude Code を支える実行ループと同じものを実行します。Claude はプロンプトを評価し、ツールを呼び出してアクションを実行し、結果を受け取り、タスクが完了するまで繰り返します。このページでは、そのループ内で何が起こるかを説明し、エージェントを効果的に構築、デバッグ、最適化できるようにします。

ループの概要

すべてのエージェントセッションは同じサイクルに従います。

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

簡単な質問（「ここにはどのようなファイルがありますか？」）は、Glob を呼び出して結果で応答する 1 ～ 2 ターンで済む場合があります。複雑なタスク（「認証モジュールをリファクタリングしてテストを更新する」）は、多くのターンにわたって数十のツール呼び出しをチェーンでき、ファイルを読み取り、コードを編集し、テストを実行し、Claude が各結果に基づいてアプローチを調整します。

ターンとメッセージ

ターンはループ内の 1 往復です。Claude はツール呼び出しを含む出力を生成し、SDK はそれらのツールを実行し、結果は自動的に Claude にフィードバックされます。これはコードに制御を戻さずに発生します。Claude がツール呼び出しのない出力を生成するまでターンが続き、その時点でループが終了し、最終結果が配信されます。

プロンプト「Fix the failing tests in auth.ts」の完全なセッションがどのようなものかを考えてみましょう。

まず、SDK はプロンプトを Claude に送信し、セッションメタデータを含むSystemMessageを生成します。その後、ループが開始されます。

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を生成します。

これは 4 ターンでした。3 つはツール呼び出し、1 つは最終テキストのみの応答です。

max_turns / maxTurns でループをキャップできます。これはツール使用ターンのみをカウントします。たとえば、上記のループで max_turns=2 は編集ステップの前に停止していたでしょう。max_budget_usd / maxBudgetUsd を使用して、支出しきい値に基づいてターンをキャップすることもできます。

制限がない場合、ループは Claude が独自に終了するまで実行されます。これは適切にスコープされたタスクには問題ありませんが、オープンエンドのプロンプト（「このコードベースを改善する」）では長時間実行される可能性があります。予算を設定することは、本番エージェントの良いデフォルトです。以下のターンと予算でオプションリファレンスを参照してください。

メッセージタイプ

ループが実行されると、SDK はメッセージのストリームを生成します。各メッセージは、ループのどのステージから来たかを示すタイプを持ちます。5 つのコアタイプは次のとおりです。

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

これら 5 つのタイプは、両方の SDK でエージェントループライフサイクル全体をカバーしています。TypeScript SDK は、追加の観測可能性イベント（フックイベント、ツール進捗、レート制限、タスク通知）も生成し、追加の詳細を提供しますが、ループを駆動するために必須ではありません。完全なリストについては、Python メッセージタイプリファレンスとTypeScript メッセージタイプリファレンスを参照してください。

メッセージを処理する

処理するメッセージは、構築しているものによって異なります。

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

メッセージタイプをチェックする方法は SDK によって異なります。

• 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}")

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

for await (const message of query({ prompt: "Summarize this project" })) {
if (message.type === "assistant") {
console.log(`Turn completed: ${message.message.content.length} content blocks`);
}
if (message.type === "result") {
if (message.subtype === "success") {
console.log(message.result);
} else {
console.log(`Stopped: ${message.subtype}`);
}
}
}

ツール実行

ツールはエージェントにアクションを実行する機能を提供します。ツールがなければ、Claude はテキストでのみ応答できます。ツールを使用すると、Claude はファイルを読み取り、コマンドを実行し、コードを検索し、外部サービスと相互作用できます。

組み込みツール

SDK には Claude Code を支えるのと同じツールが含まれています。

組み込みツール以外に、以下を実行できます。

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

ツール権限

Claude はタスクに基づいてどのツールを呼び出すかを決定しますが、それらの呼び出しの実行を許可するかどうかを制御します。特定のツールを自動承認したり、他のツールを完全にブロックしたり、すべてに対して承認を要求したりできます。3 つのオプションが連携して、何が実行されるかを決定します。

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

"Bash(npm *)" のようなルールで個別のツールをスコープすることもできます。これにより、特定のコマンドのみを許可できます。完全なルール構文については、権限を参照してください。

ツールが拒否されると、Claude はツール結果として拒否メッセージを受け取り、通常は別のアプローチを試みるか、進めなかったことを報告します。

並列ツール実行

Claude が単一のターンで複数のツール呼び出しをリクエストすると、両方の SDK はツールに応じて同時または順序に実行できます。読み取り専用ツール（Read、Glob、Grep、読み取り専用としてマークされた MCP ツール）は同時に実行できます。状態を変更するツール（Edit、Write、Bash）は競合を避けるために順序に実行されます。

カスタムツールはデフォルトで順序実行されます。カスタムツールの並列実行を有効にするには、その注釈で readOnlyHint を設定します。TypeScriptとPythonSDK の両方は MCP SDK からこのフィールド名を使用します。

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

ループが実行するターン数、コスト、Claude がどの程度推論するか、ツールが実行前に承認を必要とするかどうかを制限できます。これらはすべてClaudeAgentOptions（Python）/ Options（TypeScript）のフィールドです。

ターンと予算

どちらかの制限に達すると、SDK は対応するエラーサブタイプ（error_max_turns または error_max_budget_usd）を含む ResultMessage を返します。これらのサブタイプをチェックする方法については結果を処理するを、構文についてはClaudeAgentOptions / Optionsを参照してください。

努力レベル

effort オプションは Claude が適用する推論の量を制御します。低い努力レベルはターンあたりのトークンが少なく、コストが削減されます。すべてのモデルが努力パラメータをサポートしているわけではありません。どのモデルがサポートしているかについては、努力を参照してください。

effort を設定しない場合、Python SDK はパラメータを設定したままにして、モデルのデフォルト動作に委譲します。TypeScript SDK はデフォルトで "high" です。

単純でスコープが明確なタスク（ファイルのリストや単一の grep の実行など）を実行するエージェントの場合は、低い努力を使用してコストとレイテンシを削減します。トップレベルの query() オプションでセッション全体に effort を設定するか、AgentDefinitionの effort フィールドでサブエージェントごとにセッションレベルをオーバーライドします。

権限モード

権限モードオプション（Python では permission_mode、TypeScript では permissionMode）は、エージェントがツールを使用する前に承認を求めるかどうかを制御します。

インタラクティブアプリケーションの場合は、ツール承認コールバックで "default" を使用して承認プロンプトを表示します。開発マシン上の自律型エージェントの場合は、"acceptEdits" を使用してファイル編集と一般的なファイルシステムコマンド（mkdir、touch、mv、cp など）を自動承認しながら、他の Bash コマンドを許可ルールの背後にゲートします。CI、コンテナ、またはその他の隔離環境に対して "bypassPermissions" を予約します。詳細については、権限を参照してください。

モデル

model を設定しない場合、SDK は Claude Code のデフォルトを使用します。これは認証方法とサブスクリプションによって異なります。特定のモデルをピン留めするか、より高速で安価なエージェント用に小さいモデルを使用するために明示的に設定します（たとえば、model="claude-sonnet-4-6"）。利用可能な ID については、モデルを参照してください。

コンテキストウィンドウ

コンテキストウィンドウは、セッション中に Claude が利用できる情報の総量です。セッション内のターン間でリセットされません。すべてが蓄積されます。システムプロンプト、ツール定義、会話履歴、ツール入力、およびツール出力。ターン間で同じままのコンテンツ（システムプロンプト、ツール定義、CLAUDE.md）は自動的にプロンプトキャッシュされ、繰り返されるプリフィックスのコストとレイテンシが削減されます。

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

SDK でのコンテキストへの各コンポーネントの影響は次のとおりです。

大きなツール出力は大量のコンテキストを消費します。大きなファイルを読み取るか、詳細な出力を含むコマンドを実行すると、単一のターンで数千のトークンを使用できます。コンテキストはターン間で蓄積されるため、多くのツール呼び出しを含む長いセッションは、短いセッションよりもはるかに多くのコンテキストを構築します。

自動圧縮

コンテキストウィンドウが制限に近づくと、SDK は会話を自動的に圧縮します。古い履歴を要約してスペースを解放し、最新の交換と重要な決定を保持します。SDK はこれが発生したときにストリームで type: "system" と subtype: "compact_boundary" を含むメッセージを生成します（Python では SystemMessage。TypeScript では別の SDKCompactBoundaryMessage タイプです）。

圧縮は古いメッセージを要約に置き換えるため、会話の早い段階からの特定の指示は保持されない可能性があります。永続的なルールは初期プロンプトではなく CLAUDE.md に属します（settingSources経由でロード）。CLAUDE.md コンテンツはすべてのリクエストで再注入されるためです。

圧縮動作をいくつかの方法でカスタマイズできます。

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

機能ごとのコンテキストコストの詳細な内訳については、コンテキストコストを理解するを参照してください。

セッションと継続性

SDK との各インタラクションはセッションを作成または継続します。ResultMessage.session_id からセッション ID をキャプチャして（両方の SDK で利用可能）、後で再開します。TypeScript SDK は init SystemMessage の直接フィールドとしても公開します。Python では、SystemMessage.data にネストされています。

再開すると、以前のターンからの完全なコンテキストが復元されます。読み取られたファイル、実行された分析、および実行されたアクション。セッションをフォークして、元のセッションを変更せずに別のアプローチに分岐することもできます。

セッション再開、継続、フォークパターンの完全なガイドについては、セッション管理を参照してください。

結果を処理する

ループが終了すると、ResultMessage は何が起こったかを示し、出力を提供します。subtype フィールド（両方の SDK で利用可能）は、終了状態をチェックする主な方法です。

result フィールド（最終テキスト出力）は success バリアントにのみ存在するため、読み取る前に常にサブタイプをチェックしてください。すべての結果サブタイプは total_cost_usd、usage、num_turns、および session_id を持つため、コストを追跡し、エラー後でも再開できます。Python では、total_cost_usd と usage はオプションとして型付けされ、一部のエラーパスで None である可能性があるため、フォーマットする前にガードしてください。コストと使用量の追跡を参照して、usage フィールドの解釈の詳細を確認してください。

結果には、モデルが最終ターンで生成を停止した理由を示す stop_reason フィールド（TypeScript では string | null、Python では str | None）も含まれます。一般的な値は end_turn（モデルが通常終了）、max_tokens（出力トークン制限に達した）、および refusal（モデルがリクエストを拒否）です。エラー結果サブタイプでは、stop_reason はループが終了する前の最後のアシスタント応答からの値を持ちます。拒否を検出するには、stop_reason === "refusal"（TypeScript）または stop_reason == "refusal"（Python）をチェックしてください。完全なタイプについては、SDKResultMessage（TypeScript）またはResultMessage（Python）を参照してください。

Hooks

Hooksは、ループの特定のポイントで発火するコールバックです。ツールが実行される前、戻った後、エージェントが終了したときなど。一般的に使用されるフックは次のとおりです。

フックはエージェントのコンテキストウィンドウ内ではなく、アプリケーションプロセスで実行されるため、コンテキストを消費しません。フックはループをショートサーキットすることもできます。ツール呼び出しを拒否する PreToolUse フックはそれが実行されるのを防ぎ、Claude は代わりに拒否メッセージを受け取ります。

両方の SDK はすべての上記のイベントをサポートしています。TypeScript SDK には、Python がまだサポートしていない追加のイベントが含まれています。完全なイベントリスト、SDK ごとの利用可能性、および完全なコールバック API については、フックで実行を制御するを参照してください。

すべてをまとめる

この例は、このページの主要な概念を、失敗するテストを修正する単一のエージェントに組み合わせています。許可されたツール（自動承認されるため、エージェントが自律的に実行される）、プロジェクト設定、およびターンと推論努力の安全制限でエージェントを構成します。ループが実行されると、潜在的な再開のためにセッション ID をキャプチャし、最終結果を処理し、総コストを出力します。

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())

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

let sessionId: string | undefined;

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)}`);
}
}

次のステップ

ループを理解したので、構築しているものに応じて、ここに行くべき場所があります。

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

agentic ループのより広い概念的な図（SDK 固有ではない）については、Claude Code の仕組みを参照してください。