社内向けエージェントのツール呼び出しループを自前で書き、結果の返し方を間違えて400エラーを出した。あるいはツールが失敗し続けて、ループが止まらなかった。小さなチームほど、この種の「ループ周りの事故」に時間を取られます。SDKのTool Runnerは、その実装を肩代わりする仕組みです。ただし任せきりにすると、上限とエラーの扱いが見えなくなります。
Tool Runnerは何を肩代わりしてくれるのか
Tool Runnerは、ツール実行・結果の返送・会話状態の管理を自動化するSDKの機能です。2026年11月時点ではベータ版です。
公式ドキュメントによると、Tool Runnerは次の4点を自動で行います。
- Claudeがツールを呼んだときに、そのツールを実行する
- リクエストとレスポンスの往復を処理する
- 会話の状態を管理する
- 型の安全性と入力の検証を提供する
Python、TypeScript、C#、Go、Java、PHP、Ruby の各SDKで利用できます。ツールはPythonなら @beta_tool デコレータ、TypeScriptなら betaZodTool() で定義します。関数の型ヒントやdocstringからJSONスキーマが導かれるため、スキーマの手書きと実装のズレを減らせます。
手動ループで起きがちな形式ミスも減ります。tool_result ブロックは対応する tool_use の直後に置き、ユーザーメッセージの先頭側に並べる必要があります。この規則を自前で守る手間が、ランナー経由では不要になります。
自前ループとTool Runnerはどう使い分けるのか
承認フロー・独自ログ・条件付き実行が要るなら手動ループ、それ以外はTool Runnerが公式の推奨です。迷えばランナーから始めます。
公式ドキュメントは、人間による承認、独自のログ、条件付きの実行が必要な場合に手動ループを使うよう案内しています。中小企業の実務では、次の基準が使えます。
| 状況 | 選ぶ方式 |
|---|---|
| 読み取り系ツールだけの社内Q&A | Tool Runner |
| 書き込みや送信の前に担当者の承認が要る | 手動ループ |
| 呼び出しごとに監査ログを残す義務がある | 手動ループ、またはランナーのループ介入 |
| まず試作して効果を測りたい | Tool Runner |
承認が要る処理を後から足す場合も、全面的な書き直しは不要です。ランナーはループの途中で制御を引き取る手段を持っています。ただし引き取った反復では、ランナーはその回のアシスタントメッセージとツール結果を履歴に追加しません。履歴を有効な状態に保つ責任は、書き手に移ります。
max_iterationsは何回に設定すべきか
ループはツール呼び出しが無くなるまで回ります。上限を決めるのは自分で、
max_iterationsを指定しないと歯止めがありません。
ランナーは、Claudeがツール呼び出しを含まない応答を返すまで、または max_iterations に達するまでループします。上限は設定した場合にだけ効きます。公式の例では10が使われています。
目安は、業務で想定される最大のツール呼び出し回数に、再試行の余地を足した値です。たとえば「在庫照会、価格照会、在庫引当」で3回なら、上限は6〜10回程度が出発点になります。上限に達した事実は必ずログへ記録します。上限到達が日常的に起きるなら、ツール定義かプロンプトに問題があります。
ループを引き取る場合も、max_iterations の指定が公式に求められています。引き取った側がループの終了条件を壊すと、ランナーが自動で抜けられなくなるためです。
ツールが失敗したらどうなり、どう傍受するのか
ツールが例外を投げると、ランナーは
is_error: trueの結果としてClaudeへ返します。スタックトレースは含まれません。
ランナーは例外を捕捉し、例外のメッセージ(Pythonでは型とメッセージ)を is_error: true の tool_result としてClaudeに返します。Claudeはその内容を踏まえて、別の方法を試すか、利用者へ状況を説明します。
運用で押さえる点は3つあります。
- ログは言語で異なる。 Pythonは未処理の例外をスタックトレース付きで標準の
loggingに出します。Go、Ruby、C#、PHPのSDKは失敗したツールをログに出さないため、ツール関数の内部で自分で記録します。 - エラーを途中で止めたいなら傍受する。 Pythonでは
generate_tool_call_response()で結果を取り出し、is_errorを確認してから送れます。TypeScriptも同様の方法を持ちます。 - SDKによっては傍受できない。 C#は結果の事前確認用フックがなく、
BetaToolErrorを投げてエラー内容を制御します。Goは傍受が未対応で、ハンドラー内で捕捉して結果を返します。
エラー文は具体的に書くと復旧しやすくなります。「失敗」だけでなく、公式の例のように「レート制限を超過。60秒後に再試行」と次の行動まで含めます。
長い作業ではコンテキストをどう扱うのか
長時間のタスクでは、サーバー側コンパクションを
context_managementで有効にします。クライアント側の自動圧縮は非推奨です。
TypeScriptとRubyのランナーには、トークン使用量が閾値を超えると要約する機能があります。ただし両SDKとも、この方式は非推奨で、全SDKのランナーで使えるサーバー側コンパクション(context_management パラメータ)が推奨されています。compact_before_next_turn() による任意のタイミングの圧縮も用意されていますが、これと context_management の圧縮設定は併用しないよう公式に記載があります。
参考
まとめ
Tool Runnerは、ツール実行ループの定型部分を任せられるベータ機能です。採用の判断は、書き込み前の承認や監査ログが要るかどうかで決まります。使うと決めたら、max_iterations を必ず指定し、言語ごとのログの差を確認し、エラーを止めるか返すかを先に決めます。
エージェントのループ設計やエラー処理の見直しは、Kuu株式会社のAI導入伴走サービスでご相談いただけます。
