ReAct (tool-use loop)

Aussi appelé : boucle d'appels d'outils, boucle d'agent (agent loop), agent à appel de fonctions (function-calling agent), LLM augmenté en boucle, agent multi-étapes (smolagents), boucle agentique (Claude Agent SDK)

Intention

Donner à un modèle un objectif et un ensemble d'outils, et le laisser choisir l'action suivante après avoir vu le résultat de la précédente. Votre code exécute chaque appel d'outil, renvoie le résultat au modèle et arrête la boucle quand le modèle donne une réponse finale ou qu'une limite est atteinte.

Le nombre et l'ordre des étapes ne sont écrits nulle part à l'avance. Ils découlent de ce que le modèle observe en chemin.

À propos du nom. Au sens strict, ReAct est la méthode de prompting publiée en 2022 par Yao et al., où le modèle écrit en texte brut des lignes Thought:, Action: et Observation:. Aujourd'hui, le mot désigne de façon plus large tout modèle qui appelle des outils en boucle, y compris les boucles construites sur l'appel de fonctions natif, avec un raisonnement caché ou absent. Cette page couvre les deux, et parle de « ReAct textuel » pour l'original quand la différence compte. Le create_react_agent de LangGraph, par exemple, est une boucle d'appels d'outils natifs, pas une boucle qui analyse du texte.

Problème

Vous construisez un assistant de code. Un développeur tape : « La CI est rouge sur la branche feature/x. Corrige-la. »

Personne ne connaît encore les étapes. Quel test échoue ? Quel fichier est en cause ? Une dépendance a-t-elle changé ? Combien de cycles « modifier puis relancer les tests » faudra-t-il ? Les deux conceptions évidentes échouent sur cette demande :

Une tâche « CI rouge » part vers un pipeline fixe, qui modifie le mauvais fichier, et vers un modèle sans outils, qui invente une cause qu'il n'a jamais vérifiée. CI rouge "corrige feature/x" Pipeline fixe lire A, le modifier, tester Un appel, sans outils raisonne sur le code de mémoire Mauvais fichier le bug était ailleurs Cause inventée tests jamais lancés
Les deux conceptions figent le chemin avant que quiconque ait vu le test en échec. Ce qui manque, c'est un moyen de regarder, décider, agir et vérifier à nouveau.

Solution

Placez le modèle dans une boucle avec des outils. À chaque tour, il lit tout ce qui précède (la tâche, ses actions antérieures et leurs résultats) et renvoie soit un appel d'outil, soit une réponse finale. Votre code, le harness (l'environnement d'exécution de la boucle), exécute l'outil et ajoute le résultat. Anthropic décrit les agents comme étant « en général simplement des LLM qui utilisent des outils, en boucle, en fonction des retours de leur environnement » (citation traduite).

Sur la tâche de CI, une exécution ressemble à ceci (la trace est adaptée des notes de recherche ; le dépôt est inventé) :

  1. Regarder. Le modèle ne sait pas ce qui échoue, il appelle donc run_tests. Résultat : 1 échec, 41 réussis ; test_discount attendait 90.0 et a obtenu 0.9.
  2. Décider d'après ce qu'il a vu. Un ratio au lieu d'un prix oriente vers la fonction de remise. Il appelle search_code("def apply_discount") et obtient shop/pricing.py:12.
  3. Lire. Il appelle read_file et voit la ligne 13 : return (100 - pct) / 100. Le facteur prix manque.
  4. Agir. Il appelle edit_file pour remplacer cette ligne par return price * (100 - pct) / 100. L'outil confirme qu'une occurrence a été remplacée.
  5. Vérifier. Il relance run_tests au lieu de supposer que la modification a marché. Résultat : 42 réussis.
  6. Terminer. Il renvoie une réponse finale sans appel d'outil : la cause, la ligne modifiée, 42 tests sur 42 qui passent. Le harness met fin à la boucle.

Les décisions sont réparties à dessein entre le modèle et le harness. Le modèle décide quel outil appeler, avec quels arguments, dans quel ordre, et quand il a fini. Le harness décide si un appel est autorisé, comment il s'exécute, quelle part du résultat le modèle voit, et quand imposer un arrêt. Tout ce qui doit être garanti (permissions, limites, arguments valides, troncature) relève du harness, pas du prompt.

