L'agent que vous ne connaissez pas : principes, architecture et pratiques d'ingénierie

0. TL;DR

Après avoir écrit « The Claude Code You Don't Know: Architecture, Governance, and Engineering Practices », j'ai réalisé que ma compréhension des couches sous-jacentes des Agents n'était pas assez approfondie. Combinée à l'expérience significative de notre équipe dans la mise en œuvre de solutions métier basées sur des Agents, j'ai ressenti le besoin d'une revue systématique. J'ai donc parcouru des documents, des implémentations open-source et mon propre code pour organiser cet article.

Cet article se concentre sur les parties de l'architecture des Agents qui ont le plus d'impact sur les résultats d'ingénierie, notamment le flux de contrôle, l'ingénierie du contexte, la conception des outils, la mémoire, l'organisation multi-agents, l'évaluation, le traçage et la sécurité. Enfin, nous utiliserons l'implémentation OpenClaw pour relier ces principes de conception.

En organisant cela, plusieurs conclusions ont différé de mes hypothèses initiales : les améliorations apportées par des modèles plus coûteux sont souvent plus faibles que prévu ; en revanche, la qualité du Harness et des tests de vérification a un plus grand impact sur les taux de réussite. Lors du débogage du comportement d'un Agent, il faut prioriser la vérification des définitions d'outils, car la plupart des erreurs de sélection d'outils proviennent de descriptions inexactes. De plus, les problèmes au sein du système d'évaluation lui-même sont souvent plus difficiles à détecter que les bugs de l'Agent. Si vous modifiez sans cesse le code de l'Agent sans succès, la réponse se trouve peut-être dans ces domaines.

1. Fonctionnement de base de la boucle d'Agent

La logique d'implémentation centrale d'une boucle d'Agent, une fois abstraite, fait moins de 20 lignes de code :

1const messages: MessageParam[] = [{ role: "user", content: userInput }];
2
3while (true) {
4  const response = await client.messages.create({
5    model: "claude-opus-4-6",
6    max_tokens: 8096,
7    tools: toolDefinitions,
8    messages,
9  });
10
11  if (response.stop_reason === "tool_use") {
12    const toolResults = await Promise.all(
13      response.content
14        .filter((b) => b.type === "tool_use")
15        .map(async (b) => ({
16          type: "tool_result" as const,
17          tool_use_id: b.id,
18          content: await executeTool(b.name, b.input),
19        }))
20    );
21    messages.push({ role: "assistant", content: response.content });
22    messages.push({ role: "user", content: toolResults });
23  } else {
24    return response.content.find((b) => b.type === "text")?.text ?? "";
25  }
26}

Le flux de contrôle correspondant est le suivant : un cycle continu de Perception -> Décision -> Action -> Retour jusqu'à ce que le modèle renvoie du texte brut :

Ayant vu de nombreuses implémentations d'Agents et SDK officiels, les structures sont similaires. La boucle elle-même est assez stable. D'une implémentation minimale à la prise en charge de sous-agents, de la compression du contexte et du chargement de compétences, la boucle principale change rarement. Les nouvelles capacités sont généralement ajoutées à l'extérieur de la boucle plutôt qu'en modifiant son intérieur.

Les nouvelles capacités sont principalement intégrées de trois manières : en étendant les ensembles d'outils et les gestionnaires, en ajustant les structures des invites système, et en externalisant l'état vers des fichiers ou des bases de données. Le corps de la boucle ne doit pas devenir une machine à états massive. Le modèle gère le raisonnement, tandis que les systèmes externes gèrent l'état et les limites. Une fois cette division du travail établie, la logique centrale de la boucle a rarement besoin d'être ajustée fréquemment.

Quelle est la différence entre Workflow et Agent ?

Anthropic fait une distinction directe : un système dont le chemin d'exécution est pré-écrit dans le code est un Workflow ; un système où le LLM décide dynamiquement de la prochaine étape est un Agent. La différence fondamentale est de savoir qui détient le contrôle. En réalité, de nombreux produits étiquetés comme Agents sont plus proches de Workflows, mais aucun des deux n'est intrinsèquement supérieur. Ce qui compte, c'est de trouver la bonne solution pour la tâche.

