La boucle

// vous dites OÙ aller — l'agent trouve COMMENT y aller

Imaginez un artisan soigneux. Il regarde autour de lui, fait une chose, vérifie que c'est bon, puis passe à la suite. Il ne devine pas tout d'un coup : il avance pas à pas en se servant de ce qu'il vient d'apprendre.

Un agent fonctionne pareil. La grande différence avec un simple chatbot : vous ne lui dictez pas la marche à suivre. Vous décrivez le résultat voulu, et il enchaîne tout seul contexte → action → vérification jusqu'à y arriver.

Exemple complet — une première session

Vous n'avez écrit aucune ligne : vous avez décrit le but. L'agent a bouclé jusqu'au résultat — et vous auriez pu l'arrêter à n'importe quel tour pour préciser.

À retenir

1. Décrivez le but (« exporte en CSV »), pas la procédure technique étape par étape.
2. Demandez-lui de vérifier son travail (lancer l'appli, tester) — la vérification fait partie de la boucle.
3. Vous gardez la main : interrompez et réorientez dès que ça part dans la mauvaise direction.

// le modèle propose des appels d'outils, le SDK les exécute, les résultats reviennent — et ça boucle

Dans le SDK, un tour est un aller-retour : le modèle répond avec un ou plusieurs appels d'outils, le SDK les exécute, et il renvoie automatiquement les résultats au modèle. Les tours s'enchaînent sans rendre la main à votre code tant que le modèle continue d'appeler des outils. La boucle s'arrête quand il répond sans aucun appel d'outil.

Les messages qui défilent

Pendant la boucle, le SDK émet un flux de messages. Les principaux : SystemMessage (sous-type init, métadonnées de session), AssistantMessage (texte + appels d'outils d'un tour), UserMessage (le résultat d'un outil renvoyé au modèle), et ResultMessage qui clôt la boucle avec le texte final, le coût, l'usage de tokens et l'session_id.

Exemple complet — Python (Claude Agent SDK)

# Corriger des tests qui échouent — l'agent boucle tout seul
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage

async def corrige_les_tests():
    async for message in query(
        prompt="Trouve et corrige le bug qui fait échouer les tests du module d'authentification",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Edit", "Bash", "Glob", "Grep"],  # outils auto-approuvés
            setting_sources=["project"],   # charge CLAUDE.md, skills et hooks du projet
            max_turns=30,                  # garde-fou : stoppe avant l'emballement
            effort="high",                 # raisonnement poussé pour du debug
        ),
    ):
        if isinstance(message, ResultMessage):
            if message.subtype == "success":
                print("Terminé :", message.result)
            elif message.subtype == "error_max_turns":
                print("Limite de tours atteinte — reprendre la session pour continuer.")
            else:
                print("Arrêt :", message.subtype)
            if message.total_cost_usd is not None:
                print(f"Coût : ${message.total_cost_usd:.4f}")

asyncio.run(corrige_les_tests())

Vous décrivez la tâche et les outils permis ; c'est le SDK qui tient la boucle. Vous lisez le ResultMessage pour savoir ce qui s'est passé.

Les manettes de la boucle

max_turns plafonne le nombre d'allers-retours d'outils, max_budget_usd plafonne le coût, effort règle la profondeur de raisonnement (low → max), et model choisit le modèle (ex. claude-sonnet-4-6). Les outils en lecture seule (Read, Glob, Grep) peuvent tourner en parallèle ; ceux qui modifient l'état (Edit, Write, Bash) s'exécutent en série.

À retenir

1. Bornez la boucle en production : max_turns et/ou max_budget_usd évitent les runs qui s'emballent.
2. Lisez le subtype du ResultMessage avant de lire result — il n'est garanti que sur success.
3. Réglez l'effort selon la difficulté : low pour lister des fichiers, high/max pour debugger ou refactorer.

// la compaction ne suffit pas — il faut une architecture qui laisse des traces

Dans une session, le contexte s'accumule et ne se réinitialise pas entre les tours : system prompt, définition des outils, historique, entrées et sorties d'outils. De grosses sorties (un gros fichier lu, une commande verbeuse) peuvent engloutir des milliers de tokens d'un coup. Quand la limite approche, le SDK compacte automatiquement : il résume l'historique ancien et garde l'essentiel récent (un message compact_boundary le signale).

Conséquence directe : les instructions placées tout en début de conversation peuvent disparaître au résumé. Les règles durables vont dans le CLAUDE.md (réinjecté à chaque requête), pas dans le premier prompt.

Exemple complet — guider la compaction via CLAUDE.md

# Instructions de résumé

Lors du résumé de cette conversation, conserve toujours :
- l'objectif courant et les critères d'acceptation
- les chemins des fichiers lus ou modifiés
- les résultats de tests et les messages d'erreur
- les décisions prises et leur justification

Le piège des runs longs (et la parade d'Anthropic)

La compaction seule ne suffit pas. Même un modèle de pointe lancé en boucle sur plusieurs fenêtres de contexte échoue à livrer une appli de qualité production s'il ne reçoit qu'un prompt vague (« clone claude.ai »). Deux travers reviennent : tenter de tout faire d'un coup, et tomber à court de contexte en plein milieu en laissant un travail partiel et non documenté.

La parade repose sur deux rôles complémentaires : un agent initialiseur qui prépare l'environnement, écrit la liste des fonctionnalités, crée les scripts de test et documente l'état ; puis un agent de production chargé de progresser par incréments à chaque session, en laissant des artefacts clairs pour la suivante. Variante recommandée pour le très long : une architecture à trois agents planificateur / générateur / évaluateur.

Garder le contexte léger

Déléguez les sous-tâches à des sous-agents : chacun démarre sur un contexte neuf et ne renvoie au parent que sa réponse finale — le contexte principal ne grossit que de ce résumé, pas de tout le détail. Un sous-agent « relecteur » peut ainsi pointer les manques sans polluer la session principale. Soyez aussi sélectif sur les outils (chaque définition coûte du contexte) et baissez l'effort sur les tâches routinières.

Les hooks : surveiller la boucle de l'extérieur

Les hooks se déclenchent à des points précis du cycle, hors du contexte du modèle : PreToolUse (valider/bloquer une commande dangereuse), PostToolUse (auditer), Stop (valider le résultat), PreCompact (archiver le transcript avant résumé). Un PreToolUse qui refuse un appel empêche son exécution et le modèle reçoit le refus.

À retenir

1. Concevez pour le contexte : compaction guidée, règles dans le CLAUDE.md, sous-agents pour isoler le détail.
2. Rendez le travail vérifiable et laissez des artefacts (liste de tâches, tests, PROGRESS.md) — c'est ce qui sauve les runs longs.
3. Échouez en sécurité : plafond de tours + liste blanche d'outils, et jamais de bypassPermissions hors environnement isolé.