AI Agent

Le node AI Agent exécute un LLM autonome capable de planifier, d'appeler des outils et des serveurs MCP pour accomplir des tâches multi-étapes.

À quoi sert le node AI Agent ?#

Le node AI Agent transforme un LLM en exécuteur autonome. Contrairement au node LLM — qui produit une réponse unique à partir d’un prompt — l’Agent raisonne sur vos instructions, décide quels outils, datasources ou serveurs MCP appeler, observe les résultats et itère jusqu’à atteindre l’objectif. Il renvoie une seule réponse texte une fois qu’il considère la tâche terminée.

Cas d’usage typiques :

• Recherche multi-étapes combinant recherche web, scraping et synthèse dans un seul node.
• Question-réponse ancrée sur une base de connaissances privée via RAG (datasources).
• Pilotage de systèmes externes via des serveurs MCP (API internes, bases de données) sans avoir à créer de nodes dédiés.
• Workflows d’enrichissement de données mêlant contexte documentaire, outils web et raisonnement structuré.

Configuration rapide#

Suivez ces étapes pour ajouter et configurer le node AI Agent dans votre workflow :

Enregistrer et mettre à jour le prompt#

Depuis le canevas, ouvrez le node Agent et cliquez sur Edit instructions en bas du panneau pour rédiger le prompt qui définit la tâche et le comportement de l’agent à chaque run.

Edit instructions#

Enhance Instructions#

La fonctionnalité Enhance Instructions (badge BETA) transforme un prompt minimal en instructions structurées et détaillées, adaptées à la tâche et aux variables déjà présentes dans le node. Partez par exemple d’une consigne aussi simple que génère un article optimisé pour le SEO avec YourText.Guru : l’assistant génère un prompt complet (persona, étapes, contraintes de format) en tenant compte des variables connectées ({{ytt_data}}, {{target_keyword}}, etc.).

Pendant la génération, le bouton Stop & Revert instructions interrompt le processus et restaure le prompt précédent :

Une fois la génération terminée, le prompt enrichi s’affiche dans l’éditeur et reste entièrement modifiable. Vous pouvez le retoucher manuellement, cliquer sur Rollback previous instructions pour revenir à la version antérieure, ou relancer Enhance Instructions pour une nouvelle proposition :

Guider l’agent : Tools, RAG et MCP#

Attacher des capacités dans Agent Settings ne suffit pas : l’agent doit savoir quand, comment et jusqu’où les utiliser. Sans cadre explicite dans le prompt, il peut ignorer un outil, boucler sur le même appel ou dépasser un budget raisonnable.

Principes à intégrer dans vos instructions :

• Nommez chaque capacité attachée et son rôle dans la tâche (« utilise le RAG pour… », « appelle le serveur MCP CRM pour… »).
• Définissez un ordre de priorité : par exemple RAG d’abord, puis Web Search seulement si la réponse manque dans les sources.
• Fixez des limites : nombre maximal d’appels d’outils, de requêtes RAG ou de fonctions MCP par exécution.
• Précisez le comportement en cas d’échec : continuer avec les données partielles, signaler l’absence d’information, ou s’arrêter.
• Indiquez le format de sortie attendu une fois les capacités utilisées (texte, JSON, liste de sources citées).

Exemples d’instructions — RAG seul

Capacités attachées : datasource « Product docs » (PDF, MARKDOWN).

• Interroge la base de connaissances avant de formuler ta réponse.
• Réponds uniquement à partir des documents RAG attachés ; si l’information est absente, indique « Non documenté dans les sources disponibles ».
• Cite le titre du document source pour chaque affirmation clé.
• Limite-toi à 3 requêtes RAG maximum, puis synthétise.

Exemples d’instructions — Tools (Web Search + Web Scraper)

Capacités attachées : Web Search, Web Scraper.

• Utilise Web Search pour identifier le site officiel à partir du domaine de {{lead_email}}.
• Scrape uniquement la homepage et la page « About » — pas d’autres URLs sans justification.
• Effectue au maximum 5 appels d’outils au total ; si une page est inaccessible, passe à l’étape suivante.
• Retourne un JSON avec les clés company_name, website, summary.

Exemples d’instructions — MCP (serveur Fathom)

Capacités attachées : serveur MCP Fathom (list_meetings, get_meeting_transcript).

• Appelle list_meetings pour récupérer les réunions des 7 derniers jours liées à {{contact_email}}.
• N’invoque get_meeting_transcript que si une réunion correspond explicitement à la demande utilisateur.
• Ne dépasse pas 3 appels MCP ; résume les points d’action en fin de réponse.
• Si aucune réunion n’est trouvée, réponds sans inventer de contenu.

Exemples d’instructions — Tools + RAG + MCP combinés

Capacités attachées : RAG « Product docs », Haloscan tool, serveur MCP CRM, Web Search.

• Étape 1 — RAG : consulte « Product docs » pour le positionnement produit et les arguments de vente.
• Étape 2 — Haloscan : une analyse SEO par mot-clé cible ({{target_keyword}}) ; ne relance pas l’outil sur des variantes proches.
• Étape 3 — MCP CRM : vérifie si le compte {{company_domain}} existe déjà ; n’effectue qu’un seul appel de lecture.
• Étape 4 — Web Search : uniquement pour des données marché récentes absentes du RAG.
• Budget global : 10 appels d’outils/MCP maximum, puis produis la synthèse finale et arrête.