Vu dans un diagramme, c'est plus intuitif :

Cinq modèles de contrôle courants

La plupart des systèmes d'IA, une fois démontés, sont des combinaisons de ces cinq modèles. De nombreux scénarios n'ont pas besoin d'une autonomie totale de l'Agent ; combiner quelques-uns de ces modèles suffit. La clé est de savoir quelle conception correspond à la tâche.

1. Prompt Chaining : Les tâches sont divisées en étapes séquentielles où chaque étape LLM traite la sortie précédente. Des points de contrôle de code peuvent être ajoutés. Convient aux processus linéaires comme la traduction après génération ou la rédaction du corps du texte après un plan.
2. Routing : Classe l'entrée et la dirige vers un processus spécialisé. Les questions simples vont vers des modèles légers, les complexes vers des modèles puissants ; les requêtes de support technique et de facturation suivent une logique différente.
3. Parallelization : Deux variantes : Sectioning (division des tâches en sous-tâches indépendantes) et Voting (exécution de la même tâche plusieurs fois pour un consensus). Convient aux décisions à haut risque ou aux besoins multi-perspectives.
4. Orchestrator-Workers : Un LLM central décompose dynamiquement les tâches et les délègue à des LLM travailleurs, puis synthétise les résultats. C'est le prototype de l'outil spawn de nanobot et du mode sous-agent de learn-claude-code.
5. Evaluator-Optimizer : Un générateur produit une sortie, et un évaluateur fournit des retours en boucle jusqu'à ce que les normes soient atteintes. Convient aux tâches comme la traduction ou l'écriture créative où les normes de qualité sont difficiles à définir précisément dans le code.

Ces modèles résolvent comment construire le flux de contrôle. Voyons maintenant une question plus axée sur l'ingénierie : pourquoi un système fonctionne-t-il de manière stable ?

2. Pourquoi le Harness est plus critique que le modèle

Un Harness fait référence à l'infrastructure de test, de vérification et de contrainte construite autour d'un Agent. Un Harness comprend au moins quatre parties : les bases d'acceptation, les limites d'exécution, les signaux de retour et les méthodes de repli.

Bien que le modèle soit important, ces conditions d'ingénierie périphériques déterminent souvent si un système fonctionne de manière stable. Ce jugement est le plus vrai pour les tâches hautement vérifiables comme le codage, mais dans les tâches à faible vérification comme la recherche ouverte ou la négociation multi-tours, la limite supérieure du modèle reste plus critique.

Pratique de développement Agent-First d'OpenAI

Trois ingénieurs ont écrit un million de lignes de code en cinq mois avec près de 1 500 PRs—10 fois la vitesse du développement traditionnel. Cette vitesse ne venait pas seulement de la puissance du modèle, mais de bonnes décisions d'ingénierie :

1. Ce que l'Agent ne peut pas voir n'existe pas : La connaissance doit exister dans le codebase lui-même. Les documents externes sont invisibles pour un Agent en cours d'exécution. AGENTS.md est maintenu à environ 100 lignes comme index, avec les détails répartis dans des répertoires docs pour une référence à la demande.
2. Contraindre par le code, ne pas documenter : Les normes dans les documents sont facilement ignorées. Les contraintes encodées dans les Linters, les systèmes de types ou les règles CI sont exécutables. La stratification architecturale est imposée mécaniquement par des Linters personnalisés, pas par une revue manuelle.
3. Réalisation autonome de bout en bout des tâches : De la vérification de l'état et de la reproduction des bugs à l'implémentation des correctifs et au pilotage de la vérification de l'application, en passant par l'ouverture de PRs, la gestion des revues et la fusion—toute la chaîne ne nécessite aucune intervention humaine. Les Agents vérifient activement les logs, les métriques et les traces.
4. Minimiser les frictions de fusion : Gérer les échecs de tests intermittents avec des tentatives plutôt que de bloquer la progression. Dans les environnements à haut débit, le coût de l'attente d'une revue manuelle est souvent plus élevé que la correction de petites erreurs. La discipline de codage n'a pas disparu ; elle est passée de la revue manuelle aux contraintes exécutées par machine.

