Styr Anthropic API versioner och betahuvuden i en gateway för flera tenant

En Anthropic-kompatibel API-gateway ska inte behandla anthropic-version och anthropic-beta som vanliga pass-through-rubriker. De väljer protokollbeteende och experimentella funktioner som kan ändra valideringsregler, svarsblockeringar, strömmande händelser, tillgänglighet, prissättning och cacheredovisning.

Det praktiska problemet är att bevara det inbyggda Claude-beteendet utan att tillåta en hyresgästs förfrågningsrubriker att kringgå plattformspolicyn. Lösningen är att göra protokolltillträde till ett förstklassigt gatewaybeslut: autentisera den som ringer, lös dess versionspolicy, validera begärda betafunktioner, välj en kompatibel rutt och spela in exakt vad som skickades uppströms.

Definiera policygränsen

Fakta: Direkta Claude API förfrågningar kräver ett anthropic-version-huvud, även om officiella SDK:er normalt tillhandahåller det. Anthropic betafunktioner begärs via anthropic-beta eller en SDK-specifik betaparameter.

Rekommendation: Tolka båda värdena som begärda funktioner, inte betrodda routinginstruktioner. En klient kan begära en version eller beta, men gatewayen avgör om den kombinationen stöds för klienten, API-nyckeln, modellen, regionen och uppströmsuppgifterna.

Ta inte bort en ogodkänd betaversion tyst. Det kan förvandla en explicit begäran till ett framgångsrikt samtal med olika semantik. Avvisa det före avsändning med ett stabilt gateway-fel som identifierar den funktion som inte stöds utan att exponera uppströms autentiseringsuppgifter eller interna ruttdetaljer.

{
  "type": "gateway_policy_error",
  "code": "beta_not_allowed",
  "message": "The requested Anthropic beta is not enabled for this API key.",
  "details": {
    "beta": "example-beta-2026-01-01",
    "policy_id": "claude-production"
  }
}

Returnera ett 4xx-svar för antagningsfel och reservera 5xx-svar för gateway- eller uppströmsfel. Håll felschemat stabilt även om Anthropic ändrar sitt eget felformat.

Bygg ett versions- och kapacitetsregister

En datumformad versionssträng är lätt att validera syntaktisk men omöjlig att styra från enbart syntax. Gatewayen behöver ett register som innehåller de versioner och betafunktioner som den faktiskt har testat.

Versionsposter

Varje versionspost bör innehålla:

• Kanonisk versionsidentifierare och livscykelstatus: testning, tillgänglig, standard, utfasad eller blockerad.
• Fält för förfrågningar som stöds, innehållsblockeringar, stopporsaker, användningsfält och kända streaminghändelser.
• Kompatibla modeller, uppströmsplattformar, regioner och autentiseringspooler.
• Resultat av kontrakt och datum för det senaste framgångsrika testet.
• Priskatalogkompatibilitet och alla kända cachekonsekvenser.
• Antagandebegränsningar, utfasningsdatum och vägledning för ersättning.

Betaposter

Betafunktioner behöver separata uppgifter eftersom deras tillgänglighet och operativa risker kan skilja sig från basversionen API. Spela in det kanoniska betanamnet, kompatibla versioner och modeller, tillåtna regioner, obligatoriska förfrågningsfält, möjliga svarsblockeringar, streaminghändelser, prisbehandling, frekvensgränsklass och lanseringstillstånd.

Modela detta som data snarare än programvillkor. En policyutvärderare kan sedan svara på en konkret fråga: "Får nyckel K använda version V med betauppsättning B på väg R?" Samma katalog kan stödja en multi-model API gateway för team utan att tvinga varje adapter att implementera sina egna hyresgästregler.

Ge varje hyresgäst en explicit versionspolicy

Stöd tre policylägen:

1. Fäst: Hyresgästen eller nyckeln måste använda en exakt version. Avvisa saknade eller andra värden.
2. Gateway aktuell: En saknad rubrik löser sig till gatewayens testade standard. Ett explicit klientvärde är fortfarande validerat.
3. Godkänd intervall: Klienten kan välja från en ändlig godkännandelista med testade versioner.

Undvik att tolka "intervall" som varje datum mellan två slutpunkter. Anthropic versioner är identifierare, inte en kontinuerlig semantisk versionssekvens. Lagra en explicit uppsättning tillåtna värden.

Lös den effektiva versionen innan du väljer en uppströmsrutt:

requested = parse_version_header(request)
policy = load_policy(tenant_id, api_key_id)
effective = resolve_version(requested, policy, registry)
betas = parse_and_canonicalize_betas(request)
admitted = authorize_betas(betas, policy, effective, registry)
route = select_compatible_route(model, region, effective, admitted)
dispatch(route, effective, admitted)

Håll de begärda och effektiva värdena åtskilda. De kan skilja sig åt när en policy anger en standard, men en granskningspost måste göra ersättningen synlig.

Parse beta-rubriker strukturellt

Auktorisera inte betafunktioner med delsträngsmatchning eller råsträngslikhet. Analysera rubriken enligt syntaxen som accepteras av uppströms API, avvisa felaktiga eller dubbletter av poster som är lämpligt och jämför kanoniska funktionsidentifierare.

Kanonisk ordning är användbar för policycache-nycklar och telemetridimensioner:

requested header: beta-b, beta-a
canonical policy set: [beta-a, beta-b]
upstream header: beta-b,beta-a  // serialized in accepted upstream syntax

Bevara tillräckligt med metadata för begäranden för felsökning, men behåll inte råa rubriker på obestämd tid när normaliserade identifierare är tillräckliga. Rubrikloggar kan innehålla onödig klientmetadata, och lagring av dem ökar omfattningen av lagring och åtkomstkontroller.

Beta-auktorisering bör vara klientomfattning och helst nyckelomfattande. En utvecklingsnyckel kan ta emot en experimentell förmåga utan att automatiskt ge den till produktionsbelastningar. Ändringar av godkännandelistor bör producera kontrollplansrevisionshändelser med aktör, orsak, tidigare tillstånd, nytt tillstånd och effektiv tid.

Separat tillträde från routing

En begäran är inte routbar bara för att dess modellnamn finns. Ruttbehörighet är skärningspunkten mellan protokoll och infrastrukturkapacitet:

eligible(route) =
  route.platform supports effective_version
  AND route.model supports every admitted_beta
  AND route.region permits every admitted_beta
  AND route.credentials are entitled to those capabilities
  AND route.pricing_catalog can account for the result

Om ingen rutt uppfyller hela uppsättningen, misslyckas du innan du skickar begäran. Släpp inte betafunktioner för att göra en rutt kvalificerad. Byt inte automatiskt ut en annan version om inte hyresgästpolicyn uttryckligen definierar det beteendet.

Denna åtskillnad är viktig i gateways som samlar autentiseringsuppgifter, stödjer kundlevererade nycklar eller fungerar över regioner. Två rutter till samma modell kan ha olika funktionsåtkomst, bosättningsbegränsningar eller hastighetsbegränsningar.

Bevara inbyggd respons semantik

Fakta: Anthropic Meddelandesvar kan sluta med orsaker som verktygsanvändning, token-gränser, sammanhangsfönstergränser, pausade svängar och avslag. Strömmande svar använder namngivna serversända händelser, och Anthropics kompatibilitetsvägledning kräver att klienter tolererar nya händelsetyper.

Rekommendation: Dölj inte alla lyckade terminaltillstånd till "avslutade". Bevara uppströmsstoppet i det ursprungliga svaret och i gateway-telemetri. Appar kan behöva köra ett verktyg, fortsätta en pausad sväng, minska kontexten eller visa upp ett avslag.

Strömproxyn bör känna igen händelser som krävs för redovisning och livscykelhantering samtidigt som den förblir framåtkompatibel:

• Vidarebefordra okända händelsetyper när hyresgästens policy tillåter inbyggd pass-through.
• Behåll det råa händelsenamnet och sekvenspositionen i avgränsad diagnostisk metadata.
• Använd inte en uttömmande uppräkning som stänger strömmen vid en obekant additiv händelse.
• Särskilj en uppströmsfelhändelse från en transportnedkoppling och en klientavbokning.
• Avsluta endast användning från auktoritativa fält; markera ofullständiga strömmar som provisoriska när slutlig användning inte är tillgänglig.

Om gatewayen också exponerar en OpenAI-formad slutpunkt, håll den adaptern åtskild från den inbyggda meddelandesökvägen. Anthropics OpenAI kompatibilitetslager har dokumenterade fält- och funktionsbegränsningar. Ett gemensamt internt kuvert kan hjälpa till med routing, men det får inte förkasta innehållsblockeringsordning, cachekontroller, tankesignaturer, verktygstillstånd eller leverantörsspecifika stopporsaker.

Gör bokföringsversionsmedveten

Fakta: Användning av prompt-cache separerar vanliga indatatoken, cache-skapande indatatoken och cache-läs indatatoken. Den totala insatsförbrukningen måste stå för alla tillämpliga kategorier.