Paramètres de configuration#

Configurer le node revient à choisir un modèle, rédiger des instructions claires et exposer les bonnes capacités — rien d’autre n’est obligatoire.

LLM Settings#

Agent Settings#

Ouvrez les paramètres du node et basculez sur l’onglet Agent Settings pour attacher des outils, des sources RAG, des serveurs MCP et le message système de l’agent.

Que renvoie le node ?#

Le node renvoie la réponse texte finale de l’agent sous forme de string — une fois qu’il décide que la tâche est terminée. Les appels d’outils, le raisonnement intermédiaire et les observations ne font pas partie de la sortie : seule la réponse l’est.

Comment récupérer l’output ?#

Dans Draft & Goal, vous n’avez pas besoin de chercher un nom de variable complexe généré par le système. Pour exploiter le résultat :

1. Tirez un lien depuis la sortie du node AI Agent.
2. Connectez-le à l’entrée du node suivant.
3. Dans ce node suivant, créez et nommez votre propre variable (par exemple agent_answer). La réponse finale de l’agent y sera injectée automatiquement.

Exemples d’utilisation#

Cas 1 : Q&A ancré sur une base de connaissances privée#

Vous voulez que l’agent réponde aux questions support strictement à partir de votre documentation.

Configuration :

• Model name : un LLM avec capacités de raisonnement (classe GPT-4 par exemple).
• System Message :

You are a support assistant. Only answer using information from the
attached knowledge base. If the answer is not in the sources, say
"I don't know based on the available documentation."

• prompt :

Question from the customer: {{customer_question}}

Search the knowledge base, then provide:
- A concise answer (max 4 sentences)
- The 1-3 most relevant source titles you used

• RAG : sélectionnez votre datasource « Product docs ».
• Tools / MCP Servers : aucun — l’agent doit s’appuyer uniquement sur le RAG.

Cas 2 : Recherche multi-étapes avec outils et MCP#

Vous voulez que l’agent enrichisse un lead en combinant des outils web et un CRM interne exposé via MCP.

Configuration :

• prompt :

Enrich the lead {{lead_email}}:
1. Use the web search tool to find the company website from the email domain.
2. Scrape the homepage and "About" page to extract industry, size, and value proposition.
3. Call the CRM MCP server to check whether this account already exists.
4. Return a JSON object with keys: company_name, website, industry, size_estimate, exists_in_crm, summary.

Use at most 8 tool calls. If a step fails, continue with whatever information you have.

• Tools : Web Search, Web Scraper.
• MCP Servers : votre serveur CRM interne.
• Temperature : 0.3 pour rendre la sélection d’outils reproductible.

Problèmes courants#

Le node échoue à la validation avec 'Agent requires instructions to be configured'

Cause : Le champ prompt est vide ou ne contient que des espaces.

Solution : Ouvrez les paramètres du node et remplissez le champ prompt avec la tâche à effectuer. Le validateur supprime les espaces, donc un simple espace ne suffit pas.

L'agent boucle, refait le même appel d'outil ou ne termine jamais

Cause : Les instructions ne définissent pas de condition d’arrêt claire, ou le modèle est trop faible pour planifier de manière fiable.

Solution : Ajoutez un budget explicite dans le prompt (« Use at most N tool calls », « If you cannot find X, say so and stop »). Passez sur un modèle de raisonnement plus puissant. Baissez Temperature à 0,2–0,4.

La réponse finale est tronquée

Cause : Max output tokens est trop bas pour le format demandé, ou l’agent a consommé son budget en raisonnement intermédiaire.

Solution : Augmentez Max output tokens. Demandez à l’agent dans le prompt une réponse plus courte et structurée. Pour les modèles de raisonnement, augmentez aussi Thinking Budget si la troncature survient pendant le thinking.

La connexion d'un node File échoue avec une erreur de type de fichier

Cause : Le node Agent n’accepte que les Structured Documents (csv, xlsx, json, xml) et Unstructured Documents (pdf, txt, md, docx, pptx) provenant d’un node File input. Les autres types sont rejetés à la connexion.

Solution : Modifiez le type du node File pour un type supporté, ou pré-traitez le fichier avec un node de conversion avant de l’envoyer à l’agent.

L'agent ignore mes datasources ou serveurs MCP

Cause : Les instructions ne les mentionnent pas, donc l’agent ne sait pas qu’ils sont disponibles — ou il les a jugés non pertinents pour la tâche en cours.

Solution : Référencez explicitement la capacité dans le prompt (« Use the knowledge base to answer », « Call the CRM MCP server to verify the account »). Indiquez le nom de la datasource dans le system message.

Bonnes pratiques et pièges à éviter#

Comment s’intègre-t-il dans un workflow ?#

Le node AI Agent remplace typiquement une chaîne de nodes LLM + outils dès qu’un raisonnement entre étapes est nécessaire. Voici un schéma typique d’intégration pour un workflow recherche-puis-action :

graph LR
    Input[Text Input
<br/>topic or lead] --> Agent[AI Agent
<br/>plans + uses tools/RAG/MCP]
    Agent --> FR[Find and Replace
<br/>strip Markdown fences]
    FR --> Extractor[JSON Path Extractor]
    Extractor --> Writer[Google Docs Writer]

Nodes complémentaires#