【ITニュース解説】JSON vs Programmatic Tool Calling with Claude

AIモデルであるClaudeを使ってアプリケーションを開発する際、外部のツール（データベースへの問い合わせやメッセージ送信など）と連携させることは、AIに実用的な機能を持たせるための最初の重要なステップだ。しかし、これらのツールをどのように組み込むかによって、アプリケーションの性能、運用コスト、そして開発の複雑さが大きく変わってくる。ここでは、Claude APIが提供する主な3つのツール連携方法について、システムエンジニアを目指す初心者が理解しやすいように解説する。

まず、共通して理解すべき問題点として「ラウンドトリップ」という概念がある。従来のツール呼び出しの仕組みでは、AIモデルが何か外部ツールを使って作業をしたいと判断すると、まずそのツールの使用をアプリケーションのサーバーに「リクエスト」する。サーバーはそのリクエストを受けてツールを実行し、結果をモデルに「返信」する。モデルはその結果を基に次の行動を考え、必要であれば再びツール使用をリクエストするという一連の「対話のループ」が発生する。この、モデルとサーバーが互いに情報をやり取りする一往復の通信を「ラウンドトリップ」と呼ぶ。問題は、ツール呼び出しが複数回必要な場合、このラウンドトリップがツールを使うたびに発生することだ。例えば、20人分の経費をチェックするのに20回のツール呼び出しが必要だとすれば、20回のラウンドトリップが発生し、そのたびにAIモデルの推論時間と通信時間が発生するため、処理が遅くなり、コストも増大する。さらに、これらの中間結果はすべてモデルの「コンテキスト」（AIが認識している情報）に積み重ねられ、モデルが処理すべき情報量（トークン数）を増加させる。トークンとはAIが情報を処理する際の最小単位であり、トークン数が増えれば増えるほど、処理にかかる時間とコストも増えることになる。

Claude APIにおけるツール連携の最初のアプローチは、「JSONスキーマと手動ループ」を使う方法だ。これは、各ツールの機能や必要な入力情報をJSONスキーマという形式で厳密に定義し、APIにリクエストを送信する。AIモデルがツールを使いたいと返答してきたら、その返答の内容（tool_useブロックと呼ばれる）を開発者自身が解析し、対応するツールを実行し、その結果を再度モデルに送り返すという一連の処理を、プログラムコード内で「手動のループ」を組んで行う。具体的には、while Trueのような無限ループを使って、モデルからの応答を待ち、必要に応じてツールを実行し、結果をモデルにフィードバックするというサイクルを繰り返す。この方法の最大の利点は、すべてのステップを完全にコントロールできる点だ。モデルとツールの間に独自のログ記録、結果のフィルタリング、あるいは特定のビジネスロジックを挿入するなど、非常に柔軟な処理が可能である。しかし、その反面、ツールの定義、モデルからの応答解析、ツール実行、結果のフィードバック、そしてエラー処理まで、すべての処理を開発者が自分でコードに記述しなければならないため、多くの「ボイラープレートコード」（定型的な繰り返しコード）が必要となり、開発が複雑になりがちだ。また、ツールの結果がたとえ中間的なものであっても、毎回モデルを経由してやり取りされるため、ツールの呼び出し回数が多いほど、その回数分のAIモデルによる推論処理（インファレンスパス）が発生し、処理速度とコストに影響が出る。

次に紹介するアプローチは、「Tool Runner SDK」を利用する方法だ。これはAnthropicが公式に提供しているSDK（ソフトウェア開発キット）に含まれるヘルパー機能で、先ほどの手動ループでの課題を解決するために作られた。Tool Runnerは、ツールの定義から実行、会話の状態管理、そして入力値の型検証まで、アジェンティックな（AIが自律的に判断して行動するような）ループ処理を自動化してくれる。Pythonであれば、@beta_toolというデコレータを使うことで、関数の型ヒントや説明文から自動的にJSONスキーマを生成できるため、ツールの定義が非常に簡潔になる。TypeScriptでは、Zodというスキーマ定義ライブラリと連携するbetaZodToolを使うことで、厳密な型検証が行える。Tool Runnerを使うことで、開発者は手動でwhile Trueループを記述したり、tool_useブロックを解析したりする必要がなくなり、よりシンプルで読みやすいコードでツール連携を実装できるようになる。この方法の利点は、コード量が減り、型安全性が高まり、エラー処理も組み込まれているため、開発者の負担が大幅に軽減される「開発体験（DX）」の向上にある。しかし、注意すべきは、その内部的な実行モデルは手動ループと同じであるという点だ。つまり、各ツール呼び出しのたびに、やはりモデルとのラウンドトリップが発生するため、パフォーマンス面での劇的な改善は期待できない。主に開発効率とコードの安全性を向上させるためのアプローチと言える。

