Agents Harnesses : une norme de dossier pour les compétences et les références

Un « harness » d’agent est un moyen de structurer le fonctionnement et la façon de penser d’un système d’IA, afin qu’un même modèle de base puisse être utilisé pour de nombreuses tâches différentes. Cette idée s’appuie sur quelques concepts antérieurs, qui seront abordés en premier : ce qu’est un LLM, ce qu’est un agent, comment le raisonnement et l’utilisation d’outils s’intègrent, ainsi que les compétences supplémentaires nécessaires. Une fois ces éléments clarifiés, le « harness » lui-même représente une étape mineure, et un simple organisationnel de dossiers suffit pour le décrire.

Les bases

Les modèles de langage en tant que fonctions

À cette fin, un LLM peut être considéré comme une fonction : du texte est entré et du texte en sort. Il ne fait rien d’autre que répondre au texte par du texte, pourtant la plupart des produits d’IA récents sont conçus sur la base de ce comportement fondamental.

Qu’est-ce qu’un agent ?

« Agent » reste un terme très général. Les travaux académiques décrivent plusieurs types d’agents qui fonctionnent de manières fondamentalement différentes. Cependant, dans la conversation quotidienne, presque tout le monde entend par là une chose : un système de chat qui reçoit un message, effectue certaines opérations, puis répond. Ce modèle est communément appelé ReAct, une fine couche de code qui relie un modèle à des fonctions lui permettant de raisonner, d’agir et d’observer. ReAct permet au modèle de réfléchir à ce qu’il va faire, de choisir une action qui influence l’environnement, puis de lire une observation concernant le résultat. Tout ce qui suit utilise le terme « agent » dans ce sens proche de ReAct.

Raisonnement et action

Deux idées sous-tendent ce mécanisme. Le raisonnement est généralement géré par une chaîne de pensée, ce qui consiste à inciter un modèle à explorer différentes solutions avant de se décider pour une réponse. L’étude qui l’a introduit a fait cela en incluant un exemple résolu dans la demande, et une question qui échouait avec des instructions ordinaires a fonctionné correctement avec le même modèle une fois l’exemple ajouté.

Cette technique est devenue si essentielle que de nombreux modèles sont désormais entraînés pour générer eux-mêmes une chaîne de pensée. Les modèles ordinaires ont tendance à réfléchir à un problème avant de répondre, tandis que les modèles de raisonnement popularisés par DeepSeek disposent d’une étape dédiée où le modèle explore une solution à l’aide d’une très longue chaîne de pensée.

L’utilisation d’outils a une histoire similaire : elle existe depuis un certain temps, continue de se révéler utile et devient une norme. Dans sa forme la plus simple, elle indique au modèle que s’il génère un texte particulier, un code sera exécuté et le résultat reviendra. Le modèle décide alors s’il faut rechercher sur le web, parcourir des fichiers ou, dans le pire des cas, envoyer de l’argent là où ce n’est pas approprié. Les questions complexes nécessitent souvent une combinaison de raisonnement et d’action, et les comparaisons des stratégies de prompting montrent que cette combinaison est supérieure à chacune d’elles prise séparément.

Compétences

Au fur et à mesure que les agents, l’utilisation d’outils et les techniques de prompting se développent, de nouvelles pratiques émergent. Supposons qu’un agent doive ajouter des lignes dans une base de données. Il a besoin d’outils qui permettent au modèle de voir et d’accéder à la base de données, ainsi que de prompts qui décrivent la structure de cette base et les outils disponibles.

Une compétence est un moyen standard pour structurer ce paquet. Les informations et les fonctionnalités sont regroupées en une seule unité, de sorte que l’agent les reçoit sous forme de package complet. Une compétence est un dossier :

my-skill/
├── SKILL.md          # Required: metadata + instructions
├── scripts/          # Optional: executable code
├── references/       # Optional: documentation
├── assets/           # Optional: templates, resources
└── ...               # Any additional files or directories

La plupart des compétences ne sont en réalité que des fichiers de texte. Néanmoins, elles permettent à un agent de comprendre et d’exploiter des systèmes complexes, et elles offrent aux développeurs d’agents une couche réutilisable et portable pour les plans et procédures.

Qu’est-ce qu’un harness ?

Un harness doit être considéré comme une extension des compétences. Une compétence regroupe une capacité large telle que l’édition d’un site web, l’administration d’une base de données ou l’interprétation des retours clients. Un travail sérieux, comme celui d’assistant des développeurs d’un produit, peut nécessiter l’utilisation conjointe de nombreuses compétences. Un harness regroupe plusieurs compétences ainsi que les documents de référence dont l’agent a besoin pour comprendre son rôle et l’environnement dans lequel il travaille.

