Fonctionnement de la boucle d'agent

​

La boucle en un coup d’œil

1. Recevoir le prompt. Claude reçoit votre prompt, ainsi que le prompt système, les définitions d’outils et l’historique de conversation. Le SDK produit un SystemMessage avec le sous-type "init" contenant les métadonnées de session.
2. Évaluer et répondre. Claude évalue l’état actuel et détermine comment procéder. Il peut répondre avec du texte, demander un ou plusieurs appels d’outils, ou les deux. Le SDK produit un AssistantMessage contenant le texte et toutes les demandes d’appels d’outils.
3. Exécuter les outils. Le SDK exécute chaque outil demandé et collecte les résultats. Chaque ensemble de résultats d’outils est renvoyé à Claude pour la décision suivante. Vous pouvez utiliser des hooks pour intercepter, modifier ou bloquer les appels d’outils avant qu’ils ne s’exécutent.
4. Répéter. Les étapes 2 et 3 se répètent en cycle. Chaque cycle complet est un tour. Claude continue à appeler les outils et à traiter les résultats jusqu’à ce qu’il produise une réponse sans appels d’outils.
5. Retourner le résultat. Le SDK produit un AssistantMessage final avec la réponse textuelle (sans appels d’outils), suivi d’un ResultMessage avec le texte final, l’utilisation des tokens, le coût et l’ID de session.

​

Tours et messages

1. Tour 1 : Claude appelle Bash pour exécuter npm test. Le SDK produit un AssistantMessage avec l’appel d’outil, exécute la commande, puis produit un UserMessage avec la sortie (trois défaillances).
2. Tour 2 : Claude appelle Read sur auth.ts et auth.test.ts. Le SDK retourne le contenu des fichiers et produit un AssistantMessage.
3. Tour 3 : Claude appelle Edit pour corriger auth.ts, puis appelle Bash pour relancer npm test. Les trois tests réussissent. Le SDK produit un AssistantMessage.
4. Tour final : Claude produit une réponse textuelle uniquement sans appels d’outils : « Correction du bug d’authentification, les trois tests réussissent maintenant. » Le SDK produit un AssistantMessage final avec ce texte, puis un ResultMessage avec le même texte plus le coût et l’utilisation.

​

Types de messages

• SystemMessage : événements du cycle de vie de la session. Le champ subtype les distingue : "init" est le premier message (métadonnées de session), et "compact_boundary" se déclenche après compaction. En TypeScript, la limite de compaction est son propre type SDKCompactBoundaryMessage plutôt qu’un sous-type de SDKSystemMessage.
• AssistantMessage : émis après chaque réponse de Claude, y compris la réponse textuelle finale. Contient les blocs de contenu textuel et les blocs d’appels d’outils de ce tour.
• UserMessage : émis après chaque exécution d’outil avec le résultat d’outil renvoyé à Claude. Également émis pour toute entrée utilisateur que vous diffusez en boucle.
• StreamEvent : émis uniquement lorsque les messages partiels sont activés. Contient les événements de diffusion API bruts (deltas de texte, chunks d’entrée d’outil). Voir Réponses en flux.
• ResultMessage : marque la fin de la boucle d’agent. Contient le résultat textuel final, l’utilisation des tokens, le coût et l’ID de session. Vérifiez le champ subtype pour déterminer si la tâche a réussi ou a atteint une limite. Un petit nombre d’événements système de fin, tels que prompt_suggestion, peuvent arriver après, donc itérez le flux jusqu’à la fin plutôt que de vous arrêter au résultat. Voir Gérer le résultat.

​

Gérer les messages

• Résultats finaux uniquement : gérez ResultMessage pour obtenir la sortie, le coût et si la tâche a réussi ou a atteint une limite.
• Mises à jour de progression : gérez AssistantMessage pour voir ce que Claude fait à chaque tour, y compris les outils qu’il a appelés.
• Diffusion en direct : activez les messages partiels (include_partial_messages en Python, includePartialMessages en TypeScript) pour obtenir les messages StreamEvent en temps réel. Voir Réponses en flux en temps réel.

• Python : vérifiez les types de messages avec isinstance() par rapport aux classes importées de claude_agent_sdk (par exemple, isinstance(message, ResultMessage)).
• TypeScript : vérifiez le champ de chaîne type (par exemple, message.type === "result"). AssistantMessage et UserMessage enveloppent le message API brut dans un champ .message, donc les blocs de contenu sont à message.message.content, pas message.content.

from claude_agent_sdk import query, AssistantMessage, ResultMessage

async for message in query(prompt="Summarize this project"):
    if isinstance(message, AssistantMessage):
        print(f"Turn completed: {len(message.content)} content blocks")
    if isinstance(message, ResultMessage):
        if message.subtype == "success":
            print(message.result)
        else:
            print(f"Stopped: {message.subtype}")

​

Exécution des outils

​

Outils intégrés

• Connecter des services externes avec des serveurs MCP (bases de données, navigateurs, API)
• Définir des outils personnalisés avec des gestionnaires d’outils personnalisés
• Charger les compétences du projet via des sources de paramètres pour des flux de travail réutilisables

​

Permissions des outils

