Nœud Agent IA

Le nœud Agent IA est le moteur d'intelligence de vos flux : il comprend un objectif métier, raisonne sur le contexte de l'exécution, puis agit en mobilisant les bons outils au bon moment. Sans code, il permet de passer d'un flux « automatisé » à un flux « intelligent » : comprendre un objectif métier décrit en langage naturel, raisonner sur le contexte disponible (données du déclencheur, variables du flux), agir en appelant des outils internes (un autre nœud du flux) ou des serveurs MCP, et renvoyer une réponse exploitable par les nœuds suivants, texte ou JSON structuré.

Paramètres

Paramètre	Type	Obligatoire	Défaut	Description
App	App	❌	—	Application associée au nœud.
Message système	Texte	❌	—	Cadre global de l'agent : ton, rôle, règles de décision.
Message utilisateur	Texte	❌	—	Consigne métier à exécuter à chaque exécution.
Paramètres modèle	Objet	✅	—	Modèle IA à utiliser : fournisseur (`Gemini`, `OpenAI`, `Mistral`, `Anthropic`), nom du modèle, clé API, température, limites de tokens.
URL du modèle personnalisé	String	❌	—	Endpoint API alternatif (modèle auto-hébergé, proxy ou gateway). Laissez vide pour utiliser les endpoints par défaut du fournisseur.
Outils	Liste	❌	—	Capacités d'action : associe un outil à un nœud du flux que l'agent peut appeler.
Serveurs MCP	Liste	❌	—	Outils externes exposés à l'agent via un serveur MCP (HTTP ou SSE).
Sortie structurée	Chaîne JSON	❌	—	JSON Schema qui force l'agent à renvoyer une réponse structurée et validée.
Clé de sortie	String	❌	`agentOutput`	Emplacement de la réponse dans le contexte.
Limite d'étapes	Nombre	❌	`25`	Nombre maximal d'appels d'outils et d'itérations de l'agent.

Message système et Message utilisateur

Le Message système installe le comportement de l'agent (« Tu es un assistant qui rédige des réponses d'incidents en français, en moins de 3 phrases. »).
Le Message utilisateur est la consigne d'exécution, avec les variables du flux :

Résume ce ticket en 5 points maximum : {{context.ticket}}

Paramètres modèle

Le fournisseur doit être supporté par la plateforme : Gemini, OpenAI, Mistral et Anthropic (modèles Claude) sont disponibles.

Clé API : renseignez-la dans les paramètres du modèle, ou laissez-la vide si une méthode d'authentification fournit le token.
Température : plus elle est basse, plus la réponse est déterministe (utile pour une sortie structurée).

Outils (nœuds du flux)

Champ	Obligatoire ?	Description
`Message système` (`systemPrompt`)	❌	Cadre global, ton, règles de décision de l’agent.
`Message utilisateur` (`message`)	❌	Consigne métier à exécuter à chaque run.
`Paramètres modèle` (`model`)	✅	Configuration du LLM : provider supporté (`Gemini`, `OpenAI`, `Mistral`, `Anthropic`), nom du modèle, clé API du LLM (`apiKey`), température, limites de tokens.
`URL du modèle personnalisé` (`model.url`)	❌	Optionnellement spécifiez une URL d'endpoint API personnalisé. Cela vous permet d'utiliser des modèles auto-hébergés ou des endpoints API alternatifs. Laissez vide pour utiliser les endpoints par défaut du fournisseur.
`Outils` (`tools`)	❌	Capacités d’action internes du flux (cœur de l’intelligence).
`Serveurs MCP` (`mcpServers`)	❌	Outils externes exposés à l’agent via HTTP/SSE.
`Sortie structurée` (`responseFormat`)	❌	JSON Schema de validation de la réponse.
`Clé de sortie` (`outputKey`)	❌	Emplacement de sortie dans le contexte (défaut: `agentOutput`).
`Limite d’étapes` (`recursionLimit`)	❌	Nombre max d’appels tools/itérations (défaut: `25`).

Un outil relie l'agent à un nœud existant du flux. Quand l'agent décide d'agir, le flux exécute ce nœud puis revient vers l'agent avec le résultat.

Champ d'un outil	Description
Nom	Identifiant de l'outil (minuscules, chiffres et `_` uniquement).
Description	Explique à l'agent quand et comment utiliser l'outil — la qualité de cette description influence directement la performance.
Schéma d'entrée	JSON Schema (sous forme de chaîne) décrivant les paramètres attendus par l'outil.
Nœud cible	Nœud du flux à exécuter lorsque l'outil est appelé.

Exemple d'outil

