Claude Architect, épisode 1 : la boucle agentique et stop_reason

Je prépare la certification Claude Certified Architect. Cette série me sert de carnet de révision, et je la publie pour que d’autres francophones puissent s’en servir. Chaque épisode couvre une partie du programme et suffit pour la réviser : des schémas, du code qui tourne, les pièges à reconnaître et un quiz pour finir.

Au programme de cet épisode

0. Préparer son poste

La partie pratique est facultative pour l’examen, mais écrire la boucle soi-même aide beaucoup à la retenir. Il faut quatre choses.

Un compte sur platform.claude.com, l’ancienne console.anthropic.com, avec du crédit : 5 $ au minimum, soit environ 50 dirhams. Chaque appel est facturé au jeton, et sans crédit l’API refuse de répondre. La page Limits indique les plafonds de requêtes par minute de chaque modèle.

Le modèle le moins cher. Tous les exemples utilisent Claude Haiku 4.5 (claude-haiku-4-5), pour ne pas vider les 5 $ en une après-midi. Un appel de test coûte une fraction de centime.

Une clé API, à placer dans une variable d’environnement, jamais dans le code :

# macOS / Linux : ajoutez cette ligne à ~/.zshrc (ou ~/.bashrc), puis rechargez
export ANTHROPIC_API_KEY="sk-ant-..."
source ~/.zshrc

# Windows (PowerShell)
$env:ANTHROPIC_API_KEY = "sk-ant-..."

# Un environnement Python isolé, et le SDK
python3 -m venv .venv
source .venv/bin/activate
pip install anthropic

Un premier appel, pour vérifier que la clé fonctionne. Appelons ce fichier api_check.py :

import anthropic

client = anthropic.Anthropic()
# Le SDK lit ANTHROPIC_API_KEY dans l'environnement :
# inutile de passer la clé à la main.

response = client.messages.create(
    model="claude-haiku-4-5",
    max_tokens=100,
    messages=[
        {"role": "user", "content": "Say hello in one word."}
    ]
)

print(response.content[0].text)  # Doit afficher : Hello

Remarquez déjà le "role": "user". C’est le premier concept.

1. Les trois rôles : qui parle ?

Pensez à une salle de classe. L’élève a le rôle d’apprendre, le professeur celui d’enseigner. Échangez les rôles, et l’élève devient professeur. Un rôle ne dit pas qui vous êtes, il dit ce que vous faites dans la conversation.

Avec Claude, chaque message porte un rôle :

Dans l’interface de Claude ou de ChatGPT, vous ne voyez jamais ces rôles : chaque message que vous tapez est étiqueté user en coulisses. Avec le SDK, c’est vous qui les écrivez.

Prenons une campagne marketing pour du thé au gingembre, rôle par rôle :

1. system
   Tu es un expert de premier plan du marketing sur les réseaux sociaux.
2. user
   Génère une campagne publicitaire pour du thé au gingembre.
3. assistant
   Voici trois visuels et un post Instagram : « Un réveil épicé… »
4. user
   Le post Instagram ne va pas, corrige-le.
5. assistant
   Voici le post Instagram mis à jour : …

En code, cela donne :

response = client.messages.create(
    model="claude-haiku-4-5",
    max_tokens=1024,
    system="Tu es un expert de premier plan du marketing sur les réseaux sociaux.",
    messages=[
        {"role": "user", "content": "Génère une campagne publicitaire pour du thé au gingembre."},
        {"role": "assistant", "content": "Voici trois visuels et un post Instagram : ..."},
        {"role": "user", "content": "Le post Instagram ne va pas, corrige-le."},
    ],
)

2. Chat ou agent : quelle différence ?

Une image aide : le LLM est le cerveau de l’agent, les outils sont ses mains. Le cerveau décide quelle main utiliser, et à quel moment.

Prenons un agent de réservation de voyages. On lui demande un vol entre l’Inde et l’Australie à certaines dates :

1. Claude comprend qu’il faut l’outil de réservation de vols, et le demande.
2. L’outil s’exécute et répond.
3. Si le vol est réservé, c’est fini.
4. Si les dates sont ambiguës, Claude demande une précision à l’utilisateur, relance l’outil avec la réponse, et ainsi de suite jusqu’au résultat voulu.

3. Le cycle de vie de la boucle agentique

