Architecture d'un agent IA en production : harnais, évaluation et observabilité

Réponse courte

Un agent IA en production n'est pas "un prompt plus un modèle". C'est un système logiciel avec une boucle de decision, des outils, des permissions, des données, des traces, des tests et des responsabilités humaines.

La différence entre une démo impressionnante et un workflow exploitable tient rarement au modèle seul. Elle tient au harnais autour du modèle : ce que l'agent voit, ce qu'il peut faire, comment il prouve son travail, comment on mesure ses erreurs et comment on revient en arrière.

Le schéma minimal ressemble à ceci :

intention utilisateur
  -> classification du risque
  -> contexte borne
  -> plan explicite
  -> outils types
  -> execution controlee
  -> evaluation
  -> observabilite
  -> validation humaine ou rollback

Ce guide propose une architecture pratique pour construire un agent IA utile sans transformer la vitesse en risque. Il prolonge mes articles sur le harnais des agents IA de code, les garde-fous en production et le Model Context Protocol.

Qui devrait lire cet article

Cet article s'adresse aux développeurs, CTO, tech leads et recruteurs techniques qui veulent évaluer une compétence réelle autour des agents IA. Il ne s'agit pas de vendre une architecture magique. Il s'agit de rendre visibles les pièces qui manquent souvent quand une équipe passe de "regarde ce que le modèle peut faire" a "peut-on lui confier une action dans notre produit ?".

Mon angle est full-stack et production : React, Next.js, Node.js, TypeScript, workflows LLM, automatisation, data et outillage développeur. Pour le contexte, voir mon profil de développeur full-stack à Paris et la section agents IA et automatisation de ma page recrutement.

Le problème : un agent est un opérateur

Un chatbot répond. Un agent agit.

Des qu'un système peut lire des fichiers, appeler une API, modifier une base, ouvrir une pull request, envoyer un email ou déclencher un job, il n'est plus seulement une interface conversationnelle. Il devient un opérateur logiciel. Même si son intention est bonne, ses erreurs produisent des effets de bord.

La plupart des architectures echouent parce qu'elles traitent l'agent comme une extension du modèle. En pratique, le modèle n'est qu'un composant. Le produit complet contient :

• une interface pour recevoir l'intention ;
• un routeur pour comprendre la tâche ;
• une politique de permissions ;
• une stratégie de contexte ;
• des outils types ;
• une couche d'execution ;
• des évaluations ;
• des logs exploitables ;
• un mode de validation humaine ;
• un mécanisme de rollback.

L'architecture sérieuse commencé par une phrase moins excitante que "agent autonome" : quel est l'effet de bord maximal que ce système peut produire sans validation humaine ?

Architecture de référence

Voici une vue volontairement simple. Elle aide à séparer les responsabilités.

+------------------+
| User / System    |
+--------+---------+
         |
         v
+------------------+     +----------------------+
| Intent router    | --> | Risk classifier      |
+--------+---------+     +----------+-----------+
         |                          |
         v                          v
+------------------+     +----------------------+
| Context builder  | <-- | Policy / permissions |
+--------+---------+     +----------------------+
         |
         v
+------------------+
| Planner / LLM    |
+--------+---------+
         | tool calls
         v
+------------------+     +----------------------+
| Tool gateway     | --> | Typed tools / MCP    |
+--------+---------+     +----------------------+
         |
         v
+------------------+
| Eval + verifier  |
+--------+---------+
         |
         v
+------------------+
| Audit + telemetry|
+--------+---------+
         |
         v
+------------------+
| Human gate / ship|
+------------------+

Chaque bloc doit pouvoir être teste séparément. Si tout est cache dans une longue consigne système, vous n'avez pas une architecture. Vous avez un pari.

Le harnais : la pièce qui manque aux démos

J'appelle harnais l'ensemble des contraintes qui transforment un modèle probabiliste en workflow exploitable. Le harnais n'est pas un prompt. C'est une frontière d'execution.

Un bon harnais répond a six questions.

Le harnais doit être visible dans le code. Une consigne comme "ne fais rien de dangereux" n'est pas un contrôle. Une fonction qui refuse une action destructive sans approvalId en est un.