Le voisin le plus proche est Plan-and-Execute. ReAct ne choisit que l'action suivante, après avoir vu le dernier résultat, et gère donc bien les surprises. Plan-and-Execute écrit tout le plan au départ et ne replanifie qu'en cas de besoin, ce qui demande moins d'appels au grand modèle et fournit un plan qu'une personne peut relire.

Analogie

Un plombier appelé pour une fuite. Il n'arrive pas avec une liste d'étapes figée. Il regarde sous l'évier, tâte le tuyau mouillé, resserre un raccord, rouvre l'eau et observe. Si ça goutte encore, il passe au raccord suivant. Chaque geste dépend de ce que le précédent a montré. Le plombier est le modèle, la clé et le robinet sont les outils, et « rouvrir l'eau et observer » est l'étape de vérification.

L'analogie s'arrête aux limites. Un plombier sait quand le chantier devient ingérable et appelle le client. Une boucle de modèle ne s'arrête pas d'elle-même de façon fiable : le harness doit compter les tours et l'argent dépensé, et couper.

Structure

La tâche entre dans le contexte ; le modèle lit le contexte et renvoie soit une réponse finale, soit un appel d'outil ; le harness valide l'appel et exécute l'outil sur l'environnement ; l'observation est ajoutée au contexte et la boucle recommence jusqu'à ce que le modèle termine ou qu'une limite impose l'arrêt. fini appel d'outil ajout limite atteinte Tâche Contexte prompt, outils, échanges Modèle choisit la suite Réponse finale sans appel d'outil Harness contrôle et exécute Outils fichiers, tests, web Observation résultat ou erreur, coupé Arrêt forcé tours, budget, délai 1 2 3 4 5 6 7
Les flèches d'accent forment la boucle : contexte, modèle, harness, observation, retour au contexte. Les flèches en pointillés transportent des résultats. La boucle se termine soit quand le modèle répond sans appel d'outil, soit quand le harness atteint une limite.
  1. Contexte. Le prompt système (rôle, règles, manière de terminer), les définitions d'outils (nom, description, JSON Schema des arguments) et l'historique des messages. Par défaut, on ne fait qu'y ajouter : c'est ainsi que le modèle se souvient de ce qu'il a trouvé, et c'est aussi pourquoi le contexte grossit à chaque étape.
  2. Modèle. Lit tout le contexte et renvoie un ou plusieurs appels d'outils, ou une réponse finale. Sa capacité à bien choisir ses outils et à savoir quand il a fini dépend surtout du modèle lui-même : le billet d'Anthropic sur SWE-bench attribue une grande partie d'un bond de score à un modèle plus récent, sur un échafaudage inchangé.
  3. Harness. Votre code. Il vérifie que l'outil existe, que les arguments sont valides et que l'appel est autorisé, puis l'exécute et intercepte les erreurs. Il fait aussi respecter les limites et enregistre une trace de chaque étape.
  4. Outils et environnement. Des fonctions qui lisent des données ou modifient quelque chose : le système de fichiers, un lanceur de tests, une API de recherche, une base de données. Elles s'exécutent dans votre processus, ou côté fournisseur pour les outils hébergés comme la recherche web.
  5. Observation. La sortie de l'outil ou un message d'erreur, tronqué et mis en forme, ajouté sous forme de tool_result, function_call_output ou ToolMessage selon l'API. Les erreurs reviennent comme des observations, pour que le modèle puisse essayer autre chose.
  6. Réponse finale. La fin naturelle : une réponse sans appel d'outil, un outil finish explicite, ou une sortie structurée qui passe la validation.
  7. Arrêt forcé. Le harness met fin à l'exécution quand il atteint le nombre maximal de tours, un budget en tokens ou en dollars, un délai, ou une série d'appels identiques, et renvoie une erreur ou un résultat partiel.

Générateur de prompt

Décrivez un agent : son rôle, son objectif, les outils qu'il peut appeler et la manière dont il doit prouver que le travail est fait. Vous obtenez un prompt système pour un agent unique qui appelle des outils. Collez-le comme prompt système d'une boucle écrite directement sur l'API d'un fournisseur, ou comme instructions d'un agent tout prêt (LangChain create_agent, OpenAI Agents SDK Agent, Claude Agent SDK, Google ADK LlmAgent). Les descriptions d'outils que vous écrivez ici doivent aussi figurer dans les définitions d'outils elles-mêmes.

