Tool Runner (SDK)

Tool Runnerはエージェントループ、エラーラッピング、型安全性を処理するため、手動で対応する必要がありません。手動ループは、人間によるループ内承認、カスタムログ、または条件付き実行が必要な場合にのみ使用してください。Python、TypeScript、およびRuby SDKで利用可能です。

Tool Runnerは、Claudeでツールを実行するためのすぐに使用できるソリューションを提供します。ツール呼び出し、ツール結果、会話管理を手動で処理する代わりに、Tool Runnerは自動的に以下を行います：

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

ほとんどのツール使用実装にはTool Runnerを使用してください。

基本的な使用方法

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

ツール関数は、テキスト、画像、またはドキュメントブロックを含むコンテンツブロックまたはコンテンツブロック配列を返す必要があります。これにより、ツールはリッチなマルチモーダルレスポンスを返すことができます。返された文字列はテキストコンテンツブロックに変換されます。構造化されたJSONオブジェクトをClaudeに返したい場合は、返す前にそれをJSON文字列にエンコードしてください。数値、ブール値、またはその他の非文字列プリミティブも文字列に変換する必要があります。

Tool Runnerの反復処理

Tool Runnerはイテラブルで、Claudeからのメッセージを生成します。これはしばしば「ツール呼び出しループ」と呼ばれます。各反復で、ランナーはClaudeがツール使用をリクエストしたかどうかをチェックします。そうである場合、ツールを呼び出し、結果を自動的にClaudeに送り返し、次のメッセージをClaudeから生成してループを続けます。

任意の反復でbreakステートメントを使用してループを終了できます。ランナーはClaudeがツール使用なしでメッセージを返すまでループします。

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

高度な使用方法

ループ内で、Tool Runnerの次のMessages APIリクエストを完全にカスタマイズできます。ランナーはツール結果をメッセージ履歴に自動的に追加するため、手動で管理する必要はありません。ログやデバッグのためにツール結果を検査し、次のAPI呼び出しの前にリクエストパラメータを変更することができます。

ツール実行のデバッグ

ツールが例外をスローすると、Tool Runnerはそれをキャッチし、エラーをis_error: trueのツール結果としてClaudeに返します。デフォルトでは、完全なスタックトレースではなく、例外メッセージのみが含まれます。

完全なスタックトレースとデバッグ情報を表示するには、ANTHROPIC_LOG環境変数を設定します：

# View info-level logs including tool errors
export ANTHROPIC_LOG=info

# View debug-level logs for more verbose output
export ANTHROPIC_LOG=debug

有効にすると、SDKは完全な例外の詳細（Pythonのloggingモジュール、TypeScriptのコンソール、またはRubyのロガーを使用）をログに記録し、ツールが失敗したときの完全なスタックトレースを含みます。

ツールエラーの傍受

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

ツール応答メソッドを使用してツール結果を傍受し、Claudeに送信される前にエラーをチェックします：

ツール結果の変更

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

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

ストリーミング

ストリーミングを有効にして、イベントが到着したときに受け取ります。各反復はストリームオブジェクトを生成し、イベントを反復処理できます。

次のステップ

• ツール呼び出しループの手動制御については、ツール呼び出しの処理を参照してください。
• 複数のツールを同時に実行する場合は、並列ツール使用を参照してください。
• 完全なツール使用ワークフローについては、ツールの定義を参照してください。