Steuern Sie Anthropic API Versionen und Beta-Header in einem Multi-Tenant-Gateway

Ein Anthropic-kompatibles API-Gateway sollte anthropic-version und anthropic-beta nicht als gewöhnliche Pass-Through-Header behandeln. Sie wählen Protokollverhalten und experimentelle Funktionen aus, die Validierungsregeln, Antwortblöcke, Streaming-Ereignisse, Verfügbarkeit, Preise und Cache-Abrechnung ändern können.

Das praktische Problem besteht darin, das native Verhalten Claude beizubehalten, ohne zuzulassen, dass die Anforderungsheader eines Mandanten die Plattformrichtlinie umgehen. Die Lösung besteht darin, die Protokollzulassung zu einer erstklassigen Gateway-Entscheidung zu machen: Authentifizieren Sie den Anrufer, klären Sie seine Versionsrichtlinie, validieren Sie angeforderte Betafunktionen, wählen Sie eine kompatible Route aus und zeichnen Sie genau auf, was im Upstream gesendet wurde.

Definieren Sie die Richtliniengrenze

Fakt: Direkte Claude API Anfragen erfordern einen anthropic-version-Header, obwohl offizielle SDKs ihn normalerweise bereitstellen. Anthropic Betafunktionen werden über anthropic-beta oder einen SDK-spezifischen Betaparameter angefordert.

Empfehlung: Interpretieren Sie beide Werte als angeforderte Funktionen und nicht als vertrauenswürdige Routing-Anweisungen. Ein Client kann nach einer Version oder Beta fragen, aber das Gateway entscheidet, ob diese Kombination für Mandant, API Schlüssel, Modell, Region und Upstream-Anmeldeinformationen unterstützt wird.

Entfernen Sie nicht stillschweigend eine nicht genehmigte Betaversion. Dadurch kann aus einer expliziten Anfrage ein erfolgreicher Anruf mit unterschiedlicher Semantik werden. Lehnen Sie es vor dem Versand mit einem stabilen Gateway-Fehler ab, der die nicht unterstützte Funktion identifiziert, ohne Upstream-Anmeldeinformationen oder interne Routendetails offenzulegen.

{
  "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"
  }
}

Eine 4xx-Antwort für Zulassungsfehler zurückgeben und 5xx-Antworten für Gateway- oder Upstream-Fehler reservieren. Halten Sie das Fehlerschema stabil, auch wenn Anthropic sein eigenes Fehlerformat ändert.

Erstellen Sie eine Versions- und Funktionsregistrierung

Eine datumsförmige Versionszeichenfolge lässt sich syntaktisch leicht validieren, lässt sich jedoch nicht allein anhand der Syntax steuern. Das Gateway benötigt eine Registry mit den tatsächlich getesteten Versionen und Betafunktionen.

Versionsdatensätze

Jeder Versionseintrag sollte Folgendes enthalten:

• Kanonische Versionskennung und Lebenszyklusstatus: getestet, verfügbar, Standard, veraltet oder blockiert.
• Unterstützte Anforderungsfelder, Inhaltsblöcke, Stoppgründe, Nutzungsfelder und bekannte Streaming-Ereignisse.
• Kompatible Modelle, Upstream-Plattformen, Regionen und Anmeldeinformationspools.
• Vertragsergebnis und Datum des letzten erfolgreichen Tests.
• Preis-Katalog-Kompatibilität und alle bekannten Auswirkungen auf die Cache-Abrechnung.
• Einführungsbeschränkungen, Einstellungstermine und Ersetzungshinweise.

Beta-Datensätze

Betafunktionen benötigen separate Datensätze, da ihre Verfügbarkeit und ihr Betriebsrisiko von der Basisversion API abweichen können. Notieren Sie den Namen der kanonischen Beta, kompatible Versionen und Modelle, zulässige Regionen, erforderliche Anforderungsfelder, mögliche Antwortblöcke, Streaming-Ereignisse, Preisbehandlung, Ratenbegrenzungsklasse und Rollout-Status.

