Switchyard AI Gateway : guide complet Rust (2026)

Switchyard AI Gateway est à tester comme une couche de conversion et de routage, pas comme une solution déjà prête pour remplacer votre passerelle de production. Cette semaine, commencez par le proxy Python et son lanceur Claude Code ou Codex, puis validez séparément le serveur Rust si vous recherchez un service autonome et durable. Le projet reste en évolution rapide, et la frontière entre les composants doit être vérifiée avant chaque déploiement.

Cette page s’adresse à trois profils : vous développez un agent qui doit changer de backend sans modifier son client ; vous construisez une plateforme interne de routage LLM ; ou vous comparez une exécution Python avec un Rust server indépendant. Si votre besoin se limite à appeler un seul fournisseur depuis un script, Switchyard ajoute probablement une couche de configuration inutile.

Dernière mise à jour : 14 août 2026. Les informations techniques ont été revérifiées à partir du dépôt officiel, de la structure Python, des fichiers Cargo, du guide d’installation et de la documentation du serveur.

Pourquoi un agent ne peut pas toujours parler directement à chaque modèle

Claude Code, Codex et une application maison ne parlent pas nécessairement le même dialecte HTTP. Même lorsqu’ils utilisent tous du JSON, les différences portent sur les noms de champs, le format des messages, les outils, les réponses structurées, le raisonnement et le streaming.

Un agent peut attendre un format Anthropic Messages alors que votre serveur local expose /v1/chat/completions. À l’inverse, un backend compatible OpenAI peut accepter le texte principal mais ignorer une partie des outils ou des métadonnées envoyées par le client. Le résultat est trompeur : la connexion fonctionne, mais l’agent perd une capacité importante au premier appel complexe.

Les coûts réels ne se limitent pas à la conversion :

• Compatibilité fonctionnelle : un modèle qui répond au premier message peut échouer dès qu’un outil, une image ou une réponse structurée est utilisée.
• Gestion des secrets : une clé stockée dans plusieurs clients augmente les risques de fuite, de rotation oubliée et de permissions excessives.
• Stabilité des sessions : un agent multi-tour peut nécessiter une affinité vers la même route ou le même profil.
• Diagnostic fragmenté : sans métriques intermédiaires, vous ne savez pas si l’erreur vient du client, du proxy, du fournisseur ou du modèle.
• Dépendance au poste local : un lanceur exécuté sur votre ordinateur disparaît dès que le terminal, la session ou la machine s’arrête.

Switchyard se place précisément entre le client et les backends. Le client conserve son format habituel ; la passerelle sélectionne une cible, convertit la requête si nécessaire, transmet l’appel, puis reconstruit la réponse dans le format attendu. C’est une architecture de médiation, non un moteur d’inférence. (Dépôt officiel de Switchyard)

Pour comprendre ce type de chaîne dans un contexte de développement assisté, vous pouvez aussi consulter notre guide sur les règles et compétences d’un flux de codage avec l’IA.

Switchyard AI Gateway : une conversion utile, mais limitée par la route

La documentation officielle décrit trois familles de formats : OpenAI Chat Completions, OpenAI Responses et Anthropic Messages. Le proxy peut conserver le protocole natif du client tout en envoyant la requête vers un backend exposant une autre interface. Les backends compatibles OpenAI, les serveurs locaux et certains fournisseurs hébergés entrent dans cette logique lorsqu’ils respectent réellement le contrat annoncé. (Documentation officielle des protocoles)

La distinction entre capacité supportée, capacité expérimentale et capacité dépendante du backend est essentielle. Une conversion de texte simple est généralement plus facile à valider qu’un appel d’outil en plusieurs tours. Pour un workflow audio ou vidéo, par exemple, vous devrez vérifier le transport des pièces jointes, les types MIME, la taille des contenus et la conservation des métadonnées. La présence d’un champ dans la requête ne prouve pas qu’il est correctement interprété en aval.

Attention : la conversion de protocole ne transforme pas automatiquement les capacités d’un modèle. Si le backend ne sait pas exécuter les outils, Switchyard ne peut pas les lui ajouter ; il ne fait que relayer ou adapter la demande.

Deux architectures à ne pas confondre : proxy Python et serveur Rust

Le titre de cet article parle d’un projet « écrit en Rust », mais cette formule est trop large si elle laisse croire que tous les usages passent par le même binaire. La vérification du projet montre une coexistence de deux chemins.

