1. Introduction#
Le harness est l’infrastructure logicielle qui permet à un modèle de langage de fonctionner comme un agent IA.
Le LLM fournit les capacités de raisonnement et de décision, tandis que le harness organise leur mise en œuvre : accès aux outils, gestion du contexte, exécution des actions et contrôle des permissions.
Un même modèle peut donc présenter des capacités agentiques très différentes selon le harness utilisé.
Le terme harness n’est pas strictement standardisé : son périmètre varie selon les frameworks et les plateformes.
2. Architecture d’un système agentique#
Un système agentique repose généralement sur plusieurs couches complémentaires.
| Couche | Rôle | Exemples |
|---|---|---|
| Interface | Recevoir les demandes et restituer les résultats | CLI, IDE, Web UI |
| Agent | Définir le comportement à partir du modèle et des instructions | Agent de développement |
| Harness | Orchestrer les appels au modèle, les outils et les contrôles | Runtime agentique |
| Tools | Exposer les actions disponibles | Terminal, Python, APIs, MCP |
| Environnement | Héberger et exécuter les opérations | Machine locale, conteneur, cloud |
| État et stockage | Conserver le contexte et les artefacts | Historique, fichiers, base de données |
Ces couches sont logiques et non nécessairement des logiciels indépendants. Une même application peut en assurer plusieurs.
Harness et Runtime#
Les deux notions sont proches, mais peuvent être distinguées :
- Harness : ensemble des mécanismes qui encadrent et pilotent le fonctionnement de l’agent.
- Runtime : environnement logiciel dans lequel ces mécanismes s’exécutent.
Le terme runtime peut aussi désigner le moteur d’exécution de la boucle agentique, selon les implémentations.
3. Responsabilités du Harness#
Le harness coordonne plusieurs fonctions essentielles.
| Fonction | Description |
|---|---|
| Model orchestration | Préparation et transmission des requêtes au LLM |
| Tool execution | Exécution des appels d’outils et récupération des résultats |
| Context management | Construction et actualisation du contexte |
| State management | Conservation de la progression et des résultats |
| Execution control | Gestion des itérations, interruptions et conditions d’arrêt |
| Security | Application des permissions et des restrictions |
| Observability | Journalisation, traces et suivi des exécutions |
Exemple : agent de développement#
Lorsqu’un agent doit modifier un programme Python :
- Le harness transmet l’objectif et les instructions au modèle.
- Le modèle demande la lecture de certains fichiers.
- Le harness exécute cette lecture et retourne le contenu.
- Le modèle propose des modifications.
- Le harness vérifie les autorisations et applique les modifications permises.
- Les tests sont exécutés et leurs résultats transmis au modèle.
- L’exécution se poursuit ou se termine selon les résultats et les conditions d’arrêt.
Le LLM choisit les actions ; le harness contrôle leur exécution.
Le détail des stratégies d’itération est traité dans Boucles agentiques.
4. Gestion du contexte et de l’état#
Un agent doit disposer d’informations pertinentes tout au long de son exécution.
Deux notions doivent être distinguées :
- Context : informations transmises au modèle lors d’un appel.
- State : informations conservées par le système sur la progression de la tâche.
Le contexte constitue une partie de l’état global du système.
Les principales sources de contexte#
| Source | Contenu |
|---|---|
| Instructions | Règles générales, comportement et contraintes |
| Conversation | Demandes et réponses précédentes |
| Projet | Code, documentation, configuration |
| Tools | Résultats des commandes et appels d’API |
| Memory | Informations persistantes récupérées si nécessaire |
Gestion de la fenêtre de contexte#
La fenêtre de contexte d’un LLM étant limitée, le harness peut employer plusieurs stratégies :
- Truncation : suppression de certaines informations anciennes.
- Compaction : condensation ou résumé de l’historique.
- Retrieval : récupération ciblée de documents ou d’informations.
- Persistence : sauvegarde de l’état pour reprendre une exécution.
Ces techniques permettent de limiter la consommation de tokens, mais peuvent entraîner une perte d’informations.
Un contexte plus volumineux n’est pas nécessairement un contexte de meilleure qualité.
5. Outils et environnement d’exécution#
Le harness expose au modèle un ensemble d’outils (tools).
Le modèle peut demander leur utilisation, mais leur exécution dépend de l’environnement et des permissions.
| Outil | Fonction |
|---|---|
| File System | Lire, créer ou modifier des fichiers |
| Terminal / Shell | Exécuter des commandes système |
| Python | Exécuter des scripts et traitements |
| APIs | Communiquer avec des services externes |
| MCP | Accéder à des outils et ressources via un protocole standardisé |
| Browser | Consulter ou manipuler des pages web |
Tool Calling#
Le tool calling suit généralement trois étapes :
- Le modèle sélectionne un outil et génère ses arguments.
- Le harness valide et exécute l’appel selon les autorisations.
- Le résultat est renvoyé au modèle.
Les outils peuvent être intégrés directement au harness ou fournis par des services externes.
Voir : Outils et intégrations.
6. Permissions et Sandbox#
L’autonomie d’un agent doit être limitée aux actions nécessaires.
Deux mécanismes sont particulièrement importants.
Permissions#
Les permissions définissent les opérations autorisées.
| Mode | Fonctionnement |
|---|---|
| Read-only | Consultation sans modification |
| Workspace-write | Écriture limitée à un espace de travail |
| Full access | Accès étendu aux ressources autorisées |
Ces appellations sont illustratives et peuvent varier selon les outils.
Sandbox#
Une sandbox est un environnement isolé destiné à limiter les conséquences des actions exécutées.
Elle peut notamment restreindre :
- l’accès aux fichiers ;
- les permissions système ;
- les connexions réseau ;
- l’accès aux secrets et aux identifiants ;
- les ressources matérielles.
Les permissions et la sandbox sont complémentaires.
Une instruction demandant au modèle de ne pas modifier un fichier ne remplace pas une restriction technique d’écriture.
Human-in-the-Loop (HITL)#
Certaines actions peuvent nécessiter une validation humaine :
- suppression de fichiers ;
- installation de dépendances ;
- modification d’une base de production ;
- déploiement ;
- opérations irréversibles.
Le niveau de supervision doit être proportionné aux conséquences potentielles.
7. Observabilité et contrôle d’exécution#
Un système agentique doit permettre de comprendre ce qui a été réellement exécuté.
| Mécanisme | Objectif |
|---|---|
| Logs | Conserver les événements et erreurs |
| Traces | Retracer les appels au modèle et aux outils |
| Metrics | Suivre coûts, latence, tokens et taux de réussite |
| Guardrails | Vérifier certaines entrées, sorties ou actions |
| Checkpoints | Sauvegarder un état pour reprendre une exécution |
Les guardrails peuvent contribuer à détecter ou bloquer des comportements non souhaités, mais ne garantissent pas l’absence d’erreurs.
Les traces sont particulièrement utiles pour distinguer une erreur de raisonnement du modèle d’un problème d’outil, de configuration ou d’environnement.
8. Harness et frameworks agentiques#
Un harness peut être développé spécifiquement ou s’appuyer sur un framework.
| Approche | Exemples | Caractéristiques |
|---|---|---|
| Harness intégré | Codex, Claude Code | Environnement agentique déjà constitué |
| Framework / SDK | OpenAI Agents SDK, LangGraph, Claude Agent SDK | Composants réutilisables pour créer ses agents |
| Développement personnalisé | Python + API LLM + outils | Contrôle important, davantage de maintenance |
Un SDK ne fournit pas nécessairement un environnement complet prêt à l’emploi. Certaines responsabilités restent à la charge du développeur : stockage, permissions, infrastructure ou intégrations.
Le choix dépend notamment du niveau de personnalisation, des besoins de production et des contraintes de sécurité.
Un framework n’est pas indispensable pour construire un agent. Une implémentation simple peut suffire lorsque le nombre d’outils et les besoins d’orchestration sont limités.
9. Synthèse#
Le harness constitue une composante essentielle de l’architecture agentique.
Les notions principales sont :
- Harness : infrastructure orchestrant le modèle, les outils et les contrôles.
- Runtime : environnement ou moteur d’exécution du système.
- Context : informations fournies au modèle pour décider.
- State : progression et informations conservées par l’application.
- Tool Calling : mécanisme permettant au modèle de demander une action.
- Sandbox : isolation technique limitant les capacités d’exécution.
- Observability : mécanismes permettant de comprendre et vérifier les opérations.
La fiabilité d’un agent dépend autant de son infrastructure d’exécution que des capacités de son modèle.