Modellieren Sie dies als Daten und nicht als Anwendungsbedingungen. Ein Policy-Evaluator kann dann eine konkrete Frage beantworten: „Darf Key K Version V mit Beta-Set B auf Route R verwenden?“ Derselbe Katalog kann ein Gateway mit mehreren Modellen API für Teams unterstützen, ohne dass jeder Adapter seine eigenen Mandantenregeln implementieren muss.

Geben Sie jedem Mandanten eine explizite Versionsrichtlinie

Unterstützt drei Richtlinienmodi:

1. Angepinnt: Der Mandant oder Schlüssel muss eine exakte Version verwenden. Fehlende oder unterschiedliche Werte ablehnen.
2. Gateway current: Ein fehlender Header wird in den getesteten Standard des Gateways aufgelöst. Ein expliziter Clientwert wird weiterhin validiert.
3. Genehmigter Bereich: Der Client kann aus einer endlichen Zulassungsliste getesteter Versionen auswählen.

Vermeiden Sie es, „Bereich“ als jedes Datum zwischen zwei Endpunkten zu interpretieren. Anthropic-Versionen sind Bezeichner, keine kontinuierliche semantische Versionssequenz. Speichern Sie einen expliziten Satz zugelassener Werte.

Lösen Sie die effektive Version auf, bevor Sie eine Upstream-Route auswählen:

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)

Halten Sie die angeforderten und effektiven Werte getrennt. Sie können unterschiedlich sein, wenn eine Richtlinie einen Standardwert bereitstellt, aber ein Prüfdatensatz muss diese Ersetzung sichtbar machen.

Beta-Header strukturell analysieren

Beta-Funktionen mit Teilstring-Übereinstimmung oder Rohstring-Gleichheit nicht autorisieren. Analysieren Sie den Header gemäß der vom Upstream akzeptierten Syntax API, lehnen Sie gegebenenfalls fehlerhafte oder doppelte Einträge ab und vergleichen Sie kanonische Feature-IDs.

Kanonische Reihenfolge ist nützlich für Richtlinien-Cache-Schlüssel und Telemetriedimensionen:

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

Behalten Sie genügend Anfragemetadaten für das Debuggen bei, aber bewahren Sie Rohheader nicht auf unbestimmte Zeit auf, wenn normalisierte Bezeichner ausreichen. Header-Protokolle können unnötige Client-Metadaten enthalten und ihre Speicherung erhöht den Umfang der Aufbewahrungs- und Zugriffskontrollen.

Die Beta-Autorisierung sollte mandantenbezogen und vorzugsweise schlüsselbezogen sein. Ein Entwicklungsschlüssel kann eine experimentelle Funktion erhalten, ohne diese automatisch Produktions-Workloads zu gewähren. Änderungen an Zulassungslisten sollten zu Überwachungsereignissen auf Kontrollebene mit Akteur, Grund, vorherigem Status, neuem Status und effektiver Zeit führen.

Getrennte Zulassung und Streckenführung

Eine Anfrage ist nicht weiterleitbar, nur weil ihr Modellname existiert. Die Routenberechtigung ist die Schnittstelle zwischen Protokoll und Infrastrukturfunktionen:

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

Wenn keine Route den gesamten Satz erfüllt, schlagen Sie fehl, bevor Sie die Anfrage senden. Lassen Sie Betafunktionen nicht fallen, um eine Route förderfähig zu machen. Ersetzen Sie nicht automatisch eine andere Version, es sei denn, die Mandantenrichtlinie definiert dieses Verhalten ausdrücklich.

Diese Trennung ist bei Gateways wichtig, die Anmeldeinformationen bündeln, vom Kunden bereitgestellte Schlüssel unterstützen oder über Regionen hinweg arbeiten. Zwei Routen zum selben Modell können unterschiedliche Funktionszugriffe, Residenzbeschränkungen oder Ratenbeschränkungen haben.

Native Antwortsemantik beibehalten

Fakt: Anthropic Nachrichtenantworten können mit Gründen wie der Verwendung von Werkzeugen, Token-Beschränkungen, Kontextfenster-Beschränkungen, unterbrochenen Abbiegevorgängen und Ablehnungen enden. Streaming-Antworten verwenden benannte, vom Server gesendete Ereignisse, und die Kompatibilitätsrichtlinien von Anthropic erfordern, dass Clients neue Ereignistypen tolerieren.

