Gouverner Anthropic API versions et en-têtes bêta dans une passerelle multi-locataires

Une passerelle API compatible Anthropic ne doit pas traiter anthropic-version et anthropic-beta comme des en-têtes pass-through ordinaires. Ils sélectionnent le comportement du protocole et les fonctionnalités expérimentales qui peuvent modifier les règles de validation, les blocs de réponse, les événements de streaming, la disponibilité, les tarifs et la comptabilité du cache.

Le problème pratique est de préserver le comportement natif Claude sans permettre aux en-têtes de requête d'un locataire de contourner la politique de la plate-forme. La solution consiste à faire de l'admission du protocole une décision de passerelle de premier ordre : authentifier l'appelant, résoudre sa politique de version, valider les fonctionnalités bêta demandées, sélectionner une route compatible et enregistrer exactement ce qui a été envoyé en amont.

Définir les limites de la stratégie

Fait : Les requêtes directes Claude API nécessitent un en-tête anthropic-version, bien que les SDK officiels le fournissent normalement. Anthropic fonctionnalités bêta sont demandées via anthropic-beta ou un paramètre bêta spécifique à SDK.

Recommandation : Interprétez les deux valeurs comme des capacités demandées, et non comme des instructions de routage fiables. Un client peut demander une version ou une version bêta, mais la passerelle décide si cette combinaison est prise en charge pour le locataire, la clé API, le modèle, la région et les informations d'identification en amont.

Ne supprimez pas silencieusement une version bêta non approuvée. Cela peut transformer une demande explicite en un appel réussi avec une sémantique différente. Rejetez-le avant l'envoi avec une erreur de passerelle stable qui identifie la fonctionnalité non prise en charge sans exposer les informations d'identification en amont ou les détails de l'itinéraire interne.

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

Renvoie une réponse 4xx pour les échecs d'admission et réserve les réponses 5xx pour les échecs de passerelle ou en amont. Gardez le schéma d'erreur stable même si Anthropic modifie son propre format d'erreur.

Créer un registre de versions et de fonctionnalités

Une chaîne de version en forme de date est facile à valider syntaxiquement mais impossible à gouverner à partir de la seule syntaxe. La passerelle a besoin d'un registre contenant les versions et les fonctionnalités bêta qu'elle a réellement testées.

Enregistrements de version

Chaque enregistrement de version doit inclure :

• Identificateur de version canonique et état du cycle de vie : test, disponible, par défaut, obsolète ou bloqué.
• Champs de requête pris en charge, blocs de contenu, motifs d'arrêt, champs d'utilisation et événements de streaming connus.
• Modèles compatibles, plates-formes en amont, régions et pools d'informations d'identification.
• Résultats du contrat et date du dernier test réussi.
• Compatibilité du catalogue de prix et toutes implications connues en matière de comptabilité cache.
• Restrictions d'adoption, dates d'obsolescence et conseils de remplacement.

Enregistrements bêta

Les fonctionnalités bêta nécessitent des enregistrements distincts, car leur disponibilité et leur risque opérationnel peuvent différer de la version de base API. Enregistrez le nom canonique de la version bêta, les versions et modèles compatibles, les régions autorisées, les champs de requête obligatoires, les blocages de réponse possibles, les événements de streaming, le traitement tarifaire, la classe de limite de débit et l'état de déploiement.

Modélisez ceci sous forme de données plutôt que de conditions d'application. Un évaluateur de politiques peut alors répondre à une question concrète : « La clé K peut-elle utiliser la version V avec l’ensemble bêta B sur la route R ? Le même catalogue peut prendre en charge une passerelle multimodèle API pour les équipes sans obliger chaque adaptateur à implémenter ses propres règles de locataire.

Donner à chaque locataire une politique de version explicite

Supporte trois modes de stratégie :

1. Épinglé : Le locataire ou la clé doit utiliser une version exacte. Rejeter les valeurs manquantes ou différentes.
2. Gateway current : Un en-tête manquant correspond à la valeur par défaut testée de la passerelle. Une valeur client explicite est toujours validée.
3. Plage approuvée : Le client peut sélectionner parmi une liste autorisée limitée de versions testées.

Évitez d'interpréter « plage » comme chaque date entre deux points de terminaison. Anthropic versions sont des identifiants, pas une séquence sémantique continue de versions. Stockez un ensemble explicite de valeurs admises.

Résolvez la version effective avant de sélectionner une route en amont :

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)

Gardez les valeurs demandées et effectives séparées. Ils peuvent différer lorsqu'une stratégie fournit une valeur par défaut, mais un enregistrement d'audit doit rendre cette substitution visible.