Le chemin principal historique du proxy et de la CLI comprend une implémentation Python. Il permet d’installer les extras serveur ou CLI, de lancer Claude Code et Codex, de définir des profils de routage et d’exécuter un proxy local. Le dépôt contient également une arborescence Rust avec un serveur indépendant, des bibliothèques de protocole et des algorithmes de routage. (Structure officielle du projet)

Le choix du Rust server devient pertinent si vous voulez un binaire indépendant, une configuration déclarative claire et un service séparé du terminal d’un développeur. Le choix Python est plus direct pour un essai local, un script d’automatisation ou un lanceur d’agent. Il ne s’agit pas d’un classement absolu : le meilleur chemin dépend de la durée de vie du service, de votre chaîne de déploiement et du niveau de personnalisation attendu.

Cette clarification évite une erreur fréquente : voir Cargo.toml, des crates et un répertoire Rust, puis conclure que la commande de lancement Python et le serveur autonome sont deux interfaces équivalentes. Ils représentent des composants liés, mais leurs parcours d’installation et leurs contrats de configuration sont distincts. (Documentation d’installation et d’architecture)

Routage : simple transparence ou décision entre plusieurs modèles

Switchyard propose plusieurs mécanismes. Le mode passthrough envoie une route vers une cible unique. Il constitue le meilleur point de départ pour tester la conversion, car il retire la variable « choix du modèle ». Le routage aléatoire répartit ensuite les requêtes selon une proportion configurée. C’est utile pour une comparaison A/B, un banc de test ou une expérience de trafic contrôlée.

Un routeur fondé sur un classifieur peut décider si une requête doit utiliser une cible faible ou forte. Un stage router peut exploiter des signaux déjà présents dans la conversation, comme une erreur d’outil ou un résultat intermédiaire. Le projet documente également des scénarios d’escalade dans lesquels une première réponse est évaluée avant de renvoyer la demande vers une cible plus capable. (Mécanismes de routage documentés)

Ne transformez pas ces mécanismes en promesse automatique de réduction des coûts ou d’amélioration de la qualité. Un classifieur ajoute lui-même une décision et parfois un appel supplémentaire. Un mauvais seuil peut envoyer les tâches simples vers un modèle trop puissant, ou dégrader les tâches complexes en les orientant trop longtemps vers une cible faible.

Avant de choisir une stratégie, séparez quatre questions :

1. La décision peut-elle être déterministe ? Pour un benchmark, le routage aléatoire est plus facile à reproduire.
2. Le contenu de la requête doit-il être analysé ? Si oui, vous devez mesurer la latence et les erreurs du classifieur.
3. La conversation doit-elle rester sur la même cible ? Un agent multi-tour peut bénéficier d’une session affinitaire.
4. Que se passe-t-il en cas d’échec ? Une route de repli doit être testée avec les mêmes outils et le même format de réponse.

Pour un premier déploiement, commencez par une route unique, ajoutez un second backend, puis activez le routage. Cette progression vous permet d’identifier la couche qui introduit un problème.

Première étape : connecter Claude Code ou Codex sans masquer les erreurs

Le lanceur est conçu pour réduire la configuration manuelle. Le principe consiste à installer l’extra CLI, à définir la clé API et l’URL du backend, puis à demander à Switchyard de lancer l’agent. Le proxy local est démarré pour la session et le client est orienté vers celui-ci. Le dépôt documente des commandes dédiées à Claude Code, Codex et d’autres clients compatibles. (Guide officiel du lanceur)

Procédez dans cet ordre :

1. Choisissez un seul backend de référence. Utilisez un endpoint dont le format, le modèle et la gestion des outils sont documentés.
2. Créez une clé limitée. Évitez de réutiliser une clé de production dans votre poste de développement.
3. Testez une requête texte simple. Vérifiez la réponse, le modèle sélectionné et le format de sortie avant d’ajouter un agent.
4. Lancez Claude Code ou Codex via Switchyard. Utilisez une route directe avant d’activer un classifieur.
5. Testez un appel d’outil. Ajoutez une commande sans effet destructif et observez les arguments réellement transmis.
6. Testez le streaming. Certains écarts n’apparaissent qu’avec les événements partiels ou les réponses longues.
7. Testez l’échec du backend. Coupez volontairement la cible ou fournissez une route indisponible afin de vérifier le comportement de repli.
8. Conservez les journaux de corrélation. Sans identifiant de requête, il devient difficile de relier l’erreur du client à celle du serveur.

