La boucle agentique expliquée

Un agent, c’est un modèle qui agit, observe le résultat et décide de la suite, en boucle, jusqu’à ce que la tâche soit faite. Le cours officiel fait d’abord écrire cette boucle à la main, pour bien voir ce qui se passe, avant de la confier au SDK. C’est l’objet de cette leçon.

Le contrat de l’utilisation d’outils

La documentation décrit l’utilisation d’outils comme un contrat entre votre application et le modèle. Vous déclarez les opérations disponibles et la forme de leurs entrées et sorties ; Claude décide quand et comment les appeler. Le modèle n’exécute jamais rien lui-même : il émet une demande structurée, votre code (ou les serveurs d’Anthropic) exécute l’opération, et le résultat revient dans la conversation. Deux idées du cours officiel en découlent : la fenêtre de contexte borne ce que Claude peut voir, et les outils et leurs permissions décident de ce qu’il peut faire.

Où s’exécutent les outils

Tout outil appartient à l’une de trois familles, et la famille décide de ce que votre application doit faire :

La boucle côté client

Pour les deux premières familles, c’est votre application qui fait tourner la boucle, car le modèle ne peut pas exécuter votre code. Chaque appel d’outil est un aller-retour :

1. vous envoyez une requête avec la liste tools et le message de l’utilisateur ;
2. Claude répond avec stop_reason: "tool_use" et un ou plusieurs blocs tool_use ;
3. vous exécutez chaque outil et mettez les résultats dans des blocs tool_result ;
4. vous renvoyez une requête avec les messages d’origine, la réponse de Claude, et un message utilisateur qui contient les tool_result ;
5. vous recommencez tant que stop_reason vaut "tool_use".

En TypeScript, la boucle écrite à la main ressemble à ceci :

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();
const tools: Anthropic.Tool[] = [/* vos définitions d'outils */];
const messages: Anthropic.MessageParam[] = [{ role: "user", content: userInput }];

while (true) {
  const response = await client.messages.create({
    model: "claude-opus-5-5",
    max_tokens: 16000,
    tools,
    messages,
  });

  // end_turn, max_tokens, refusal… : tout ce qui n'est ni tool_use ni pause_turn arrête la boucle
  if (response.stop_reason !== "tool_use" && response.stop_reason !== "pause_turn") break;

  if (response.stop_reason === "pause_turn") {
    // un outil serveur a atteint sa limite d'itérations : on relance
    messages.push({ role: "assistant", content: response.content });
    continue;
  }

  messages.push({ role: "assistant", content: response.content });

  const toolResults: Anthropic.ToolResultBlockParam[] = [];
  for (const block of response.content) {
    if (block.type === "tool_use") {
      const result = await executeTool(block.name, block.input);
      toolResults.push({ type: "tool_result", tool_use_id: block.id, content: result });
    }
  }
  messages.push({ role: "user", content: toolResults });
}

Deux détails comptent. Claude peut demander plusieurs outils dans une même réponse : exécutez-les, puis renvoyez tous les résultats dans un seul message utilisateur. Et si un outil échoue, renvoyez quand même un tool_result, avec is_error: true, plutôt que de l’omettre.

La boucle côté serveur

Les outils exécutés par le serveur font tourner leur propre boucle chez Anthropic : une seule de vos requêtes peut déclencher plusieurs recherches web ou exécutions de code avant que la réponse ne revienne. Cette boucle a une limite d’itérations. Si Claude est encore en train d’itérer quand il l’atteint, la réponse arrive avec stop_reason: "pause_turn" : le travail n’est pas fini, et il faut renvoyer la conversation, réponse en pause comprise, pour qu’il reprenne.

Quand un agent n’est pas la bonne réponse

La documentation invite à commencer simple. Un appel unique suffit pour classer, résumer, extraire ou répondre à une question. Un enchaînement d’étapes piloté par votre code suffit pour un traitement connu d’avance. L’agent se justifie quand la tâche est en plusieurs étapes et difficile à spécifier d’avance, que le résultat vaut le coût et la latence supplémentaires, que Claude sait faire ce type de tâche, et que les erreurs peuvent être rattrapées (tests, relecture, retour arrière).

À vous de jouer

Dessiner votre boucle. Pour un agent que vous aimeriez construire, listez ses outils, la condition qui arrête la boucle, et ce qui se passe si un outil échoue. Écrivez ensuite en pseudo-code la boucle while stop_reason == "tool_use" qui le fait tourner.

Sources officielles : The agent loop explained (Claude Academy) · How tool use works · Tool use overview

Points clés à retenir

• Le modèle n’exécute rien : il demande, votre code ou le serveur exécute, le résultat revient dans la conversation
• Trois familles d’outils : définis par vous, à schéma Anthropic (exécutés chez vous), exécutés par le serveur
• La boucle client tourne tant que stop_reason vaut tool_use ; tous les résultats d’un tour reviennent dans un seul message
• Les outils serveur ont leur propre boucle ; pause_turn signifie qu’il faut relancer
• Pas d’agent quand un appel unique ou un enchaînement fixe suffit