そして、最も革新的なアプローチが「プログラム的なツール呼び出し」である。この方法は、従来の実行モデルを根本的に覆すものだ。AIモデルであるClaudeは、ツールの使用をリクエストする代わりに、あなたのサーバー上にある「コード実行コンテナ」内で直接ツールを呼び出すPythonコードを生成する。このコンテナは、あたかもClaudeが一時的に利用できる小さな仮想コンピュータのようなものだと考えると良い。AIモデルが生成したコードは、このコンテナ内で複数のツールを連続して呼び出したり、並列に実行したりできる。最も重要なのは、ツールが実行された際の中間結果が、AIモデルのコンテキストに毎回送り返されるのではなく、このコンテナ内に留まる点だ。Claudeは、コンテナ内で必要なすべてのツールを実行し、結果を処理・フィルタリング・集約した後、その「最終的な要約」だけをモデルのコンテキストに送信する。これにより、例えば3つのツール呼び出しが必要な場合でも、従来の3回のモデルラウンドトリップではなく、1回の推論でコードが生成され、その後3つのツール呼び出しはコンテナ内で実行されるため、AIモデルとのやり取りは大幅に削減される。その結果、消費するトークン数と応答までのレイテンシ（遅延時間）が劇的に減少する。このアプローチを利用するには、APIリクエストにcode_executionという特別なツールを含め、呼び出したい各ツールにallowed_callers: ["code_execution_20260120"]という設定を追加して、コード実行コンテナからの呼び出しを許可する必要がある。利点は非常に大きく、データ集計や複雑な調査タスクのように、多数のツール呼び出しが必要なシナリオで、パフォーマンスとコストの大幅な改善が見込める。欠点としては、このcode_executionツールがまだベータ版であること、コード実行コンテナには最大約5分という寿命があること、そして一部のクラウドプラットフォーム（Amazon BedrockやGoogle Cloud）ではまだ利用できない点が挙げられる。また、allowed_callersの設定は、あくまでClaudeに対する「推奨」であり、厳密なセキュリティ境界ではない点も理解しておく必要がある。

これらの3つのアプローチをどのように使い分けるべきだろうか。 「JSONスキーマと手動ループ」は、各ツール呼び出しの間に人間による確認が必要なワークフロー、詳細なログを記録したい場合、あるいは複雑な条件分岐のビジネスロジックを挟み込みたい場合など、きめ細やかな制御が必須な場合に適している。また、Tool Runner SDKやプログラム的なツール呼び出しが利用できない環境（特定のクラウドプロバイダーなど）での唯一の選択肢となることもあるだろう。 ほとんどの一般的なユースケースでは、「Tool Runner SDK」が推奨される。コードがクリーンになり、型検証が自動化されるため、開発効率が高まる。内部的には手動ループと同じ挙動をするため、ある程度の制御を保ちつつ、開発のしやすさを優先する際に良い選択肢だ。 そして、「プログラム的なツール呼び出し」は、1リクエストあたりのツール呼び出し回数が非常に多い場合や、中間結果のデータ量が大きい場合に最も威力を発揮する。例えば、複数のデータソースから情報を集めてフィルタリングし、要約だけを抽出するようなタスクだ。Claudeがデータを探索・整理した後に最終的な結論を出すような、複雑な調査タスクにおいても最も効率的なアプローチとなる。

これらのアプローチは、一つのプロジェクト内で組み合わせて使うことも可能だ。あるツールは直接呼び出し（direct）で手動ループやTool Runner経由で使い、別のツールはコード実行コンテナから呼び出すように設定できる。プロジェクトの初期段階では、開発が容易なTool Runnerから始め、もしトークン消費量やレイテンシが問題となるようであれば、プログラム的なツール呼び出しへの移行を検討するのが賢明な進め方と言えるだろう。それぞれの方法が持つ特性を理解し、プロジェクトの要件に合わせて最適なアプローチを選択することが、効率的で高性能なClaudeアプリケーションを構築する鍵となる。