Bygg et Responses API-kompatibilitetslag i en AI API-gateway

Ikke implementer /v1/responses ved å oversette hver forespørsel til /v1/chat/completions og håpe at formen er nær nok. Denne adapteren kan returnere tekst, men den kan i det stille miste delene utviklere bryr seg om: svarelementer, serversidestatus, verktøykall, resonneringskontinuitet, strømmelivssyklushendelser, kanselleringssemantikk og bruksattribusjon på varenivå.

Det praktiske målet er et kompatibilitetslag som behandler Responses API som en rikere protokoll. Behold støtte for chatfullføringer for eksisterende klienter, men bygg Responses som sin egen gateway-overflate med sin egen tilstandsmodell, strømnormalisering, verktøy-anropsbok, evnematrise og reserveregler.

Hva er fakta, hva er politikk og hva er prediksjon?

Fakta: OpenAI beskriver Responses API som samlende funksjoner som tidligere var delt mellom chatfullføringer og assistenter, inkludert støtte for verktøy som nettsøk, filsøk og datamaskinbruk. API-en viser felt som previous_response_id, streaming, verktøyvalg og innebygde verktøy. SDK-dokumentasjon viser at previous_response_id kan gi samtalekontinuitet, mens tidligere instruksjoner ikke overføres automatisk og må sendes på nytt når de fortsatt skal gjelde. OpenAIs strømmereferanse inkluderer distinkte responslivssyklus og utdatahendelser i stedet for bare token-deltaer.

Anbefalinger: En gateway bør bevare denne semantikken i stedet for å flate ut dem som standard. Den bør avvise eller eksplisitt nedgradere forespørsler når en målleverandør ikke kan støtte nødvendig oppførsel.

Prediksjon: Flere agentarbeidsbelastninger vil avhenge av responselementstruktur, verktøyutførelsesspor og tilstandskontekst. Gatewayer som modellerer disse konseptene nå, vil være lettere å utvide enn gatewayer som behandler Responses som et kosmetisk endepunkt.

Definer en egen kompatibilitetskontrakt for svar

Den første implementeringsfeilen er å anta at OpenAI-kompatibel betyr ett universelt forespørsel- og svarskjema. I praksis bør /v1/chat/completions og /v1/responses være separate kompatibilitetskontrakter.

Behold et delt autentiserings-, fakturerings-, kvote- og rutinglag, men separer protokolllaget:

• Chatfullføringer vises: meldinger, valg, deltas, verktøyanrop i chat-format, eldre klientadferd.
• Svaroverflater: inndataelementer, utdataelementer, svar-ID-er, tidligere svarreferanser, rikere verktøyhendelser, livssyklusstrømhendelser, resonnementrelaterte felt og endelig svarstatus.

Denne delingen er viktig for samsvarstester. En leverandøradapter som består chattester, kan fortsatt mislykkes i responstestene fordi den ikke kan bevare previous_response_id, varebestilling, avvisningsstruktur, vertsverktøyets metadata eller strømmehendelsesnavn.

En minimal kompatibilitetskontrakt skal svare:

• Hvilke forespørselsfelt blir akseptert, avvist, transformert eller ignorert?
• Hvilke svarelementtyper er bevart?
• Hvilke verktøytyper støttes per leverandør og modell?
• Kan leverandøren opprettholde samtalestatus, eller må gatewayen opprettholde den?
• Hva skjer når store=false blir forespurt?
• Hvilke strømmehendelser er garantert?
• Hvordan registreres kansellering, tidsavbrudd og delvis bruk?

Hvis du allerede har en AI API-gateway, behandle Responses-støtte som en protokollutvidelse, ikke et rutealias.

Bruk en kanonisk svarelementmodell

Responses API returnerer mer enn én assistentmelding. Det kan representere forskjellige utdataelementer og hendelser. Gatewayen din trenger en intern kanonisk modell før den tilordnes til en hvilken som helst leverandør.

Et praktisk internt vareskjema kan starte slik:

{
  "gateway_response_id": "gw_resp_...",
  "provider_response_id": "resp_...",
  "tenant_id": "ten_123",
  "key_id": "key_456",
  "model_alias": "agent-standard",
  "provider": "openai",
  "varer": [
    {
      "item_id": "item_1",
      "type": "tekst",
      "role": "assistent",
      "content": [{ "type": "output_text", "text": "..." }],
      "status": "fullført"
    },
    {
      "item_id": "item_2",
      "type": "funksjonskall",
      "call_id": "call_abc",
      "name": "oppslagsordre",
      "arguments_json": "{\"order_id\":\"123\"}",
      "status": "fullført"
    }
  ],
  "bruk": {
    "input_tokens": 0,
    "output_tokens": 0,
    "reasoning_tokens": null,
    "verktøy_enheter": []
  },
  "status": "fullført"
}