Empfehlung: Reduzieren Sie nicht alle erfolgreichen Endstatus auf „abgeschlossen“. Behalten Sie den Upstream-Stoppgrund in der nativen Antwort und in der Gateway-Telemetrie bei. Anwendungen müssen möglicherweise ein Tool ausführen, eine angehaltene Runde fortsetzen, den Kontext reduzieren oder eine Ablehnung anzeigen.

Der Stream-Proxy sollte Ereignisse erkennen, die für die Buchhaltung und Lebenszyklusverwaltung erforderlich sind, und gleichzeitig vorwärtskompatibel bleiben:

• Unbekannte Ereignistypen weiterleiten, wenn die Richtlinie des Mandanten natives Pass-Through zulässt.
• Behalten Sie den Rohereignisnamen und die Sequenzposition in begrenzten Diagnosemetadaten bei.
• Verwenden Sie keine erschöpfende Aufzählung, die den Stream bei einem unbekannten additiven Ereignis schließt.
• Unterscheiden Sie ein Upstream-Fehlerereignis von einer Transportunterbrechung und einem Clientabbruch.
• Nutzung nur aus maßgeblichen Feldern abschließen; Markieren Sie unvollständige Streams als vorläufig, wenn die endgültige Nutzung nicht verfügbar ist.

Wenn das Gateway auch einen OpenAI-förmigen Endpunkt bereitstellt, halten Sie diesen Adapter vom nativen Nachrichtenpfad getrennt. Die OpenAI-Kompatibilitätsebene von Anthropic weist dokumentierte Feld- und Funktionseinschränkungen auf. Ein gemeinsamer interner Umschlag kann beim Routing helfen, darf jedoch nicht die Inhaltsblockreihenfolge, Cache-Kontrollen, Denksignaturen, den Tool-Status oder anbieterspezifische Stoppgründe verwerfen.

Buchhaltung versioniert machen

Fakt: Bei der Verwendung des Prompt-Cache werden gewöhnliche Eingabe-Tokens, Eingabe-Tokens für die Cache-Erstellung und Cache-Lese-Eingabe-Tokens getrennt. Der gesamte Inputverbrauch muss alle anwendbaren Kategorien berücksichtigen.

Eine Versions- oder Betaänderung kann die Cache-Berechtigung, die Inhaltsdarstellung oder zurückgegebene Nutzungsfelder ändern. Daher sollte jedes Nutzungsereignis Folgendes enthalten:

• Gewünschte und wirksame API Version.
• Angeforderte und zugelassene Beta-Sets.
• Mandant, API Schlüssel, Richtlinie, Route, Modell, Region und Upstream-Anfrage-ID.
• Status, Stoppgrund, Stream-Abschlussstatus und Fehlerzuordnung.
• Eingabe-, Ausgabe-, Cache-Erstellungs- und Cache-Lese-Token-Kategorien.
• Preiskatalogversion und vorläufiger oder endgültiger Kostenstand.

Anhand dieser Dimensionen kann unified AI API billing erklären, warum ansonsten ähnliche Anfragen unterschiedliche Kosten verursachten. Vermeiden Sie die Abrechnung anhand einer einzigen kombinierten Token-Zählung, wenn der Anbieter Kategorien mit unterschiedlichen Tarifen bereitstellt.

Testen Sie, bevor Sie eine Version oder Beta aktivieren

Erstellen Sie Vertragsbestandteile für gewöhnlichen Text, Streaming-Text, Tool-Aufrufe, strukturierte Ausgabe, Ablehnungen, Token-Kürzung, Erschöpfung des Kontextfensters, pausierte Runden, Eingabeaufforderungs-Caching, fehlerhafte Anfragen, Ratenbeschränkungen und Mid-Stream-Fehler.

Vergleichen Sie für jedes Spiel mehr als HTTP Status. Erfassen Sie Inhaltsblocktyp und -reihenfolge, Stoppgrund, Tool-IDs und -Argumente, Ereignissequenz, Vorhandensein von Nutzungsfeldern, Cache-Kategorien und Fehlerform. Speichern Sie genehmigte strukturelle Erwartungen statt exakter Prosaausgabe.

