Architecture d'agent Claude : tools, memory, orchestration

Si tu pilotes un projet d'agent Claude en interne ou avec un prestataire, tu n'as pas besoin de savoir coder une boucle agentique. Tu as besoin de comprendre les trois briques qui la composent, parce que ce sont elles qui détermineront ton coût mensuel, ta vitesse de mise en prod, et le moment où ton agent va dérailler. Cet article décortique l'architecture qu'Anthropic expose via son API : la boucle d'orchestration, les outils, la mémoire, et les arbitrages structurants. Pour le contexte plus large sur ce qu'est un agent et à quoi il sert, va voir le guide complet pour apprendre Claude. Ici, on entre sous le capot.

Ce qu'on appelle vraiment un agent Claude

Anthropic utilise une définition opératoire simple : un agent, c'est un LLM qui exécute une boucle. Claude raisonne, décide d'appeler un outil, lit le résultat, recommence. Ça s'arrête quand il renvoie une réponse finale ou quand un critère d'arrêt est atteint. C'est tout.

Trois choses à distinguer pour ne pas se tromper de vocabulaire en réunion :

• Un chat : Claude répond, point. Pas d'outil, pas de boucle.
• Un workflow : une séquence d'appels LLM scriptée par toi (étape 1, étape 2, étape 3). Claude n'a pas le contrôle du chemin.
• Un agent : Claude décide lui-même quels outils appeler, dans quel ordre, et quand s'arrêter. C'est lui qui pilote.

L'architecture qu'on décrit ici est celle de l'API Anthropic avec tool use, pas une surcouche type framework. Pourquoi c'est important : si ton prestataire te vend un "agent" qui est en fait un workflow déguisé, tu paies du conseil pour quelque chose qui aurait coûté trois fois moins. La construction d'agents IA autonomes avec Claude implique vraiment de laisser le modèle décider, sinon ce n'en est pas un.

La boucle agentique : le coeur de l'orchestration

Le cycle est mécaniquement simple. Tu envoies à l'API un prompt système, un objectif, et la liste des outils disponibles. Claude répond avec soit du texte final, soit un ou plusieurs tool calls. Ton code exécute les tool calls côté serveur, renvoie les résultats dans le contexte, et Claude reprend la main. Boucle jusqu'à terminaison.

boucle:
  réponse = claude.messages.create(messages, tools)
  si réponse.stop_reason == "end_turn": fin
  si réponse.stop_reason == "tool_use":
    résultats = exécuter(réponse.tool_calls)
    messages.append(résultats)
    continuer

La vraie unité d'architecture, ce n'est pas le prompt système, c'est cette boucle. Trois paramètres la pilotent et tu dois les connaître pour arbitrer.

• max_tokens par réponse : combien Claude peut écrire à chaque tour. Trop bas, il coupe ; trop haut, tu paies pour rien.
• Nombre max d'itérations : ton garde-fou contre un agent qui tourne en rond. Mets-le entre 10 et 30 selon la tâche.
• Stop conditions : critères logiques côté ton code (budget atteint, objectif validé par un autre LLM, signal humain).

Un agent sans cap sur ces trois paramètres, c'est un agent qui peut consommer 50 € sur une tâche qui aurait dû en coûter 2. C'est le premier garde-fou à demander à ton équipe.

Les tools : l'interface entre Claude et le monde réel

Un tool, c'est une fonction que tu déclares à Claude via un schéma JSON. Trois champs : name, description, input_schema. Exemple pour un outil qui interroge HubSpot :

{
  "name": "search_crm",
  "description": "Recherche un contact dans HubSpot par email ou nom de société. Renvoie les 5 résultats les plus pertinents avec leur statut, leur owner, et la date du dernier contact.",
  "input_schema": {
    "type": "object",
    "properties": {
      "query": {"type": "string"},
      "filter": {"type": "string", "enum": ["email", "company"]}
    },
    "required": ["query"]
  }
}

Le point critique, et c'est contre-intuitif quand on vient du code classique : la qualité de la description compte plus que celle du code derrière. Claude choisit d'appeler un tool en lisant sa description. Une description vague ("recherche dans le CRM"), c'est des appels ratés, des doublons, des hallucinations sur les paramètres. Une description précise (avec les cas d'usage, les limites, ce que renvoie l'outil), c'est un agent fiable.