Les limites du lanceur doivent rester visibles. La présence d’une commande launch claude ne garantit pas que tous les modèles fonctionnent avec MCP, les outils ou les alias de modèle. Le dépôt signale notamment une contrainte spécifique pour des routes reposant sur Bedrock : les noms d’outils peuvent dépasser la limite acceptée par ce backend dans certaines intégrations MCP. Il faut alors changer de cible ou adapter la configuration. (Limitation MCP décrite dans la documentation)

Le serveur indépendant : quand le proxy doit survivre au terminal

Un proxy local lancé avec une session d’agent est adapté à un développeur qui expérimente. Il l’est moins si plusieurs machines, pipelines ou équipes doivent l’utiliser. Dans ce cas, vous devez déployer un service indépendant, avec une adresse stable, une rotation de clés, une supervision et une procédure de redémarrage.

Le serveur Rust officiel possède son propre binaire et son propre schéma TOML. La documentation prévoit une validation à blanc, un démarrage sur une adresse et un port choisis, puis un contrôle de santé. Cela ressemble davantage au cycle de vie d’un service qu’à celui d’un outil de terminal. (Documentation du serveur autonome)

La configuration doit séparer au moins :

• les clients, c’est-à-dire les formats et points d’entrée acceptés ;
• les cibles, c’est-à-dire les fournisseurs ou serveurs de modèles ;
• les routes, qui déterminent la sélection et le repli ;
• les identifiants, qui ne doivent pas être commis dans le dépôt ;
• les métriques, indispensables pour comparer latence, erreurs et volume.

Si vous prévoyez un hôte distant, ne placez pas le fichier de configuration dans un répertoire accessible par tous les utilisateurs. Utilisez un compte de service, des permissions minimales et un mécanisme de secret adapté à votre environnement. Le fait qu’un serveur soit écrit en Rust ne règle pas la gestion des clés, le chiffrement du transport ou la séparation des locataires.

Ce que les statistiques permettent réellement de décider

Les métriques annoncées couvrent notamment les requêtes, les erreurs, la latence, les jetons et le coût ou la surcharge de routage selon le chemin utilisé. Ces données sont utiles pour comparer deux routes, mais elles ne remplacent pas une observation complète du fournisseur.

Vous devez distinguer :

• le temps d’attente avant transmission ;
• le temps consommé par la conversion ;
• le temps d’attente du backend ;
• le temps de réception du premier fragment ;
• le temps total de génération ;
• le nombre de jetons réellement facturés par le fournisseur.

Pour un agent de codage, la latence du premier fragment n’a pas le même impact que la durée totale d’une génération. Pour un pipeline audio ou vidéo, la taille des contenus et les transferts réseau peuvent devenir plus importants que le temps de décision du routeur. Une moyenne globale peut donc masquer un problème propre à un type de requête.

La session affinitaire mérite également un test séparé. Si deux tours d’une même tâche sont envoyés vers des cibles différentes, le fournisseur peut perdre un état externe, une capacité de cache ou une hypothèse de contexte. Ce n’est pas systématiquement incorrect, mais il faut le savoir avant de comparer les résultats.

Checklist d’acceptation avant un usage durable

• [ ] Le format entrant de Claude Code, Codex ou de votre application est identifié.
• [ ] Le format sortant de chaque backend est documenté et testé.
• [ ] Une requête texte, une réponse en streaming et un appel d’outil ont été validés.
• [ ] Les clés API sont séparées entre développement, test et production.
• [ ] Le mode Python ou le serveur Rust a été choisi explicitement.
• [ ] Le fichier de configuration correspond au runtime choisi.
• [ ] Une route directe fonctionne avant l’activation d’un routeur intelligent.
• [ ] Le comportement de repli est testé lorsque la cible est indisponible.
• [ ] Les sessions multi-tour ont été testées avec et sans affinité.
• [ ] Les métriques de latence, erreurs et jetons sont exportées.
• [ ] Le service redémarre correctement après une coupure.
• [ ] Les journaux ne contiennent ni clé ni contenu sensible inutile.
• [ ] Les limites des outils, de MCP et des réponses structurées sont écrites dans la documentation interne.