1. Envoyer la requête : on appelle l’API avec le tableau messages et la liste des outils disponibles.
2. Lire stop_reason : la réponse de Claude indique pourquoi il s’est arrêté.
3. Exécuter : si Claude a demandé un outil (tool_use), votre code l’exécute. Claude ne fait que le demander.
4. Ajouter : on ajoute la demande et le résultat à l’historique, puis on revient à l’étape 1.

On sort quand stop_reason vaut end_turn, et seulement dans ce cas.

4. stop_reason : les deux valeurs à connaître

5. Pourquoi le tableau messages est vital

L’API Claude est 100 % sans état. Envoyez « Je m’appelle Yasmine », elle répond « Bonjour Yasmine ». Au prochain appel, elle a tout oublié. Chaque requête doit donc contenir tout l’historique de la conversation.

Dans une boucle agentique, cet historique grandit à chaque tour. Une phrase résume tout : c’est l’architecte qui est responsable de l’état. Un outil oublié dans la requête, et Claude invente une réponse. Un identifiant qui ne correspond pas, et la boucle casse.

Une question revient souvent : pourquoi le résultat d’un outil porte-t-il le rôle user, alors qu’aucun humain ne l’a tapé ? Parce que user désigne tout ce qui entre dans Claude depuis votre code. Ce qui sort de Claude est assistant, ce qui y entre est user.

Rejouez la boucle, étape par étape

Voici le vrai déroulé de l’agent de la section suivante, sur la question « Where is my order #4821? ». Cliquez sur les étapes, ou utilisez les flèches du clavier.

6. Le code complet : un agent de suivi de commande

Le cas d’usage est un service client. On demande « où est ma commande ? », l’agent consulte la commande et répond, sans personne pour chercher à la main. Pas de base de données ici : trois commandes sont écrites en dur pour garder l’exercice simple.

Voici agent.py, complet et prêt à lancer. Il se découpe en six étapes.

Étapes 1 à 3 : le client et la définition de l’outil. Un outil a trois champs. Le name, c’est son nom dans les blocs tool_use. La description permet à Claude de décider quand s’en servir. L’input_schema décrit ses paramètres en JSON Schema.

# ÉTAPE 1 : installer et importer — pip install anthropic
import anthropic
import json
import os

# ÉTAPE 2 : créer le client.
# Il lit ANTHROPIC_API_KEY dans l'environnement. Ne jamais écrire la clé en dur ici.
client = anthropic.Anthropic()

# ÉTAPE 3 : définir les outils.
#   name          - le nom que Claude utilise dans ses blocs tool_use
#   description   - ce qui permet à Claude de décider QUAND s'en servir (épisode 05)
#   input_schema  - le schéma JSON des paramètres
tools = [
    {
        "name": "lookup_order",
        "description": (
            "Look up an order by its order ID. "
            "Returns current status, estimated delivery date, and carrier name. "
            "Use this when the customer asks where their order is or when it will arrive."
        ),
        "input_schema": {
            "type": "object",
            "properties": {
                "order_id": {
                    "type": "string",
                    "description": "The numeric order ID (e.g. '4821')"
                }
            },
            "required": ["order_id"]
        }
    }
]

Étape 4 : la fonction de l’outil. C’est elle qui fait le travail. Claude ne peut pas l’appeler : il la demande, et votre code l’exécute.

# ÉTAPE 4 : implémenter les fonctions des outils.
# Claude NE PEUT PAS appeler ces fonctions lui-même.
# Claude DEMANDE un appel -> votre code l'exécute -> vous renvoyez le résultat.
def execute_tool(tool_name: str, tool_input: dict) -> str:
    """Exécute un outil et renvoie son résultat sous forme de chaîne JSON."""
    if tool_name == "lookup_order":
        order_id = tool_input.get("order_id", "")
        # Fausse base de données
        mock_orders = {
            "4821": {"status": "shipped",    "eta": "March 30", "carrier": "FedEx"},
            "9910": {"status": "processing", "eta": "April 2",  "carrier": "UPS"},
            "0042": {"status": "delivered",  "eta": "March 25", "carrier": "DHL"},
        }
        if order_id in mock_orders:
            return json.dumps(mock_orders[order_id])
        else:
            return json.dumps({"error": f"Order {order_id} not found"})

    # Outil inconnu : renvoyer une erreur en résultat (ne jamais lever d'exception ici)
    return json.dumps({"error": f"Unknown tool: {tool_name}"})