Inkluder varetyper selv før hver leverandør kan produsere dem. Nyttige kategorier inkluderer:

• Tekstutdata
• Avslag
• Funksjonsanrop
• Funksjonsutdata sendt inn av søknaden
• Begrunnelsessammendrag eller resonnementrelaterte metadata der tilgjengelig
• Filreferanser
• Nettsøk, filsøk, datamaskinbruk eller andre vertsbaserte verktøyhendelser
• Endelig bruk og faktureringsmetadata

Poenget er ikke å avsløre et proprietært skjema for brukere. Poenget er å forhindre at gatewayen kaster informasjon før den kan revidere, fakturere, streame, spille på nytt eller transformere den.

Bygg en gateway-eid statsbok

previous_response_id er feltet som viser mest forskjellen mellom stateless chat proxying og Responses-kompatibilitet. Hvis en klient refererer til et tidligere svar, må gatewayen vite hva denne IDen betyr, om leietakeren har lov til å bruke den, og om leverandøren kan fortsette fra den.

Opprett en hovedbok tastet av leietaker og svar-ID:

{
  "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-...",
  "provider": "openai",
  "store_mode": "leverandør|gateway|ingen",
  "retention_policy": "standard|null_retention|custom_30d",
  "instructions_hash": "sha256:...",
  "tool_policy_id": "tools_readonly_v3",
  "created_at": "...",
  "expires_at": "...",
  "deleted_at": null
}

Viktig regel: ikke emuler previous_response_id automatisk ved å spille av hele chatteloggen på nytt med mindre leietakeren eksplisitt har tillatt denne oppbevaringen og kostnadsatferden. Replay kan øke token-kostnadene, endre personvernstilling og endre modellens oppførsel. Det er tryggere å returnere en tydelig funksjonsfeil enn å sende lagret samtaleinnhold som programmet ikke forventet at du skulle beholde eller gjenbruke.

State-håndteringsmoduser

• Tilbyderstatus: Oppstrømsleverandøren lagrer nok kontekst, og gatewayen tilordner gateway-svar-ID-er til leverandør-svar-ID-er.
• Gateway-tilstand: Gatewayen lagrer nødvendige tidligere elementer og rekonstruerer konteksten når det er tillatt.
• Ingen tilstand: Forespørselen bruker store=false eller retningslinjer for leietakere forbyr oppbevaring. previous_response_id bør avvises med mindre leverandøren kan oppfylle forespørselen uten gateway-oppbevaring og policyen tillater det.

Husk også at tidligere instruksjoner kanskje må sendes på nytt av klienten når de skal fortsette å søke. Gatewayen skal ikke finne opp skjulte instruksjoner for å kompensere med mindre denne oppførselen er en del av en eksplisitt leietakerpolicy.

Valider verktøy før utsendelse

Responser gjør verktøybruken mer sentral. Et kompatibilitetslag bør håndtere to brede kategorier:

• Applikasjonsverktøy: Funksjonsdefinisjoner levert av klienten, utført utenfor modellleverandøren, med utdata sendt tilbake til API.
• Vertsleverandørverktøy: Nettsøk, filsøk, datamaskinbruk, kodekjøring, jording eller lignende verktøy utført av leverandøren eller gateway-kontrollert infrastruktur.

Ved innføring, valider verktøyskjemaer før ruting:

• Avvis ugyldig JSON-skjema tidlig.
• Håndhev maksimal skjemastørrelse og hekkedybde.
• Sjekk verktøynavn for leverandørkompatibilitet.
• Bruk leier-, nøkkel-, bruker- og miljøomfang.
• Krev godkjenningsporter for verktøy som skriver data, bruker penger, får tilgang til sensitive systemer eller ringer eksterne kontakter.

For applikasjonsfunksjoner må du kreve en stabil anrops-ID. Modellen sender ut et funksjonskall med call_id; applikasjonen sender inn verktøyutgangen som refererer til denne IDen; gatewayen registrerer begge i samme spor. Uten den sammenføyningsnøkkelen blir revisjonslogger og gjenforsøk tvetydige.

For vertsbaserte verktøy, reserver budsjett før sending og avgjør kostnadene etterpå. Vertsbaserte verktøy kan legge til kostnader utenfor vanlig token-regnskap, så koble verktøyets hovedbok til unified AI API-fakturering i stedet for å skjule disse kostnadene i en generisk modellanropssum.

Normaliser strømming som hendelser, ikke tokentekst