L'application distribue les logs, les métriques et les traces via Vector vers la couche de stockage Victoria, correspondant aux interfaces LogQL, PromQL et TraceQL. Codex interroge, corrèle et raisonne à travers ces interfaces. Après les modifications, il redémarre l'application, réexécute les charges de travail et renvoie les résultats à Codex. Les parcours UI sont également des entrées. Cette pile d'observabilité est créée par tâche et détruite à la fin. L'Agent n'attend pas qu'on lui signale les erreurs ; il interroge l'état du système pour vérifier les correctifs.

Quelle est la conclusion clé pour le Harness ?

Le diagramme utilise la clarté de la tâche et l'automatisation de la vérification pour diviser les tâches en quatre états. Le quadrant supérieur droit (objectifs clairs, vérification automatisée) est la zone idéale pour les Agents. Le quadrant supérieur gauche (tâche claire mais revue manuelle) est limité par la vitesse de revue humaine. Le quadrant inférieur droit (retour automatisé mais objectifs vagues) conduit à un mouvement efficace dans la mauvaise direction. Le quadrant inférieur gauche (manque des deux) rend les Agents inutiles.

Le travail du Harness est de pousser les tâches vers le quadrant supérieur droit, en s'assurant que le juste et le faux sont jugés par des normes exécutables par machine, et non par des yeux humains.

3. Pourquoi l'ingénierie du contexte détermine la stabilité

La complexité de l'attention du Transformer est O(n²). Plus le contexte est long, plus il est facile pour les signaux clés d'être dilués par le bruit. Un mode de défaillance courant est la « pourriture du contexte », où un contenu non pertinent domine le contexte, entraînant une baisse de la qualité des décisions de l'Agent. De nombreux problèmes qui semblent être une incapacité du modèle sont en réalité dus à une mauvaise organisation du contexte.

Pourquoi superposer le contexte ?

Le problème n'est généralement pas que la fenêtre n'est pas assez longue, mais que la densité d'information est erronée. Charger des éléments rarement utilisés à chaque fois ou mélanger des règles stables avec des états dynamiques rend plus difficile pour le modèle de remarquer ce qui est utile.

La solution est de superposer l'information par fréquence et stabilité :

• Couche permanente : Identité, conventions du projet, interdictions absolues. Contenu qui doit tenir pour chaque session. Gardez-le court, dur et exécutable.
• Chargement à la demande : Compétences et connaissances du domaine. Gardez les descripteurs permanents, mais injectez le contenu complet uniquement lorsqu'il est déclenché.
• Injection au moment de l'exécution : Informations dynamiques comme l'heure actuelle, l'ID du canal, les préférences utilisateur. Injectées par tour selon les besoins.
• Couche mémoire : Expérience inter-sessions écrite dans MEMORY.md. Pas directement dans l'invite système ; lue uniquement lorsque nécessaire.
• Couche système : Hooks ou règles de code pour la logique déterministe. Reste entièrement hors du contexte.

Ne mettez pas de logique déterministe dans le contexte. Tout ce qui peut être exprimé via des Hooks, des règles de code ou des contraintes d'outils doit être géré par des systèmes externes.

Trois stratégies de compression courantes

1. Fenêtre glissante : Supprime les anciens messages. Faible coût, mais perd le contexte précoce. Bon pour les courtes discussions.
2. Résumé LLM : Le modèle génère un résumé. Coût moyen, perd des détails mais conserve les décisions. Bon pour les longues tâches.
3. Remplacement du résultat d'outil : Remplace la sortie brute par des espaces réservés. Faible coût, bon pour les tâches riches en outils.

