Développement IA

Qu’est-ce qu’un Agent Harness dans un agent de code IA ? Model, Harness, Tools et JSON State (2026)

Environ 16 min

Le texte DeepSeek couvrait un hôte produit. Celui-ci découpe les quatre couches génériques : Model, Harness, Tools, JSON State. Le modèle remplit les arguments. L’hôte fait tourner la boucle. Les outils passent le Schema. L’état se rejoue.

Avant de lire

Couche Ce qu’elle verrouille Qui exécute
Model tool_use / arguments Le modèle remplit du JSON ; il n’exécute pas d’effets
Harness boucle / droits / compactage L’hôte assemble le contexte, puis exécute
Tools inputSchema Le Schema est la porte ; l’hôte appelle ensuite
State session / turn / JSONL Si on ne peut pas reconstruire, ce n’est pas un état

Quatre couches sont des objets. Un prompt n’est pas une architecture.

Un harness est la boucle, pas le modèle

Un agent de code 2026 ressemble à « un modèle qui édite un dépôt ». Découpé, ce sont quatre objets. Le modèle n’émet que l’action suivante en JSON. Le harness charge le contexte, vérifie le Schema, évalue les droits, exécute les outils, réécrit les résultats et compacte l’historique quand la fenêtre se remplit. Sans cette boucle, le modèle n’est qu’un chat. La boucle officielle de Claude Code dit la même chose : recevoir le prompt, évaluer, exécuter les outils, réévaluer, jusqu’à ce qu’il n’y ait plus d’appels d’outils. Codex écrit la continuité dans un Thread et un enregistrement de session. Cursor est aussi une boucle d’hôte. Le modèle ne touche pas le disque.

  • Model : remplit lookup_order et A-1042. Il ne voit pas le socket et ne crée pas de processus.
  • Harness : prompt système, table d’outils, droits, compactage, budget, max_turns. C’est l’état de l’hôte, pas les poids du modèle.
  • Tools et State : les outils ont un Schema. La session a du JSON inspectable. Le texte de chat n’est pas un état.

Comment les outils intégrés remplissent le JSON : Agents de code IA et appels d’outils JSON. Le saut MCP : Comment les agents de code appellent MCP. Pourquoi le Schema est une porte : Pourquoi l’IA a besoin de JSON Schema. L’hôte à plugins d’un produit : Texte DeepSeek Harness. Ce texte ne raconte pas ce produit. Il empile seulement les quatre couches.

Couche un : le modèle ne remplit que du JSON

Le modèle voit la table d’outils publiée par l’hôte et les messages jusqu’ici. Sa sortie est du texte, un appel d’outil, ou les deux. Consultation fictive — pas de vrais secrets :

{
  "type": "tool_use",
  "id": "call_3c91",
  "name": "lookup_order",
  "input": { "order_id": "A-1042" }
}

Cet objet n’est pas du HTTP ni un tools/call MCP. C’est le modèle qui dit à l’hôte « cherche A-1042 ». L’hôte vérifie la forme, puis autorise ou bloque. Traiter le modèle comme l’exécuteur, c’est rater ce saut.

Couche deux : le harness fait tourner la boucle

Une session est une machine à états, pas une seule complétion. La boucle officielle tient dans un objet : immuables, le nom du modèle et la table d’outils ; mutables, le nombre de messages, l’outil en attente, le budget. Le tour 2 sur 8, c’est l’hôte qui compte. Le modèle ne tient pas un journal :

{
  "session_id": "sess_7f2a",
  "turn": 2,
  "max_turns": 8,
  "immutable": {
    "model": "coding-agent",
    "tools": ["lookup_order", "Read", "Bash"]
  },
  "mutable": {
    "messages": 6,
    "pending_tool": "lookup_order",
    "budget_tokens": 128000
  }
}

Un tour Claude Code : le modèle émet une réponse avec des outils, l’hôte les exécute, réécrit tool_result, puis redemande. Sans appel d’outil, la boucle s’arrête et rend l’usage plus un session_id. Les hooks peuvent intercepter avant l’exécution. Codex choisit un bac à sable après approbation, puis exécute. Écrire les droits en règles : Modèle de droits de l’agent de code. Le harness appelle les droits. Il n’est pas le droit.

Couche trois : les outils passent le Schema

La table d’outils est le menu du modèle. Chaque ligne a besoin d’un nom, d’une description et d’un JSON Schema. Un object trop large invite des clés inventées. Une consultation ne porte pas de champs de remboursement :

{
  "name": "lookup_order",
  "description": "Look up an order by ID. Confirm before any refund.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "order_id": { "type": "string", "pattern": "^[A-Z]-\\d{4}$" }
    },
    "required": ["order_id"],
    "additionalProperties": false
  }
}

Après la porte, l’hôte exécute et renvoie le résultat comme objet. Le modèle lit le retour, pas le défilement du terminal. Un échec est aussi un objet. Ne jetez pas une phrase de prose :

{
  "type": "tool_result",
  "tool_use_id": "call_3c91",
  "content": "{\"order_id\":\"A-1042\",\"status\":\"paid\"}"
}

Couche quatre : le JSON State se rejoue

L’état n’est pas « ce dont on vient de parler ». L’état, ce sont les messages, les résultats d’outils, un identifiant de session, les frontières de compactage. Codex ajoute la session en JSONL et reconstruit au resume. Une ligne doit pointer une consultation :

