Erstellen Sie eine Responses-API-Kompatibilitätsschicht in einem AI API Gateway

Implementieren Sie /v1/responses nicht, indem Sie jede Anfrage in /v1/chat/completions übersetzen und hoffen, dass die Form nah genug ist. Dieser Adapter gibt möglicherweise Text zurück, kann jedoch stillschweigend die Teile verlieren, die den Entwicklern wichtig sind: Antwortelemente, serverseitiger Status, Toolaufrufe, Argumentationskontinuität, Stream-Lebenszyklusereignisse, Abbruchsemantik und Nutzungszuordnung auf Elementebene.

Das praktische Ziel ist eine Kompatibilitätsschicht, die die Responses API als umfangreicheres Protokoll behandelt. Behalten Sie die Chat Completions-Unterstützung für vorhandene Clients bei, erstellen Sie Responses jedoch als eigene Gateway-Oberfläche mit eigenem Statusmodell, Stream-Normalisierer, Tool-Call-Ledger, Fähigkeitsmatrix und Fallback-Regeln.

Was ist sachlich, was ist Politik und was ist Vorhersage?

Fakten: OpenAI beschreibt die Responses API als vereinheitlichende Funktionen, die zuvor auf Chat Completions und Assistants aufgeteilt waren, einschließlich der Unterstützung für Tools wie Websuche, Dateisuche und Computernutzung. Die API stellt Felder wie previous_response_id, Streaming, Toolauswahl und integrierte Tools bereit. Die SDK-Dokumentation zeigt, dass previous_response_id Konversationskontinuität gewährleisten kann, während frühere Anweisungen nicht automatisch übernommen werden und erneut gesendet werden müssen, wenn sie noch gelten sollten. Die Streaming-Referenz von OpenAI umfasst unterschiedliche Antwortlebenszyklen und Ausgabeereignisse und nicht nur Token-Deltas.

Empfehlungen: Ein Gateway sollte diese Semantik beibehalten, anstatt sie standardmäßig zu reduzieren. Es sollte Anfragen ablehnen oder explizit herabstufen, wenn ein Zielanbieter das erforderliche Verhalten nicht unterstützen kann.

Vorhersage: Mehr Agenten-Arbeitslasten hängen von der Antwortelementstruktur, den Tool-Ausführungsspuren und dem zustandsbehafteten Argumentationskontext ab. Gateways, die diese Konzepte jetzt modellieren, lassen sich einfacher erweitern als Gateways, die Antworten als kosmetischen Endpunkt behandeln.

Definieren Sie einen separaten Kompatibilitätsvertrag für Antworten

Der erste Implementierungsfehler besteht darin, anzunehmen, dass OpenAI-kompatibel ein universelles Anforderungs- und Antwortschema bedeutet. In der Praxis sollten /v1/chat/completions und /v1/responses separate Kompatibilitätsverträge sein.

Behalten Sie eine gemeinsame Authentifizierungs-, Abrechnungs-, Kontingent- und Routing-Ebene bei, aber trennen Sie die Protokollebene:

• Chat-Abschlussoberfläche: Nachrichten, Auswahlmöglichkeiten, Deltas, Toolaufrufe im Chat-Format, Legacy-Client-Verhalten.
• Antwortoberfläche: Eingabeelemente, Ausgabeelemente, Antwort-IDs, frühere Antwortreferenzen, umfangreichere Tool-Ereignisse, Lebenszyklus-Stream-Ereignisse, begründungsbezogene Felder und endgültiger Antwortstatus.

Diese Aufteilung ist für Konformitätstests wichtig. Ein Anbieteradapter, der Chat-Tests besteht, kann dennoch Antworttests nicht bestehen, da er previous_response_id, Elementreihenfolge, Ablehnungsstruktur, Metadaten gehosteter Tools oder Streaming-Ereignisnamen nicht beibehalten kann.

Ein Mindestkompatibilitätsvertrag sollte Folgendes beantworten:

• Welche Anforderungsfelder werden akzeptiert, abgelehnt, umgewandelt oder ignoriert?
• Welche Antwortelementtypen bleiben erhalten?
• Welche Werkzeugtypen werden pro Anbieter und Modell unterstützt?
• Kann der Anbieter den Konversationsstatus aufrechterhalten oder muss das Gateway ihn aufrechterhalten?
• Was passiert, wenn store=false angefordert wird?
• Welche Stream-Events sind garantiert?
• Wie werden Stornierung, Zeitüberschreitung und Teilnutzung erfasst?

Wenn Sie bereits über ein AI-API-Gateway verfügen, betrachten Sie die Responses-Unterstützung als Protokollerweiterung und nicht als Routenalias.

Verwenden Sie ein kanonisches Antwortelementmodell

Die Antwort-API gibt mehr als eine Assistentennachricht zurück. Es kann verschiedene Ausgabeelemente und Ereignisse darstellen. Ihr Gateway benötigt ein internes kanonisches Modell, bevor es einem Anbieter zugeordnet werden kann.

Ein praktisches internes Artikelschema kann wie folgt beginnen:

{
  „gateway_response_id“: „gw_resp_…“,
  „provider_response_id“: „resp_…“,
  „tenant_id“: „ten_123“,
  „key_id“: „key_456“,
  „model_alias“: „agent-default“,
  „Anbieter“: „openai“,
  „Artikel“: [
    {
      „item_id“: „item_1“,
      „Typ“: „Text“,
      „role“: „Assistent“,
      „content“: [{ „type“: „output_text“, „text“: „…“ }],
      „Status“: „abgeschlossen“
    },
    {
      „item_id“: „item_2“,
      „type“: „function_call“,
      „call_id“: „call_abc“,
      „name“: „lookup_order“,
      "arguments_json": "{\"order_id\":\"123\"}",
      „Status“: „abgeschlossen“
    }
  ],
  "Nutzung": {
    „input_tokens“: 0,
    „output_tokens“: 0,
    „reasoning_tokens“: null,
    "tool_units": []
  },
  „Status“: „abgeschlossen“

Beziehen Sie Artikeltypen ein, noch bevor sie jeder Anbieter produzieren kann. Zu den nützlichen Kategorien gehören:

• Textausgabe
• Ablehnungen
• Funktionsaufrufe
• Von der Anwendung übermittelte Funktionsausgaben
• Begründungszusammenfassungen oder begründungsbezogene Metadaten, sofern verfügbar
• Dateiverweise
• Websuche, Dateisuche, Computernutzung oder andere gehostete Tool-Ereignisse
• Endgültige Nutzungs- und Abrechnungsmetadaten

Es geht nicht darum, Benutzern ein proprietäres Schema zur Verfügung zu stellen. Der Sinn besteht darin, zu verhindern, dass das Gateway Informationen wegwirft, bevor es sie prüfen, abrechnen, streamen, wiedergeben oder umwandeln kann.

Erstellen Sie ein Gateway-eigenes Statusbuch

previous_response_id ist das Feld, das den Unterschied zwischen zustandslosem Chat-Proxy und Responses-Kompatibilität am deutlichsten verdeutlicht. Wenn ein Client auf eine frühere Antwort verweist, muss das Gateway wissen, was diese ID bedeutet, ob der Mandant sie verwenden darf und ob der Anbieter damit fortfahren kann.

Erstellen Sie ein Staatsbuch, das nach Mandant und Antwort-ID verschlüsselt ist:

{
  „gateway_response_id“: „gw_resp_789“,
  „provider_response_id“: „resp_provider_789“,
  „ previous_gateway_response_id“: „gw_resp_456“,
  „tenant_id“: „ten_123“,
  „user_id“: „user_999“,
  „key_id“: „key_456“,
  „model“: „gpt-…“,
  „Anbieter“: „openai“,
  „store_mode“: „provider|gateway|none“,
  „retention_policy“: „standard|zero_retention|custom_30d“,
  „instructions_hash“: „sha256:…“,
  „tool_policy_id“: „tools_readonly_v3“,
  "created_at": "...",
  „expires_at“: „…“,
  „deleted_at“: null

Wichtige Regel: Emulieren Sie previous_response_id nicht automatisch durch die Wiedergabe des gesamten Chat-Verlaufs, es sei denn, der Mandant hat dieses Aufbewahrungs- und Kostenverhalten ausdrücklich zugelassen. Die Wiederholung kann die Token-Kosten erhöhen, den Datenschutzstatus ändern und das Modellverhalten ändern. Es ist sicherer, einen eindeutigen Funktionsfehler zurückzugeben, als gespeicherte Konversationsinhalte stillschweigend zu senden, von denen die Anwendung nicht erwartet hat, dass Sie sie behalten oder wiederverwenden.

Zustandsbehandlungsmodi

• Anbieterstatus: Der Upstream-Anbieter speichert genügend Kontext und das Gateway ordnet Gateway-Antwort-IDs Anbieter-Antwort-IDs zu.
• Gateway-Status: Das Gateway speichert notwendige vorherige Elemente und rekonstruiert den Kontext, wenn dies zulässig ist.
• Kein Status: Die Anfrage verwendet store=false oder die Mandantenrichtlinie verbietet die Aufbewahrung. previous_response_id sollte abgelehnt werden, es sei denn, der Anbieter kann der Anfrage ohne Gateway-Aufbewahrung nachkommen und die Richtlinie erlaubt dies.

Denken Sie auch daran, dass frühere Anweisungen möglicherweise vom Kunden erneut gesendet werden müssen, wenn sie weiterhin gelten sollen. Das Gateway sollte keine versteckten Anweisungen zum Ausgleich erfinden, es sei denn, dieses Verhalten ist Teil einer expliziten Mandantenrichtlinie.

Werkzeuge vor dem Versand validieren

Responses macht die Tool-Nutzung zentraler. Eine Kompatibilitätsschicht sollte zwei große Kategorien abdecken:

• Anwendungstools: Vom Client bereitgestellte Funktionsdefinitionen, die außerhalb des Modellanbieters ausgeführt werden und deren Ausgaben an die API zurückgesendet werden.
• Gehostete Anbietertools: Websuche, Dateisuche, Computernutzung, Codeausführung, Erdung oder ähnliche Tools, die vom Anbieter oder der Gateway-gesteuerten Infrastruktur ausgeführt werden.

Validieren Sie beim Eingang die Tool-Schemata vor dem Routing:

• Ungültiges JSON-Schema frühzeitig ablehnen.
• Erzwingen Sie die maximale Schemagröße und Verschachtelungstiefe.
• Überprüfen Sie die Toolnamen auf Anbieterkompatibilität.
• Mandanten-, Schlüssel-, Benutzer- und Umgebungsbereiche anwenden.
• Genehmigungstore für Tools fordern, die Daten schreiben, Geld ausgeben, auf sensible Systeme zugreifen oder externe Konnektoren aufrufen.

Für den Aufruf von Anwendungsfunktionen ist eine stabile Aufruf-ID erforderlich. Das Modell gibt einen Funktionsaufruf mit call_id aus; Die Anwendung übermittelt die Tool-Ausgabe mit Verweis auf diese ID. Das Gateway zeichnet beides im selben Trace auf. Ohne diesen Join-Schlüssel werden Prüfprotokolle und Wiederholungsversuche mehrdeutig.

Reservieren Sie für gehostete Tools das Budget vor dem Versand und begleichen Sie die Kosten anschließend. Gehostete Tools können Gebühren außerhalb der normalen Token-Abrechnung hinzufügen. Verbinden Sie daher das Tool-Ledger mit der einheitlichen AI-API-Abrechnung, anstatt diese Kosten in einer generischen Modellaufrufsumme zu verbergen.

Streaming als Ereignisse normalisieren, nicht als Token-Text

Ein Chat-Proxy kann oft mit Weiterleitungstoken-Deltas davonkommen. Ein Responses-Gateway kann dies nicht. Der Stream hat eine Lebenszyklusbedeutung: Eine Antwort kann beginnen, Ausgabeelemente können beginnen und abgeschlossen werden, Text kann in Deltas eintreffen, Werkzeugaufrufe können inkrementell zusammengestellt werden, die Verwendung kann am Ende oder während des Streams eintreffen und die Antwort kann fehlschlagen oder abgebrochen werden.

Definieren Sie ein Gateway-Ereignisschema und ordnen Sie ihm dann jeden Anbieter-Stream zu:

event: Response_started
Daten: { „response_id“: „gw_resp_123“, „status“: „in_progress“ }

Ereignis: Output_item_startedDaten: { „item_id“: „item_1“, „type“: „text“ }

Ereignis: text_delta
Daten: { „item_id“: „item_1“, „delta“: „Hallo“ }

Ereignis: tool_call_delta
Daten: { "item_id": "item_2", "call_id": "call_abc", "arguments_delta": "{\"order" }

Ereignis: use_delta
Daten: { "output_tokens": 12 }

Veranstaltung: abgeschlossen
Daten: { "response_id": "gw_resp_123", "usage": { ... } 

Empfohlene normalisierte Ereignisse:

• response_started
• output_item_started
• output_item_completed
• text_delta
• refusal_delta
• tool_call_delta
• tool_result_received
• usage_delta
• abgeschlossen
• abgesagt
• fehlgeschlagen

Wenn der Client die Verbindung trennt, geben Sie den Abbruch im Upstream weiter, wenn der Anbieter dies unterstützt. Notieren Sie den Teilantwortstatus in beiden Fällen. Wenn der Anbieter die endgültige Nutzung später durch einen verzögerten Rückruf oder einen letzten Block zurückgibt, gleichen Sie das Hauptbuch ab. Bei der Streaming-Kompatibilität kommt es sowohl auf die Abrechnung und den Lebenszyklus als auch auf die Latenz an.

Erstellen Sie eine Anbieterfähigkeitsmatrix

Multi-Modell-Routing ist nur dann sinnvoll, wenn das Gateway versteht, was sicher weitergeleitet werden kann. Fügen Sie Ihrem Modellkatalog antwortspezifische Funktionen hinzu:

{
  „model_alias“: „agent-default“,
  "Routen": [
    {
      „Anbieter“: „openai“,
      "Modell": "...",
      „supports_responses“: wahr,
      „supports_ previous_response_id“: true,
      „supports_store_false“: wahr,
      „supports_builtin_web_search“: wahr,
      „supports_function_calling“: wahr,
      „supports_stream_lifecycle_events“: true,
      „supports_reasoning_context_continuity“: true,
      „max_tool_schema_bytes“: 65536
    },
    {
      „provider“: „provider_b“,
      "Modell": "...",
      „supports_responses“: false,
      „chat_adapter_available“: wahr,
      „loss_profile“: [„no_ previous_response_id“, „no_hosted_tools“, „flattened_stream“]
    }
  ]

Fallback sollte verlustbewusst sein. Wenn die Anfrage eine integrierte Websuche erfordert und der Fallback-Anbieter diese nicht durchführen kann, antworten Sie nicht stillschweigend ohne Suche. Wenn die Anforderung vom beibehaltenen Begründungskontext abhängt und die Fallback-Route ihn nicht beibehalten kann, wird ein Funktionsfehler oder eine Downgrade-Antwort zurückgegeben, für die sich der Client explizit entschieden hat.

Eine nützliche Anfrageoption ist:

{
  „model“: „agent-default“,
  "Eingabe": "...",
  "fallback_policy": {
    „allow_lossy“: falsch,
    „allowed_losses“: []
  }

Für weniger sensible Anwendungsfälle können Mieter bestimmte verlustbehaftete Downgrades zulassen:

{
  "fallback_policy": {
    „allow_lossy“: wahr,
    „allowed_losses“: [„flattened_stream“, „no_reasoning_summary“]
  }

Das Gateway sollte die Fallback-Entscheidung in jedem Fall protokollieren. Dies ermöglicht ein späteres Debuggen, wenn sich ein Agent nach einem Anbieterausfall oder einer Modellumleitung anders verhält.

Attributverwendung auf Antwort- und Elementebene

Antwortanrufe können mehr kosten als gleichwertige Chat-Abschlüsse, da sie die Ausführung von Tools, längeren Kontext, Argumentationstokens, Dateisuche, Websuche oder wiederholte Anweisungen umfassen können. Für ein AI-API-Nutzungsanalyse-Dashboard reicht eine einzelne aggregierte Token-Anzahl nicht aus.

Erfassen Sie die Nutzung auf zwei Ebenen:

• Antwortebene: Mandant, Schlüssel, Benutzer, Modell, Anbieter, Latenz, Endstatus, Eingabe-Tokens, Ausgabe-Tokens, Begründungs-Tokens, wo gemeldet wurden, Gesamtkosten und Fallback-Route.
• Artikel-/Werkzeugebene: Werkzeugname, Anruf-ID, gehostete Werkzeugeinheiten, Datei-IDs, Anzahl der Suchanfragen (sofern verfügbar), Werkzeuglatenz, Werkzeugkosten und Ergebnis der Genehmigungsrichtlinie.

Damit können Entwickler konkrete Fragen beantworten:

• Sind die Kosten aufgrund längerer Status, Begründungsaufwand, Toolaufrufe oder Fallback gestiegen?
• Welcher Mandant oder API-Schlüssel generiert Gebühren für gehostete Tools?
• Welche Antwort ist nach einem Toolaufruf, aber vor dem endgültigen Text fehlgeschlagen?
• Für welche abgebrochenen Streams fiel weiterhin Upstream-Nutzung an?

Behandeln Sie Nullaufbewahrung und Löschung als erstklassiges Verhalten

Der serverseitige Status ist hilfreich, ändert jedoch die Aufbewahrungspflichten des Gateways. Integrieren Sie die Richtlinie in die Protokollebene, anstatt sie als Protokollierungseinstellung zu behandeln.

Lösen Sie für jede Antwortanfrage Folgendes auf:

• Mandantenbindungsrichtlinie
• Store-Präferenz auf Anforderungsebene
• Kompatibilität der Anbieteraufbewahrung
• Ob die Gateway-Wiedergabe zulässig ist
• Ob Werkzeugeingaben und -ausgaben gespeichert werden dürfen
• Ablauf- und Löschverhalten für den Antwortstatus

Wenn die Aufbewahrung deaktiviert ist, speichert das Gateway möglicherweise immer noch minimale Betriebsmetadaten: Zeitstempel, IDs, Status, Token-Anzahl, Kosten und Richtlinienentscheidungen. Vermeiden Sie das Speichern von rohen Eingabeaufforderungen, vollständigen Tool-Ausgaben oder rekonstruierten Verlaufsdaten, es sei denn, die Richtlinien lassen dies zu.

Vor dem Start hinzuzufügende Konformitätsvorkehrungen

Verlassen Sie sich nicht auf manuelle Happy-Path-Tests. Fügen Sie Vorrichtungen hinzu, die das Protokollverhalten über direkte OpenAI-Routen, vom Anbieter angepasste Routen und Fallback-Szenarien überprüfen.

Mindesttestsatz

• Basisantwort: Textelement wird mit stabiler Antwort-ID und Verwendung zurückgegeben.
• Multi-Turn-Status: Referenzen der zweiten Anfrage previous_response_id; Gateway validiert Mandantenbesitz und Statusmodus.
• Wiederholte Anweisungen: Stellen Sie sicher, dass ausgelassene Anweisungen nicht stillschweigend vom Gateway erfunden werden.
• Funktionsaufruf-Roundtrip: Modell gibt Anruf-ID aus; Anwendung übermittelt Ausgabe; Die endgültige Antwort verbindet beide Datensätze.
• Richtlinie für gehostete Tools: Nicht autorisierte integrierte Tools werden vor dem Versand blockiert.
• Streaming-Reihenfolge: Antwortstart, Elementstart, Deltas, Elementabschluss, Nutzung und Abschluss werden in gültiger Reihenfolge ausgegeben.
• Stream-Abbruch: Die Trennung des Clients löst einen Upstream-Abbruch aus, sofern dies unterstützt wird, und zeichnet die teilweise Nutzung auf.
• Fallback-Ablehnung: Anbieter ohne erforderliche Antwortsemantik gibt Fähigkeitsfehler zurück.
• Opt-in für verlustbehaftetes Fallback: Anfrage mit zulässigen Verlusten erhält eine explizite Downgrade-Markierung.
• Modus ohne Aufbewahrung: Die Statuswiedergabe und die Beibehaltung von Eingabeaufforderungen auf der Gateway-Seite sind blockiert.

Empfohlene Rollout-Reihenfolge

1. Stellen Sie eine Beta-Route bereit. Fügen Sie /v1/responses hinzu, ohne das bestehende Chat-Verhalten zu ändern.
2. Implementieren Sie Passthrough zuerst für Anbieter mit nativer Responses-Unterstützung. Behalten Sie IDs, Elemente, Streams, Nutzung und Fehler bei.
3. Fügen Sie das Staatsbuch hinzu. Ordnen Sie Gateway-IDs Anbieter-IDs zu und erzwingen Sie die Eigentümerschaft des Mandanten.
4. Kanonische Elemente hinzufügen. Elementmetadaten speichern, die für die Prüfung, Abrechnung und Stream-Rekonstruktion benötigt werden.
5. Tool-Governance hinzufügen. Schemata validieren, Bereiche erzwingen und Tool-Aufruf-Joins aufzeichnen.
6. Streaming-Normalisierung hinzufügen. Anbieterspezifische Streams in Gateway-Lebenszyklusereignisse umwandeln.
7. Fähigkeitsbewusstes Routing hinzufügen. Standardmäßig nur sichere Fallbacks zulassen.
8. Analyse und Abrechnung hinzufügen. Token, Argumentation und Tool-Nutzung separat zuordnen.
9. Kompatibilitätshinweise veröffentlichen. Entwicklern mitteilen, welche Felder nativ, emuliert, nicht unterstützt oder verlustbehaftet sind.

Umsetzbare Schlussfolgerung

Eine Responses-API-Kompatibilitätsschicht sollte die Protokollbedeutung bewahren und nicht nur plausiblen Text zurückgeben. Bauen Sie es um fünf dauerhafte Objekte herum auf: ein kanonisches Antwortelementmodell, ein Konversationsstatus-Ledger, ein Tool-Call-Ledger, einen Streaming-Ereignisnormalisierer und eine Anbieterfähigkeitsmatrix.

Die sicherste Standardeinstellung ist strikte Kompatibilität: Wenn eine Route den erforderlichen Status, Tools, Argumentationskontext, Stream-Ereignisse oder Aufbewahrungsverhalten nicht beibehalten kann, wird ein eindeutiger Fähigkeitsfehler zurückgegeben. Fügen Sie ein verlustbehaftetes Opt-in-Fallback nur hinzu, wenn Entwickler wissen, was weggelassen wird. Dieser Ansatz fühlt sich möglicherweise weniger bequem an als die automatische Reduzierung, verhindert jedoch den schlimmsten Fehlermodus: eine Anwendung, die kompatibel zu sein scheint, dabei jedoch stillschweigend die Semantik verliert, die sie ursprünglich zur Verwendung der Responses-API veranlasst hat.

Verwandte Lektüre

• Streaming-Token-Abrechnung und Stornierungsverarbeitung