Function Callingとは？OpenAI、Gemini、ClaudeはJSONでAPIと外部ツールをどう呼び出すのか？

Function Callingは、モデルにAPIを直接実行させる機能ではなく、工具のSchemaに沿ったJSON形式の呼び出し要求を生成させる仕組みです。今週は、まず読み取り専用のAPIで3社の呼び出しを試し、その後に認証、権限、再試行を分離した適応層を作ってください。OpenAI、Google Gemini、Claude APIの共通フローは似ていますが、実装JSONは同一ではありません。

初めてツール型AIを作るバックエンド開発者は、モデルから実行器までの一連の流れを確認できます。多モデル対応を担当するプラットフォームエンジニアは、共通契約と各社アダプターの分け方を整理できます。安全管理を担う担当者は、Schemaでは解決できない認可と高リスク操作の境界を確認してください。

モデル層と実行層を分けると、Function Calling JSON APIの責任が明確になる

基本のデータフローは次のとおりです。

1. 開発者がツール名、説明、入力Schemaをモデルへ渡します。
2. ユーザーの依頼を受けたモデルが、利用するツールと引数をJSON形式で提案します。
3. アプリケーションが呼び出し名と引数を検証します。
4. 実行器が認証、API通信、タイムアウト、冪等性を管理します。
5. 実行結果をツール結果としてモデルへ返します。
6. モデルが結果を読み、ユーザー向けの最終回答を生成します。

Google Geminiの公式説明でも、モデルは関数名と引数を返し、関数コードの実行はアプリケーション側の責任とされています。Function Callingの本質は「判断の補助」と「構造化された要求の生成」であり、外部システムへのアクセス権そのものではありません。(ai.google.dev)

ここを混同すると、少なくとも3つの問題が起きます。第一に、モデルが生成した引数を検証せずにAPIへ渡し、想定外のユーザーやリソースを操作します。第二に、APIキーや長期トークンをプロンプトへ入れてしまい、ログや会話履歴から漏えいする危険があります。第三に、タイムアウトや再試行をモデル任せにして、書き込み処理が重複する可能性があります。

OpenAI、Google Gemini、Claude APIは共通概念でも呼び出し構造が異なる

3社とも、ツールの説明と入力Schemaをモデルへ提示し、モデルから呼び出し要求を受け、実行結果を返す流れを採用しています。しかし、アプリケーションが読むべきイベントの形は異なります。

OpenAIの構造

OpenAIでは、ツール定義に関数名、説明、JSON Schema形式のparameters、必要に応じてstrictを設定します。モデルの応答にはtool_callsが含まれ、各呼び出しにはid、name、argumentsが入ります。実行結果は対応するtool_call_idを使って返します。公式リファレンスは、生成された引数が常に有効なJSONやSchemaどおりになるとは限らないため、コード側で検証するよう説明しています。(platform.openai.com)

{
  "type": "function",
  "function": {
    "name": "get_weather",
    "description": "指定地域の天気を取得します",
    "parameters": {
      "type": "object",
      "properties": {
        "location": { "type": "string" }
      },
      "required": ["location"]
    },
    "strict": true
  }
}

Google Geminiの構造

Google Geminiでは、function declarationにname、description、parametersを設定します。現行ドキュメントでは、API入口によってfunctionCall、function_response、Interactions APIのfunction_callなど、確認するイベント名が異なります。複数ツールの並列呼び出しや、先の結果を次の呼び出しへ渡す連鎖的な処理にも対応しています。(ai.google.dev)

{
  "type": "function",
  "name": "get_weather",
  "description": "指定地域の天気を取得します",
  "parameters": {
    "type": "object",
    "properties": {
      "location": { "type": "string" }
    },
    "required": ["location"]
  }
}

ここで注意したいのは、GeminiのFunction Calling用Schemaと、最終回答を整形するStructured Output用Schemaを同じものとして扱わないことです。Googleの公式資料でも、Structured Outputは特定形式の回答生成、Function Callingは会話中に外部処理を依頼する用途として区別されています。(ai.google.dev)

Claude APIの構造

