# Claude Tool Runnerの上限設定とエラー傍受の設計

> Claude SDKのTool Runnerは、max_iterationsとis_errorの扱いを決めれば自前ループより短く安全に書ける。中小企業向けに採用基準と運用設計を整理する。

- Canonical: https://kuucorp.com/blog/claude-tool-runner-max-iterations-error-intercept-design-smb/
- Date: 2026-11-02
- Last modified: 2026-11-02
- Publisher: Kuu株式会社 (https://kuucorp.com)

---
社内向けエージェントのツール呼び出しループを自前で書き、結果の返し方を間違えて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つあります。

1. **ログは言語で異なる。** Pythonは未処理の例外をスタックトレース付きで標準の `logging` に出します。Go、Ruby、C#、PHPのSDKは失敗したツールをログに出さないため、ツール関数の内部で自分で記録します。
2. **エラーを途中で止めたいなら傍受する。** Pythonでは `generate_tool_call_response()` で結果を取り出し、`is_error` を確認してから送れます。TypeScriptも同様の方法を持ちます。
3. **SDKによっては傍受できない。** C#は結果の事前確認用フックがなく、`BetaToolError` を投げてエラー内容を制御します。Goは傍受が未対応で、ハンドラー内で捕捉して結果を返します。

エラー文は具体的に書くと復旧しやすくなります。「失敗」だけでなく、公式の例のように「レート制限を超過。60秒後に再試行」と次の行動まで含めます。

## 長い作業ではコンテキストをどう扱うのか

> 長時間のタスクでは、サーバー側コンパクションを `context_management` で有効にします。クライアント側の自動圧縮は非推奨です。

TypeScriptとRubyのランナーには、トークン使用量が閾値を超えると要約する機能があります。ただし両SDKとも、この方式は非推奨で、全SDKのランナーで使えるサーバー側コンパクション（`context_management` パラメータ）が推奨されています。`compact_before_next_turn()` による任意のタイミングの圧縮も用意されていますが、これと `context_management` の圧縮設定は併用しないよう公式に記載があります。

## 参考

- [Tool runner (SDK) - Claude Platform Docs](https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-runner)
- [Handle tool calls - Claude Platform Docs](https://platform.claude.com/docs/en/agents-and-tools/tool-use/handle-tool-calls)

## まとめ

Tool Runnerは、ツール実行ループの定型部分を任せられるベータ機能です。採用の判断は、書き込み前の承認や監査ログが要るかどうかで決まります。使うと決めたら、`max_iterations` を必ず指定し、言語ごとのログの差を確認し、エラーを止めるか返すかを先に決めます。

エージェントのループ設計やエラー処理の見直しは、[Kuu株式会社のAI導入伴走サービス](https://kuucorp.com/services/ai-ops/)でご相談いただけます。