Un outil get_customer avec la description « Récupère un client par email » et un schéma d'entrée {"type":"object","required":["email"],"properties":{"email":{"type":"string"}}}. Quand l'agent a besoin du client, il appelle l'outil, le flux exécute le nœud cible (par exemple une requête SQL), et l'agent reçoit le résultat.

Serveurs MCP

Connectez un serveur MCP (Model Context Protocol) pour exposer à l'agent des outils hébergés à l'extérieur du flux :

Nom : identifiant du serveur ;
Transport : HTTP ou SSE ;
URL : adresse du serveur MCP ;
Headers : en-têtes éventuels (ex. authentification).

Sortie structurée

Collez un JSON Schema (sous forme de chaîne) pour contraindre la réponse : l'agent doit renvoyer un objet qui respecte ce schéma, sinon le nœud échoue. C'est le moyen fiable d'alimenter les nœuds suivants avec un objet aux clés garanties.

Exemple — classifier une demande support :

{
  "type": "object",
  "required": ["category", "priority"],
  "properties": {
    "category": { "type": "string" },
    "priority": { "type": "string", "enum": ["LOW", "MEDIUM", "HIGH"] }
  }
}

Points d'attention

astuce

Sortie structurée et Schéma d'entrée se collent comme des chaînes JSON valides, pas comme des objets.
Sans Sortie structurée, la sortie est le dernier message de l'agent (texte) — moins fiable pour automatiser un traitement.
Un Outil dont le nœud cible est absent ou invalide provoque une erreur à l'exécution.
Si la Limite d'étapes est atteinte, le nœud renvoie une erreur explicite : augmentez la limite si l'agent doit enchaîner beaucoup d'actions.
Sans outils, l'agent reste surtout conversationnel : pour qu'il agisse, donnez-lui des outils bien décrits.

Entrée

Le nœud reçoit le contexte de l'exécution (données du déclencheur, variables du flux) ainsi que la consigne métier du Message utilisateur, qui peut utiliser les variables Handlebars du contexte :

Résume ce ticket en 5 points maximum : {{context.ticket}}

Sortie

La réponse de l'agent est injectée dans context.<outputKey> (défaut : context.agentOutput) :

{
  "agentOutput": {
    "answer": "Voici l'analyse du texte demandé…",
    "model": "gpt-4-turbo",
    "usage": {
      "promptTokens": 150,
      "completionTokens": 300,
      "totalTokens": 450
    },
    "stopReason": "stop"
  }
}

Propriété	Description
`answer`	Réponse de l'agent : texte du dernier message, ou objet structuré si une Sortie structurée est configurée.
`model`	Modèle utilisé pour la génération.
`usage`	Consommation de tokens (`promptTokens`, `completionTokens`, `totalTokens`).
`stopReason`	Raison de fin de génération (`stop`, `length`, `tool_calls`, …).

Dans les nœuds suivants, accédez à la réponse via {{agentOutput.answer}} (champs des nœuds) ou context.agentOutput.answer (nœud Code). Si vous avez personnalisé la Clé de sortie, remplacez agentOutput par votre clé.

Erreurs

Outil invalide — un outil dont le nœud cible est absent ou invalide provoque une erreur à l'exécution.
Limite d'étapes atteinte — le nœud renvoie une erreur explicite ; augmentez la limite si l'agent doit enchaîner beaucoup d'actions.
Sortie non conforme — si une Sortie structurée est configurée et que la réponse de l'agent ne respecte pas le schéma, le nœud échoue.

En cas d'échec, ajoutez un nœud On Error au flux pour gérer proprement l'échec.

Limites

La Limite d'étapes (défaut 25) borne le nombre d'appels d'outils et d'itérations de l'agent ; une fois atteinte, le nœud renvoie une erreur explicite.
Le fournisseur du modèle doit être supporté par la plateforme (voir Paramètres modèle).

Exemple

Récupérer un client avec l'outil get_customer :

Dans les Outils, ajoutez un outil get_customer avec la description « Récupère un client par email » et le schéma d'entrée {"type":"object","required":["email"],"properties":{"email":{"type":"string"}}}.
Reliez l'outil à un nœud cible existant du flux (par exemple une requête SQL).
Quand l'agent a besoin du client, il appelle l'outil : le flux exécute le nœud cible puis revient vers l'agent avec le résultat.
La réponse de l'agent est disponible dans context.agentOutput pour les nœuds suivants.

Paramètres​

Message système et Message utilisateur​

Paramètres modèle​

Outils (nœuds du flux)​

Serveurs MCP​

Sortie structurée​

Points d'attention​

Entrée​

Sortie​

Erreurs​

Limites​

Exemple​

Voir aussi​