Les fenêtres glissantes sont les plus faciles mais perdent le contexte précoce. Les résumés LLM avancés utilisent le « résumé par branche », préservant explicitement les décisions architecturales, les tâches inachevées et les contraintes clés. Dans le remplacement d'outil, micro_compact remplace les anciennes sorties d'outil à chaque tour, tandis que auto_compact se déclenche lorsque le contexte dépasse un seuil.

Mise en cache des invites pour réduire les frais généraux redondants

L'inférence LLM calcule des paires Clé-Valeur pour chaque token. Si un préfixe correspond exactement à une requête précédente, il est lu depuis le cache. La mise en cache nécessite une correspondance exacte du préfixe. Une conception adaptée au cache se concentre sur la stabilité : les invites système, les définitions d'outils et les longs documents sont stables et adaptés à la mise en cache. Les informations dynamiques (heure, entrée, résultats d'outils) doivent être placées à la fin.

Cela est lié à la superposition du contexte. Plus la couche permanente est stable, plus le taux de succès du cache est élevé et plus le coût marginal est faible. « Court et stable » n'est pas seulement pour économiser des tokens ; cela protège le cache. Le chargement différé des compétences aide également en ajoutant du contenu après le préfixe stable. Un point contre-intuitif : une invite système stable et volumineuse peut être moins chère qu'une petite qui change fréquemment, car la remise de 90 % sur les lectures suivantes compense le coût d'écriture initial.

Pourquoi charger les compétences à la demande ?

Les compétences sont un modèle efficace : gardez uniquement l'index dans l'invite système, chargez la connaissance complète si nécessaire.

1const systemPrompt = `
2Compétences disponibles :
3- deploy : Processus complet de déploiement en production
4- code-review : Liste de contrôle pour la revue de code
5- git-workflow : Stratégie de branche et normes PR
6`;
7
8async function executeLoadSkill(name: string): Promise<string> {
9  return fs.readFile(`./skills/${name}.md`, "utf-8");
10}

Les descriptions des compétences doivent être courtes pour éviter le gonflement des tokens et doivent servir de conditions de routage. Expliquez quand l'utiliser, quand NE PAS l'utiliser, et quel est le résultat. Utilisez « Utiliser quand / Ne pas utiliser quand » avec des exemples négatifs. De nombreux échecs de routage sont dus à des limites floues, pas à la capacité du modèle. L'invite système doit clarifier les règles : analyser available_skills avant chaque réponse, charger le SKILL.md spécifique en cas de correspondance, et ne charger qu'un seul à la fois.

Les données sont claires : sans exemples négatifs, la précision chute de 73 % à 53 % ; en les ajoutant, elle monte à 85 % et réduit le temps de réponse de 18,1 %. Les exemples négatifs sont essentiels.

Les descripteurs de compétences ont deux pièges. Premièrement, le nombre de mots : les longues descriptions pour chaque compétence s'accumulent. Deuxièmement, la précision : « aide pour le backend » est trop vague. Les descripteurs efficaces sont des conditions de routage, pas des introductions de fonctionnalités. « Quand m'utiliser » est plus important que « Ce que je peux faire ».

Contrôlez la quantité : ne gardez que les compétences à haute fréquence dans l'invite permanente. Les compétences à basse fréquence peuvent être introduites manuellement ou conservées comme documents. Les anti-patrons typiques incluent le fait de bourrer des centaines de lignes de manuels dans une compétence ou d'avoir une compétence qui couvre trop de tâches distinctes (revue, déploiement, débogage).

Qu'est-ce que la compression perd le plus facilement ?

Le problème le plus courant n'est pas que le résumé soit trop long, mais que la priorité de rétention soit erronée. Les LLM suppriment souvent les informations qui semblent ré-obtenables. Les sorties d'outils partent en premier, mais les décisions architecturales et les chemins d'échec associés disparaissent souvent aussi. Définissez explicitement les priorités de rétention dans CLAUDE.md :

1### Instructions de compactage : Comment conserver les informations clés
2Priorité :
31. Décisions architecturales (ne pas résumer)
42. Fichiers modifiés et changements clés
53. Statut de vérification (réussite/échec)
64. TODOs non résolus et notes de retour arrière
75. Sortie d'outil (peut être supprimée, ne garder que la conclusion réussite/échec)

Un autre piège : ne pas changer les identifiants. Les UUID, hachages, IP et noms de fichiers doivent être préservés exactement. Un seul caractère erroné dans un hash de commit casse les appels d'outils ultérieurs.

Pourquoi les systèmes de fichiers sont d'excellentes interfaces de contexte

Cursor appelle cela la « Découverte dynamique de contexte » : donner moins par défaut, lire quand nécessaire. Les systèmes de fichiers sont des interfaces naturelles. Les appels d'outils renvoient souvent du JSON massif ; au lieu de le fourrer dans le contexte, écrivez-le dans un fichier. L'Agent peut utiliser grep ou rg pour lire si nécessaire. Cela garde le contexte propre et est lisible par les développeurs.

Cursor l'a vérifié avec les outils MCP : ils synchronisent les descriptions d'outils dans des dossiers. Les Agents ne voient que les noms d'outils par défaut et interrogent les définitions si nécessaire. Dans les tests A/B, cela a réduit la consommation totale de tokens de 46,9 %.

Cela fonctionne aussi pour la compression des longues tâches. Au lieu de jeter l'historique, sauvegardez le journal de chat complet dans un fichier et référencez le chemin dans le résumé. Si l'Agent a besoin de détails, il peut les récupérer depuis le fichier, faisant de la compression une opération avec perte mais traçable.

4. La conception des outils détermine ce qu'un Agent peut faire

Le contexte détermine ce que le modèle voit ; les outils déterminent ce qu'il peut faire. La qualité prime sur la quantité. Seulement 5 serveurs MCP peuvent coûter environ 55 000 tokens en définitions—près de 30 % d'un contexte de 200K avant même que le chat ne commence. Trop d'outils diluent l'attention du modèle.

La plupart des problèmes d'outils ne viennent pas du fait d'en avoir trop peu, mais de choisir le mauvais, de descriptions incompréhensibles ou de renvoyer des données inutiles.

Comment la conception des outils évolue

La conception des outils a traversé trois étapes. Au début, les API existantes étaient simplement enveloppées en tant qu'outils. Plus tard, on a découvert que les erreurs de sélection étaient souvent dues au fait que les outils étaient conçus pour les ingénieurs, pas pour les Agents.

1ère génération : Encapsulation d'API : Chaque endpoint est un outil. Trop granulaire ; les Agents doivent coordonner plusieurs outils pour un seul objectif.

2ème génération : ACI (Agent-Computer Interface) : Les outils correspondent aux objectifs de l'Agent, pas aux API de bas niveau. Au lieu de create_file et set_permissions, fournissez create_script(path, content, executable).

3ème génération : Utilisation avancée des outils : Optimisation de la découverte et de l'appel :

• Recherche d'outils : Ne fourrez pas toutes les définitions à la fois. Les Agents trouvent les définitions via search_tools. La rétention du contexte atteint 95 %.
• Appel d'outils programmatique : Laissez le modèle utiliser du code pour orchestrer plusieurs appels. Les résultats intermédiaires restent dans l'environnement d'exécution, pas dans le contexte LLM. Les tokens peuvent passer de 150 000 à 2 000.
• Exemples d'utilisation d'outils : Chaque outil reçoit 1 à 5 exemples réels. JSON Schema décrit les types, mais les exemples montrent l'utilisation. La précision peut passer de 72 % à 90 %.

Principes de conception d'outils ACI

La conception des outils affecte directement les Agents. Ce n'est pas seulement « peut-il être appelé », mais « peut-il s'auto-corriger s'il est mal appelé ? »

Les mauvaises conceptions ont des paramètres vagues et des erreurs non corrigibles. Les bonnes conceptions utilisent betaZodTool pour lier la définition et l'implémentation, en utilisant Zod pour les contraintes de format et les suggestions d'erreur structurées :

1const updateTool = betaZodTool({
2  name: "update_yuque_post",
3  description: "Met à jour le contenu d'un post Yuque ; pas pour créer de nouveaux posts",
4  inputSchema: z.object({
5    post_id: z.string().describe("ID du post Yuque, chaîne numérique comme '12345678'"),
6    title: z.string().optional().describe("Titre du post, omettre si inchangé"),
7    content_markdown: z.string().describe("Corps en Markdown"),
8  }),
9  run: async (input) => {
10    const post = await getPost(input.post_id);
11    if (!post) throw new ToolError("L'ID du post n'existe pas", {
12      error_code: "POST_NOT_FOUND",
13      suggestion: "Appelez d'abord list_yuque_posts pour obtenir un post_id valide",
14    });
15    return await updatePost(input.post_id, input.title, input.content_markdown);
16  },
17});

Une mauvaise conception dit seulement ce qu'elle fait, pas quand l'utiliser. Une bonne conception ACI a des limites claires et des erreurs structurées, aidant les Agents à choisir correctement et à corriger les échecs rapidement. Déboguez d'abord les outils ; la plupart des erreurs sont dans les descriptions, pas dans la capacité du modèle.

Pourquoi isoler les messages d'outils ?

Les frameworks génèrent des événements internes (compression, notifications). Ceux-ci doivent être dans l'historique de session mais pas envoyés au LLM, car ils gaspillent des tokens et confondent le modèle. La solution est deux types de messages : AgentMessage pour la couche applicative (avec des champs personnalisés) et Message standard (user, assistant, tool_result) pour le LLM.

5. Conception du système de mémoire

Les Agents manquent de continuité temporelle native. Le contexte est effacé après une session. Pour atteindre une cohérence inter-sessions, une couche mémoire doit être conçue comme une infrastructure, pas comme une réflexion après coup.

Où vivent les quatre types de mémoire ?

Catégorisés par le problème qu'ils résolvent :

• Fenêtre de contexte (Mémoire de travail) : Informations minimales pour la tâche en cours. Tokens limités ; doit être gérée.
• Compétences (Mémoire procédurale) : Comment faire les choses (flux de travail, normes). Chargées à la demande.
• Historique de session JSONL (Mémoire épisodique) : Ce qui s'est passé. Persisté sur disque ; interrogeable.
• MEMORY.md (Mémoire sémantique) : Faits stables écrits par l'Agent. Injecté dans les invites système.

Comment MEMORY.md et les compétences collaborent

L'essentiel est de conserver les faits importants tout en contrôlant le volume de contenu.

Mémoire à 4 couches de ChatGPT : Structure simple. Métadonnées de session (non persistées), Mémoire utilisateur (~33 faits, persistés/injectés), Résumé de conversation (~15 résumés récents, persistés), Session en cours (fenêtre glissante).

Récupération hybride OpenClaw : Journaux quotidiens (memory/YYYY-MM-DD.md), MEMORY.md pour les faits organisés, et memory_search utilisant la récupération hybride (70 % similarité vectorielle + 30 % mots-clés). Pour la plupart des Agents, le Markdown structuré + la recherche par mots-clés suffisent pour la débogabilité et le coût.

Déclenchement et retour arrière de la consolidation de la mémoire

Quand tokenUsage / maxTokens >= 0.5, déclenchez la consolidation. Résumez les messages, ajoutez à MEMORY.md et mettez à jour l'index. En cas d'échec, écrivez les messages bruts dans une archive. Le processus doit être réversible ; déplacez les pointeurs, ne supprimez pas les données brutes.

6. Augmentation progressive de l'autonomie de l'Agent

L'autonomie nécessite trois éléments d'infrastructure : la reprise inter-sessions, les contraintes de progression intra-session, et les E/S en arrière-plan pour les tâches lentes.

Comment continuer les longues tâches entre les sessions

Les longues tâches échouent lorsque les sessions se terminent avant la fin. Une approche stable utilise un Agent initialisateur et un Agent de codage. L'initialisateur s'exécute une fois pour créer feature-list.json, init.sh et claude-progress.txt. L'Agent de codage s'exécute ensuite en plusieurs sessions, reprenant à partir de ces fichiers, implémentant une fonctionnalité, exécutant des tests et mettant à jour le fichier de progression. Cela rend la tâche un état externe.

Gardez la progression dans des fichiers, pas dans le contexte. Utilisez JSON pour la structure. La tâche est terminée uniquement lorsque toutes les fonctionnalités dans feature-list.json ont passes: true.

Pourquoi écrire explicitement l'état de la tâche ?

Sans ancres externes, les Agents dérivent ou terminent prématurément. Enregistrez l'état comme un objet de contrôle externe :

1{
2  "tasks": [
3    {"id": "1", "desc": "Lire la configuration", "status": "completed"},
4    {"id": "2", "desc": "Modifier le schéma", "status": "in_progress"}
5  ]
6}

Contrainte : un seul in_progress à la fois. Mettez à jour l'état après chaque étape.

Intégration des E/S en arrière-plan

Les E/S lentes (opérations fichier, réseau) ne doivent pas bloquer la boucle principale. Mettez les sous-processus lents dans des threads d'arrière-plan et injectez les résultats via une file d'attente de notification avant le prochain appel LLM. C'est plus maintenable qu'un runtime asynchrone complexe.

7. Organisation des systèmes multi-agents

L'ingénierie des systèmes multi-agents repose sur l'isolation et la collaboration.

Mode Directeur : Synchrone. L'humain interagit étroitement avec un Agent. Le contexte est perdu lorsque la session se termine.

Mode Coordinateur : Délégation asynchrone. L'humain définit des objectifs, les Agents travaillent en parallèle, l'humain révise la sortie. La sortie devient des artefacts persistants (PRs, branches).

Un Orchestrateur gère des sous-agents qui travaillent en parallèle, communiquant via des protocoles de boîte de réception JSONL et utilisant Worktrees pour l'isolation.

À quoi servent les sous-agents ?

La recherche et les essais-erreurs ne doivent pas polluer le contexte de l'Agent principal. L'Agent principal n'a besoin que de la conclusion.

1const result = await runAgentLoop(task, { messages: [] });
2return summarize(result); // Le contexte principal ne voit que cette ligne

Pourquoi écrire la collaboration comme un protocole ?

La collaboration en langage naturel échoue lorsque les Agents oublient les promesses. Utilisez un protocole structuré :

1{ request_id, from_agent, to_agent, content, status: 'pending', timestamp }

Utilisez une boîte de réception JSONL en ajout seulement pour la reprise après crash. Isolation d'abord, puis collaboration.

Les hallucinations s'amplifient dans les systèmes multi-agents

Les erreurs se propagent en cascade entre les Agents. La validation croisée brise cette chaîne en faisant juger la conclusion par un Agent indépendant ou un retour externe (tests, compilateurs).

8. Comment évaluer les Agents

L'évaluation nécessite des cas de test, des normes de notation et une vérification automatisée.

L'évaluation traditionnelle à un seul tour (Invite -> Réponse) est insuffisante. L'évaluation des Agents nécessite des outils et des environnements. La notation est basée sur ce qui s'est passé dans l'environnement, pas seulement sur ce que l'Agent a dit.

Concepts clés : Tâche, Essai, Correcteur. Transcription (journal d'exécution) vs Résultat (état final). Vous avez besoin des deux. Un Agent peut dire « billet réservé » (transcription) mais échouer à créer l'enregistrement en base de données (résultat).

Statut et métriques d'évaluation

De nombreuses équipes s'appuient encore sur une révision manuelle ou des juges LLM. Métriques courantes : Pass@k (peut-il théoriquement le faire ?) et Pass^k (est-il stable pour la production ?). Ne les mélangez pas.

Trois types d'évaluateurs

1. Évaluateurs de code : Correspondance de chaînes, tests unitaires. Certitude la plus élevée.
2. Évaluateurs de modèle : Juges LLM basés sur des critères. Bon pour la qualité sémantique.
3. Évaluateurs humains : Révision par des experts. Lent mais établit la référence.

Construire un système d'évaluation à partir de zéro

Commencez avec 20 à 50 cas d'échec réels. Assurez l'isolation de l'environnement pour que les tests ne se polluent pas mutuellement. Incluez à la fois des cas positifs et négatifs. Si deux experts ne sont pas d'accord sur un cas, les critères ne sont pas encore clairs.

Corriger l'évaluation avant de corriger l'agent

Si les scores baissent, vérifiez d'abord le système d'évaluation. Les problèmes d'environnement (limites de mémoire, bugs dans les évaluateurs) ressemblent à une dégradation du modèle.

9. Tracer le processus d'exécution

Sans traces, les échecs ne peuvent pas être reproduits. Les métriques APM (latence, taux d'erreur) ne suffisent pas ; vous avez besoin de la chaîne de raisonnement.

Que enregistrer dans une trace ?

Prompt complet, messages multi-tours, appels/arguments/retours d'outils, chaîne de réflexion, sortie finale, tokens et latence.

Observabilité à deux couches

1. Échantillonnage manuel : Échantillonnage basé sur des règles des erreurs ou des retours négatifs pour trouver des schémas d'échec.
2. Auto-évaluation LLM : Couverture complète des traces en utilisant la couche manuelle comme base de calibration.

Les flux d'événements comme fondation

Émettez des événements à tool_start, tool_end et turn_end. Les systèmes en aval (logs, UI, évaluation) consomment ces événements sans modifier le code de la boucle centrale.

10. Déployer des agents avec OpenClaw

OpenClaw utilise cinq couches découplées : Gateway, Channel Adapters, Pi Agent (boucle centrale), Toolsets (conception ACI) et Context/Memory.

Découplage par bus de messages

Un bus de messages sépare les canaux de l'agent. Les canaux ne gèrent que les E/S ; l'agent ne gère que le traitement.

Prompts système en couches

SOUL.md définit l'identité et les normes d'achèvement. Les prompts sont en couches : Informations d'exécution -> Identité -> Mémoire -> Compétences -> Injection dynamique.

Les limites de sécurité en premier

Avant d'ajouter des fonctionnalités, établissez : Listes blanches d'utilisateurs, Isolation de l'espace de travail (vérifications de chemin) et Journaux d'audit.

Protection contre l'injection de prompts : Traitez le contenu externe comme non fiable. Utilisez la séparation source-puits. Ne donnez pas aux agents des outils dont ils n'ont pas besoin. Exigez une confirmation humaine explicite pour les actions sensibles.

Repli de fournisseur : Basculez automatiquement de fournisseur (Anthropic -> OpenAI) si l'un échoue.

11. Anti-patrons courants

1. Prompt système comme base de connaissances (trop long).
2. Prolifération d'outils (l'agent choisit les mauvais outils).
3. Boucles de vérification manquantes.
4. Systèmes multi-agents sans limites.
5. Pas de consolidation de la mémoire (la qualité chute après 20 tours).
6. Pas de système d'évaluation.
7. Complexité multi-agents prématurée.
8. Se fier aux attentes plutôt qu'aux contraintes mécaniques.

12. Conclusion

1. Le cœur de l'agent est une boucle stable ; les nouvelles fonctionnalités doivent être externalisées.
2. Le harnais détermine la convergence plus que le modèle.
3. L'ingénierie du contexte empêche la « pourriture du contexte ».
4. La conception d'outils ACI se concentre sur les objectifs et la correction des erreurs.
5. La mémoire est en couches (de travail, procédurale, épisodique, sémantique).
6. Les tâches longues reposent sur l'état et les fichiers externalisés.
7. Les systèmes multi-agents ont besoin de protocoles et d'isolation.
8. Évaluation Pass@k pour la capacité, Pass^k pour la qualité.
9. Le traçage est le prérequis pour le débogage.
10. Les agents stables reposent sur des détails d'ingénierie comme le découplage et les limites de sécurité.