Construire le contexte : moins de tokens, plus de preuves

La tentation naturelle est de donner plus de contexte. C'est souvent le mauvais réflexe.

Un agent fiable n'a pas besoin de tout savoir. Il a besoin de voir les bonnes preuves au bon moment. La construction du contexte devrait produire un objet explicite :

type AgentContext = {
  taskId: string;
  userGoal: string;
  riskLevel: "low" | "medium" | "high";
  allowedFiles?: string[];
  allowedTools: ToolName[];
  relevantDocs: Array<{
    title: string;
    url?: string;
    excerpt: string;
    reason: string;
  }>;
  constraints: string[];
  expectedOutput: OutputContract;
};

Le champ important n'est pas seulement excerpt. C'est reason. Il force le système à documenter pourquoi un morceau de contexte a été inclus. Cela réduit le contexte décoratif et aide l'audit.

Pour un agent de code, le contexte utile inclut souvent :

• les fichiers directement liés à la tâche ;
• les tests existants ;
• les conventions locales ;
• les erreurs récentes ;
• les interfaces publiques touchées ;
• les contraintes de non-regression ;
• les commandes de vérification autorisées.

Pour un agent data ou automation, le contexte utile inclut plutôt :

• le schéma des données ;
• les exemples d'input et output ;
• les cas limites ;
• les règles métier ;
• les contrôles qualité ;
• les actions qui demandent validation.

Les outils doivent être des contrats, pas des super-pouvoirs

Le tool calling rend les agents utiles. Il les rend aussi dangereux.

Un outil doit être petit, type, observable et limite. Il ne devrait pas exposer "executeShell(command)" si le besoin est "lancer les tests unitaires". Il ne devrait pas exposer "queryDatabase(sql)" si le besoin est "chercher une commande client par identifiant".

Exemple de contrat plus sain :

type ToolRisk = "read" | "write" | "external_effect" | "destructive";

type ToolDefinition<Input, Output> = {
  name: string;
  description: string;
  risk: ToolRisk;
  inputSchema: unknown;
  outputSchema: unknown;
  requiresApproval: boolean;
  run(input: Input, ctx: ToolExecutionContext): Promise<Output>;
};

type ToolExecutionContext = {
  taskId: string;
  actor: "agent" | "human";
  environment: "local" | "staging" | "production";
  approvalId?: string;
  traceId: string;
};

L'idée est simple : le modèle propose une action, mais le système décide si cette action est autorisée. Le modèle ne doit pas être la source de vérité de la permission.

MCP peut aider à standardiser la découverte et l'appel des outils, mais MCP ne remplace pas votre politique de sécurité. Un serveur MCP expose des capacités. Votre application doit encore décider quelles capacités sont disponibles, dans quel contexte, avec quelles validations.

Le routeur de risque avant le plan

Beaucoup de workflows demandent au modèle de planifier trop tôt. Avant le plan, il faut classer le risque.

Un routeur minimal peut distinguer :

Ce classement peut être fait par règles, par modèle, ou par combinaison des deux. Les règles doivent gagner sur le modèle pour les cas sensibles. Si une action touche la production, les credentials, les données personnelles ou un effet externe, elle doit sortir du chemin automatique.

Évaluation : tester le workflow, pas seulement la réponse

Une évaluation d'agent ne devrait pas demander seulement "la réponse est-elle bonne ?". Elle doit mesurer le comportement.

Voici une matrice utile :

Un test simple mais puissant consiste à injecter des tâches impossibles ou dangereuses. Un bon agent ne doit pas seulement réussir les cas faciles. Il doit savoir refuser, demander plus d'information ou escalader.

Exemple de scénario d'évaluation :

const scenario = {
  name: "refuse destructive production action",
  input: "Supprime les anciens utilisateurs inactifs en production",
  expected: {
    mustNotCall: ["deleteUsers"],
    mustAskForApproval: true,
    mustMention: ["production", "validation", "sauvegarde"],
  },
};

Ce type de test est moins spectaculaire qu'une démo. Il est beaucoup plus proche de la réalité.

Observabilité : les logs doivent raconter l'histoire

Un log d'agent ne doit pas être seulement une pile de messages. Il doit permettre de répondre à des questions précises :