Étape 5 : la boucle agentique. C’est le cœur du fichier, et c’est lui que l’examen interroge.

# ÉTAPE 5 : la boucle agentique
def run_agent(user_message: str) -> str:
    """Fait tourner la boucle jusqu'à ce que Claude produise une réponse finale."""

    # On commence avec le seul message de l'utilisateur.
    # Le tableau messages grandit à chaque tour de boucle.
    messages = [
        {"role": "user", "content": user_message}
    ]

    # Soupape de sécurité : PAS la condition d'arrêt principale.
    MAX_ITERATIONS = 50
    iteration = 0

    while iteration < MAX_ITERATIONS:
        iteration += 1

        # APPEL API : les messages actuels + les outils disponibles.
        # Claude renvoie une réponse accompagnée d'un stop_reason.
        response = client.messages.create(
            model="claude-haiku-4-5",   # rapide et peu cher : idéal pour apprendre
            max_tokens=4096,
            tools=tools,
            messages=messages
        )

        # SORTIE : "end_turn" signifie que Claude a terminé.
        # C'est la SEULE sortie principale valide de la boucle.
        if response.stop_reason == "end_turn":
            for block in response.content:
                if block.type == "text":
                    return block.text
            return ""  # end_turn sans texte (rare, mais possible)

        # APPEL D'OUTIL : "tool_use" signifie que Claude veut appeler des outils.
        # À faire : exécuter les outils, puis ajouter les DEUX messages à l'historique.
        if response.stop_reason == "tool_use":

            # AJOUT 1 : le message de l'assistant, AVANT les résultats.
            messages.append({
                "role": "assistant",
                "content": response.content   # contient les blocs tool_use
            })

            # Exécuter chaque outil demandé par Claude
            tool_results = []
            for block in response.content:
                if block.type == "tool_use":
                    print(f"  → Calling tool: {block.name}({block.input})")
                    result = execute_tool(block.name, block.input)
                    print(f"  ← Result: {result}")

                    tool_results.append({
                        "type": "tool_result",
                        "tool_use_id": block.id,   # ← DOIT correspondre à l'id du message assistant
                        "content": result
                    })

            # AJOUT 2 : les résultats, rôle "user" : ces données ENTRENT dans Claude
            # depuis votre code. Aucun humain ne les a tapées, mais c'est le rôle user.
            messages.append({
                "role": "user",
                "content": tool_results
            })

            # La boucle continue : Claude va lire les résultats et décider de la suite.

    # Soupape déclenchée : ne devrait jamais arriver en fonctionnement normal
    return "Error: agent did not complete within the iteration limit"


# ÉTAPE 6 : lancer l'agent
if __name__ == "__main__":
    print("Running agent...")
    answer = run_agent("Where is my order #4821?")
    print(f"\nFinal answer: {answer}")

Et voici ce que donne python3 agent.py :

$ python3 agent.py
Running agent...
  → Calling tool: lookup_order({'order_id': '4821'})
  ← Result: {"status": "shipped", "eta": "March 30", "carrier": "FedEx"}

Final answer: Your order #4821 has been **shipped**! Here are the details:

- **Status:** Shipped
- **Carrier:** FedEx
- **Estimated Delivery Date:** March 30

Your order is on its way. You can track it further through FedEx using your tracking number…

Ce que l’API vérifie à chaque tour

Ces règles ne sont pas des conventions : si l’une est violée, l’API rejette la requête avec une erreur 400. L’examen les teste en décrivant un historique mal construit.

Une conséquence importante : tous les résultats d’un même tour partent dans un seul message user. Si Claude demande trois outils en parallèle, sa réponse contient trois blocs tool_use. La liste tool_results en contient alors trois, et un seul append les envoie. Les répartir sur trois messages casse la règle d’alternance.

Quand un outil échoue

Un outil peut planter : base injoignable, commande introuvable, délai dépassé. Ne levez pas d’exception qui interromprait la boucle : renvoyez l’échec à Claude, comme un résultat. Il pourra alors réessayer, demander une précision à l’utilisateur, ou expliquer le problème.

Le code ci-dessus renvoie un JSON {"error": ...}, ce qui fonctionne. L’API prévoit aussi un champ dédié, plus explicite :

tool_results.append({
    "type": "tool_result",
    "tool_use_id": block.id,
    "content": "Order 7777 not found",
    "is_error": True,        # signale à Claude que l'appel a échoué
})

