Construire son harness d'agent de code

Un lundi matin, l'équipe facturation d'un grossiste reçoit trois réclamations : des clients qui ont commandé exactement 50 ramettes n'ont pas eu leur remise. La correction tient en un caractère. Le vrai sujet est ailleurs : vous voulez qu'un agent fasse ce genre de correction seul, sur votre dépôt, sans qu'il puisse lire votre .env, appeler Internet depuis un test, réécrire les tests pour les faire passer ou vous coûter 40 € de tokens en boucle.

Ce qui fait la différence entre un agent qui vous rend service et un agent dangereux n'est presque jamais le modèle. C'est le harness : le programme qui entoure le modèle, lui expose des outils, décide ce qu'il a le droit de faire, choisit ce qu'il garde en mémoire, sait revenir en arrière et trace chaque action. Claude Code, Gemini CLI, Codex CLI, OpenHands et Aider sont des harness. Ce projet vous fait écrire le vôtre, environ 1 000 lignes de Python, tests non compris, pour savoir exactement ce que les leurs font, et ce qu'ils font de plus.

Ce que vous livrez

Un dépôt prêt à cloner (files/) qui contient :

• une boucle d'agent en function calling manuel avec google-genai, sans ADK ni LangChain ;
• cinq outils : lister, lire (paginé, numéroté), chercher (regex façon grep), éditer (remplacement exact, unique, avec diff) et exécuter une commande ;
• un bac à sable de commandes : sous-processus, délai avec destruction du groupe de processus, répertoire confiné, environnement vidé de toute clé, réseau coupé par unshare -rn ;
• un système de permissions à trois modes (ask, auto, deny) : lecture libre, écritures soumises à approbation avec diff, commandes en liste blanche ;
• une gestion du contexte : troncature des sorties d'outils, compaction des anciens tours par résumé, plafond de tokens par session ;
• des points de reprise git qui ne touchent ni votre branche ni votre index, et une commande undo ;
• un journal de trajectoire JSONL et un rapport HTML ;
• 28 tests sans clé ni réseau, et un make e2e qui fait passer une vraie suite du rouge au vert.

Architecture

flowchart LR
  U["Tâche"] --> L["Boucle agent.py"]
  L -->|"historique + déclarations"| M["Gemini (google-genai)"]
  M -->|"appels d'outils"| L
  L --> P{"Permissions"}
  P -->|"lecture"| T["Outils confinés au dépôt"]
  P -->|"écriture approuvée"| C["Point de reprise git"] --> T
  P -->|"commande en liste blanche"| S["Bac à sable : délai, sans réseau, sans clé"]
  P -->|"refus"| L
  T --> X["Troncature"] --> L
  S --> X
  L --> K["Compaction si budget dépassé"]
  L --> J["Journal JSONL + rapport HTML"]

Stack, coût, durée

Prérequis

• Python professionnel : typage, subprocess, pathlib, tests pytest.
• Avoir déjà écrit une boucle d'agent simple (par exemple dans Construire un agent IA de A à Z).
• git en ligne de commande ; une clé Gemini (Google AI Studio) pour make run et make e2e.

Programme

Démarrage

cd files
make setup        # .venv, dépendances, .env
make test         # 28 tests, sans clé ni réseau
make run          # sans clé : scénario hors ligne ; avec clé : vrai modèle, vous approuvez chaque écriture
make e2e          # vrai modèle, approbation automatique, échoue si la suite n'est pas verte
make clean        # supprime sorties/ (dépôt de travail, journal, rapport)