Vytvořte vrstvu kompatibility rozhraní Responses API v bráně AI API
Brána Responses API není jen proxy pro dokončení chatu s novou cestou. Zachovejte položky odpovědí, stav, volání nástrojů, streamy, kontinuitu uvažování, přiřazení použití a chování při přechodu na nižší verzi pomocí prvotřídní vrstvy kompatibility.
Neimplementujte /v1/responses tím, že byste každý požadavek překládali do /v1/chat/completions a doufali, že je tvar dostatečně blízký. Tento adaptér může vrátit text, ale může v tichosti ztratit části, o které se vývojáři starají: položky odpovědí, stav na straně serveru, volání nástrojů, kontinuita uvažování, události životního cyklu streamu, sémantika zrušení a přiřazení použití na úrovni položky.
Praktickým cílem je vrstva kompatibility, která zachází s Responses API jako s bohatším protokolem. Udržujte podporu dokončování chatu pro stávající klienty, ale sestavujte odpovědi jako vlastní povrch brány s vlastním modelem stavu, normalizátorem streamu, knihou volání nástrojů, maticí schopností a nouzovými pravidly.
Co je fakt, co je politika a co je předpověď?
Fakta: OpenAI popisuje Responses API jako sjednocující funkce, které byly dříve rozděleny mezi dokončování chatu a asistenty, včetně podpory nástrojů, jako je vyhledávání na webu, vyhledávání souborů a používání počítače. Rozhraní API zpřístupňuje pole jako previous_response_id, streamování, výběr nástrojů a vestavěné nástroje. Dokumentace sady SDK ukazuje, že previous_response_id může zajistit kontinuitu konverzace, zatímco předchozí pokyny se automaticky nepřenášejí a musí být znovu odeslány, pokud by měly stále platit. Odkaz na streamování OpenAI zahrnuje odlišný životní cyklus odezvy a výstupní události, nikoli pouze delty tokenů.
Doporučení: Brána by měla zachovat tuto sémantiku, nikoli ji ve výchozím nastavení sloučit. Pokud cílový poskytovatel nemůže podporovat požadované chování, měl by odmítnout nebo výslovně snížit požadavky na nižší verzi.
Předpověď: Více zátěží agentů bude záviset na struktuře položek odezvy, trasování provádění nástroje a kontextu uvažování stavu. Brány, které tyto koncepty modelují nyní, bude snazší rozšířit než brány, které zacházejí s odpověďmi jako s kosmetickým koncovým bodem.
Definujte samostatnou smlouvu o kompatibilitě pro odpovědi
První chybou implementace je předpoklad, že kompatibilní s OpenAI znamená jedno univerzální schéma požadavku a odpovědi. V praxi by /v1/chat/completions a /v1/responses měly být samostatné smlouvy o kompatibilitě.
Zachovat sdílenou vrstvu ověřování, fakturace, kvóty a směrování, ale oddělit vrstvu protokolu:
- Plocha dokončení chatu: zprávy, volby, delta, volání nástrojů ve formátu chatu, chování starších klientů.
- Povrch odpovědí: vstupní položky, výstupní položky, ID odpovědí, odkazy na předchozí odpovědi, bohatší události nástroje, události proudu životního cyklu, pole související s uvažováním a konečný stav odpovědi.
Toto rozdělení je důležité pro testy shody. Adaptér poskytovatele, který projde testy chatu, může stále selhat v testech odpovědí, protože nedokáže zachovat previous_response_id, řazení položek, strukturu odmítnutí, metadata hostovaného nástroje ani názvy událostí streamování.
Smlouva o minimální kompatibilitě by měla odpovídat:
- Která pole požadavku jsou přijata, zamítnuta, transformována nebo ignorována?
- Které typy položek odpovědí jsou zachovány?
- Jaké typy nástrojů jsou podporovány podle poskytovatele a modelu?
- Může poskytovatel udržovat stav konverzace, nebo jej musí udržovat brána?
- Co se stane, když je požadováno
store=false? - Jaké streamované události jsou zaručeny?
- Jak se zaznamenává zrušení, časový limit a částečné využití?
Pokud již máte bránu AI API, považujte podporu odpovědí za rozšíření protokolu, nikoli za alias trasy.
Použijte kanonický model položky odpovědi
Rozhraní Responses API vrací více než jednu zprávu asistenta. Může představovat různé výstupní položky a události. Vaše brána potřebuje interní kanonický model, než se namapuje na jakéhokoli poskytovatele.
Praktické interní schéma položky může začít takto:
{
"gateway_response_id": "gw_resp_...",
"provider_response_id": "resp_...",
"tenant_id": "ten_123",
"key_id": "key_456",
"model_alias": "agent-default",
"poskytovatel": "openai",
"položky": [
{
"item_id": "item_1",
"type": "text",
"role": "asistent",
"content": [{ "type": "output_text", "text": "..." }],
"stav": "dokončeno"
},
{
"item_id": "item_2",
"type": "function_call",
"call_id": "call_abc",
"name": "lookup_order",
"arguments_json": "{\"id_objednávky\":\"123\"}",
"stav": "dokončeno"
}
],
"usage": {
"input_tokens": 0,
"output_tokens": 0,
"reasoning_tokens": null,
"tool_units": []
},
"stav": "dokončeno"
}Zahrňte typy položek ještě předtím, než je každý poskytovatel dokáže vyrobit. Mezi užitečné kategorie patří:
- Textový výstup
- Odmítnutí
- Volání funkcí
- Výstupy funkcí odeslané aplikací
- Souhrny odůvodnění nebo metadata související s odůvodněním, pokud jsou k dispozici
- Odkazy na soubory
- Vyhledávání na webu, vyhledávání souborů, používání počítače nebo jiné události hostovaných nástrojů
- Konečné využití a metadata fakturace
Jde o to, abyste uživatelům nevystavovali proprietární schéma. Jde o to, aby brána nevyhazovala informace dříve, než je bude moci auditovat, účtovat, streamovat, přehrát nebo transformovat.
Vytvoření účetní knihy státu vlastněné bránou
previous_response_id je pole, které nejvíce odhaluje rozdíl mezi bezstavovým chatováním proxy a kompatibilitou odpovědí. Pokud klient odkazuje na předchozí odpověď, brána musí vědět, co toto ID znamená, zda jej tenant smí používat a zda z něj může poskytovatel pokračovat.
Vytvořte hlavní knihu stavu klíčovanou tenantem a ID odpovědi:
{
"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-...",
"poskytovatel": "openai",
"store_mode": "poskytovatel|brána|žádná",
"retention_policy": "standard|zero_retention|custom_30d",
"instructions_hash": "sha256:...",
"tool_policy_id": "tools_readonly_v3",
"created_at": "...",
"expires_at": "...",
"deleted_at": null
}Důležité pravidlo: Neemulujte automaticky previous_response_id přehráním celé historie chatu, pokud tenant výslovně nepovolil toto uchování a chování nákladů. Opakované přehrávání může zvýšit cenu tokenu, změnit postoj ochrany soukromí a změnit chování modelu. Je bezpečnější vrátit jasnou chybu schopnosti, než tiše odeslat uložený obsah konverzace, u kterého aplikace neočekávala, že si ho ponecháte nebo znovu použijete.
Režimy zpracování stavu
- Stav poskytovatele: Upstreamový poskytovatel ukládá dostatek kontextu a brána mapuje ID odpovědí brány na ID odpovědí poskytovatele.
- Stav brány: Brána ukládá nezbytné předchozí položky a rekonstruuje kontext, je-li to povoleno.
- Žádný stav: Požadavek používá
store=falsenebo zásady tenanta zakazují uchování.previous_response_idby měl být odmítnut, pokud poskytovatel nemůže vyhovět požadavku bez zachování brány a zásady to umožňují.
Mějte také na paměti, že pokud by měly nadále platit, může být nutné, aby klient znovu poslal předchozí pokyny. Brána by neměla vymýšlet skryté pokyny, které by to kompenzovaly, pokud toto chování není součástí explicitních zásad klienta.
Ověřte nástroje před odesláním
Odpovědi činí používání nástroje centrálnějším. Vrstva kompatibility by měla zpracovávat dvě široké kategorie:
- Aplikační nástroje: Definice funkcí dodané klientem, spouštěné mimo poskytovatele modelu, s výstupy odeslanými zpět do rozhraní API.
- Nástroje hostovaného poskytovatele: Vyhledávání na webu, vyhledávání souborů, používání počítače, spouštění kódu, uzemnění nebo podobné nástroje spouštěné poskytovatelem nebo infrastrukturou řízenou bránou.
Při vstupu ověřte schémata nástroje před směrováním:
- Předčasně odmítněte neplatné schéma JSON.
- Vynutit maximální velikost schématu a hloubku vnoření.
- Zkontrolujte kompatibilitu názvů nástrojů.
- Použijte rozsahy tenanta, klíče, uživatele a prostředí.
- Vyžadovat schvalovací brány pro nástroje, které zapisují data, utrácejí peníze, přistupují k citlivým systémům nebo volají externí konektory.
Pro volání funkcí aplikace požadujte stabilní ID volání. Model vydává volání funkce s call_id; aplikace odešle výstup nástroje s odkazem na toto ID; brána zaznamená oba ve stejném trasování. Bez tohoto klíče spojení se protokoly auditu a opakované pokusy stanou nejednoznačnými.
U hostovaných nástrojů si před odesláním zarezervujte rozpočet a následně uhraďte náklady. Hostované nástroje mohou přidávat poplatky mimo běžné účtování tokenů, takže propojte knihu nástrojů s sjednoceným účtováním AI API místo toho, abyste tyto náklady skrývali v celkovém součtu volání podle modelu.
Normalizovat streamování jako události, nikoli text tokenu
Proxy chatu často projde rozdílem tokenů pro přeposílání. Brána odpovědí nemůže. Stream má význam životního cyklu: odpověď se může spustit, výstupní položky se mohou spustit a dokončit, text může přicházet v deltách, volání nástrojů lze sestavovat postupně, použití může dojít na konci nebo během streamu a odezva může selhat nebo být zrušena.
Definujte schéma události brány a poté do něj namapujte každý stream poskytovatele:
událost: response_started
data: { "response_id": "gw_resp_123", "status": "in_progress" }
událost: output_item_starteddata: { "item_id": "item_1", "type": "text" }
událost: text_delta
data: { "item_id": "item_1", "delta": "Dobrý den" }
událost: tool_call_delta
data: { "item_id": "item_2", "call_id": "call_abc", "arguments_delta": "{\"objednávka" }
událost: use_delta
data: { "output_tokens": 12 }
akce: dokončena
data: { "response_id": "gw_resp_123", "usage": { ... } }Doporučené normalizované události:
response_startedoutput_item_startedoutput_item_completedtext_deltarefusal_deltatool_call_deltatool_result_receivedusage_deltadokončenozrušenose nezdařilo
Když se klient odpojí, rozšiřte zrušení upstream, pokud to poskytovatel podporuje. Zaznamenejte stav částečné odpovědi v obou směrech. Pokud poskytovatel později vrátí konečné využití prostřednictvím zpožděného zpětného volání nebo posledního bloku, srovnejte účetní knihu. Kompatibilita streamování je stejně tak o účetnictví a životním cyklu jako o latenci.
Vytvořte matici schopností poskytovatele
Směrování více modelů je užitečné pouze tehdy, když brána rozumí tomu, co lze bezpečně směrovat. Přidejte do katalogu modelů funkce specifické pro odpovědi:
{
"model_alias": "agent-default",
"trasy": [
{
"poskytovatel": "openai",
"model": "...",
"supports_responses": true,
"supports_previous_response_id": true,
"supports_store_false": true,
"supports_builtin_web_search": pravda,
"supports_function_calling": true,
"supports_stream_lifecycle_events": true,
"supports_reasoning_context_continuity": pravda,
"max_tool_schema_bytes": 65536
},
{
"poskytovatel": "poskytovatel_b",
"model": "...",
"supports_responses": nepravda,
"chat_adapter_available": true,
"loss_profile": ["no_previous_response_id", "no_hosted_tools", "flattened_stream"]
}
]
}Záložní opatření by si měla uvědomovat ztrátu. Pokud požadavek vyžaduje vestavěné vyhledávání na webu a záložní poskytovatel jej nemůže provést, neodpovídejte tiše bez hledání. Pokud požadavek závisí na uchovaném kontextu uvažování a záložní trasa jej nemůže zachovat, vraťte chybu schopnosti nebo odpověď na downgrade, ke které se klient výslovně přihlásil.
Užitečnou možností požadavku je:
{
"model": "agent-default",
"vstup": "...",
"fallback_policy": {
"allow_lossy": false,
"allowed_losses": []
}
}Pro méně citlivé případy použití mohou nájemci povolit konkrétní ztrátové downgrady:
{
"fallback_policy": {
"allow_lossy": pravda,
"allowed_losses": ["flattened_stream", "no_reasoning_summary"]
}
}Brána by měla zaprotokolovat záložní rozhodnutí v obou směrech. To umožňuje pozdější ladění, když se agent po výpadku poskytovatele nebo přesměrování modelu chová jinak.
Použití atributu na úrovni odpovědi a položky
Hovory s odpovědí mohou stát více než ekvivalentní dokončení chatu, protože mohou zahrnovat spuštění nástroje, delší kontext, tokeny uvažování, vyhledávání souborů, vyhledávání na webu nebo opakované pokyny. Jeden souhrnný počet tokenů nestačí pro panel analýzy využití AI API.
Zaznamenávejte využití na dvou úrovních:
- Úroveň odezvy: tenant, klíč, uživatel, model, poskytovatel, latence, konečný stav, vstupní tokeny, výstupní tokeny, tokeny zdůvodnění, pokud jsou hlášeny, celkové náklady a záložní trasa.
- Úroveň položky/nástroje: název nástroje, ID volání, jednotky hostovaných nástrojů, ID souborů, počet vyhledávacích dotazů, je-li k dispozici, latence nástroje, cena nástroje a výsledek zásad schvalování.
To umožňuje vývojářům odpovědět na konkrétní otázky:
- Zvýšily se náklady kvůli delšímu stavu, úsilí o uvažování, volání nástrojů nebo záložním řešením?
- Který tenant nebo klíč API generuje poplatky za hostovaný nástroj?
- Která odpověď selhala po volání nástroje, ale před konečným textem?
- Které zrušené streamy stále využívají upstream?
Zpracovat nulové uchovávání a mazání jako prvotřídní chování
Stav na straně serveru je užitečný, ale mění povinnosti uchování brány. Zabudujte zásady do vrstvy protokolu namísto toho, abyste je považovali za nastavení protokolování.
Pro každý požadavek odpovědí vyřešte:
- Zásady uchovávání nájemníků
- Předvolba
obchoduna úrovni požadavku - Kompatibilita se zachováním poskytovatele
- Zda je povoleno opakované přehrávání brány
- Zda lze ukládat vstupy a výstupy nástroje
- Chování vypršení platnosti a mazání pro stav odpovědi
Pokud je uchovávání zakázáno, brána může stále uchovávat minimální provozní metadata: časová razítka, ID, stav, počty tokenů, náklady a rozhodnutí o zásadách. Neukládejte nezpracované výzvy, úplné výstupy nástrojů nebo rekonstruovanou historii, pokud to zásady nepovolují.
Zařízení pro přizpůsobení, která se mají přidat před spuštěním
Nespoléhejte na manuální testy šťastnou cestou. Přidejte příslušenství, která ověřují chování protokolu napříč přímými trasami OpenAI, trasami přizpůsobenými poskytovateli a záložními scénáři.
Minimální testovací sada
- Základní odpověď: textová položka je vrácena se stabilním ID odpovědi a využitím.
- Stav s více otáčkami: druhý požadavek odkazuje na
previous_response_id; brána ověřuje vlastnictví nájemce a režim stavu. - Opakované pokyny: ověřte, zda vynechané pokyny nejsou v tichosti vymyšleny bránou.
- Zpětná cesta volání funkce: model vydává ID volání; aplikace odešle výstup; konečná odpověď spojí oba záznamy.
- Zásady hostovaných nástrojů: neautorizovaný vestavěný nástroj je před odesláním zablokován.
- Pořadí streamování: začátek odpovědi, začátek položky, rozdíly, dokončení položky, použití a dokončení jsou vysílány v platném pořadí.
- Zrušení streamu: odpojení klienta spustí zrušení upstreamu, pokud je podporováno, a zaznamená částečné využití.
- Odmítnutí záložních reklam: poskytovatel bez povinných odpovědí vrací chybu schopnosti sémantiky.
- Záložní přihlášení ke ztrátě: požadavek s povolenými ztrátami obdrží explicitní značku pro snížení verze.
- Režim nulového uchování: přehrání stavu a uchování výzvy na straně brány jsou blokovány.
Doporučená sekvence zavádění
- Ukažte trasu beta. Přidejte
/v1/responses, aniž byste změnili stávající chování chatu. - Implementujte nejprve předávání pro poskytovatele s podporou nativních odpovědí. Zachovejte ID, položky, streamy, využití a chyby.
- Přidejte knihu stavu. Mapujte ID bran na ID poskytovatelů a vynucujte vlastnictví tenantů.
- Přidejte kanonické položky. Uložte metadata položek potřebná pro auditování, fakturaci a rekonstrukci streamu.
- Přidejte správu nástrojů. Ověřujte schémata, vynucujte rozsahy a zaznamenávejte spojení volání nástroje.
- Přidejte normalizaci streamování. Převeďte streamy specifické pro poskytovatele na události životního cyklu brány.
- Přidejte směrování s ohledem na možnosti. Ve výchozím nastavení povolte pouze bezpečná záložní řešení.
- Přidejte analýzy a vypořádání fakturace. Token, zdůvodnění a použití nástroje přiřaďte samostatně.
- Publikujte poznámky ke kompatibilitě. Řekněte vývojářům, která pole jsou nativní, emulovaná, nepodporovaná nebo ztrátová.
Akční závěr
Vrstva kompatibility rozhraní Responses API by měla zachovat význam protokolu, nikoli pouze vracet věrohodný text. Sestavte jej na pěti odolných objektech: kanonický model položky odezvy, účetní kniha stavu konverzace, kniha volání nástrojů, normalizátor událostí streamování a matice schopností poskytovatele.
Nejbezpečnějším výchozím nastavením je přísná kompatibilita: pokud trasa nemůže zachovat požadovaný stav, nástroje, kontext uvažování, události streamu nebo chování uchovávání, vrátí jasnou chybu schopnosti. Ztrátovou zálohu přidejte pouze tehdy, když vývojáři pochopí, co bude zrušeno. Tento přístup se může zdát méně pohodlný než automatické zploštění, ale zabraňuje nejhoršímu režimu selhání: aplikaci, která se jeví jako kompatibilní, a přitom v tichosti ztrácí sémantiku, kvůli které na prvním místě používala rozhraní Responses API.