Claude APIは、特別なfunctionロールを中心に設計するのではなく、assistantメッセージ内のtool_useブロックと、userメッセージ内のtool_resultブロックで状態を表現します。tool_useにはid、name、inputが含まれ、実行結果はtool_use_idで対応付けます。Anthropicの公式ドキュメントでは、tool_useの直後に対応するtool_resultを置く必要があり、履歴の順序が崩れるとエラーになる点も説明されています。(docs.anthropic.com)

{
  "type": "tool_use",
  "id": "toolu_example",
  "name": "get_weather",
  "input": {
    "location": "東京"
  }
}

つまり、3社のJSONをそのまま一つの「共通リクエスト形式」にまとめるのは危険です。共通化すべきなのは、ツール名、入力、実行結果、エラー、認可状態といった内部イベントであり、各社SDKへ渡す最終JSONではありません。

適応層と実行器を分けると、多モデル運用の故障点を減らせる

多モデル構成では、次の内部イベントを最低限持たせると管理しやすくなります。

• provider
• model
• tool_name
• call_id
• arguments
• schema_version
• approval_required
• execution_status
• result
• error_code
• raw_response

適応層は、OpenAIのtool_calls、GeminiのfunctionCall、Claude APIのtool_useをこの内部イベントへ変換します。反対方向では、内部イベントから各社固有のtool result形式へ戻します。原始レスポンスも保存してください。正規化だけを保存すると、将来の障害調査で停止理由、追加フィールド、モデル固有の警告を失うことがあります。

実行器はモデルとは別のプロセス、または少なくとも別モジュールにします。担当範囲は次のとおりです。

• 秘密情報の取得と短期トークンへの交換
• 接続先の許可リスト確認
• タイムアウトとサーキットブレーカー
• 書き込み操作の冪等キー
• レスポンスサイズの上限
• 外部APIエラーの分類
• 監査ログへの記録

JSON Schemaは、型や必須項目を検証するための契約です。Schema自体がユーザーの同意、リソース所有権、業務上の上限額、ネットワーク接続先の安全性を保証するわけではありません。JSON Schemaはデータの構造と制約を表し、異なるシステム間の相互運用を助ける仕組みです。(json-schema.org)

注意：strict: trueやSchema検証を有効にしても、値の意味まで安全になるわけではありません。たとえばuser_idが文字列として正しくても、ログイン中の利用者がそのIDを操作できるかは、別の認可処理で確認します。

役割別に見る、実装前の判断分岐

次の条件で、直接SDKを使うか、内部適応層を作るかを決めてください。

• 単一モデルで、読み取り専用ツールが少ない場合
  公式SDKを直接使います。最初から全社共通仕様を作るより、呼び出し履歴と失敗条件を先に把握できます。

• OpenAI、Google Gemini、Claude APIを同じ業務ツールで切り替える場合
  内部契約と適応層を追加します。モデルごとに分岐するコードを業務ロジックへ混ぜないでください。

• 同じツールを複数のエージェントで共有する場合
  Schemaにバージョンを付けます。必須項目を変更すると、過去のモデル設定や保存済み履歴が壊れるためです。

• メール送信、課金、削除、デプロイなどの書き込み操作がある場合
  承認状態を内部イベントに持たせます。モデルが呼び出しを提案しても、ユーザー確認や業務ルールが通るまで実行しません。

• macOSコマンド、Xcode、Apple自動化が必要な場合
  API実行器とMac実行ノードを分けて評価します。短い検証ならローカル環境、継続的なジョブやチーム共有なら、遠隔Mac実行ノードの選び方を確認してください。

FAQ：実装時に迷いやすい境界

Function Callingを使うと、モデルがAPIを直接実行するのですか？

いいえ。モデルが行うのは、利用するツール名と引数を構造化して提案することです。実際のAPI呼び出し、認証、タイムアウト、権限確認、結果の整形は、あなたのアプリケーション側の実行器が担当します。モデルに長期利用の認証情報を渡してはいけません。

OpenAI、Gemini、Claudeのツール呼び出しJSONは同じ形式ですか？

共通する考え方はありますが、JSONの入れ子、呼び出しID、結果を返すメッセージ、停止理由、並列呼び出しの扱いは同じではありません。OpenAIはtool_calls、GeminiはfunctionCallやtoolResponse、Claude APIはtool_useとtool_resultを使うため、共通アダプターが必要です。

Function CallingにJSON Schemaが必要なのはなぜですか？

