OmniRoute Auto Combo : tutoriel budget Agent 2026

Deux contrôles sont à distinguer dans OmniRoute Auto Combo : le plafond monétaire par requête et la limite périodique de tokens par clé. Pour un Agent utilisé en production, commencez par une liste blanche de modèles, ajoutez un budget par requête, activez le repli « strict », puis testez le blocage, la panne d’un fournisseur, l’échec d’identifiants et la limitation de débit avant d’ouvrir la règle à toute l’équipe.

Cette méthode concerne les développeurs qui veulent limiter le coût d’une requête d’Agent, les équipes plateforme qui centralisent plusieurs outils de programmation et les équipes distantes qui préparent le passage d’un relais local à une passerelle toujours disponible. Le principe reste le même pour un Agent de code, un flux audio ou une application de design génératif : aucun modèle non vérifié ne doit entrer silencieusement dans le pool de production.

Le périmètre réel du budget

Le premier piège consiste à appeler « budget » trois mécanismes qui ne répondent pas au même risque.

Le plafond par requête limite le coût estimé d’un appel individuel. Dans la documentation Auto Combo, il est transmis par l’en-tête X-OmniRoute-Budget, exprimé comme un nombre positif représentant le montant maximal autorisé pour la requête. Les candidats dont le coût estimé dépasse cette limite sont filtrés avant la sélection. (github.com)

La limite de tokens par clé protège une période d’utilisation. L’API documente trois portées : model, provider et global. Elle permet aussi trois intervalles de réinitialisation : daily, weekly et monthly, avec monthly comme valeur par défaut indiquée dans le schéma. Une clé peut donc respecter son plafond par requête tout en épuisant sa limite mensuelle, ou l’inverse. (github.com)

Le budget d’équipe relève enfin d’une politique opérationnelle : répartition par projet, membre, client ou environnement. Il ne doit pas être déduit du plafond envoyé par une requête. Pour l’équipe plateforme, il est préférable de créer un point d’entrée distinct pour chaque Agent critique et de conserver une trace de la clé, du combo et du propriétaire de la configuration.

Avant toute modification, rédigez une fiche courte contenant :

• le budget maximal d’une requête ;
• la limite de tokens de la clé ;
• la période de suivi de l’équipe ;
• l’action en cas de dépassement : bloquer, dégrader ou avertir ;
• les modèles autorisés et leur solution de remplacement ;
• la personne capable de reprendre la décision manuellement.

Attention : le repli « cheapest » n’est pas une garantie de non-dépassement. Il signifie que le système peut continuer avec le candidat globalement le moins cher lorsque tous les candidats restent au-dessus du plafond. Pour une règle financière stricte, le comportement attendu est strict, pas cheapest. (github.com)

La liste blanche avant la logique de routage

OmniRoute peut construire un pool virtuel à partir des connexions actives et des identifiants utilisables. Cette souplesse est utile pour explorer plusieurs modèles, mais elle est trop large pour un premier déploiement d’AI Agent : l’ajout ultérieur d’un fournisseur peut modifier le pool sans modification visible du client. Le moteur documente aussi des variantes telles que auto, auto/coding, auto/fast et auto/cheap, chacune orientée vers un objectif différent. (github.com)

Pour une première configuration, ne retenez que les candidats qui remplissent simultanément les conditions suivantes :

1. les identifiants ont été validés avec une requête simple ;
2. le modèle accepte le format réellement envoyé par le client ;
3. les outils nécessaires, comme les appels de fonctions ou la sortie en continu, ont été testés ;
4. le contexte attendu par l’Agent reste compatible avec la fenêtre du modèle ;
5. un remplacement explicite existe en cas d’indisponibilité.

Un candidat doit également recevoir une fiche d’exploitation. Celle-ci indique son usage principal, sa limite connue, la raison de son entrée dans le pool et le modèle de repli autorisé. Pour un Agent de programmation, la liste peut distinguer génération de code, revue, planification et débogage. Pour un flux audio ou vidéo, ajoutez le délai acceptable, la taille des fichiers et la tolérance aux interruptions.

L’objectif n’est pas de constituer le plus grand ensemble possible. Il s’agit de réduire le nombre de chemins non testés. Le pool initial doit être assez petit pour que chaque décision soit explicable dans un journal.

Le budget de requête et le mode strict

La configuration suivante utilise uniquement des valeurs de remplacement ; elle ne doit pas être copiée avec des identifiants ou des adresses réelles.

curl -sS "<OMNIROUTE_BASE_URL>/v1/chat/completions" \
  -H "Authorization: Bearer <AGENT_API_KEY>" \
  -H "Content-Type: application/json" \
  -H "X-OmniRoute-Budget: <REQUEST_BUDGET>" \
  -H "X-OmniRoute-Budget-Fallback: strict" \
  -d '{
    "model": "auto/coding",
    "messages": [
      {
        "role": "user",
        "content": "<TEST_PROMPT>"
      }
    ],
    "stream": false
  }'