Pour compléter cette vérification par une réflexion sur l’environnement d’exécution, voyez aussi notre dossier sur le choix entre poste local haut de gamme et environnement cloud pour l’IA.

FAQ : les réponses à vérifier avant l’installation

Switchyard AI Gateway est-il seulement un routeur de modèles ?

Non. Le routage est central, mais le projet traite aussi la conversion entre plusieurs formats d’API, le lancement d’agents et la collecte de statistiques. Il faut toutefois distinguer ce qui appartient au proxy Python, au serveur Rust et aux bibliothèques intégrables. Votre installation ne fournit pas automatiquement toutes les capacités dans un seul processus.

Switchyard est-il écrit en Rust ou en Python ?

Les deux composants coexistent. La ligne proxy et CLI comprend une implémentation Python, tandis que switchyard-server est un binaire Rust séparé, avec une configuration TOML distincte. Le bon choix dépend du mode d’exécution recherché. Ne déduisez pas l’architecture complète de la seule présence d’un fichier Cargo.

Comment connecter Switchyard à Claude Code ?

Installez le parcours CLI, préparez la clé et l’URL de base du backend, puis utilisez le lanceur Claude Code. Commencez avec une route directe et un modèle explicitement indiqué. Testez ensuite les outils, le streaming, les fonctions MCP et les erreurs de backend. Le lanceur simplifie l’orientation du client, mais ne vérifie pas à votre place la compatibilité fonctionnelle du modèle.

Quels protocoles sont pris en charge ?

Les formats documentés sont OpenAI Chat Completions, OpenAI Responses et Anthropic Messages. La conversion exacte dépend du chemin et du backend. Une compatibilité OpenAI minimale peut suffire pour une conversation texte, mais échouer pour les outils, les réponses structurées ou les événements de streaming. Vous devez donc valider chaque fonction nécessaire à votre agent.

Peut-il être déployé comme proxy indépendant ?

Oui, avec le serveur autonome. Vous définissez les clients, les cibles et les routes, puis vous exécutez le service sur un hôte persistant. Le serveur Rust doit être traité comme un composant distinct du proxy Python. Pour une équipe, ajoutez supervision, rotation des secrets, contrôle de santé, journaux et tests de reprise avant d’exposer le point d’entrée à plusieurs utilisateurs.

Quand choisir Switchyard et quand attendre

Switchyard est intéressant si vous avez réellement plusieurs protocoles, plusieurs backends ou plusieurs stratégies de routage à gérer. Il peut réduire les changements côté client, rendre les tests A/B plus explicites et centraliser une partie des statistiques. En revanche, son statut évolutif impose une validation stricte. Le dépôt officiel indique une maturité pré-alpha et déconseille l’usage en production dans l’état documenté. (État de maturité indiqué par le projet)

Choisissez-le maintenant pour :

• un laboratoire de routage LLM ;
• une expérimentation avec Claude Code ou Codex ;
• une comparaison entre serveur local et fournisseur distant ;
• un prototype de passerelle interne ;
• l’intégration d’algorithmes de routage dans une application Rust.

Attendez ou isolez-le si vous avez besoin d’un contrat d’API stable, d’un support fournisseur garanti, d’une conformité formalisée ou d’un service critique sans période de qualification. Dans ce cas, commencez par une zone de test séparée et conservez un chemin direct vers le fournisseur.

La solution actuelle est souvent un poste Windows, Linux ou macOS qui lance le proxy dans un terminal. Elle est simple, mais elle dépend de la machine allumée, de la connexion locale, des mises à jour Python et de la conservation correcte des secrets. Un déploiement improvisé sur un ordinateur personnel rend aussi les journaux, les redémarrages et l’accès multi-utilisateur difficiles à contrôler.

Pour un environnement de test distant destiné à Claude Code, Codex ou à un flux d’automatisation, louer une machine Mac auprès de Hashvps peut offrir une base plus pratique : session persistante, accès distant centralisé et séparation entre votre poste quotidien et le service de développement. Cela ne remplace pas une architecture de production ni un GPU dédié, et l’achat d’un Mac reste plus rationnel pour une charge lourde, stable et permanente ou pour un besoin d’interface physique. Mais pour valider Switchyard, tester un Rust server et maintenir temporairement un agent accessible, l’environnement loué évite plusieurs contraintes du poste local sans vous engager immédiatement dans un achat matériel.