Verwenden Sie Schattenanfragen nur, wenn die doppelte Ausführung sicher ist. Anfragen mit Tools, externen Nebenwirkungen, sensiblen Daten oder Materialkosten können ungeeignet sein. Spielen Sie für diese Arbeitslasten desinfizierte Geräte in einer kontrollierten Umgebung wieder.

Vorhersage: Neue Versionen und Betafunktionen werden weiterhin Antwortvarianten und Ereignisse hinzufügen. Ein Gateway, das auf Fähigkeitsdatensätzen und additivem Parsing basiert, wird diese Änderungen normalerweise mit weniger Notfallaufwand absorbieren als eines, das auf festen Aufzählungen und globalen Standardwerten basiert.

Funktionen sicher einführen und außer Betrieb nehmen

Bewerben Sie eine Funktion durch die Status „Testen“, „Intern“, „Opt-in“, „Canary“, „Verfügbar“, „Veraltet“ und „Blockiert“. Vergleichen Sie beim Canarying Statusverteilungen, Stoppgründe, Inhaltsblocksequenzen, Toolverhalten, Nutzungsfelder, Latenz und Cache-Ergebnisse. Definieren Sie Rollback-Schwellenwerte, bevor der Datenverkehr beginnt.

Der Ruhestand sollte schrittweise erfolgen:

1. Blockieren Sie die Einführung neuer Mandanten, während bestehende Zuweisungen fortgeführt werden.
2. Identifizieren Sie betroffene Mandanten, Schlüssel, Modelle und aktuelle Anforderungsmuster.
3. Stellen Sie einen Kompatibilitätsbericht oder einen Testendpunkt für den Ersatz bereit.
4. Warnung bei zugelassenen Anfragen und Veröffentlichung einer festen Frist.
5. Erfordern Sie explizite Ausnahmen mit Eigentümern und Ablaufdaten.
6. Blockieren Sie die Funktion und bewahren Sie den Registrierungseintrag für historische Prüfungen und Abrechnungsinterpretationen auf.

Pinning erhöht die Reproduzierbarkeit, erweitert aber die Testmatrix. Eine Gateway-weite Version reduziert Betriebsvarianten, koppelt jedoch unabhängige Mandanten an einen Migrationsplan. Ein umfassender Beta-Pass-Through beschleunigt den Funktionszugriff, schwächt jedoch die Kosten-, Residenz- und Supportgarantien. Für einen mandantenfähigen Dienst ist eine explizite mandantenspezifische Richtlinie normalerweise der vertretbare Mittelweg.

Implementierungs-Checkliste

• Erfordern Sie eine Versionsrichtlinie für jeden Mandanten oder API Schlüssel.
• Verwalten Sie die Datensätze zu getesteten Versionen und Betafunktionen.
• Lehnen Sie fehlerhafte, unbekannte oder nicht autorisierte Funktionen vor dem Versand ab.
• Wählen Sie Routen erst aus, nachdem die vollständige Protokollanfrage aufgelöst wurde.
• Native Inhaltsblöcke, Stoppgründe, Nutzungsfelder und Streams beibehalten.
• Additive Stream-Ereignisse sicher weiterleiten und ihre Ereignisnamen beibehalten.
• Erfassen Sie angeforderte und effektive Protokollwerte zu Nutzungs- und Prüfereignissen.
• Führen Sie Vertragsfixierungen und kontrollierte Kanarienvögel aus, bevor Sie die Standardeinstellungen ändern.
• Alte Funktionen durch maßvolle Einführungskontrollen außer Betrieb nehmen, nicht durch stillschweigendes Umschreiben.

Die wichtigste Designentscheidung ist einfach: Versions- und Beta-Header sind Richtlinieneingaben. Sobald das Gateway sie als Fähigkeiten zulässt, weiterleitet, testet und misst, wird die native API Kompatibilität steuerbar, ohne dass experimentelles Verhalten als normale HTTP Metadaten vorgetäuscht werden muss.

Verwandte Lektüre

• unter Berücksichtigung der endgültigen Nutzung, Stornierungen und teilweisen Streaming-Antworten