Byg et Responses API-kompatibilitetslag i en AI API-gateway
En Responses API-gateway er ikke bare en Chat Completions-proxy med en ny rute. Bevar svarelementer, tilstand, værktøjsopkald, streams, ræsonnementkontinuitet, brugstilskrivning og nedgraderingsadfærd med et førsteklasses kompatibilitetslag.
Implementer ikke /v1/responses ved at oversætte hver anmodning til /v1/chat/completions og håbe, at formen er tæt nok. Denne adapter returnerer muligvis tekst, men den kan stille og roligt miste de dele, udviklere interesserer sig for: svarelementer, server-sidetilstand, værktøjskald, ræsonnementkontinuitet, stream-livscyklushændelser, annulleringssemantik og brugstilskrivning på vareniveau.
Det praktiske mål er et kompatibilitetslag, der behandler Responses API som en mere rig protokol. Behold chatafslutningsunderstøttelse for eksisterende klienter, men opbyg Responses som sin egen gateway-overflade med sin egen tilstandsmodel, strømnormalisering, værktøjsopkaldsreskontro, kapacitetsmatrix og reserveregler.
Hvad er faktuelt, hvad er politik, og hvad er forudsigelse?
Fakta: OpenAI beskriver Responses API som samlende egenskaber, der tidligere var opdelt på tværs af chatafslutninger og assistenter, herunder understøttelse af værktøjer såsom websøgning, filsøgning og computerbrug. API'en afslører felter såsom previous_response_id, streaming, værktøjsvalg og indbyggede værktøjer. SDK-dokumentation viser, at previous_response_id kan give samtalekontinuitet, mens tidligere instruktioner ikke automatisk videreføres og skal sendes igen, når de stadig skulle gælde. OpenAIs streamingreference inkluderer distinkte responslivscyklus- og outputhændelser i stedet for kun token-deltaer.
Anbefalinger: En gateway bør bevare denne semantik i stedet for at udjævne dem som standard. Den bør afvise eller eksplicit nedgradere anmodninger, når en måludbyder ikke kan understøtte påkrævet adfærd.
Forudsigelse: Flere agentarbejdsbelastninger vil afhænge af svarelementstruktur, værktøjsudførelsesspor og tilstandsfuld begrundelseskontekst. Gateways, der modellerer disse koncepter nu, vil være lettere at udvide end gateways, der behandler Responses som et kosmetisk slutpunkt.
Definer en separat kompatibilitetskontrakt for svar
Den første implementeringsfejl er at antage, at OpenAI-kompatibel betyder ét universelt anmodnings- og svarskema. I praksis bør /v1/chat/completions og /v1/responses være separate kompatibilitetskontrakter.
Behold et delt godkendelses-, fakturerings-, kvote- og routinglag, men adskil protokollaget:
- Chatafslutninger vises: beskeder, valg, deltaer, værktøjsopkald i chatformat, ældre klientadfærd.
- Svaroverfladen: inputelementer, outputelementer, svar-id'er, tidligere svarreferencer, rigere værktøjshændelser, livscyklusstrømhændelser, begrundelsesrelaterede felter og endelige svartilstand.
Denne opdeling har betydning for overensstemmelsestests. En udbyderadapter, der består chattest, kan stadig mislykkes i svartest, fordi den ikke kan bevare previous_response_id, varebestilling, afvisningsstruktur, hostede værktøjs metadata eller streaminghændelsesnavne.
En minimal kompatibilitetskontrakt skal svare:
- Hvilke anmodningsfelter accepteres, afvises, transformeres eller ignoreres?
- Hvilke svarelementtyper er bevaret?
- Hvilke værktøjstyper understøttes pr. udbyder og model?
- Kan udbyderen opretholde samtaletilstand, eller skal gatewayen opretholde den?
- Hvad sker der, når
store=falseanmodes om? - Hvilke stream-begivenheder er garanteret?
- Hvordan registreres annullering, timeout og delvis brug?
Hvis du allerede har en AI API-gateway, skal du behandle Responses-support som en protokoludvidelse, ikke et rutealias.
Brug en kanonisk svarelementmodel
Respons-API'en returnerer mere end én assistentmeddelelse. Det kan repræsentere forskellige output-elementer og begivenheder. Din gateway har brug for en intern kanonisk model, før den tilknyttes en udbyder.
Et praktisk internt vareskema kan starte sådan her:
Inkluder varetyper, selv før hver udbyder kan producere dem. Nyttige kategorier omfatter:
- Tekstoutput
- Afvisninger
- Funktionskald
- Funktionsoutput indsendt af applikationen
- Begrundelsesresuméer eller begrundelsesrelaterede metadata, hvor de er tilgængelige
- Filreferencer
- Websøgning, filsøgning, computerbrug eller andre hostede værktøjsbegivenheder
- Endelig brug og faktureringsmetadata
Pointen er ikke at afsløre et proprietært skema for brugerne. Pointen er at forhindre gatewayen i at smide information væk, før den kan revidere, fakturere, streame, genafspille eller transformere den.
Byg en gateway-ejet statsbog
previous_response_id er det felt, der mest afslører forskellen mellem stateless chat proxying og Responses-kompatibilitet. Hvis en klient refererer til et tidligere svar, skal gatewayen vide, hvad dette id betyder, om lejeren har tilladelse til at bruge det, og om udbyderen kan fortsætte fra det.
Opret en delstatsbog indtastet af lejer og svar-id:
Vigtig regel: efterlign ikke automatisk previous_response_id ved at afspille hele chathistorikken, medmindre lejeren udtrykkeligt har tilladt denne opbevaring og omkostningsadfærd. Genafspilning kan øge token-omkostninger, ændre privatlivets fred og ændre modeladfærd. Det er sikrere at returnere en klar kapacitetsfejl end at sende gemt samtaleindhold, som programmet ikke forventede, at du skulle beholde eller genbruge.
Tilstandshåndteringstilstande
- Udbydertilstand: Opstrømsudbyderen gemmer nok kontekst, og gatewayen kortlægger gateway-svar-id'er til udbyder-svar-id'er.
- Gateway-tilstand: Gatewayen gemmer nødvendige tidligere elementer og rekonstruerer kontekst, når det er tilladt.
- Ingen tilstand: Anmodningen bruger
store=false, eller lejerpolitikken forbyder opbevaring.previous_response_idbør afvises, medmindre udbyderen kan efterkomme anmodningen uden gateway-retention, og politikken tillader det.
Husk også, at tidligere instruktioner muligvis skal sendes igen af klienten, når de skal fortsætte med at anvende. Gatewayen bør ikke opfinde skjulte instruktioner for at kompensere, medmindre denne adfærd er en del af en eksplicit lejerpolitik.
Valider værktøjer før afsendelse
Responser gør brugen af værktøjet mere central. Et kompatibilitetslag bør håndtere to brede kategorier:
- Applikationsværktøjer: Funktionsdefinitioner leveret af klienten, udført uden for modeludbyderen, med output sendt tilbage til API'en.
- Værktøjer til værtsudbydere: Websøgning, filsøgning, computerbrug, kodeudførelse, jordforbindelse eller lignende værktøjer udført af udbyderen eller gateway-kontrolleret infrastruktur.
Ved indgang, valider værktøjsskemaer før routing:
- Afvis ugyldigt JSON-skema tidligt.
- Tving maksimal skemastørrelse og indlejringsdybde.
- Tjek værktøjsnavne for udbyderkompatibilitet.
- Anvend lejer-, nøgle-, bruger- og miljøomfang.
- Kræv godkendelsesporte for værktøjer, der skriver data, bruger penge, får adgang til følsomme systemer eller ringer til eksterne forbindelser.
For applikationsfunktionsopkald skal du kræve et stabilt opkalds-id. Modellen udsender et funktionskald med kald_id; applikationen indsender værktøjsoutput, der refererer til dette ID; gatewayen registrerer begge i samme spor. Uden denne joinnøgle bliver revisionslogfiler og genforsøg tvetydige.
For hostede værktøjer skal du reservere budget inden afsendelse og afregne omkostningerne bagefter. Hostede værktøjer kan tilføje gebyrer uden for almindelige token-regnskaber, så tilslut værktøjets hovedbog til unified AI API-fakturering i stedet for at skjule disse omkostninger i en generisk model-call-total.
Normaliser streaming som begivenheder, ikke tokentekst
En chatproxy kan ofte slippe af sted med at videresende token-deltaer. En Responses-gateway kan ikke. Streamen har livscyklusbetydning: et svar kan starte, outputelementer kan starte og fuldføre, tekst kan ankomme i deltaer, værktøjsopkald kan samles trinvist, brug kan ankomme ved slutningen eller under streamen, og svaret kan mislykkes eller blive annulleret.
Definer et gateway-hændelsesskema, og tilknyt derefter hver udbyderstrøm til det:
hændelse: response_startet
data: { "response_id": "gw_resp_123", "status": "i_gang" }
hændelse: output_item_starteddata: { "item_id": "item_1", "type": "tekst" }
hændelse: text_delta
data: { "item_id": "item_1", "delta": "Hej" }
hændelse: tool_call_delta
data: { "item_id": "item_2", "call_id": "call_abc", "arguments_delta": "{\"ordre" }
hændelse: usage_delta
data: { "output_tokens": 12 }
begivenhed: afsluttet
data: { "response_id": "gw_resp_123", "usage": { ... } }Anbefalede normaliserede hændelser:
svar_startetoutput_item_startedoutput_item_completedtekst_deltaafvisningsdeltaværktøjskaldsdeltatool_result_receivedusage_deltafuldførtannulleretmislykkedes
Når klienten afbryder forbindelsen, skal du udbrede annullering opstrøms, hvis udbyderen understøtter det. Registrer den delvise responstilstand på begge måder. Hvis udbyderen senere returnerer den endelige brug gennem et forsinket tilbagekald eller sidste del, skal du afstemme hovedbogen. Streamingkompatibilitet handler lige så meget om regnskab og livscyklus, som det handler om ventetid.
Opret en matrix for udbyderegenskaber
Multi-model routing er kun nyttig, når gatewayen forstår, hvad der sikkert kan dirigeres. Tilføj svarspecifikke funktioner til dit modelkatalog:
Fallback bør være tabsbevidst. Hvis anmodningen kræver indbygget websøgning, og reserveudbyderen ikke kan udføre den, skal du ikke svare stille uden søgning. Hvis anmodningen afhænger af bevaret begrundelseskontekst, og reserveruten ikke kan bevare den, skal du returnere en kapacitetsfejl eller et nedgraderingssvar, som klienten eksplicit har valgt.
En nyttig anmodningsmulighed er:
For mindre følsomme brugssager kan lejere tillade specifikke tabsgivende nedgraderinger:
Gatewayen skal logge tilbagefaldsbeslutningen på begge måder. Det gør senere fejlretning mulig, når en agent opfører sig anderledes efter en udbyderafbrydelse eller modelomdirigering.
Attributbrug på svar- og elementniveau
Svaropkald kan koste mere end tilsvarende chatafslutninger, fordi de kan omfatte værktøjsudførelse, længere kontekst, ræsonnementstokens, filsøgning, websøgning eller gentagne instruktioner. Et enkelt samlet tokenantal er ikke nok til et betjeningspanel til analyse af AI API-brug.
Registrer brug på to niveauer:
- Responsniveau: lejer, nøgle, bruger, model, udbyder, latens, endelig status, inputtokens, outputtokens, ræsonnementstokens hvor rapporteret, samlede omkostninger og reserverute.
- Vare-/værktøjsniveau: værktøjsnavn, opkalds-id, hostede værktøjsenheder, fil-id'er, antal søgeforespørgsler, hvis tilgængeligt, værktøjsforsinkelse, værktøjsomkostninger og resultat af godkendelsespolitik.
Dette lader udviklere besvare konkrete spørgsmål:
- Blev omkostningerne steget på grund af længere tilstand, ræsonnement, værktøjskald eller fallback?
- Hvilken lejer eller API-nøgle genererer hostede værktøjsafgifter?
- Hvilket svar mislykkedes efter et værktøjskald, men før den endelige tekst?
- Hvilke annullerede streams pådrog sig stadig opstrømsbrug?
Håndter nul-retention og sletning som førsteklasses adfærd
Tilstand på serversiden er nyttig, men den ændrer gatewayens opbevaringsforpligtelser. Byg politik ind i protokollaget i stedet for at behandle det som en logindstilling.
For hver svaranmodning skal du løse:
- Politik for fastholdelse af lejer
- Foretrukket
butikpå anmodningsniveau - Kompatibilitet med udbyderfastholdelse
- Om gateway-genafspilning er tilladt
- Om værktøjets input og output kan gemmes
- Udløbs- og sletningsadfærd for svartilstand
Hvis opbevaring er deaktiveret, kan gatewayen stadig beholde minimale operationelle metadata: tidsstempler, id'er, status, tokenantal, omkostninger og politiske beslutninger. Undgå at gemme rå prompter, komplette værktøjsoutput eller rekonstrueret historie, medmindre politikken tillader det.
Konformitetsarmaturer, der skal tilføjes før lancering
Stol ikke på happy-path manuelle tests. Tilføj fixtures, der verificerer protokoladfærd på tværs af direkte OpenAI-ruter, udbydertilpassede ruter og reservescenarier.
Minimum testsæt
- Grundlæggende svar: tekstelementet returneres med stabilt svar-id og brug.
- Multi-turn-tilstand: anden anmodningsreferencer
previous_response_id; gateway validerer lejers ejerskab og tilstandstilstand. - Gentagne instruktioner: bekræft, at udeladte instruktioner ikke stilles op af gatewayen.
- Funktionsopkald tur-retur: modellen udsender opkalds-id; ansøgning indsender output; endelige svar forbinder begge poster.
- Politik for værtsværktøj: uautoriseret indbygget værktøj er blokeret før afsendelse.
- Streamingrækkefølge: svarstart, varestart, deltas, vareafslutning, brug og afslutning udsendes i gyldig rækkefølge.
- Strømannullering: Klientafbrydelse udløser opstrømsannullering, hvor det understøttes, og registrerer delvis brug.
- Fallback afvisning: udbyder uden påkrævet Svar semantik returnerer kapacitetsfejl.
- Tabs fallback opt-in: Anmodning med tilladte tab modtager en eksplicit nedgraderingsmarkør.
- Nul-retention-tilstand: tilstandsgenafspilning og gateway-side-prompt-retention er blokeret.
Anbefalet udrulningssekvens
- Afslør en beta-rute. Tilføj
/v1/responsesuden at ændre eksisterende chatadfærd. - Implementer først pass-through for udbydere med native Responses-understøttelse. Bevar id'er, elementer, streams, brug og fejl.
- Tilføj hovedbogen. Kortlæg gateway-id'er til udbyder-id'er og håndhæv lejers ejerskab.
- Tilføj kanoniske elementer. Gem elementmetadata, der kræves til revision, fakturering og streamgenopbygning.
- Tilføj værktøjsstyring. Valider skemaer, håndhæv scopes, og optag værktøjsopkald-sammenføjninger.
- Tilføj streamingnormalisering. Konverter udbyderspecifikke streams til gateway-livscyklushændelser.
- Tilføj kapacitetsbevidst routing. Tillad kun sikre fallbacks som standard.
- Tilføj analyser og faktureringsafregning. Tilskriv token, ræsonnement og værktøjsbrug separat.
- Offentliggør kompatibilitetsnoter. Fortæl udviklerne, hvilke felter der er indbyggede, emulerede, ikke-understøttede eller tabsgivende.
Aktiv konklusion
Et Responses API-kompatibilitetslag skal bevare protokolbetydningen, ikke blot returnere plausibel tekst. Byg det op omkring fem holdbare objekter: en kanonisk svarelementmodel, en konversationstilstandsbog, en værktøjsopkaldsbog, en normalisering af streaminghændelser og en matrix for udbyderkapacitet.
Den sikreste standard er streng kompatibilitet: Hvis en rute ikke kan bevare den påkrævede tilstand, værktøjer, begrundelseskontekst, streambegivenheder eller opbevaringsadfærd, skal du returnere en klar funktionsfejl. Tilføj kun tilvalg med tab, når udviklerne forstår, hvad der vil blive droppet. Den tilgang kan føles mindre bekvem end automatisk udfladning, men den forhindrer den værste fejltilstand: en applikation, der ser ud til at være kompatibel, mens den i det stille mister den semantik, der gjorde, at den brugte Responses API i første omgang.