Analyser structurellement les en-têtes bêta

N'autorisez pas les fonctionnalités bêta avec correspondance de sous-chaînes ou égalité de chaînes brutes. Analysez l'en-tête selon la syntaxe acceptée par le API en amont, rejetez les entrées mal formées ou en double, le cas échéant, et comparez les identifiants de fonctionnalités canoniques.

L'ordre canonique est utile pour les clés de cache de règles et les dimensions de télémétrie :

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

Conservez suffisamment de métadonnées de requête pour le débogage, mais ne conservez pas indéfiniment les en-têtes bruts lorsque les identifiants normalisés sont suffisants. Les journaux d'en-tête peuvent contenir des métadonnées client inutiles, et leur stockage augmente la portée des contrôles de conservation et d'accès.

L'autorisation bêta doit être limitée au client et de préférence à la clé. Une clé de développement peut recevoir une capacité expérimentale sans l’accorder automatiquement aux charges de travail de production. Les modifications apportées aux listes autorisées doivent produire des événements d'audit du plan de contrôle avec l'acteur, la raison, l'état précédent, le nouvel état et l'heure d'effet.

Admission séparée du routage

Une requête n'est pas routable simplement parce que son nom de modèle existe. L'éligibilité des routes est l'intersection des capacités du protocole et de l'infrastructure :

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

Si aucune route ne satisfait l'ensemble complet, échouez avant d'envoyer la requête. N'abandonnez pas les fonctionnalités bêta pour rendre un itinéraire éligible. Ne remplacez pas automatiquement une autre version à moins que la stratégie du locataire ne définisse explicitement ce comportement.

Cette séparation est importante dans les passerelles qui regroupent les informations d'identification, prennent en charge les clés fournies par le client ou opèrent dans plusieurs régions. Deux itinéraires vers le même modèle peuvent avoir des accès aux fonctionnalités, des contraintes de résidence ou des limites de débit différents.

Préserver la sémantique de réponse native

Fait : Anthropic Les réponses aux messages peuvent se terminer par des raisons telles que l'utilisation de l'outil, les limites de jetons, les limites de la fenêtre contextuelle, les tours en pause et les refus. Les réponses en streaming utilisent des événements nommés envoyés par le serveur, et les conseils de compatibilité de Anthropic exigent que les clients tolèrent les nouveaux types d'événements.

Recommandation : Ne réduisez pas tous les états terminaux réussis en « terminé ». Conservez le motif d’arrêt en amont dans la réponse native et dans la télémétrie de la passerelle. Les applications peuvent avoir besoin d'exécuter un outil, de poursuivre un tour en pause, de réduire le contexte ou de faire apparaître un refus.

Le proxy de flux doit reconnaître les événements requis pour la comptabilité et la gestion du cycle de vie tout en restant compatible avec les versions ultérieures :

• Transférer les types d'événements inconnus lorsque la stratégie du locataire autorise le transfert natif.
• Conserver le nom brut de l'événement et la position de la séquence dans les métadonnées de diagnostic limitées.
• N'utilisez pas d'énumération exhaustive qui ferme le flux sur un événement additif inconnu.
• Distinguer un événement d'erreur en amont d'une déconnexion de transport et d'une annulation client.
• Finaliser l'utilisation uniquement à partir des champs faisant autorité ; marquer les flux incomplets comme provisoires lorsque l'utilisation finale n'est pas disponible.

Si la passerelle expose également un point de terminaison de forme OpenAI, conservez cet adaptateur séparé du chemin natif des messages. La couche de compatibilité OpenAI de Anthropic présente des limitations documentées en matière de champs et de fonctionnalités. Une enveloppe interne commune peut faciliter le routage, mais elle ne doit pas ignorer l'ordre des blocs de contenu, les contrôles de cache, les signatures de réflexion, l'état de l'outil ou les raisons d'arrêt spécifiques au fournisseur.

Rendre la comptabilité compatible avec la version

Fait : L'utilisation du cache d'invite sépare les jetons d'entrée ordinaires, les jetons d'entrée de création de cache et les jetons d'entrée de lecture du cache. La consommation totale d'intrants doit tenir compte de toutes les catégories applicables.

Une modification de version ou de version bêta peut modifier l'éligibilité au cache, la représentation du contenu ou les champs d'utilisation renvoyés. Par conséquent, chaque événement d'utilisation doit inclure :