Le format Agent Harnesses

Sous cette norme proposée, un harnais se compose de trois éléments : un fichier Markdown qui le décrit, un ensemble de compétences permettant d’interagir avec l’environnement, et un ensemble de références qui aident l’agent à comprendre l’endroit où il travaille. Il s’agit d’un projet open source géré en public.

my-harness/
├── HARNESS.md        # Required: metadata + instructions
├── skills/           # Optional: a set of skills
└── references/       # Optional: a set of reference documents

Le fichier de niveau supérieur, HARNESS.md, doit être concis. Il offre à l’agent une vue d’ensemble rapide du problème et indique où trouver des détails dans les compétences et les références.

La conception suit le principe de la divulgation progressive, un modèle récemment popularisé par la norme Agent Skills. Elle se déroule en trois phases :

1. Découverte. Lors du démarrage, l’agent ne charge que HARNESS.md, qui présente la structure du système. Lorsqu’une demande arrive, l’agent la compare à ces descriptions et parcourt progressivement les noms et descriptions des compétences et des références jusqu’à trouver ce dont il a besoin.
2. Activation. Une fois le matériel pertinent trouvé, toute la documentation relative à ces compétences et références est chargée et lue.
3. Exécution. L’agent suit les indications fournies par le système et peut exécuter des compétences.

Le fichier HARNESS.md

Tout comme pour les compétences, le harnais utilise du frontmatter, des faits clés placés en haut d’un fichier Markdown afin que l’agent puisse examiner efficacement les ressources.

---
name: <name of the harness>
description: <description of what the harness is for>
---

<body>

Un nom et une description sont obligatoires afin que l’agent puisse immédiatement savoir de quoi il s’agit. Le corps du texte fournit une brève explication des éléments principaux, guidant l’agent vers les compétences et références qu’il doit utiliser.

Le répertoire des compétences

Ce répertoire contient des compétences conformes à la norme Agent Skills, qui en définit une comme suit :

my-skill/
├── SKILL.md          # Required: metadata + instructions
├── scripts/          # Optional: executable code
├── references/       # Optional: documentation
├── assets/           # Optional: templates, resources
└── ...               # Any additional files or directories

Un harnais s’appuie sur cela, de sorte que le répertoire des compétences ressemble à ceci :

my-harness/
├── HARNESS.md
├── skills/
|  ├── my-skill-1/
|  |  ├── SKILL.md
|  |  ├── scripts/
|  |  ├── references/
|  |  ├── assets/
|  |  └── ...
|  └── my-skill-2/
|     ├── SKILL.md
|     ├── scripts/
|     ├── references/
|     ├── assets/
|     └── ...
└── references/

Le répertoire des références

Le répertoire des références contient des documents arbitraires qui aident l’agent à comprendre son environnement, son rôle ou d’autres éléments contextuels de haut niveau.

Les compétences disposent également de références, et ces deux niveaux diffèrent par leur portée. Les références au sein d’une compétence expliquent comment utiliser cette compétence spécifique. Les références au niveau du framework doivent contenir ce que plusieurs compétences ont en commun, à un niveau d’abstraction plus élevé.

Prenons un agent conçu pour aider à créer du contenu marketing. Il pourrait disposer d’une compétence pour rédiger des articles de blog, d’une autre pour générer des images et d’une troisième pour analyser les réseaux sociaux :

my-mraketing-harness/
├── HARNESS.md
├── skills/
|  ├── create-blog-post/
|  |  ├── SKILL.md
|  |  └── ...
|  ├── generate-images/
|  |  ├── SKILL.md
|  |  └── ...
|  └── scan-social/
|     ├── SKILL.md
|     └── ...
└── references/

Chaque compétence peut avoir ses propres références. La compétence de balayage social peut énumérer les comptes de l’entreprise, la compétence d’image peut indiquer où sont stockées les images finalisées, et la compétence de blog peut décrire le processus de publication. Les références au niveau du système constituent le lieu naturel pour les éléments utilisés par les trois compétences, tels que les guides de style et les priorités de la marque :

my-mraketing-harness/
├── HARNESS.md
├── skills/
|  ├── create-blog-post/
|  |  ├── SKILL.md
|  |  └── ...
|  ├── generate-images/
|  |  ├── SKILL.md
|  |  └── ...
|  └── scan-social/
|     ├── SKILL.md
|     └── ...
└── references/
   ├── style-guide.md
   └── brand-priorities.md