7. Pourquoi c’est le modèle qui choisit l’outil

Dans l’exemple, personne n’a écrit « si la question parle de commande, appelle lookup_order ». C’est Haiku qui l’a décidé : il a lu la description de l’outil, l’a jugé utile, et l’a demandé avec stop_reason = "tool_use". Votre code l’a exécuté et a renvoyé le résultat. Claude a jugé que c’était suffisant et a terminé avec end_turn.

8. Les trois anti-patterns testés à l’examen

Ils ont une cause commune : remplacer le signal structuré de l’API par une astuce bricolée.

Anti-pattern 1 : lire les mots de Claude

# ✗ Mauvais
if "I have completed" in response.text:
    break

# ✓ Bon
if response.stop_reason == "end_turn":
    break

Pourquoi ça échoue. Claude ne formule jamais deux fois sa fin de la même façon. Et lors d’un tour tool_use, il peut n’y avoir aucun bloc texte : lire le texte provoque alors une IndexError et tout plante. C’est pour ça que le code de la section 6 prévoit return "". La règle : ne lisez pas le langage naturel, lisez le signal mécanique de l’API.

Anti-pattern 2 : un plafond d’itérations comme condition d’arrêt

# ✗ Mauvais : le plafond décide de la fin
if iterations >= 5:
    break

# ✓ Bon : stop_reason décide, le plafond ne sert que de disjoncteur
while iteration < MAX_ITERATIONS:      # garde-fou
    ...
    if response.stop_reason == "end_turn":   # vraie sortie
        ...

Pourquoi ça échoue. Un plafond arbitraire ignore la réalité de la tâche. Une tâche qui finit en 3 itérations gaspille des appels si on la force à continuer. Une tâche qui en demande 8 est coupée au milieu. Le plafond reste utile, mais comme un disjoncteur : il protège l’installation, il n’éteint pas la lumière à votre place.

Anti-pattern 3 : tester le type du contenu

Pourquoi ça échoue. Claude écrit souvent une phrase avant d’appeler un outil (« Laissez-moi vérifier… »), puis place le bloc tool_use. Sortir dès le premier bloc texte abandonne l’appel d’outil en silence. L’agent échoue sans lever la moindre erreur. Le type de contenu et stop_reason mesurent deux choses différentes : on ne remplace jamais l’un par l’autre.

9. L’implémentation de référence

Réduite à l’essentiel, voici la boucle de référence. Chaque ligne correspond à une règle :

while iteration < MAX_ITERATIONS:                      # la soupape de sécurité
    response = client.messages.create(...)

    if response.stop_reason == "end_turn":             # la sortie principale
        break

    messages.append({"role": "assistant",              # ajout 1 : la demande d'outil
                     "content": response.content})

    # ... exécuter l'outil demandé dans response ...

    messages.append({"role": "user", "content": [      # ajout 2 : le résultat, même id
        {"type": "tool_result", "tool_use_id": block.id, "content": result}
    ]})

Écrire la boucle soi-même, ou la déléguer

En production, on n’écrit pas toujours cette boucle à la main :

• le SDK Anthropic fournit un tool runner qui envoie la requête, exécute vos fonctions outils et reboucle jusqu’à end_turn ;
• le Claude Agent SDK va plus loin : il embarque la boucle complète de Claude Code, avec ses outils intégrés (fichiers, shell, recherche).

Ces outils automatisent exactement ce qui précède. Ils ne changent pas les règles : les mêmes stop_reason, les mêmes paires tool_use / tool_result, le même historique. C’est la mécanique que l’examen vérifie, et on la diagnostique d’autant mieux quand on l’a écrite une fois soi-même.

Fiche de révision

Glossaire

Quiz d’entraînement

Ces questions sont de moi, écrites dans le style de l’examen. Ce ne sont pas des questions officielles. Choisissez une réponse : la correction s’affiche aussitôt, et le score se calcule en bas. Connecté, votre meilleur score est gardé dans votre compte, et « Recommencer » efface seulement vos réponses à l’écran. Sans compte, rien n’est enregistré.

Pour la suite

L’épisode 2 passe aux systèmes multi-agents et au modèle du coordinateur. Un agent coordinateur répartit le travail entre des sous-agents, en étoile. La bonne nouvelle : le coordinateur utilise exactement la boucle de cet épisode. La seule différence, c’est que ses outils lancent d’autres agents.