• Version API demandée et effective.
• Ensembles bêta demandés et admis.
• Client, API clé, stratégie, itinéraire, modèle, région et ID de demande en amont.
• Statut, motif de l'arrêt, état d'achèvement du flux et attribution des erreurs.
• Catégories de jetons d'entrée, de sortie, de création de cache et de lecture du cache.
• Version du catalogue tarifaire et état des coûts provisoire ou finalisé.

Ces dimensions permettent à l'IA unifiée API facturation d'expliquer pourquoi des demandes similaires généraient des coûts différents. Évitez de facturer à partir d'un seul nombre de jetons combinés lorsque le fournisseur expose des catégories avec des tarifs différents.

Tester avant d'activer une version ou une version bêta

Créez des contrats pour le texte ordinaire, le texte en streaming, les appels d'outils, la sortie structurée, les refus, la troncature de jeton, l'épuisement de la fenêtre contextuelle, les tours en pause, la mise en cache des invites, les requêtes mal formées, les limites de débit et les erreurs en cours de flux.

Pour chaque appareil, comparez plus de HTTP statuts. Capturez le type et l'ordre des blocs de contenu, la raison de l'arrêt, les identifiants et arguments des outils, la séquence d'événements, la présence du champ d'utilisation, les catégories de cache et la forme de l'erreur. Stockez les attentes structurelles approuvées plutôt que le résultat exact.

Utilisez les requêtes fantômes uniquement lorsque l'exécution en double est sûre. Les demandes comportant des outils, des effets secondaires externes, des données sensibles ou un coût matériel peuvent être inappropriées. Pour ces charges de travail, rejouez des appareils nettoyés dans un environnement contrôlé.

Prédiction : Les nouvelles versions et fonctionnalités bêta continueront d'ajouter des variantes de réponse et des événements. Une passerelle conçue autour d'enregistrements de capacités et d'une analyse additive absorbera généralement ces modifications avec moins de travail d'urgence qu'une passerelle construite autour d'énumérations fixes et de valeurs par défaut globales.

Déployez et retirez des fonctionnalités en toute sécurité

Promouvoir une fonctionnalité via des états de test, internes, opt-in, Canary, disponibles, obsolètes et bloqués. Pendant la mise en ligne, comparez les distributions d'état, les raisons d'arrêt, les séquences de blocs de contenu, le comportement de l'outil, les champs d'utilisation, la latence et les résultats du cache. Définissez des seuils de restauration avant le début du trafic.

La retraite devrait se faire par étapes :

1. Bloquer l'adoption de nouveaux locataires pendant que les attributions existantes se poursuivent.
2. Identifiez les locataires, les clés, les modèles et les modèles de requêtes récents concernés.
3. Fournissez un rapport de compatibilité ou un point de terminaison de test pour le remplacement.
4. Avertir des demandes admises et publier un délai ferme.
5. Exiger des exceptions explicites avec les propriétaires et les dates d'expiration.
6. Bloquez la fonctionnalité et conservez l'enregistrement du registre pour l'audit historique et l'interprétation de la facturation.

L'épinglage augmente la reproductibilité mais élargit la matrice de test. Une version à l'échelle de la passerelle réduit les variantes opérationnelles mais associe les locataires non liés à un seul calendrier de migration. Une large diffusion bêta accélère l’accès aux fonctionnalités mais affaiblit les garanties de coût, de résidence et de support. Pour un service multi-locataire, une politique explicite par locataire constitue généralement le juste milieu défendable.

Liste de contrôle de mise en œuvre

• Exiger une stratégie de version pour chaque locataire ou clé API.
• Maintenir les enregistrements des versions testées et des fonctionnalités bêta.
• Rejeter les fonctionnalités mal formées, inconnues ou non autorisées avant l'expédition.
• Sélectionnez les routes uniquement après avoir résolu la demande de protocole complète.
• Préserver les blocs de contenu natifs, les motifs d'arrêt, les champs d'utilisation et les flux.
• Transférer les événements de flux additifs en toute sécurité et conserver leurs noms d'événements.
• Enregistrez les valeurs de protocole demandées et efficaces sur les événements d'utilisation et d'audit.
• Exécutez les appareils contractuels et contrôlez les canaris avant de modifier les valeurs par défaut.
• Retirez les anciennes fonctionnalités grâce à des contrôles d'adoption mesurés, et non à des réécritures silencieuses.

La décision clé en matière de conception est simple : les en-têtes de version et bêta sont des entrées de stratégie. Une fois que la passerelle les admet, les achemine, les teste et les mesure en tant que capacités, API la compatibilité native devient gouvernable sans prétendre que le comportement expérimental est des métadonnées HTTP ordinaires.

Lecture connexe

• compte tenu de l'utilisation finale, des annulations et des réponses de streaming partielles