Tout contenu peut être placé dans le répertoire des références au niveau du harnais, mais l’utilisation de Markdown est fortement recommandée, accompagnée d’une brève description en haut de chaque fichier afin qu’un agent puisse évaluer rapidement sa pertinence. Un guide de style dans cet exemple pourrait commencer comme ceci :

---
description: a style guide for the marketing website, which covers the creation
of all visual assets and standard typography rules
---

<body>

Organiser un harnais complexe

Un harnais peut contenir de très nombreuses compétences et références. Lorsque les ensembles deviennent suffisamment volumineux, leur maintenance devient complexe et la transmission d’informations aux agents devient inefficace.

my-harness/
├── HARNESS.md
├── skills/
|  ├── skill1/
|  ├── skill2/
|  ├── skill3/
|  └── ...
└── references/
   ├── reference1
   ├── reference2
   ├── reference3
   └── ...

La réponse réside dans les sous-dossiers. À l’intérieur des catégories « compétences » et « références », des dossiers peuvent regrouper des éléments en sous-ensembles :

my-harness/
├── HARNESS.md
├── skills/
│   ├── software-development/
│   │   ├── SKILLS.md
│   │   ├── skill1/
│   │   │   └── SKILL.md
│   │   └── skill2/
│   │       └── SKILL.md
│   ├── market-analysis/
│   │   ├── SKILLS.md
│   │   └── skill3/
│   │       └── SKILL.md
│   └── social-media/
│       ├── SKILLS.md
│       ├── skill4/
│       │   └── SKILL.md
│       └── skill5/
│           └── SKILL.md
└── references/
    ├── brand-assets/
    │   ├── REFERENCES.md
    │   ├── reference1.md
    │   └── reference2.md
    ├── software-infrastructure/
    │   ├── REFERENCES.md
    │   ├── reference3.md
    │   └── reference4.md
    └── product-information/
        ├── REFERENCES.md
        └── reference5.md

Afin que l’agent comprenne pleinement cette structure de manière efficace, HARNESS.md doit la décrire. Chaque sous-dossier contient également un fichier descriptif : SKILLS.md décrit les compétences présentes dans le sous-dossier, tandis que REFERENCES.md liste ses références.

C’est là que la divulgation progressive s’avère utile. L’agent lit le fichier de niveau supérieur pour en saisir la structure globale, puis ouvre uniquement les fichiers SKILLS.md et REFERENCES.md pertinents lorsque c’est nécessaire, ce qui constitue un moyen efficace d’accéder au matériel pertinent.

Le niveau de nesting peut aller aussi profond que le contenu l’exige, permettant ainsi d’organiser une grande collection de manière structurée. Chaque sous-dossier doit disposer de son propre SKILLS.md ou REFERENCES.md afin que l’agent comprenne chaque niveau au fur et à mesure de sa descente dans la hiérarchie.

...
└── references/
  └── data-sources/
      ├── REFERENCES.md
      ├── relational/
      │   ├── REFERENCES.md
      │   └── schema-overview.md
      └── warehouse/
          ├── REFERENCES.md
          └── dataset-catalog.md

Pourquoi ce format fonctionne

Ce format ne demande que très peu à l’auteur. Tout se trouve sous forme de fichiers texte dans un dossier, ce qui permet de gérer les versions, d’en effectuer la revue et de les partager comme pour n’importe quel autre projet. L’agent n’a jamais besoin de charger l’ensemble de la collection, car chaque fichier descriptif agit comme un petit indicateur qui décide s’il faut aller plus loin. Un ensemble destiné à une équipe de marketing et un autre destiné à un administrateur de base de données ne diffèrent que par leur contenu, tandis que le flux de découverte, d’activation et d’exécution reste identique.

Deux habitudes permettent de maintenir un ensemble en bon état. Premièrement, rédigez chaque description de manière à indiquer quand le matériel est pertinent, et non seulement ce qu’il contient, car c’est à partir de cette seule phrase que l’agent choisit ce qu’il faut ouvrir. Deuxièmement, assurez-vous que les références au niveau de l’ensemble soient véritablement partagées. Si un document concerne une seule compétence, il doit se trouver à l’intérieur de cette compétence ; le promouvoir vers un niveau supérieur ne fait qu’ajouter du bruit à toutes les recherches ultérieures.