En chatproxy kan ofte slippe unna med å videresende token-deltaer. En Responses-gateway kan ikke. Strømmen har livssyklusbetydning: et svar kan starte, utdataelementer kan starte og fullføre, tekst kan komme i deltaer, verktøykall kan settes sammen trinnvis, bruk kan komme på slutten eller under strømmen, og svaret kan mislykkes eller kanselleres.

Definer et gateway-hendelsesskjema, og kartlegg deretter hver leverandørstrøm inn i den:

hendelse: response_startet
data: { "response_id": "gw_resp_123", "status": "pågår" }

hendelse: output_item_starteddata: { "item_id": "item_1", "type": "tekst" }

hendelse: tekst_delta
data: { "item_id": "item_1", "delta": "Hei" }

hendelse: tool_call_delta
data: { "item_id": "item_2", "call_id": "call_abc", "arguments_delta": "{\"ordre" }

hendelse: usage_delta
data: { "output_tokens": 12 }

hendelse: fullført
data: { "response_id": "gw_resp_123", "usage": { ... } }

Anbefalte normaliserte hendelser:

• respons_startet
• output_item_started
• output_item_completed
• tekst_delta
• refusal_delta
• tool_call_delta
• tool_result_received
• bruksdelta
• fullført
• avbrutt
• mislyktes

Når klienten kobler fra, spre kansellering oppstrøms hvis leverandøren støtter det. Registrer den delvise responstilstanden uansett. Hvis leverandøren senere returnerer endelig bruk gjennom en forsinket tilbakeringing eller siste del, avstem hovedboken. Streaming-kompatibilitet handler like mye om regnskap og livssyklus som det handler om ventetid.

Opprett en leverandørkapasitetsmatrise

Multi-modell ruting er nyttig bare når gatewayen forstår hva som trygt kan rutes. Legg til svarspesifikke funksjoner i modellkatalogen din:

{
  "model_alias": "agent-standard",
  "ruter": [
    {
      "provider": "openai",
      "model": "...",
      "supports_responses": sant,
      "supports_previous_response_id": sant,
      "supports_store_false": sant,
      "supports_builtin_web_search": sant,
      "supports_function_calling": sant,
      "supports_stream_lifecycle_events": sant,
      "supports_reasoning_context_continuity": sant,
      "max_tool_schema_bytes": 65536
    },
    {
      "provider": "provider_b",
      "model": "...",
      "supports_responses": usant,
      "chat_adapter_available": sant,
      "loss_profile": ["no_previous_response_id", "no_hosted_tools", "flattened_stream"]
    }
  ]
}

Tilbakeslag bør være tapsbevisst. Hvis forespørselen krever innebygd nettsøk og reserveleverandøren ikke kan utføre det, ikke svar stille uten søk. Hvis forespørselen avhenger av bevart resonnementkontekst og reserveruten ikke kan bevare den, returnerer du en funksjonsfeil eller et nedgraderingssvar som klienten eksplisitt har valgt.

Et nyttig forespørselsalternativ er:

{
  "model": "agent-standard",
  "input": "...",
  "fallback_policy": {
    "allow_lossy": usant,
    "allowed_losses": []
  }
}

For mindre sensitive brukstilfeller kan leietakere tillate spesifikke nedgraderinger med tap:

{
  "fallback_policy": {
    "allow_lossy": sant,
    "allowed_losses": ["flatened_stream", "no_reasoning_summary"]
  }
}

Gatewayen bør logge reservebeslutningen uansett. Det gjør senere feilsøking mulig når en agent oppfører seg annerledes etter en leverandøravbrudd eller modellomdirigering.

Attributbruk på respons- og varenivå

Svaranrop kan koste mer enn tilsvarende chatfullføringer fordi de kan inkludere verktøykjøring, lengre kontekst, resonnementtokens, filsøk, nettsøk eller gjentatte instruksjoner. Et enkelt samlet tokenantall er ikke nok for et dashbord for bruksanalyse for AI API.

Registrer bruk på to nivåer:

• Responsnivå: leietaker, nøkkel, bruker, modell, leverandør, ventetid, endelig status, inndatatokens, utdatatokens, resonnementstokener der rapportert, totalkostnad og reserverute.
• Vare-/verktøynivå: verktøynavn, anrops-ID, vertsbaserte verktøyenheter, fil-ID-er, antall søkeord hvis tilgjengelig, verktøyforsinkelse, verktøykostnad og resultat av godkjenningspolicy.

Dette lar utviklere svare på konkrete spørsmål:

• Vokte kostnadene på grunn av lengre tilstand, resonnementarbeid, verktøykall eller fallback?
• Hvilken leietaker eller API-nøkkel genererer vertsbaserte verktøykostnader?
• Hvilket svar mislyktes etter et verktøykall, men før endelig tekst?
• Hvilke kansellerte strømmer har fortsatt oppstrømsbruk?