En version eller betaändring kan ändra cachebehörighet, innehållsrepresentation eller returnerade användningsfält. Därför bör varje användningshändelse innehålla:

• Begärd och effektiv API version.
• Begärda och godkända betauppsättningar.
• Tenant, API nyckel, policy, rutt, modell, region och uppströms begäran-ID.
• Status, stopporsak, status för slutförande av stream och feltillskrivning.
• kategorier för inmatning, utdata, skapande av cache och cachelästa token.
• Priskatalogversion och preliminär eller slutgiltig kostnadsstatus.

De här dimensionerna låter unified AI API billing förklara varför liknande förfrågningar annars orsakade olika kostnader. Undvik fakturering från ett enda kombinerat tokenantal när leverantören exponerar kategorier med olika priser.

Testa innan du aktiverar en version eller beta

Skapa kontraktsfixturer för vanlig text, strömmande text, verktygsanrop, strukturerad utdata, avslag, tokentrunkering, kontextfönsterutmattning, pausade svängar, promptcache, felaktiga förfrågningar, hastighetsgränser och midstream-fel.

Jämför mer än HTTP status för varje match. Fånga innehållsblockstyp och ordning, stopporsak, verktygsidentifierare och argument, händelsesekvens, användningsfältsnärvaro, cachekategorier och felform. Lagra godkända strukturella förväntningar snarare än exakt prosa.

Använd bara skuggförfrågningar när dubblettkörning är säker. Förfrågningar med verktyg, externa biverkningar, känsliga uppgifter eller materialkostnader kan vara olämpliga. För dessa arbetsbelastningar, spela om sanerade fixturer i en kontrollerad miljö.

Prognos: Nya versioner och betafunktioner kommer att fortsätta lägga till svarsvarianter och händelser. En gateway som är designad kring kapacitetsposter och additiv parsning kommer vanligtvis att absorbera dessa ändringar med mindre nödarbete än en byggd kring fasta uppräkningar och globala standardinställningar.

Rulla ut och avveckla funktioner på ett säkert sätt

Främja en kapacitet genom testning, intern, opt-in, kanariefågel, tillgänglig, utfasad och blockerad. Under kanariefågel, jämför statusfördelningar, stopporsaker, innehållsblocksekvenser, verktygsbeteende, användningsfält, latens och cacheresultat. Definiera trösklar för återställning innan trafiken börjar.

Pensionering bör ske i etapper:

1. Blockera adoption av nya hyresgäster medan befintliga uppdrag fortsätter.
2. Identifiera berörda hyresgäster, nycklar, modeller och senaste begärandemönster.
3. Tillhandahåll en kompatibilitetsrapport eller testslutpunkt för ersättningen.
4. Varna för godkända förfrågningar och publicera en fast cutoff.
5. Kräv explicita undantag med ägare och utgångsdatum.
6. Blockera kapaciteten och behåll registerposten för historisk granskning och tolkning av fakturering.

Näsning ökar reproducerbarheten men utökar testmatrisen. En gateway-omfattande version minskar driftsvarianter men kopplar icke-relaterade hyresgäster till ett migreringsschema. Bred beta-genomföring påskyndar tillgången till funktioner men försvagar kostnads-, uppehålls- och supportgarantier. För en tjänst med flera hyresgäster är explicit policy för per-tenant vanligtvis den försvarbara mellanvägen.

Checklista för implementering

• Kräv en versionspolicy för varje hyresgäst eller API-nyckel.
• Upprätthåll testade versioner och betafunktioner.
• Avvisa felaktiga, okända eller obehöriga funktioner före avsändning.
• Välj rutter först efter att ha löst hela protokollförfrågan.
• Bevara inbyggda innehållsblockeringar, stopporsaker, användningsfält och strömmar.
• Vidarebefordra additiv stream-händelser på ett säkert sätt och behåll deras evenemangsnamn.
• Spela in begärda och effektiva protokollvärden för användnings- och granskningshändelser.
• Kör kontraktsfixturer och kontrollerade kanariefåglar innan du ändrar standardinställningar.
• Ta bort gamla funktioner genom uppmätta användningskontroller, inte tysta omskrivningar.

Nyckeldesignbeslutet är enkelt: versions- och betahuvuden är policyindata. När gatewayen godkänner, rutter, testar och mäter dem som kapaciteter, blir inbyggd API-kompatibilitet styrbar utan att låtsas som att experimentellt beteende är vanligt HTTP metadata.

Relaterad läsning

• redovisning för slutlig, användning och partiell strömning, användning och partiell redovisning svar