• allowed_tools / allowedTools approuve automatiquement les outils listés. Un agent en lecture seule avec ["Read", "Glob", "Grep"] dans sa liste d’outils autorisés exécute ces outils sans demander. Les outils non listés sont toujours disponibles mais nécessitent une permission.
• disallowed_tools / disallowedTools bloque les outils listés, indépendamment des autres paramètres. Voir Permissions pour l’ordre dans lequel les règles sont vérifiées avant qu’un outil s’exécute.
• permission_mode / permissionMode contrôle ce qui se passe pour les outils qui ne sont pas couverts par les règles d’autorisation ou de refus. Voir Mode de permission pour les modes disponibles.

​

Exécution parallèle des outils

​

Contrôler le fonctionnement de la boucle

​

Tours et budget

​

Niveau d’effort

​

Mode de permission

​

Modèle

​

La fenêtre de contexte

​

Ce qui consomme du contexte

​

Compaction automatique

• Instructions de résumé dans CLAUDE.md : Le compacteur lit votre CLAUDE.md comme tout autre contexte, donc vous pouvez inclure une section lui indiquant ce qu’il faut préserver lors de la résumé. L’en-tête de section est libre (pas une chaîne magique) ; le compacteur correspond sur l’intention.
• Hook PreCompact : Exécutez une logique personnalisée avant la compaction, par exemple pour archiver la transcription complète. Le hook reçoit un champ trigger (manual ou auto). Voir hooks.
• Compaction manuelle : Envoyez /compact comme chaîne de prompt pour déclencher la compaction à la demande. Les commandes envoyées de cette façon sont des entrées SDK, pas des raccourcis CLI uniquement. Voir commandes dans le SDK.

# Summary instructions

When summarizing this conversation, always preserve:
- The current task objective and acceptance criteria
- File paths that have been read or modified
- Test results and error messages
- Decisions made and the reasoning behind them

​

Garder le contexte efficace

• Utilisez des sous-agents pour les sous-tâches. Chaque sous-agent commence avec une conversation fraîche (pas d’historique de messages antérieurs, bien qu’il charge son propre prompt système et le contexte au niveau du projet comme CLAUDE.md). Il ne voit pas les tours du parent, et seule sa réponse finale retourne au parent comme résultat d’outil. Le contexte de l’agent principal croît par ce résumé, pas par la transcription complète de la sous-tâche. Voir Ce que les sous-agents héritent pour les détails.
• Soyez sélectif avec les outils. Chaque définition d’outil prend de l’espace de contexte. Utilisez le champ tools sur AgentDefinition pour délimiter les sous-agents à l’ensemble minimum dont ils ont besoin.
• Surveillez les coûts des serveurs MCP. La recherche d’outils MCP diffère les schémas d’outils MCP par défaut et les charge à la demande. Lorsque la recherche d’outils est désactivée, sur Vertex AI, ou derrière une ANTHROPIC_BASE_URL non-propriétaire, chaque serveur MCP ajoute tous ses schémas d’outils à chaque requête, donc quelques serveurs avec de nombreux outils peuvent consommer un contexte significatif avant que l’agent ne fasse aucun travail.
• Utilisez un effort inférieur pour les tâches de routine. Définissez effort à "low" pour les agents qui n’ont besoin que de lire des fichiers ou de lister des répertoires. Cela réduit l’utilisation des tokens et le coût.

​

Sessions et continuité

​

Gérer le résultat

​

Hooks

​

Tout mettre ensemble

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage


async def run_agent():
    session_id = None

    async for message in query(
        prompt="Find and fix the bug causing test failures in the auth module",
        options=ClaudeAgentOptions(
            allowed_tools=[
                "Read",
                "Edit",
                "Bash",
                "Glob",
                "Grep",
            ],  # Listing tools here auto-approves them (no prompting)
            setting_sources=[
                "project"
            ],  # Load CLAUDE.md, skills, hooks from current directory
            max_turns=30,  # Prevent runaway sessions
            effort="high",  # Thorough reasoning for complex debugging
        ),
    ):
        # Handle the final result
        if isinstance(message, ResultMessage):
            session_id = message.session_id  # Save for potential resumption

            if message.subtype == "success":
                print(f"Done: {message.result}")
            elif message.subtype == "error_max_turns":
                # Agent ran out of turns. Resume with a higher limit.
                print(f"Hit turn limit. Resume session {session_id} to continue.")
            elif message.subtype == "error_max_budget_usd":
                print("Hit budget limit.")
            else:
                print(f"Stopped: {message.subtype}")
            if message.total_cost_usd is not None:
                print(f"Cost: ${message.total_cost_usd:.4f}")


asyncio.run(run_agent())

​

Étapes suivantes

• Vous n’avez pas encore exécuté un agent ? Commencez par le démarrage rapide pour obtenir le SDK installé et voir un exemple complet s’exécutant de bout en bout.
• Prêt à vous connecter à votre projet ? Chargez CLAUDE.md, les compétences et les hooks du système de fichiers afin que l’agent suive automatiquement les conventions de votre projet.
• Construisez une interface utilisateur interactive ? Activez la diffusion pour afficher le texte en direct et les appels d’outils lorsque la boucle s’exécute.
• Avez-vous besoin d’un contrôle plus strict sur ce que l’agent peut faire ? Verrouillez l’accès aux outils avec les permissions et utilisez les hooks pour auditer, bloquer ou transformer les appels d’outils avant qu’ils ne s’exécutent.
• Exécutez des tâches longues ou coûteuses ? Déléguez le travail isolé aux sous-agents pour garder votre contexte principal maigre.