Construire un agent IA avec n8n et Claude

Workflow vs agent : la différence

Un workflow n8n classique exécute une suite déterministe : étape A, puis B, puis C. Un agent, c'est un workflow qui boucle, et où le LLM décide à chaque tour quelle action prendre.

Un workflow déterministe suffit dans 80 % des cas. Mais quand le chemin de résolution dépend du contenu (genre : "lis ce ticket support, pose les bonnes questions, classifie-le"), il faut un agent.

L'architecture en 3 nœuds

1. Loop : un nœud "Loop Over Items" qui boucle tant qu'on n'a pas atteint l'état final
2. Claude (tool use) : appel à l'API Claude avec une liste de tools définis
3. Tool router : un Switch qui dispatch vers le bon sous-workflow selon le tool choisi par Claude

Définir les tools

C'est la partie qui demande le plus de soin. Chaque tool doit avoir :

• Un nom court et descriptif (search_tickets, pas fn1)
• Une description claire de quand l'utiliser (pas seulement ce qu'il fait)
• Un schema JSON strict pour les paramètres

{
  "name": "search_tickets",
  "description": "Use this when the user mentions an existing issue. Searches Linear by keyword.",
  "input_schema": {
    "type": "object",
    "properties": {
      "query": { "type": "string", "description": "Search keywords" }
    },
    "required": ["query"]
  }
}

Plus la description est précise, moins l'agent hallucine d'appels inutiles.

La boucle

Pseudo-code de la logique :

messages = [system, user_input]
while True:
    response = claude(messages, tools)
    if response.stop_reason == "end_turn":
        break
    if response.stop_reason == "tool_use":
        for tool in response.tool_calls:
            result = execute_tool(tool)
            messages.append(tool_result(tool.id, result))

Dans n8n, ça se traduit par un nœud Code qui assemble messages, un nœud HTTP qui appelle Claude, un Switch qui regarde stop_reason, et un retour en boucle si nécessaire.

Garde-fous indispensables

Sinon votre agent peut tourner en rond et coûter cher :

• Limite de tours (max 10 itérations, par exemple). Si l'agent n'a pas convergé, on stoppe et on alerte.
• Budget de tokens : compter le total et arrêter au-delà d'un seuil.
• Logs structurés : sauver chaque appel Claude + chaque tool call. Indispensable pour debugger.

Quel modèle choisir

• Haiku : pour des agents simples (1 à 3 tools, peu d'ambiguïté). Rapide et pas cher.
• Sonnet : le sweet spot. Meilleur tool use, raisonnement plus solide.
• Opus : pour des décisions complexes ou des raisonnements en plusieurs étapes. Lent et cher.

En pratique je commence sur Haiku, je monte à Sonnet si l'agent fait des erreurs de raisonnement.

Erreurs que j'ai faites

• Trop de tools (>10) : l'agent se perd. Mieux vaut grouper en sous-agents spécialisés.
• Descriptions de tools trop génériques : l'agent appelle au hasard.
• Pas de garde-fou sur le nombre de tours : un bug a fait tourner un agent 200 fois en 5 minutes. 8 USD plus tard, j'ai mis une limite.

Bonus : versionner les prompts

Le prompt système est du code. Versionnez-le dans Git, taggez les versions qui marchent, faites des A/B sur les versions candidates. Sans ça, on ne sait jamais pourquoi un agent qui marchait hier ne marche plus aujourd'hui.