Tu as deux options pour brancher tes outils. Soit tu codes des tools custom (tu écris la fonction Python ou Node, tu la connectes à l'API). Soit tu utilises le Model Context Protocol, le standard ouvert lancé par Anthropic en 2024, qui te donne des serveurs prêts à l'emploi pour GitHub, Slack, Postgres, Notion et la plupart des SaaS courants. Règle de pouce : si l'outil existe en MCP, prends MCP ; sinon, custom. Pour creuser le sujet côté implémentation, jette un œil à l'article sur la mise en place d'un serveur MCP avec Claude.

La memory : trois couches à ne pas confondre

C'est l'endroit où la majorité des projets surinvestissent. "Il faut du RAG", "il faut une base vectorielle", entend-on en kickoff. Souvent non. Trois couches existent, et elles ne servent pas à la même chose.

La fenêtre de contexte chez Claude Sonnet 4.6 et Opus 4.7 monte à 1 million de tokens. C'est énorme. Pour beaucoup de cas (analyser un contrat, traiter une fiche client complète, parcourir un repo), tu n'as besoin de rien d'autre que de bien remplir le contexte au début du run.

La mémoire de session, c'est juste un historique de messages que ton appli stocke et réinjecte au prochain tour. Une table Postgres avec session_id et messages suffit.

La mémoire long terme se découpe à son tour. Pour des faits structurés (le client X a tel plan, telle date de renouvellement), une table SQL bat n'importe quelle base vectorielle. Pour de la recherche sémantique dans un corpus non structuré (FAQ, docs internes, archives email), là, le vectoriel a du sens. Le réflexe "RAG par défaut" est souvent la mauvaise décision. Si tes données tiennent dans une table, mets-les dans une table.

Orchestration : agent unique ou multi-agents

Deux patterns coexistent. Le single-agent, c'est un Claude avec une liste de tools, qui boucle jusqu'à finir la tâche. Simple à debugger, suffisant pour la grande majorité des cas pros : qualification de leads, génération de devis, synthèse de tickets support, suivi de projet.

Le multi-agents, c'est un orchestrator (un Claude principal) qui délègue à des sub-agents spécialisés, chacun avec son propre contexte et ses propres tools. Anthropic a documenté ce pattern sous le nom orchestrator-workers. Ça devient pertinent dans deux situations précises :

• Les sous-tâches sont parallélisables (auditer 50 contrats en même temps, chercher dans 10 sources de données simultanément).
• Un contexte unique dépasse régulièrement 100k tokens et tu vois Claude se perdre dans des détails non pertinents.

Repère pratique : au-delà d'environ 15 tools déclarés à un seul agent, sa précision sur le choix du bon tool commence à se dégrader. C'est souvent le signal pour passer en multi-agents. Pas avant. Le multi-agents multiplie la complexité de debug par trois, le coût en tokens par deux à cinq, et le délai de mise en prod par deux. Ne le déclenche que si tu as une raison claire.

Les décisions d'architecture qui coûtent cher si on les rate

Cinq arbitrages reviennent dans chaque projet. Tu peux les anticiper.

1. Choix du modèle par tâche. Haiku 4.5 (à partir de 1 $ / million tokens en input) pour les sous-tâches simples : extraction, classification, reformulation. Sonnet 4.6 pour le raisonnement courant. Opus 4.7 pour les tâches longues ou qui demandent de la profondeur d'analyse. Un agent qui appelle Opus pour tout coûte 5 à 10 fois plus que nécessaire. Pour comparer plus largement avec d'autres modèles, regarde l'article Claude vs ChatGPT.

2. Gestion des erreurs de tool. Un appel API qui timeout, un schéma JSON mal validé, une 500 côté HubSpot. Sans logique de retry, fallback et escalade humaine, ton agent plante à la première anomalie. Demande explicitement à ton équipe comment chaque tool gère les trois cas.

3. Observabilité. Tu dois pouvoir relire chaque tool call avec son input, son output, son timing, son coût. Sans ça, debugger en prod prend des jours. Un simple log structuré en JSON dans une table Postgres suffit pour démarrer.

4. Budget tokens par run. Cap dur côté code : si un run dépasse X tokens ou Y euros, on stoppe et on alerte. C'est non négociable.

5. Permissions et human-in-the-loop. Un agent qui peut envoyer un email à un client, modifier une fiche CRM ou exécuter un paiement doit avoir une validation humaine sur les actions sensibles. Définis ce qui est "sensible" avant de coder, pas après le premier incident.

Schéma d'architecture minimal pour démarrer

Voici la stack qu'une équipe de deux personnes (un dev backend, un chef de projet métier) peut monter en deux à trois semaines :

• L'API Anthropic en direct, modèle Sonnet 4.6 par défaut.
• Trois à cinq tools custom couvrant les actions critiques du métier (lire/écrire dans le CRM, envoyer un email, créer une tâche).
• Une table Postgres pour la mémoire long terme et l'historique des sessions.
• Un système de logs basique mais structuré : un row par tool call, avec input/output/timing/coût.
• Un cap dur sur le nombre d'itérations et le budget tokens par run.

Ce que tu évites à ce stade : pas de framework lourd (LangChain, LangGraph), pas de multi-agents, pas de base vectorielle si tes données tiennent en SQL. Pour le setup initial côté Claude.ai et premiers prompts en amont du dev, l'article sur la configuration de Claude et premiers prompts couvre les bases.

Cette architecture minimale couvre 80 % des cas d'usage qu'on voit en entreprise. C'est seulement quand tu as un agent en prod, des logs propres et une vraie volumétrie que tu commences à arbitrer pour rajouter une couche : RAG, multi-agents, fine-tuning. Dans l'autre sens, partir tout de suite sur une archi sophistiquée, c'est six mois de chantier pour valider une idée qui aurait pu être testée en trois semaines.

Passer à la pratique

Comprendre l'architecture, c'est une chose ; faire les bons arbitrages sur ton premier projet d'agent en est une autre. Le délai entre "on lance" et "c'est en prod" se joue dans les premières décisions : choix du modèle, périmètre des tools, structure de la mémoire, garde-fous de coût. Si tu veux un cadre clair pour décider et un accompagnement pour piloter vos agents autonomes avec Ottho, c'est là que la formation Claude Agent entre en jeu : cinq semaines, six livrables concrets, pour passer du PoC au déploiement maîtrisé.