Dans cette séquence, X-OmniRoute-Budget applique un plafond à cette seule requête. X-OmniRoute-Budget-Fallback: strict demande au moteur de refuser la sélection si aucun candidat admissible ne respecte le plafond. La documentation précise que les alias block et hard correspondent à cette logique, tandis que cheapest, cheapest-viable et soft renvoient au comportement de repli souple. (github.com)

Pour un combo persistant, la politique peut être stockée dans sa configuration, avec budgetFallback défini sur strict. Une surcharge par en-tête reste utile lorsqu’un même Agent traite des tâches de natures différentes, par exemple une petite correction de code et une génération multimodale lourde.

Le résultat attendu doit être vérifié, et non supposé :

• si un candidat respecte le plafond, la requête est routée vers un modèle admissible ;
• si tous les candidats dépassent le plafond en mode strict, la requête échoue rapidement avec HTTP 402 ;
• si l’en-tête est absent, la configuration enregistrée du combo reprend la main ;
• si la valeur de l’en-tête est invalide, elle ne doit pas être considérée comme une nouvelle politique fiable : il faut consulter le journal et la version installée.

Les champs peuvent évoluer avec les versions. La page de référence consultée identifie une documentation Auto Combo version 3.8.40, mise à jour le 28 juin 2026 ; avant une mise en production, vérifiez la branche ou la version réellement déployée ainsi que le schéma du code correspondant. (github.com)

Le tableau de décision pour le premier déploiement

La règle de choix peut être exprimée simplement :

• Si le dépassement doit être impossible, choisissez strict.
• Si une réponse de secours est acceptable pendant une expérimentation, choisissez cheapest, mais consignez explicitement le risque.
• Si plusieurs Agents partagent la même passerelle mais pas le même niveau de criticité, séparez les clés ou les combos avant d’appliquer les budgets.
• Si un modèle n’a pas été testé avec les outils utilisés, retirez-le du pool, même s’il paraît moins cher.
• Si la raison de routage ne peut pas être expliquée après un test, revenez à une configuration plus petite.

Les quatre simulations indispensables

Une configuration de budget n’est pas validée par une réponse réussie. Elle l’est par la manière dont elle échoue.

Dépassement généralisé

Réduisez temporairement le plafond avec une valeur de test et envoyez une requête connue pour solliciter plusieurs candidats. Le mode strict doit produire une erreur contrôlée, idéalement HTTP 402 selon la documentation, sans basculer vers un modèle plus coûteux. Enregistrez les en-têtes, le corps de l’erreur, le combo utilisé et l’absence de modèle final.

Si une réponse est générée malgré le dépassement, interrompez la validation : le client peut avoir supprimé l’en-tête, le proxy peut filtrer les en-têtes personnalisés ou le combo utilisé n’est peut-être pas une stratégie auto.

Indisponibilité du fournisseur prioritaire

Désactivez temporairement le candidat préféré ou provoquez une indisponibilité contrôlée dans l’environnement de test. Le routeur doit écarter ce candidat et sélectionner un modèle admissible dans la liste blanche. Vérifiez que le repli ne réintroduit pas un modèle hors budget.

Le mécanisme Auto Combo tient compte de l’état de santé, du quota, du coût, de la latence et de l’adéquation à la tâche. Cela signifie que le modèle le moins cher n’est pas nécessairement choisi dans la variante équilibrée ; la stratégie et les poids influencent la décision. (github.com)

Identifiant invalide

Remplacez une clé de fournisseur par une valeur volontairement invalide, puis exécutez une requête non destructive. L’échec doit rester identifiable comme un problème d’authentification ou de connexion, et non être confondu avec un dépassement de budget. Après correction, relancez le test de validation des identifiants avant de remettre le candidat dans le pool.

Limitation de débit

Envoyez plusieurs requêtes contrôlées jusqu’à provoquer une réponse de limitation, sans utiliser de données sensibles. Contrôlez la réaction du combo, le nombre de tentatives et le comportement de reprise du client. Un Agent qui réessaie lui-même peut contourner l’intention du budget par requête en multipliant les appels : le budget doit donc être observé au niveau de chaque tentative et au niveau de la clé.

Les journaux de requêtes et d’utilisation sont essentiels pour cette étape. L’API documente notamment les routes de suivi des journaux de requêtes et des limites de tokens, tandis que la chaîne de traitement indique que les appels, les coûts estimés et les résultats de routage sont enregistrés dans les composants d’usage prévus à cet effet. (github.com)

Expérience d’exploitation : une réponse correcte ne prouve pas que le budget est respecté. Il faut conserver simultanément la décision de routage, le modèle final, le statut HTTP et l’estimation de coût, sinon une bascule silencieuse reste difficile à diagnostiquer.

Le premier Agent hors production

Ne branchez pas directement la règle sur tous les postes de l’équipe. Sélectionnez un seul client non productif, avec un projet clairement identifié et une clé dédiée.

La vérification doit suivre cet ordre :