Outils une ligne par outil ; gardez-en peu
Style d'appel d'outil

Prompt généré

Le texte surligné vient du formulaire. Le texte [entre crochets] reste à remplir.

Le prompt est la plus petite moitié

Pour son agent SWE-bench, Anthropic indique avoir passé plus de temps sur les outils que sur le prompt général. Des descriptions d'outils claires, des résultats courts et économes en tokens, et des messages d'erreur qui disent quoi faire comptent plus que la formulation du prompt. La limite de tours et les règles d'accord de ce prompt ne font qu'informer le modèle : c'est le harness qui doit les faire respecter.

Quand l'utiliser

À utiliser quand

À éviter quand

Mise en œuvre

  1. Vérifiez que vous avez besoin d'un agent. Anthropic recommande de commencer par la solution la plus simple et note qu'un seul appel bien rédigé, avec de la récupération de documents, suffit souvent.
  2. Concevez un petit ensemble d'outils. Commencez avec 3 à 10 outils bien décrits plutôt qu'un par endpoint d'API. Regroupez les opérations en plusieurs étapes (un seul schedule_event au lieu de « lister les disponibilités » puis « créer »), préférez search_* à list_*, et évitez les outils qui se recouvrent. OpenAI suggère, à titre indicatif, de garder sous une vingtaine le nombre d'outils disponibles au début d'un tour, et d'utiliser la recherche d'outils pour les ensembles plus grands.
  3. Rendez les erreurs difficiles. L'agent SWE-bench d'Anthropic se trompait avec les chemins relatifs après un changement de dossier ; exiger des chemins absolus a réglé le problème. Sa modification par correspondance exacte str_replace (échec sauf si le texte apparaît exactement une fois) a été la méthode d'édition la plus fiable de celles testées. Utilisez des schémas stricts et des enums pour que des appels invalides ne puissent pas être produits.
  4. Renvoyez des résultats exploitables par le modèle. Des noms lisibles plutôt que des UUID, une pagination et une troncature avec des valeurs par défaut raisonnables, et une note qui indique comment affiner la requête quand la sortie est coupée. Claude Code plafonne par défaut les réponses d'outils à 25 000 tokens. Les erreurs doivent dire ce qui ne va pas et montrer une entrée valide, pas une pile d'appels.
  5. Écrivez d'abord la boucle sur l'API du fournisseur. Avec l'API Messages d'Anthropic, c'est « tant que stop_reason vaut tool_use, exécuter les outils et envoyer des blocs tool_result ». L'appel de fonctions d'OpenAI fait le même aller-retour avec function_call_output. Adoptez un framework une fois que vous savez ce qu'il fait pour vous.
  6. Ajoutez plusieurs conditions d'arrêt avant de lancer la boucle sur quoi que ce soit de réel. Une fin naturelle (pas d'appel d'outil, ou un outil finish), un plafond de tours, un budget en tokens ou en dollars, un délai, et une détection de répétition (le même outil avec les mêmes arguments plusieurs fois de suite, par exemple trois : demandez au modèle de changer de stratégie). Décidez ce que renvoie un arrêt brutal : une erreur, une réponse partielle, ou un dernier appel sans outil qui « résume ce que vous avez trouvé ».
  7. Renvoyez chaque erreur d'outil sous forme d'observation. Outil inconnu, arguments invalides, permission refusée et exceptions deviennent tous des résultats is_error courts. L'exécution ne doit jamais planter sur un mauvais appel.
  8. Gérez le contexte dès que les exécutions s'allongent. Par ordre de coût : tronquer au niveau de l'outil, effacer les anciens résultats d'outils, compacter l'historique à l'approche de la limite, laisser l'agent prendre des notes dans un fichier, charger le contenu au moment voulu avec des outils de recherche, et confier les grosses explorations à un sous-agent qui renvoie un résumé (Anthropic cite environ 1 000 à 2 000 tokens). Mettez en cache le préfixe stable (prompt système et définitions d'outils).
  9. Tracez chaque étape et constituez un jeu d'évaluation. Journalisez la sortie du modèle, le nom de l'outil et ses arguments, la taille du résultat, les erreurs, les tokens, la latence et le coût. Lisez les transcriptions, pas seulement les scores, et mesurez les raisons d'arrêt et la fiabilité sur des répétitions (voir plus bas).

Le cœur de la boucle, indépendamment du fournisseur (simplifié à partir des notes de recherche) :

for turn in range(max_turns):
    resp = model.generate(messages, tools=schemas)
    messages.append(assistant(resp))
    if not resp.tool_calls:
        return success(resp.text)
    results = [run_checked(call) for call in resp.tool_calls]  # errors become results
    messages.append(user(results))      # all results of the turn in one message
    if over_budget() or repeating(): return stop_early()
    if too_long(messages): messages = compact(messages)
return error_max_turns()
Prise en charge par les frameworks (vérifiez la documentation actuelle avant usage)
FrameworkForme de la boucleLimite d'étapes par défaut
API brutes des fournisseursVous écrivez la boucle sur tool_use / tool_result (Anthropic) ou function_call / function_call_output (OpenAI). Les SDK d'Anthropic proposent aussi un tool runner en bêta.À vous de la fixer
LangChain v1create_agent(model, tools, ...), étendu par des middlewares (relances, accord humain, résumé).Non indiquée dans nos sources
LangGraphcreate_react_agent : un nœud agent et un nœud outils, qui bouclent tant que le message contient des appels d'outils. Désormais déprécié au profit de create_agent ; écrire le graphe à deux nœuds à la main reste la manière habituelle de le personnaliser.recursion_limit
OpenAI Agents SDKRunner.run(agent, ...) boucle sur les appels d'outils et les handoffs ; tool_use_behavior détermine si un résultat d'outil met fin à l'exécution.max_turns, 10, lève MaxTurnsExceeded
Claude Agent SDKquery() exécute la boucle de Claude Code avec des outils intégrés, des modes de permission, des hooks et une compaction automatique. Les outils en lecture seule s'exécutent en parallèle, ceux qui modifient l'état à la suite.max_turns et max_budget_usd, aucune limite par défaut
Google ADKLlmAgent avec des outils ; PlanReActPlanner en option pour des sections plan et action guidées par le prompt.max_llm_calls, 500
smolagentsToolCallingAgent (appels JSON) ou CodeAgent (actions en code), qui se terminent par l'outil final_answer.max_steps
LlamaIndexFunctionAgent (appels natifs), ReActAgent (ReAct textuel, pour les modèles sans appel de fonctions), CodeActAgent.Non indiquée dans nos sources

Réserve. Les valeurs par défaut des frameworks changent vite. La valeur de 10 tours de l'OpenAI Agents SDK vient de sa référence et des notes de version v0.16.0, et celle de 500 pour l'ADK de sa documentation d'exécution ; revérifiez-les toutes les deux. La valeur par défaut de l'ancien AgentExecutor de LangChain, souvent citée en ligne, n'a pas pu être confirmée et n'est pas reprise ici. MCP (Model Context Protocol, annoncé par Anthropic le 25 novembre 2024) n'est pas une boucle : c'est une manière standard d'exposer des outils, que tous ces frameworks savent consommer.

Variantes

ReAct textuel (l'original)

Le modèle écrit des lignes Thought:, Action: et Observation: en texte brut. Le harness arrête la génération à Observation:, extrait l'action avec une regex, l'exécute et colle le résultat. Le papier utilisait un PaLM-540B figé avec 1 à 6 exemples et trois actions pour HotpotQA : search[entity], lookup[string] et finish[answer]. Cela marche avec n'importe quel modèle de complétion et montre le raisonnement, mais l'analyse du texte est fragile et le modèle peut écrire lui-même ses observations. Dans les ablations du papier, agir sans réfléchir et réfléchir sans agir donnaient tous deux de moins bons résultats sur la plupart des tâches.

Boucle d'appel de fonctions natif

Le modèle renvoie des appels d'outils structurés via l'API, et le raisonnement peut être visible, caché dans un modèle de réflexion (thinking), ou absent. C'est ce qu'implémentent presque tous les frameworks actuels. Cette forme permet des appels d'outils parallèles dans un même tour ; Anthropic exige que tous leurs résultats soient renvoyés dans un seul message utilisateur, sinon le modèle apprend à ne plus paralléliser.

Le code comme action (CodeAct)

L'action est un extrait de Python exécuté dans un interpréteur. Une seule étape peut appeler plusieurs outils, faire une boucle et garder des variables. Les auteurs de CodeAct rapportent jusqu'à 20 % de réussite en plus que les actions JSON ou texte sur 17 modèles, un chiffre dans le meilleur des cas, issu de leur propre benchmark. Le CodeAgent de smolagents suit cette idée. Il faut un bac à sable sécurisé.

Boucle hébergée

Le fournisseur fait tourner la boucle pour ses propres outils côté serveur, comme la recherche web et l'exécution de code d'Anthropic, dans un seul appel d'API. Quand son plafond interne d'itérations est atteint, il renvoie stop_reason: "pause_turn" et vous renvoyez la requête pour continuer.

Hybride avec repli

Changer de méthode quand l'une échoue. Dans le papier, ReAct se repliait sur un chain-of-thought avec auto-cohérence (self-consistency) après 7 étapes sans réponse sur HotpotQA (5 sur FEVER), et la combinaison inverse utilisait ReAct quand les réponses échantillonnées divergeaient. Ces combinaisons ont donné les meilleurs résultats par prompting du papier : 35,1 en exact match sur HotpotQA et 64,6 de précision sur FEVER.

Planification périodique

Le planning_interval de smolagents et le PlanReActPlanner de l'ADK insèrent des étapes de planification explicites dans la boucle. On est alors à mi-chemin de Plan-and-Execute.

Nouvelles tentatives avec leçons (Reflexion)

Après un épisode raté, l'agent note ce qui n'a pas marché et recommence. C'est une boucle de vérification placée autour de l'agent, traitée dans Evaluator–Optimizer.

Agents comme outils

Une boucle expose un autre agent comme outil (ADK AgentTool, OpenAI Agents SDK agent.as_tool()). L'appelant garde la main. C'est la brique de base d'un Supervisor.

Avantages et inconvénients

Avantages

  • Gère des situations que personne n'avait prévues, et se remet des erreurs en lisant le résultat de chaque étape.
  • Ancre les réponses dans des observations. Dans le papier ReAct, l'hallucination n'explique aucun des échecs de ReAct sur HotpotQA, contre 56 % pour le chain-of-thought.
  • Gains importants sur les tâches interactives dans le papier : 71 % de réussite sur ALFWorld (meilleur de 6) contre 37 % pour un agent entraîné par imitation.
  • Simple à construire : quelques dizaines de lignes sur une API d'appel de fonctions, et chaque grand framework en fournit une.
  • Inspectable quand il est tracé : chaque action et chaque résultat figurent dans le journal.

Inconvénients

  • Pas plus précis à lui seul sur les questions de connaissance : ReAct seul obtenait 27,4 en exact match sur HotpotQA, contre 29,4 pour le chain-of-thought. Ce sont des chiffres de 2022 avec PaLM-540B, à lire comme une tendance.
  • Le coût croît avec le nombre d'étapes multiplié par la taille du contexte. Chaque étape renvoie l'historique qui grossit : sans cache ni compaction, le coût augmente à peu près comme le carré du nombre d'étapes (notre propre raisonnement, pas une mesure).
  • Lent : les appels au modèle se suivent, et les tâches de code prennent des minutes.
  • Les erreurs s'accumulent : un mauvais pas au début peut faire dérailler toute l'exécution.
  • Imprévisible : le chemin change à chaque exécution, ce qui rend les tests plus difficiles que pour un workflow fixe.
  • Chaque outil à effet de bord pose une question de sécurité, et chaque observation est une injection de prompt possible.

Modes de défaillance

Boucles répétitives

L'agent répète la même action avec les mêmes arguments. Le papier ReAct signale les pensées et actions répétées comme une erreur de raisonnement fréquente, que les auteurs attribuent probablement au décodage glouton.

Parade : un plafond strict de tours et de budget ; détecter les paires (outil, arguments) répétées et injecter « changez de stratégie ou terminez » ; rendre les messages d'erreur précis pour que les nouvelles tentatives diffèrent. Par défaut, l'OpenAI Agents SDK réinitialise tool_choice après un appel d'outil pour éviter les boucles d'outils forcées.

Fausse réussite

Le modèle dit avoir fini sans vérifier. Le billet d'Anthropic sur SWE-bench décrit des modèles persuadés d'avoir réussi alors que les tests cachés échouaient.

Parade : exiger une étape de vérification dans le prompt et donner à l'agent l'outil pour la faire ; contrôler l'achèvement dans le harness (lancer les tests quand finish est appelé) ; ajouter un évaluateur.

Ne jamais s'arrêter

L'agent continue d'explorer : encore une recherche, encore un fichier.

Parade : un outil finish explicite, un budget, des indications dans le prompt sur le moment où l'on en sait assez, et un résultat partiel renvoyé à la limite.

Outils, arguments ou observations inventés

Le modèle appelle un outil qui n'existe pas, invente un identifiant ou devine une valeur obligatoire qu'on ne lui a pas donnée. En ReAct textuel, il peut écrire lui-même sa ligne Observation:.

Parade : l'appel de fonctions natif avec des schémas stricts et des enums ; répondre « outil inconnu, disponibles : ... » sous forme d'erreur ; dire au modèle de demander quand une information manque ; en ReAct textuel, une séquence d'arrêt sur Observation:.

De mauvais résultats font dérailler le raisonnement

Un résultat de recherche vide ou hors sujet envoie l'agent sur une fausse piste. Des résultats de recherche peu informatifs expliquent 23 % des échecs de ReAct sur HotpotQA.

Parade : de meilleurs outils de récupération, des résultats qui disent « aucune correspondance, essayez X », et de la marge pour que le modèle reformule sa requête.

Débordement du contexte

Les grosses sorties d'outils évincent la tâche, et le rappel se dégrade à mesure que le contexte grossit. Après une compaction, des instructions du début peuvent se perdre.

Parade : tronquer et paginer au niveau de l'outil, effacer les anciens résultats, compacter, utiliser des sous-agents. SWE-agent réduit à une ligne les observations antérieures aux 5 dernières ; dans son ablation, l'historique complet obtenait 15,0 % sur SWE-bench Lite contre 18,0 % pour la version réduite par défaut. Gardez les règles permanentes dans un fichier réinjecté à chaque requête.

Injection de prompt via les observations

Une page web, un e-mail, un fichier ou une sortie d'outil contient des instructions, et le modèle les suit.

Parade : ne pas réunir dans un même agent données privées, contenu non fiable et communication vers l'extérieur ; restreindre les actions lourdes de conséquences après la lecture de contenu non fiable ; étiqueter les sorties d'outils comme des données. Les défenses restent un sujet de recherche ouvert : ne comptez pas sur un seul classifieur servant de garde-fou.

Actions dangereuses

Commandes destructrices, données supprimées, dépenses imprévues.

Parade : listes d'autorisation et d'interdiction, permissions limitées, bacs à sable ou conteneurs, points de contrôle pour les modifications de fichiers, et accord humain pour les effets de bord.

Coûts qui explosent et exécutions incohérentes

Ce sont les exécutions ratées qui coûtent le plus cher. Les exécutions réussies de SWE-agent avaient une médiane de 12 étapes et 1,21 $, alors que les exécutions ratées faisaient en moyenne 21 étapes et 2,52 $ (le papier mélange médianes et moyennes, la comparaison est donc approximative). Sur τ-bench, des agents GPT-4o à appel de fonctions résolvaient moins de 50 % des tâches, et réussissaient les 8 essais répétés pour moins de 25 % des tâches du domaine retail.

Parade : budgets en dollars, détection précoce des échecs, modèles moins chers pour les sous-étapes, cache ; mesurer la fiabilité sur des exécutions répétées (pass^k), pas sur une seule exécution chanceuse.

Ce qu'il faut mesurer

La réussite des tâches avec un résultat vérifiable (les tests passent, l'état final de la base de données correspond à l'objectif). La fiabilité sur des répétitions. Les étapes, appels d'outils, tokens et dollars par tâche. Les taux d'erreurs et d'arguments invalides par outil, qui signalent des descriptions peu claires. La répartition des raisons d'arrêt : combien d'exécutions se terminent par une réussite, au plafond de tours ou sur le budget. Testez les outils unitairement, et testez la boucle avec un modèle simulé pour les chemins de limite et d'erreur.

Liens avec les autres patterns

Pour aller plus loin