Schemaがあると、ツールの引数名、型、必須項目、列挙値をモデルと実行器の間で共有できます。ただし、Schemaに適合したJSONでも、対象ユーザーに権限があるか、対象リソースを操作してよいかまでは保証しません。入力検証と認可は別に実装します。

モデルが誤った引数を生成した場合はどう処理しますか？

まずJSONとして解析し、Schema検証、業務ルール検証、認可検証の順に判定します。失敗した場合はAPIを実行せず、エラー内容を安全なツール結果としてモデルへ返すか、ユーザーへ確認を求めます。無条件の再試行は、書き込み処理の重複を招くため避けます。

多モデルのプロジェクトで同じツールを再利用するにはどうしますか？

内部のツール契約を先に定義し、各社の名称、引数、呼び出しID、結果形式をアダプターで変換します。元のレスポンスも保存すると、特定モデルの停止理由や追加フィールドを失わずに済みます。共通化するのは業務契約であり、各社のリクエストJSONそのものではありません。

5段階の実装手順と検証項目

1. 読み取り専用の業務例を一つ選ぶ

天気、在庫照会、ビルド情報取得など、データを変更しない処理から始めます。最初から削除や決済を含めると、モデルの誤判断と実行器の欠陥を切り分けにくくなります。

2. ツール契約を定義する

ツール名、目的、必須引数、型、許容値、エラーコードを決めます。descriptionには、使う条件と使わない条件も書いてください。Schemaの説明文はモデルの選択に影響しますが、最終的な安全判定ではありません。(json-schema.org)

3. 各社の最小呼び出しを個別に実装する

OpenAI、Google Gemini、Claude APIで同じ業務例を使います。ただし、実際のリクエストと応答は各社の公式形式で記録してください。三社共通の架空JSONを作るのではなく、プラットフォーム別の変換処理を検証します。

4. 適応層で内部イベントへ変換する

モデル名、呼び出しID、ツール名、引数、Schemaバージョン、承認要否を一つの内部イベントにまとめます。変換前のレスポンスを保存し、障害時に原形式へ戻れるようにします。

5. 実行器で検証と認可を行う

JSON解析の後にSchema検証を実施します。その後、ユーザー権限、対象リソース、操作種別、ネットワーク許可、レート制限を確認し、すべて通過した場合だけAPIを呼び出します。

6. 失敗するテストを先に用意する

次の項目をチェックしてください。

• [ ] 必須引数が欠けた場合にAPIを実行しない
• [ ] 型が違う引数を拒否する
• [ ] 未登録のツール名を拒否する
• [ ] 同一のcall IDを再処理しない
• [ ] 並列呼び出しの一部失敗を記録する
• [ ] タイムアウト後に安全な状態へ戻す
• [ ] ツール結果が履歴から消えた場合に検出する
• [ ] Claude APIでtool_use直後のtool_result順序を守る
• [ ] 最終回答がツール結果と矛盾しないか確認する
• [ ] SDK、モデル、API入口、実行日をログへ残す

AIエージェントの設計全体を見直す場合は、AIエージェントのフレームワーク比較や、Claude Codeのスキル設計も、ツールの責任分界を考える材料になります。

まとめ：勝者を選ぶより、実行責任を分離する

Function Calling JSON APIで最も重要なのは、モデルのブランド比較ではありません。モデル層はSchemaに沿った呼び出し要求を作り、適応層は形式差を吸収し、実行器は認証と通信を担当し、安全管理側は承認と認可を行い、テスト側は完全な往復を検証します。

現在の構成が単一サーバー上のスクリプトだけなら、環境依存、macOS権限、Xcodeの導入状態、ジョブの同時実行管理が隠れた負担になります。クラウド上の一般的なLinux実行環境ではApple固有の自動化をそのまま再現できず、ローカルMacだけに依存すると、チーム共有や長時間ジョブの管理が難しくなります。

MacOS、Xcode、Apple自動化を含むツールを一時的に検証するなら、専用の実行環境を購入する前に、HashvpsのMacリソースをタスク期間と権限要件に合わせて評価する方法があります。短期の互換性確認やエージェントの実行ノード検証では、必要な期間だけ使える構成のほうが、固定環境を抱えるより判断しやすいケースがあります。