1. renseignez l’adresse de base sous forme de placeholder, par exemple <OMNIROUTE_BASE_URL> ;
2. utilisez une clé réservée à l’Agent de test ;
3. sélectionnez un identifiant de modèle auto ou une variante explicitement autorisée ;
4. testez une réponse simple sans outil ;
5. testez la sortie en continu si le client l’utilise ;
6. testez un appel d’outil avec une action sans conséquence ;
7. envoyez une tâche longue et observez les éventuelles nouvelles tentatives ;
8. rejouez le scénario de dépassement avec strict.

Le client doit être inspecté autant que le routeur. Certains outils conservent leur propre modèle de secours, réessaient après un délai ou remplacent une erreur par un autre appel. Dans ce cas, OmniRoute peut bloquer la première requête tout en laissant le client en déclencher une seconde. Le journal de corrélation, l’identifiant de requête et la clé permettent de distinguer ces deux niveaux.

Pour les configurations partagées, consultez également la procédure de location d’un Mac cloud pour un environnement distant et les informations de tarification d’un Mac VPS. Ces pages deviennent pertinentes lorsque le problème n’est plus seulement le routage, mais la disponibilité permanente du poste qui héberge l’Agent.

La première semaine de mise en production

Une mise en ligne progressive réduit le risque de transformer une erreur de configuration en dépassement collectif. Commencez par un seul Agent, puis ajoutez les membres ou projets par groupes clairement identifiés.

Le suivi minimal doit contenir :

• le coût estimé par requête ;
• la distribution des modèles sélectionnés ;
• le taux de refus pour dépassement ;
• le taux d’échec par fournisseur ;
• le nombre de repli ;
• la fréquence des nouvelles tentatives côté client ;
• les modifications de combo, de clé et d’en-tête.

Les alertes doivent couvrir au moins trois événements : dépassement répété, hausse des erreurs d’un fournisseur et augmentation inattendue de la part d’un modèle premium. Une alerte utile indique le projet, la clé concernée, le combo, le modèle final et la dernière modification de configuration.

Séparez aussi les droits. Un membre qui peut modifier une clé fournisseur ne devrait pas nécessairement pouvoir changer le budget de production. La gestion des secrets, la conservation des journaux et la procédure d’accès doivent être documentées lorsque la passerelle est hébergée dans un environnement partagé.

La maintenance du pool et des prix

Un modèle historiquement économique peut perdre son avantage après une modification de prix, une baisse de quota ou une dégradation de disponibilité. Auto Combo s’appuie sur des facteurs comme le coût, la santé, la latence, le quota et l’adéquation à la tâche ; ces signaux changent avec l’état des connexions et du catalogue. (github.com)

À chaque changement important, répétez la validation :

1. modification d’un prix ou d’une fiche modèle ;
2. renouvellement ou expiration d’un identifiant ;
3. ajout d’un fournisseur ;
4. changement de stratégie ou de mode de coût ;
5. migration vers une nouvelle version ;
6. déplacement de l’Agent vers une autre passerelle.

Conservez une configuration précédente capable de reprendre le trafic. La restauration doit porter sur la liste candidate, la politique strict, les clés associées et les paramètres du client. Une sauvegarde uniquement du fichier de configuration ne suffit pas si les identifiants et les règles d’accès sont stockés séparément.

Pour une équipe qui passe d’un relais local à un environnement en ligne, le choix de l’infrastructure devient également une question de coût total. Un poste local peut être difficile à maintenir allumé, dépendre d’un réseau résidentiel et compliquer l’accès de plusieurs membres. Une passerelle distante apporte davantage de disponibilité, mais ajoute des sujets de contrôle d’accès, de journalisation et de reprise. La présentation de Zilmac permet de vérifier le périmètre du service avant de décider si cette externalisation correspond réellement au besoin.

Dans ce contexte, le choix rationnel n’est pas de remplacer automatiquement le poste local par un service distant. Si l’usage exige une charge stable et lourde, des interfaces physiques ou une maîtrise complète des données, l’hébergement local peut rester préférable. En revanche, pour plusieurs membres distants qui doivent partager un Agent, le montage actuel présente souvent trois limites : disponibilité dépendante d’un poste laissé allumé, accès réseau irrégulier et règles de budget difficiles à centraliser. Une location Mac auprès de Zilmac peut alors fournir un environnement plus constant pour héberger la passerelle, tester les quatre scénarios de routage et conserver un point d’administration accessible, sans transformer cette solution en obligation pour les charges qui nécessitent un matériel local dédié.

Commencez par valider OmniRoute Auto Combo sur un seul Agent non productif, puis imposez strict dès qu’un dépassement financier doit être interdit. Une fois les journaux, les alertes et la reprise validés, l’environnement distant peut être étudié pour partager la règle avec plusieurs membres sans perdre le contrôle des clés ni des coûts.

• Comparer les tarifs des modèles et les coûts d’API
• Configurer Claude Code avec Kimi K3 pour mieux maîtriser son usage