ツールランナー（SDK）

「tool runner」（ツールランナー）は、エージェントループ、エラーのラッピング、型安全性を処理するため、自分で実装する必要がありません。人間による承認（human-in-the-loop）、カスタムロギング、または条件付き実行が必要な場合は、代わりに手動ループを使用してください。

ツール呼び出し、ツール結果、会話管理を手動で処理する代わりに、ツールランナーは以下を自動的に行います。

• Claudeがツールを呼び出したときにツールを実行する
• リクエスト/レスポンスサイクルを処理する
• 会話の状態を管理する
• 型安全性とバリデーションを提供する



基本的な使い方

SDKヘルパーを使用してツールを定義し、ツールランナーを使用してそれらを実行します。

SDKのツールシグネチャに応じて、ツールは結果を文字列またはコンテンツブロック（テキスト、画像、またはドキュメントブロック）として返すため、ツールはマルチモーダルな結果を返すことができます。返された文字列は単一のテキストコンテンツブロックになります。JSONオブジェクトや数値などの構造化データを返すには、まず文字列としてエンコードしてください。



ツールランナーの反復処理

ツールランナーは、Claudeからのメッセージを生成するイテラブルです。各反復で、ランナーはClaudeがツール使用を要求したかどうかを確認します。要求した場合、ツールを実行して結果を自動的にClaudeに送り返し、次のClaudeからのメッセージを生成してループを継続します。

break文を使用して、任意の反復でループを終了できます。ランナーは、Claudeがツール使用を含まないメッセージを返すまで、または設定した場合はmax_iterationsに達するまでループします。

中間メッセージが不要な場合は、最終メッセージを直接取得できます。



高度な使い方

ループ内では、各レスポンスメッセージを読み取り、次のAPI呼び出しの前にランナーの状態を変更できます。各反復は次のライフサイクルに従います。

1. ランナーは現在の状態でMessages APIにリクエストを送信します。
2. ランナーはレスポンスメッセージをループ本体に生成します。
3. ループ本体が実行されます。メッセージを読み取り、オプションでランナーの状態を変更できます。
4. ループ本体が戻ると、ランナーはメッセージ履歴を変更したかどうかを確認します。
   • メッセージ履歴を変更しなかった場合： ランナーはアシスタントメッセージを自身の状態に追加します。メッセージにツール呼び出しが含まれている場合、ランナーはそれらを実行して結果を追加します。ツール呼び出しがない場合、ループは終了します。
   • メッセージ履歴を変更した場合： ランナーは自動追加をスキップし、変更された状態をそのまま使用します。メッセージ履歴の引き継ぎを参照してください。



メッセージ履歴の引き継ぎ

デフォルトでは、ランナーが会話の状態を管理します。各ターンの後、アシスタントメッセージとツール結果を自身のメッセージ履歴に追加します。ターンを再試行したい場合（レスポンスを破棄して再送信）、フォローアップメッセージを挿入したい場合、またはツール結果を自分で構築したい場合に、メッセージ履歴を引き継ぎます。

ループ本体内からランナーのメッセージを変更することで引き継ぎます。正確な方法はSDKによって異なります。以下の言語別タブを参照してください。

ある反復で引き継いだ場合、ランナーはそのターンのアシスタントメッセージやツール結果を追加しません。会話を有効な状態に保つ責任はあなたにあります。アシスタントメッセージとツール結果を自分で追加し（そのターンをカウントしたい場合）、ツール呼び出しがないときにループが終了できるように条件付きで状態を変更し、ループを制限するためにmax_iterationsを渡してください。7つのSDKすべてがmax_iterationsをサポートしています。



自動コンテキスト管理

長時間実行されるエージェントタスクの場合、Python、TypeScript、Rubyのツールランナーは自動コンパクションをサポートしており、トークン使用量がしきい値を超えたときに要約を生成して、会話がコンテキストウィンドウの制限を超えて継続できるようにします。3つのSDKすべてで、このクライアント側オプションは非推奨となり、すべてのSDKで利用可能なサーバー側のコンテキスト編集が推奨されています。Go、Java、C#、PHPのツールランナーにはクライアント側コンパクションは含まれていません。



ツール実行のデバッグ

ツールが例外をスローすると、ツールランナーはそれをキャッチし、is_error: trueを持つツール結果としてエラーをClaudeに返します。ツール結果には例外のメッセージ（Pythonでは型とメッセージ）が含まれ、完全なスタックトレースは含まれません。

SDKがログに記録する内容は言語によって異なります。Python SDKは、ツールが未処理の例外を発生させるたびに、標準のloggingモジュールを通じてスタックトレースを含む完全な例外をログに記録します。Python、TypeScript、Java SDKはANTHROPIC_LOG環境変数を読み取ってSDKのロギングを有効にし、リクエストとレスポンスの詳細を含めます。

# infoレベルでログ出力
export ANTHROPIC_LOG=info

# より詳細な出力のためにdebugレベルでログ出力
export ANTHROPIC_LOG=debug

Go、Ruby、C#、PHP SDKはANTHROPIC_LOGを読み取りません。Python以外では、失敗したツールをログに記録するSDKはありません。ツールが失敗した理由を確認するには、ツール関数内で例外をキャッチしてログに記録してから、返すか再スローしてください。



ツールエラーのインターセプト

デフォルトでは、ツールエラーはClaudeに返され、Claudeが適切に応答できます。ただし、エラーを検出して異なる方法で処理したい場合があります。例えば、実行を早期に停止したり、カスタムエラー処理を実装したりする場合です。

PythonおよびTypeScript SDKでは、ツールレスポンスメソッド（Pythonではgenerate_tool_call_response()、TypeScriptではgenerateToolResponse()）を使用してツール結果をインターセプトし、Claudeに送信される前にエラーを確認します。他のSDKはそのフックを公開していません。それらのタブでは最も近い代替手段を説明しています。



ツール結果の変更

ツール結果をClaudeに送り返す前に変更できます。これは、ツール結果でプロンプトキャッシングを有効にするためにcache_controlなどのメタデータを追加したり、ツール出力を変換したりする場合に便利です。

PythonおよびTypeScript SDKでは、ツールレスポンスメソッドを使用してツール結果を取得し、ランナーが進む前にそれを変更します。変更した結果を明示的に追加するか、その場で変更するかはSDKによって異なります。各タブのコードコメントを参照してください。



ストリーミング

ストリーミングを有効にして、各ターンのレスポンスを段階的に処理します。各反復は、イベントを反復処理できるストリームオブジェクトを生成します。



次のステップ