{"ts":"2026-09-28T01:12:04.221Z","type":"tool_result","id":"call_3c91","name":"lookup_order","ok":true,"order_id":"A-1042"}

Le contexte se remplit. Claude Code compacte automatiquement près de la limite et émet compact_boundary sur le flux. Les détails anciens peuvent être résumés. Le CLAUDE.md à la racine du projet est réinjecté : les règles durables vivent dans un fichier, pas seulement dans le premier prompt. Le compactage est un changement d’état, pas une amnésie silencieuse :

{
  "type": "system",
  "subtype": "compact_boundary",
  "session_id": "sess_7f2a"
}

Cinq étapes vers un harness que l’on peut montrer

Ne commencez pas par « mettre un modèle plus fort ». Écrivez des objets :

  1. Lister d’abord la table d’outils. Chaque outil a un Schema. additionalProperties: false. Ne pas donner au modèle un outil sans Schema.
  2. Écrire la condition d’arrêt. max_turns ou un budget. Ne pas lancer une tâche ouverte à nu.
  3. Écrire les droits en règles. Consultation en lecture allow. Écriture ask. Remboursement deny. « Tout approuver » n’est pas un défaut quotidien.
  4. Poser l’état en JSON. Garder au moins tool_use, tool_result, session_id. Si les id s’alignent, la boucle est branchée.
  5. Traiter le compact comme un événement. Un compact signifie qu’un résumé a remplacé d’anciens messages. Les règles qui doivent survivre vivent sur disque.

Comment le Schema sert de porte : Agents API + JSON Schema. Ce texte exige seulement quatre couches en objets, l’hôte exécutant les effets de bord.

Pour déboguer un agent, étaler quatre JSON

La plupart des échecs sont une table d’outils, un droit ou un état désaligné — pas un modèle « pas assez intelligent ».

  • formater inputSchema et input. Chercher champs manquants et clés en trop.
  • Avec extraire JSONPath, extraire $.name, $.input.order_id, $.session_id.
  • JSON Diff un retour réussi et un refus. Corriger Schema et règles d’abord. Les prompts ensuite.
  • Vérifier que call_3c91 est le même id sur tool_use et tool_result.
  • Ne pas coller JSONL de session, jetons ou chemins de dépôt dans un formateur public. JSONSort tourne dans le navigateur.

Quand les quatre objets se reconstruisent contre le Schema, vous collectez une architecture — pas la phrase « il semblait modifier des fichiers ».

Pièges fréquents

  • Prendre le harness pour un nouveau modèle. Les modèles tournent. Stabiliser d’abord la boucle, les portes et l’état. Les évaluations mal visées commencent ici.
  • Appeler architecture un system prompt plus long. Les prompts se compactent. La table d’outils, les droits et l’enregistrement de session non.
  • Sauter le Schema et exécuter. Le harness possède la boucle. Il n’épargne pas une seconde vérification. Un object trop large envoie des clés inventées dans les effets de bord.
  • Prendre la fenêtre de chat pour l’état. La fenêtre est un rendu. L’état est du JSON. Resume lit l’enregistrement, pas une capture.
  • Traiter le compact comme un non-événement. Les clients officiels émettent une frontière. Les règles imbriquées peuvent exiger une relecture de fichier.
  • Employer les mots plugin d’un produit comme mots génériques. dsh et Capability Seam appartiennent à ce texte produit. Les quatre couches génériques sont Model / Harness / Tools / State.

FAQ

Un harness est-il la même chose qu’un framework d’agents ?

Ce n’est pas la même couche. Un framework orchestre souvent des nœuds dans un dépôt métier. Un harness est la boucle hôte : charger le contexte, passer les portes, exécuter, persister l’état. On peut écrire un agent métier sur un harness. Ne pas coller les deux couches.

Le modèle édite-t-il les fichiers tout seul ?

Non. Le modèle ne remplit que du JSON d’outil. Lectures, écritures, Shell et MCP sont exécutés par l’hôte. Pas d’hôte, pas de changement de dépôt.

Le JSON State doit-il être du JSONL ?

Non. Codex utilise le JSONL de session comme enregistrement d’autorité. Claude Code utilise des transcriptions et un flux d’événements. L’exigence est de reconstruire par id ce que le modèle a vu — pas un suffixe de fichier.

Le compactage jette-t-il le Schema ?

Les définitions d’outils sont en général réinjectées comme préfixe stable. Ce qui tombe, ce sont les détails anciens de conversation. Les règles durables vont dans un fichier de projet, pas seulement dans le premier message utilisateur.

Faut-il réécrire le harness si l’on change de modèle ?

Non. L’adaptateur modèle peut changer. Le Schema d’outils, la table de droits et la forme d’état doivent tenir. Changer de modèle change la couche qui remplit le JSON, pas l’architecture à quatre couches.

Conclusion

L’architecture d’un agent de code n’est pas « un plus grand modèle ». Le modèle remplit du JSON. Le harness fait tourner la boucle. Les outils passent le Schema. L’état se rejoue.

Écrivez quel outil, quel tour et quel enregistrement d’état recevra A-1042. Si vous pouvez montrer quatre objets, vous avez un harness. Les modèles tournent. Stabilisez d’abord les quatre couches.

Pour aller plus loin

Journal : Première publication