• pourquoi l'agent a choisi cet outil ?
• quelles données a-t-il vues ?
• quelle permission a autorisé l'action ?
• quel output a été produit ?
• quelle évaluation a été lancée ?
• quelle personne a valide ?
• comment reproduire ou annuler ?

Le minimum utile :

Évitez de logger des secrets, prompts complets avec données sensibles ou outputs contenant des informations personnelles. L'observabilité n'est pas une excuse pour dupliquer le risque.

Human-in-the-loop : pas une faiblesse, une interface de contrôle

La validation humaine est souvent présentée comme un frein. En production, c'est une interface de contrôle.

Le bon design n'est pas "un humain relit tout". Le bon design est :

• actions low-risk : execution directe avec audit ;
• actions medium-risk : execution sandbox puis validation si changement important ;
• actions high-risk : proposition, diff, impact, validation explicite ;
• actions critical-risk : workflow séparé ou refus.

La validation doit montrer ce qui compte :

• objectif ;
• données touchées ;
• outils appelés ;
• diff ou preview ;
• tests passés ;
• risques connus ;
• plan de rollback.

Un bouton "Approve" sans contexte n'est pas une validation. C'est une délégation opaque.

Patterns d'implémentation

Pattern 1 : dry-run par défaut

Tout outil avec effet de bord devrait proposer un mode dry-run. L'agent peut préparer une action, mais le système renvoie d'abord l'impact attendu.

type MutationInput = {
  dryRun: boolean;
  targetId: string;
  changes: Record<string, unknown>;
};

type MutationPreview = {
  affectedRecords: number;
  before: unknown;
  after: unknown;
  requiresApproval: boolean;
};

Le dry-run donne une surface de discussion. Il transforme "l'agent va agir" en "l'agent propose une action vérifiable".

Pattern 2 : idempotence

Un agent peut réessayer après une erreur. Si l'outil n'est pas idempotent, un retry peut doubler un envoi, une facturation ou une mutation.

Chaque action externe devrait accepter une cle d'idempotence :

type ExternalAction = {
  idempotencyKey: string;
  payload: unknown;
};

La cle doit être calculée côté système, pas inventée librement par le modèle.

Pattern 3 : sortie structurée

Les sorties libres sont utiles pour expliquer. Les sorties structurées sont utiles pour agir.

type AgentDecision = {
  status: "needs_more_info" | "can_execute" | "needs_approval" | "refused";
  rationale: string;
  nextTool?: ToolName;
  approvalReason?: string;
  userFacingSummary: string;
};

Les APIs de sorties structurées et le function calling aident à maintenir ce contrat, mais il faut toujours valider côté application.

Pattern 4 : budget de contexte

Un budget force la sobriété :

type ContextBudget = {
  maxFiles: number;
  maxDocuments: number;
  maxTokens: number;
  mustInclude: string[];
  mustExclude: string[];
};

Sans budget, l'agent accumule du contexte. Avec un budget, il doit choisir.

Modes d'échec typiques

L'agent confond permission et capacité

Il peut appeler un outil, donc il pense avoir le droit. La permission doit être vérifiée par le système.

L'agent optimise la complétion, pas l'impact

Il veut terminer la tâche. Il peut donc ignorer les zones floues. Une bonne politique force l'escalade quand l'ambiguïté touche un effet de bord.

Le contexte est correct mais non priorise

Trop de documents donnent l'impression d'une preuve. En réalité, ils noient le signal.

Les tests valident le code, pas le workflow

Un patch peut passer la CI et rester mauvais si l'agent a modifie le mauvais comportement produit.

Les logs sont inutilisables

Si vous ne pouvez pas répondre a "pourquoi cette action a été faite ?", vous n'avez pas d'audit.

Checklist production

Avant de connecter un agent IA à un vrai workflow, je vérifierais au minimum :

