エージェントループの仕組み
メッセージライフサイクル、ツール実行、コンテキストウィンドウ、および SDK エージェントを支える アーキテクチャを理解します。
Agent SDK を使用すると、Claude Code の自律型エージェントループを独自のアプリケーションに組み込むことができます。SDK はスタンドアロンパッケージで、ツール、権限、コスト制限、および出力をプログラムで制御できます。これを使用するために Claude Code CLI をインストールする必要はありません。
エージェントを開始すると、SDK は Claude Code を支える実行ループと同じものを実行します。Claude はプロンプトを評価し、ツールを呼び出してアクションを実行し、結果を受け取り、タスクが完了するまで繰り返します。このページでは、そのループ内で何が起こるかを説明し、エージェントを効果的に構築、デバッグ、最適化できるようにします。
ループの概要
すべてのエージェントセッションは同じサイクルに従います。
- プロンプトを受け取る。 Claude はプロンプト、システムプロンプト、ツール定義、および会話履歴とともにプロンプトを受け取ります。SDK はセッションメタデータを含むサブタイプ
"init"のSystemMessageを生成します。 - 評価して応答する。 Claude は現在の状態を評価し、どのように進めるかを決定します。テキストで応答したり、1 つ以上のツール呼び出しをリクエストしたり、その両方を行ったりできます。SDK はテキストとツール呼び出しリクエストを含む
AssistantMessageを生成します。 - ツールを実行する。 SDK は要求された各ツールを実行し、結果を収集します。ツール結果の各セットは次の決定のために Claude にフィードバックされます。hooksを使用して、ツール呼び出しを実行前に傍受、変更、またはブロックできます。
- 繰り返す。 ステップ 2 と 3 がサイクルとして繰り返されます。各完全なサイクルは 1 ターンです。Claude はツール呼び出しと結果の処理を続け、ツール呼び出しのない応答を生成するまで続きます。
- 結果を返す。 SDK は最終的な
AssistantMessage（テキスト応答、ツール呼び出しなし）を生成し、その後に最終テキスト、トークン使用量、コスト、およびセッション ID を含むResultMessageを生成します。
簡単な質問（「ここにはどのようなファイルがありますか？」）は、Glob を呼び出して結果で応答する 1 ～ 2 ターンで済む場合があります。複雑なタスク（「認証モジュールをリファクタリングしてテストを更新する」）は、多くのターンにわたって数十のツール呼び出しをチェーンでき、ファイルを読み取り、コードを編集し、テストを実行し、Claude が各結果に基づいてアプローチを調整します。
ターンとメッセージ
ターンはループ内の 1 往復です。Claude はツール呼び出しを含む出力を生成し、SDK はそれらのツールを実行し、結果は自動的に Claude にフィードバックされます。これはコードに制御を戻さずに発生します。Claude がツール呼び出しのない出力を生成するまでターンが続き、その時点でループが終了し、最終結果が配信されます。
プロンプト「Fix the failing tests in auth.ts」の完全なセッションがどのようなものかを考えてみましょう。
まず、SDK はプロンプトを Claude に送信し、セッションメタデータを含むSystemMessageを生成します。その後、ループが開始されます。
- ターン 1： Claude は
Bashを呼び出してnpm testを実行します。SDK はAssistantMessageとツール呼び出しを生成し、コマンドを実行し、出力（3 つの失敗）を含むUserMessageを生成します。 - ターン 2： Claude は
Readを呼び出してauth.tsとauth.test.tsを読み取ります。SDK はファイルの内容を返し、AssistantMessageを生成します。 - ターン 3： Claude は
Editを呼び出してauth.tsを修正し、Bashを呼び出してnpm testを再実行します。3 つのテストすべてが成功します。SDK はAssistantMessageを生成します。 - 最終ターン： 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 を支えるのと同じツールが含まれています。
| カテゴリ | ツール | 機能 |
|---|---|---|
| ファイル操作 | Read、Edit、Write |
ファイルを読み取り、変更、作成 |
| 検索 | Glob、Grep |
パターンでファイルを検索、正規表現でコンテンツを検索 |
| 実行 | Bash |
シェルコマンド、スクリプト、git 操作を実行 |
| Web | WebSearch、WebFetch |
Web を検索、ページを取得して解析 |
| 検出 | ToolSearch |
すべてをプリロードする代わりに、オンデマンドでツールを動的に検索してロード |
| オーケストレーション | Agent、Skill、AskUserQuestion、TodoWrite |
サブエージェントを生成、スキルを呼び出し、ユーザーに質問、タスクを追跡 |
組み込みツール以外に、以下を実行できます。
- 外部サービスを接続する 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）のフィールドです。
ターンと予算
| オプション | 制御内容 | デフォルト |
|---|---|---|
最大ターン（max_turns / maxTurns） |
最大ツール使用往復数 | 制限なし |
最大予算（max_budget_usd / maxBudgetUsd） |
停止前の最大コスト | 制限なし |
どちらかの制限に達すると、SDK は対応するエラーサブタイプ（error_max_turns または error_max_budget_usd）を含む ResultMessage を返します。これらのサブタイプをチェックする方法については結果を処理するを、構文についてはClaudeAgentOptions / Optionsを参照してください。
努力レベル
effort オプションは Claude が適用する推論の量を制御します。低い努力レベルはターンあたりのトークンが少なく、コストが削減されます。すべてのモデルが努力パラメータをサポートしているわけではありません。どのモデルがサポートしているかについては、努力を参照してください。
| レベル | 動作 | 適している用途 |
|---|---|---|
"low" |
最小限の推論、高速応答 | ファイル検索、ディレクトリのリスト |
"medium" |
バランスの取れた推論 | ルーチン編集、標準タスク |
"high" |
徹底的な分析 | リファクタリング、デバッグ |
"xhigh" |
拡張推論深度 | コーディングと agentic coding タスク。Opus 4.7 で推奨 |
"max" |
最大推論深度 | 深い分析が必要な複数ステップの問題 |
effort を設定しない場合、Python SDK はパラメータを設定したままにして、モデルのデフォルト動作に委譲します。TypeScript SDK はデフォルトで "high" です。
単純でスコープが明確なタスク（ファイルのリストや単一の grep の実行など）を実行するエージェントの場合は、低い努力を使用してコストとレイテンシを削減します。トップレベルの query() オプションでセッション全体に effort を設定するか、AgentDefinitionの effort フィールドでサブエージェントごとにセッションレベルをオーバーライドします。
権限モード
権限モードオプション（Python では permission_mode、TypeScript では permissionMode）は、エージェントがツールを使用する前に承認を求めるかどうかを制御します。
| モード | 動作 |
|---|---|
"default" |
許可ルールでカバーされていないツールは承認コールバックをトリガーします。コールバックがない場合は拒否 |
"acceptEdits" |
ファイル編集と一般的なファイルシステムコマンド（mkdir、touch、mv、cp など）を自動承認します。他の Bash コマンドはデフォルトルールに従います |
"plan" |
読み取り専用ツールを実行します。Claude はソースファイルを編集せずに探索して計画を作成します |
"dontAsk" |
プロンプトしません。権限ルールによって事前承認されたツールが実行され、その他はすべて拒否されます |
"auto"（TypeScript のみ） |
モデル分類器を使用して各ツール呼び出しを承認または拒否します。利用可能性と動作については、自動モードを参照してください |
"bypassPermissions" |
尋ねずにすべての許可されたツールを実行します。Unix でルートとして実行する場合は使用できません。エージェントのアクションが気にするシステムに影響を与えられない隔離環境でのみ使用します |
インタラクティブアプリケーションの場合は、ツール承認コールバックで "default" を使用して承認プロンプトを表示します。開発マシン上の自律型エージェントの場合は、"acceptEdits" を使用してファイル編集と一般的なファイルシステムコマンド（mkdir、touch、mv、cp など）を自動承認しながら、他の Bash コマンドを許可ルールの背後にゲートします。CI、コンテナ、またはその他の隔離環境に対して "bypassPermissions" を予約します。詳細については、権限を参照してください。
モデル
model を設定しない場合、SDK は Claude Code のデフォルトを使用します。これは認証方法とサブスクリプションによって異なります。特定のモデルをピン留めするか、より高速で安価なエージェント用に小さいモデルを使用するために明示的に設定します（たとえば、model="claude-sonnet-4-6"）。利用可能な ID については、モデルを参照してください。
コンテキストウィンドウ
コンテキストウィンドウは、セッション中に Claude が利用できる情報の総量です。セッション内のターン間でリセットされません。すべてが蓄積されます。システムプロンプト、ツール定義、会話履歴、ツール入力、およびツール出力。ターン間で同じままのコンテンツ（システムプロンプト、ツール定義、CLAUDE.md）は自動的にプロンプトキャッシュされ、繰り返されるプリフィックスのコストとレイテンシが削減されます。
コンテキストを消費するもの
SDK でのコンテキストへの各コンポーネントの影響は次のとおりです。
| ソース | ロード時期 | 影響 |
|---|---|---|
| システムプロンプト | すべてのリクエスト | 小さい固定コスト、常に存在 |
| CLAUDE.md ファイル | セッション開始時、settingSources経由 |
すべてのリクエストで完全なコンテンツ（ただしプロンプトキャッシュされるため、最初のリクエストのみが完全なコストを支払う） |
| ツール定義 | すべてのリクエスト | 各ツールはそのスキーマを追加します。MCP ツール検索を使用して、すべてを一度にロードする代わりにオンデマンドでツールをロード |
| 会話履歴 | ターン間で蓄積 | 各ターンで増加。プロンプト、応答、ツール入力、ツール出力 |
| スキル説明 | セッション開始時、設定ソース経由 | 短い要約。完全なコンテンツは呼び出し時のみロード |
大きなツール出力は大量のコンテキストを消費します。大きなファイルを読み取るか、詳細な出力を含むコマンドを実行すると、単一のターンで数千のトークンを使用できます。コンテキストはターン間で蓄積されるため、多くのツール呼び出しを含む長いセッションは、短いセッションよりもはるかに多くのコンテキストを構築します。
自動圧縮
コンテキストウィンドウが制限に近づくと、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 のスラッシュコマンドを参照してください。）
例：CLAUDE.md の要約指示
プロジェクトの CLAUDE.md にセクションを追加して、圧縮機に保持する内容を指示します。ヘッダー名は特別ではありません。明確なラベルを使用してください。
# 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 サーバーはすべてのツールスキーマをすべてのリクエストに追加します。多くのツールを持つ少数のサーバーは、エージェントが何か作業を行う前に大量のコンテキストを消費できます。
ToolSearchツールはすべてをプリロードする代わりにオンデマンドでツールをロードすることで役立ちます。設定については、MCP ツール検索を参照してください。 - ルーチンタスクに低い努力を使用します。 ルーチンタスク用に努力を
"low"に設定します。これはファイルを読み取るか、ディレクトリをリストするだけで済むエージェント用です。これはトークン使用量とコストを削減します。
機能ごとのコンテキストコストの詳細な内訳については、コンテキストコストを理解するを参照してください。
セッションと継続性
SDK との各インタラクションはセッションを作成または継続します。ResultMessage.session_id からセッション ID をキャプチャして（両方の SDK で利用可能）、後で再開します。TypeScript SDK は init SystemMessage の直接フィールドとしても公開します。Python では、SystemMessage.data にネストされています。
再開すると、以前のターンからの完全なコンテキストが復元されます。読み取られたファイル、実行された分析、および実行されたアクション。セッションをフォークして、元のセッションを変更せずに別のアプローチに分岐することもできます。
セッション再開、継続、フォークパターンの完全なガイドについては、セッション管理を参照してください。
結果を処理する
ループが終了すると、ResultMessage は何が起こったかを示し、出力を提供します。subtype フィールド（両方の SDK で利用可能）は、終了状態をチェックする主な方法です。
| 結果サブタイプ | 何が起こったか | result フィールドは利用可能か？ |
|---|---|---|
success |
Claude は通常、タスクを完了しました | はい |
error_max_turns |
完了前に maxTurns 制限に達しました |
いいえ |
error_max_budget_usd |
完了前に maxBudgetUsd 制限に達しました |
いいえ |
error_during_execution |
エラーがループを中断しました（たとえば、API 障害またはキャンセルされたリクエスト） | いいえ |
error_max_structured_output_retries |
構造化出力検証が設定された再試行制限後に失敗しました | いいえ |
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 |
ツール実行前 | 入力を検証、危険なコマンドをブロック |
PostToolUse |
ツール戻り後 | 出力を監査、副作用をトリガー |
UserPromptSubmit |
プロンプト送信時 | プロンプトに追加コンテキストを注入 |
Stop |
エージェント終了時 | 結果を検証、セッション状態を保存 |
SubagentStart / SubagentStop |
サブエージェント生成/完了時 | 並列タスク結果を追跡して集約 |
PreCompact |
コンテキスト圧縮前 | 要約前に完全なトランスクリプトをアーカイブ |
フックはエージェントのコンテキストウィンドウ内ではなく、アプリケーションプロセスで実行されるため、コンテキストを消費しません。フックはループをショートサーキットすることもできます。ツール呼び出しを拒否する 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 の仕組みを参照してください。