AI API ゲートウェイでの応答 API 互換性レイヤーの構築

入力時に、ルーティング前にツール スキーマを検証します。

• 無効な JSON スキーマを早期に拒否します。
• 最大スキーマ サイズとネストの深さを強制します。
• ツール名でプロバイダーの互換性を確認してください。
• テナント、キー、ユーザー、環境のスコープを適用します。
• データの書き込み、金銭の支出、機密システムへのアクセス、外部コネクタの呼び出しを行うツールには承認ゲートを義務付ける

アプリケーション関数の呼び出しには、安定した呼び出し ID が必要です。モデルは、call_id を使用して関数呼び出しを発行します。アプリケーションは、その ID を参照するツール出力を送信します。ゲートウェイは両方を同じトレースに記録します。この結合キーがないと、監査ログと再試行があいまいになります。

ホスト型ツールの場合は、発送前に予算を予約し、後でコストを決済します。ホストされたツールでは、通常のトークン アカウンティング以外の料金が追加される場合があるため、これらのコストを一般的なモデル呼び出しの合計内に隠すのではなく、ツール台帳を統合 AI API 請求に接続します。

ストリーミングをトークン テキストではなくイベントとして正規化する

チャット プロキシは、多くの場合、トークン デルタの転送を回避できます。応答ゲートウェイではできません。ストリームにはライフサイクルの意味があります。つまり、応答が開始され、出力項目が開始および完了し、テキストがデルタで到着し、ツール呼び出しが増分的に組み立てられ、使用状況がストリームの最後または途中で到着し、応答が失敗またはキャンセルされる可能性があります。

ゲートウェイ イベント スキーマを定義し、各プロバイダー ストリームをそれにマッピングします。

イベント:response_started
データ: { "response_id": "gw_resp_123", "ステータス": "進行中" }

イベント：output_item_startedデータ: { "item_id": "item_1", "type": "text" }

イベント: テキストデルタ
データ: { "item_id": "item_1", "delta": "Hello" }

イベント:tool_call_delta
データ: { "item_id": "item_2", "call_id": "call_abc", "arguments_delta": "{\"order" }

イベント: 使用状況デルタ
データ: { "出力トークン": 12 }

イベント：完了しました
データ: { "response_id": "gw_resp_123", "usage": { ... } }

推奨される正規化イベント:

• response_started
• output_item_started
• output_item_completed
• テキストデルタ
• 拒否デルタ
• tool_call_delta
• tool_result_received
• usage_delta
• 完了
• キャンセルされました
• 失敗

クライアントが切断すると、プロバイダーがサポートしている場合はキャンセルを上流に伝播します。いずれかの方法で部分応答状態を記録します。プロバイダーが後で遅延コールバックまたは最終チャンクを通じて最終使用量を返した場合は、台帳を調整します。ストリーミングの互換性は、レイテンシと同じくらいアカウンティングとライフサイクルにも関係します。

プロバイダー機能マトリックスの作成

マルチモデル ルーティングは、何が安全にルーティングできるかをゲートウェイが理解している場合にのみ役立ちます。 Responses 固有の機能をモデル カタログに追加します。