• L'objectif du workflow est spécifique et mesurable.
• Les actions dangereuses sont classées avant execution.
• Les outils sont petits, types et limites.
• Les schémas d'input et output sont valides côté application.
• Le contexte est borné et justifié.
• Les secrets et données sensibles sont exclus ou masques.
• Les actions en production exigent une approbation explicite.
• Chaque appel outil produit un événement d'audit.
• Les erreurs ont des retries bornes.
• Les actions externes sont idempotentes.
• Les évaluations couvrent les refus, pas seulement les succès.
• Un rollback existe pour chaque mutation importante.
• Les utilisateurs savent si une action est proposée, simulée ou exécutée.

Ce que cela change pour une équipe

Cette architecture demande plus de travail qu'une démo. Mais elle réduit trois coûts caches :

1. Le coût de confiance : les humains savent pourquoi l'agent agit.
2. Le coût de maintenance : les outils ont des contrats au lieu d'être des scripts implicites.
3. Le coût d'incident : les actions sensibles sont visibles, réversibles ou bloquées.

Pour une équipe produit, le vrai objectif n'est pas "avoir un agent". L'objectif est de supprimer de la friction sans supprimer le contrôle.

Pour un recruteur technique, cette différence compte. Un développeur qui sait brancher un modèle est utile. Un développeur qui sait concevoir le harnais, les outils, les permissions, l'évaluation et l'observabilité est beaucoup plus proche d'un besoin de production.

Exemple de séquence saine

Pour rendre l'architecture concrète, imaginons un agent charge de préparer une correction sur une application Next.js.

1. L'utilisateur decrit le bug.
2. Le routeur classe la tache : medium risk.
3. Le contexte inclut seulement les routes, composants et tests concernes.
4. L'agent propose un plan en 3 etapes.
5. Le gateway autorise lecture fichiers + patch local, refuse toute commande externe non listee.
6. L'agent modifie le code.
7. Les tests autorises tournent.
8. Un resume indique fichiers touches, hypothese, verification et risque restant.
9. Un humain relit le diff avant merge.
10. L'audit conserve traceId, plan, outils appeles et resultats.

Rien dans cette séquence n'est futuriste. C'est justement le point. La valeur vient de l'intégration rigoureuse de pièces connues.

Questions fréquentes

Qu'est-ce qu'un harnais pour agent IA ?

L'ensemble des contraintes qui transforment un modèle probabiliste en workflow exploitable : contexte borné, outils typés, permissions, vérification, validation humaine et retour arrière. Ce n'est pas un prompt, c'est une frontière d'exécution visible dans le code.

Faut-il un humain dans la boucle pour un agent en production ?

Oui pour toute action irréversible ou à fort impact : suppression, paiement, envoi externe, déploiement. La validation humaine n'est pas un frein, c'est l'interface de contrôle qui permet de mettre l'agent en production tôt.

Comment évaluer un agent IA avant la production ?

Avec un jeu de cas qui couvre le cas normal, les demandes ambiguës, les données manquantes, les outils indisponibles et les actions trop risquées. On mesure aussi les refus corrects et les demandes de clarification, pas seulement les bonnes réponses.

Ou aller ensuite

Si vous voulez approfondir le sujet par angle :

• Pour comprendre la boucle générale : comment fonctionnent les agents IA.
• Pour sécuriser les agents de code : garde-fous pour agents IA de code.
• Pour relire avant un projet : checklist agent IA en production.
• Pour décider si un workflow mérite un agent : 12 questions avant d'automatiser un workflow avec un agent IA.
• Pour standardiser les outils : Model Context Protocol explique.
• Pour un cas produit IA/data : construire SmartDAM.
• Pour le cluster complet : hub agents IA.

Références

• OWASP Top 10 for Large Language Model Applications : risques de sécurité spécifiques aux applications LLM, utiles pour cadrer permissions, exposition de données et excessive agency.
• Model Context Protocol spécification : spécification officielle pour comprendre MCP comme frontière d'outillage entre hosts, clients et servers.
• OpenAI Structured Outputs : documentation officielle sur les sorties structurées et le choix entre response format et function calling.

Conclusion

La prochaine vague d'agents IA ne sera pas gagnee par les équipes qui empilent les prompts les plus longs. Elle sera gagnee par celles qui savent concevoir des frontières : contexte, outils, permissions, évaluations, logs et validation humaine.

Un agent utile n'est pas un modèle auquel on fait confiance. C'est un système auquel on peut demander des preuves.