Håndter nulloppbevaring og sletting som førsteklasses atferd

Tjenersidetilstand er nyttig, men den endrer gatewayens oppbevaringsforpliktelser. Bygg policy inn i protokolllaget i stedet for å behandle det som en logginnstilling.

For hver svarforespørsel, løs:

• Retningslinjer for oppbevaring av leietakere
• Preferanse på butikk på forespørselsnivå
• Kompatibilitet med leverandøroppbevaring
• Om gateway-replay er tillatt
• Om verktøyinnganger og -utganger kan lagres
• Utløps- og sletteatferd for svartilstand

Hvis oppbevaring er deaktivert, kan gatewayen fortsatt beholde minimale operasjonelle metadata: tidsstempler, IDer, status, tokenantall, kostnader og policybeslutninger. Unngå å lagre rå meldinger, fullstendige verktøyutdata eller rekonstruert historie med mindre policyen tillater det.

Konformitetsarmaturer å legge til før lansering

Ikke stol på happy-path manuelle tester. Legg til inventar som bekrefter protokollatferd på tvers av direkte OpenAI-ruter, leverandørtilpassede ruter og reservescenarier.

Minimumstestsett

• Grunnleggende svar: tekstelementet returneres med stabil svar-ID og bruk.
• Multi-turn state: andre forespørselsreferanser previous_response_id; gateway validerer leietakers eierskap og tilstandsmodus.
• Gjentatte instruksjoner: bekreft at utelatte instruksjoner ikke er oppfunnet i det stille av gatewayen.
• Funksjonsanrop tur/retur: modellen sender ut anrops-ID; søknaden sender ut; endelig svar slår seg sammen med begge postene.
• Retningslinjer for vertsverktøy: uautorisert innebygd verktøy blokkeres før utsendelse.
• Strømmerekkefølge: svarstart, varestart, deltas, varefullføring, bruk og fullføring sendes ut i gyldig rekkefølge.
• Strømkansellering: Klientfrakobling utløser oppstrøms kansellering der det støttes og registrerer delvis bruk.
• Tilbakeslagsavvisning: leverandør uten nødvendig Svar semantikk returnerer evnefeil.
• Tap-back-opt-in: Forespørsel med tillatte tap mottar en eksplisitt nedgraderingsmarkør.
• Nulloppbevaringsmodus: tilstandsreplay og oppbevaring av meldinger på gatewaysiden er blokkert.

Anbefalt utrullingssekvens

1. Utslør en beta-rute. Legg til /v1/responses uten å endre eksisterende chat-atferd.
2. Implementer pass-through først for leverandører med integrert Responses-støtte. Ta vare på IDer, varer, strømmer, bruk og feil.
3. Legg til hovedboken. Kartlegg gateway-ID-er til leverandør-ID-er og håndhev leietakerskap.
4. Legg til kanoniske elementer. Lagre elementmetadata som trengs for revisjon, fakturering og rekonstruksjon av strømmer.
5. Legg til verktøystyring. Validere skjemaer, håndheve omfang og registrere verktøy-anrop-koblinger.
6. Legg til strømmenormalisering. Konverter leverandørspesifikke strømmer til gateway-livssyklushendelser.
7. Legg til kapasitetsbevisst ruting. Tillat bare sikre reserver som standard.
8. Legg til analyser og faktureringsoppgjør. Tilskriv token, resonnement og verktøybruk separat.
9. Publiser kompatibilitetsnotater. Fortell utviklere hvilke felt som er opprinnelige, emulerte, ikke-støttede eller tapsfulle.

Aktiv konklusjon

Et Responses API-kompatibilitetslag skal bevare protokollens betydning, ikke bare returnere plausibel tekst. Bygg den rundt fem holdbare objekter: en kanonisk responselementmodell, en konversasjonsstatusbok, en verktøy-anropsbok, en strømmehendelsesnormalisator og en leverandørfunksjonsmatrise.

Den sikreste standarden er streng kompatibilitet: hvis en rute ikke kan bevare nødvendig tilstand, verktøy, resonnementkontekst, strømhendelser eller oppbevaringsatferd, returner en klar funksjonsfeil. Legg til opt-in tapsgivende reserve bare når utviklerne forstår hva som vil bli droppet. Den tilnærmingen føles kanskje mindre praktisk enn automatisk utflatning, men den forhindrer den verste feilmodusen: en applikasjon som virker kompatibel mens den i det stille mister semantikken som gjorde at den brukte Responses API i utgangspunktet.

Relatert lesing

• canstreaming-way23-accounting">can håndtering