Construire une passerelle pour agents de code IA

Construire une passerelle pour agents de code IA : guide de production avec décision explicite, artefact réutilisable, tests d’échec, signaux d’exploitation et limites sourcées.

Construire une passerelle pour agents de code IA : guide de production avec décision explicite, artefact réutilisable, tests d’échec, signaux d’exploitation et limites sourcées.

Réponse directe

Implémentez Construire une passerelle pour agents de code IA comme un contrat de intégration des agents de code, pas comme une configuration ponctuelle. Figez protocole, owner, preuves et rollback avant le trafic. Points de contrôle : protocol_per_agent, scoped_identity, attempt_budget, durable_usage.

La conclusion est fixée par la table de contrat et l’exemple déterministe. ai-coding-agent-api-gateway ne passe pas en rollout si un contrôle dur manque de preuve réseau, de relecture durable ou d’owner.

Périmètre et responsabilités

Séparez la tâche client du plan de contrôle. Le client possède son fichier ou sa variable ; la passerelle possède authentification, routage, limites, comptabilité et tentatives ; le fournisseur possède son protocole natif et ses capacités volatiles. Une réponse texte ne prouve qu’un seul chemin.

L’article possède la décision, les risques et la preuve ; la documentation vivante garde les commandes et étapes d’interface volatiles. On obtient ainsi un arbre de capacités sans doubler l’owner d’une intention.

Le registre owner de cette page est ai-coding-agent-api-gateway ; ses contrôles figés sont protocol_per_agent, scoped_identity, attempt_budget, durable_usage. Chaque valeur est vérifiée à la limite réseau ou durable, jamais déduite d’un libellé commercial.

Artefact pratique: Construire une passerelle pour agents de code IA

Ce registre de revue est l’artefact livrable. Les valeurs techniques explicites permettent de comparer configuration, preuve réseau et état durable sans capture d’écran.

Contrôle Décision fixée Preuve
agent_identity one_scoped_key_per_owner_or_workload key_id + owner + expiry + allowed_groups
wire_contract responses_or_messages_or_chat_selected_explicitly captured_endpoint + content_type + terminal_event
model_policy aliases_resolve_only_to_compatible_routes alias_version + selected_channel + native_probe
attempt_budget one_retry_owner_with_deadline logical_request_id + attempt_sequence + remaining_deadline
tool_boundary authorize_and_deduplicate_before_side_effect call_id + policy_decision + idempotency_record
accounting usage_and_final_charge_reconcile provider_usage + normalized_usage + durable_settlement

Exemple déterministe

L’exemple utilise des placeholders et des entrées déterministes. Remplacez seulement les identifiants validés, jamais les secrets ou données client, et gardez le snapshot exact.

agent -> protocol adapter -> policy gateway -> compatible route -> provider
          |                 |                    |
          |                 +-> attempt ledger   +-> native request ID
          +-> scoped key        usage + charge       terminal event

release gate:
  positive_probe: pass
  negative_probe: pass
  tool_side_effect_replay: no_duplicate
  rollback: tested

Niveaux de vérification

Exécutez les contrôles dans l’ordre. Un succès tardif ne compense pas une limite absente ; chaque tentative doit rejoindre une requête logique.

  1. Figer client, politique de passerelle, alias de modèle, routes et référence observable. Preuve pour agent_identity : appliquer one_scoped_key_per_owner_or_workload et conserver key_id + owner + expiry + allowed_groups.
  2. Exécuter une sonde positive déterministe et conserver réponse, request ID, route, état terminal et usage. Preuve pour wire_contract : appliquer responses_or_messages_or_chat_selected_explicitly et conserver captured_endpoint + content_type + terminal_event.
  3. Exécuter le cas négatif, limite ou déconnexion associé et vérifier la couche d’échec. Preuve pour model_policy : appliquer aliases_resolve_only_to_compatible_routes et conserver alias_version + selected_channel + native_probe.
  4. Répéter sur le vrai protocole ; ne pas déduire le support natif d’un endpoint voisin. Preuve pour attempt_budget : appliquer one_retry_owner_with_deadline et conserver logical_request_id + attempt_sequence + remaining_deadline.
  5. Déployer sur une cohorte bornée avec owner, expiration, seuil d’arrêt et rollback. Preuve pour tool_boundary : appliquer authorize_and_deduplicate_before_side_effect et conserver call_id + policy_decision + idempotency_record.
  6. Relire configuration et comptabilité durables ; supprimer accès et données temporaires. Preuve pour accounting : appliquer usage_and_final_charge_reconcile et conserver provider_usage + normalized_usage + durable_settlement.

Défaillances à éviter

Chaque point suivant bloque la publication. HTTP 200, tableau de bord ou démonstration ne remplacent pas ces contrôles.

  • protocol_flattening — Si protocol_flattening apparaît, arrêtez le rollout et appliquez owner, preuves et rollback ; une sonde réussie ne l’annule pas.
  • shared_human_key — Si shared_human_key apparaît, arrêtez le rollout et appliquez owner, preuves et rollback ; une sonde réussie ne l’annule pas.
  • nested_retry_multiplication — Si nested_retry_multiplication apparaît, arrêtez le rollout et appliquez owner, preuves et rollback ; une sonde réussie ne l’annule pas.
  • tool_replay — Si tool_replay apparaît, arrêtez le rollout et appliquez owner, preuves et rollback ; une sonde réussie ne l’annule pas.

Signaux et conditions d’arrêt

Observez ensemble succès et dommage. Le seuil vient de la politique du workload ; fixez SLO et dénominateur avant la fenêtre.

Signal Seuil Action
protocol_probe_pass_rate 100%_for_required_cases block_route_on_any_contract_failure
attempts_per_logical_request <=_reviewed_attempt_budget disable_lower_retry_layer
unattributed_usage_ratio 0 stop_rollout_and_repair_identity_mapping
duplicate_side_effect_count 0 revoke_tool_access_and_reconcile

Limites de Modelflare

Modelflare centralise routage compatible et natif, clés limitées, groupes, usage et échecs. Un canal ne prouve pas tous les champs, alias, engagements de conservation, régions ou fallbacks. Vérifiez en natif et prenez le règlement durable comme vérité financière.

C’est une méthode d’implémentation, pas une certification, conclusion juridique, historique d’uptime ou benchmark universel. Revérifiez contrat, modèles, prix, conservation et régions à T-1 ; déplacez la date si un fait central change.

Poursuivre dans le cluster

Le parent traite la décision large, le sibling l’étape suivante et la documentation la configuration actuelle. Les liens de corps sont nécessaires car le CMS géré n’a pas de related-slug.

Questions fréquentes

Construire une passerelle pour agents de code IA : Une requête réussie suffit-elle ?

Non. Cas négatif, rollout borné, relecture durable et arrêt sont des gates distincts.

Construire une passerelle pour agents de code IA : Faut-il figer modèles et prix des mois avant ?

Non. Utilisez placeholders ou snapshots et revérifiez à T-1.

Construire une passerelle pour agents de code IA : Quelles preuves conserver ?

IDs sans données sensibles, version, temps, état, usage, charge finale et décision.

Sources et date de vérification

Sources vérifiées le 2026-08-07. Elles définissent contrats et principes, pas les routes non testées ni l’état futur.