{
  "model_alias": "エージェントのデフォルト",
  「ルート」: [
    {
      "プロバイダー": "openai",
      "モデル": "...",
      "supports_responses": true、
      "supports_previous_response_id": true、
      "supports_store_false": true、
      "supports_builtin_web_search": true、
      "supports_function_calling": true、
      "supports_stream_lifecycle_events": true、
      "supports_reasoning_context_continuity": true、
      "max_tool_schema_bytes": 65536
    }、
    {
      "プロバイダー": "プロバイダー_b",
      "モデル": "...",
      "supports_responses": false、
      "chat_adapter_available": true、
      "loss_profile": ["no_previous_response_id"、"no_hosted_tools"、" flattened_stream"]
    }
  】
}

フォールバックは損失を認識する必要があります。リクエストに組み込みの Web 検索が必要で、フォールバック プロバイダーがそれを実行できない場合は、検索せずに黙って応答しないでください。リクエストが保持された推論コンテキストに依存しており、フォールバック ルートがそれを保持できない場合は、クライアントが明示的に選択した機能エラーまたはダウングレード応答を返します。

便利なリクエスト オプションは次のとおりです。

{
  "モデル": "エージェントのデフォルト",
  "入力": "...",
  "フォールバック_ポリシー": {
    "allow_lossy": false、
    "許可された損失": []
  }
}

機密性の低いユースケースの場合、テナントは特定の損失を伴うダウングレードを許可できます。

{
  "フォールバック_ポリシー": {
    "allow_lossy": true、
    "allowed_losses": [" flattened_stream "、 "no_reasoning_summary"]
  }
}

ゲートウェイは、いずれかの方法でフォールバック決定をログに記録する必要があります。これにより、プロバイダーの停止やモデルの再ルーティング後にエージェントの動作が異なる場合に、後からデバッグが可能になります。

レスポンスおよびアイテムレベルでの属性の使用

応答呼び出しには、ツールの実行、長いコンテキスト、推論トークン、ファイル検索、Web 検索、または繰り返しの指示が含まれる可能性があるため、同等のチャット完了よりもコストがかかる可能性があります。単一の集約トークン数では、AI API 使用状況分析ダッシュボードには十分ではありません。

2 つのレベルで使用状況を記録します。

• 応答レベル: テナント、キー、ユーザー、モデル、プロバイダー、レイテンシ、最終ステータス、入力トークン、出力トークン、報告された推論トークン、総コスト、フォールバック ルート
• アイテム/ツール レベル: ツール名、コール ID、ホストされているツール ユニット、ファイル ID、検索クエリ数 (利用可能な場合)、ツールの遅延、ツールのコスト、承認ポリシーの結果

これにより、開発者は具体的な質問に答えることができます。

• 長い状態、推論の労力、ツールの呼び出し、またはフォールバックによりコストは増加しましたか?
• ホストされたツールの料金を生成しているテナントまたは API キーはどれですか?
• ツール呼び出し後、最終テキストの前に失敗した応答はどれですか?
• キャンセルされたストリームのうち、依然としてアップストリームの使用量が発生しているものはどれですか?

ゼロ保持と削除を第一級の動作として処理する

サーバー側の状態は役に立ちますが、ゲートウェイの保持義務が変わります。ポリシーをログ設定として扱うのではなく、プロトコル層にポリシーを組み込みます。

すべての応答リクエストについて、以下を解決します。

• テナント保持ポリシー
• リクエストレベルのstore設定
• プロバイダー保持の互換性
• ゲートウェイのリプレイが許可されるかどうか
• ツールの入力と出力を保存できるかどうか
• 応答状態の有効期限と削除の動作

保持が無効になっている場合でも、ゲートウェイはタイムスタンプ、ID、ステータス、トークン数、コスト、ポリシー決定などの最小限の運用メタデータを保持することがあります。ポリシーで許可されている場合を除き、生のプロンプト、完全なツール出力、または再構築された履歴を保存しないでください。

発売前に追加する適合フィクスチャ

ハッピーパスの手動テストに依存しないでください。 OpenAI の直接ルート、プロバイダーに適応したルート、フォールバック シナリオにわたるプロトコルの動作を検証するフィクスチャを追加します。

最小テストセット

• 基本的な応答: テキスト項目が安定した応答 ID と使用法とともに返されます。
• マルチターン状態: 2 番目のリクエストは previous_response_id を参照します。ゲートウェイはテナントの所有権と状態モードを検証します。
• 繰り返しの命令: 省略された命令がゲートウェイによって暗黙的に作成されていないことを確認します。
• 関数呼び出しの往復: モデルは呼び出し ID を発行します。アプリケーションは出力を送信します。最終応答は両方のレコードを結合します。
• ホストされたツールのポリシー: 未承認の組み込みツールはディスパッチ前にブロックされます。
• ストリーミング順序: レスポンスの開始、アイテムの開始、デルタ、アイテムの完了、使用状況、完了が有効な順序で出力されます。
• ストリーム キャンセル: クライアントの切断により、サポートされている場合はアップストリーム キャンセルがトリガーされ、部分的な使用状況が記録されます。
• フォールバック拒否: 必要な応答セマンティクスのないプロバイダーは機能エラーを返します。
• 非可逆フォールバック オプトイン: 損失が許可されたリクエストは、明示的なダウングレード マーカーを受け取ります。
• ゼロ保持モード: 状態の再生とゲートウェイ側のプロンプト保持はブロックされます。

推奨されるロールアウト順序

実行可能な結論

Responses API 互換性レイヤーは、単にもっともらしいテキストを返すだけでなく、プロトコルの意味を保持する必要があります。正規応答アイテム モデル、会話状態台帳、ツール呼び出し台帳、ストリーミング イベント ノーマライザー、プロバイダー機能マトリックスの 5 つの耐久性のあるオブジェクトを中心に構築します。

最も安全なデフォルトは厳密な互換性です。ルートが必要な状態、ツール、推論コンテキスト、ストリーム イベント、または保持動作を保持できない場合は、明確な機能エラーを返します。開発者が何がドロップされるかを理解している場合にのみ、オプトイン非可逆フォールバックを追加します。このアプローチは、自動フラット化よりも利便性が劣るように感じられるかもしれませんが、最悪の障害モード、つまり互換性があるように見えながら、そもそも Responses API を使用するためのセマンティクスを失うアプリケーションを防ぐことができます。

関連資料

• ストリーミング トークン アカウンティングとキャンセル処理