AI Agent

The AI Agent node runs an autonomous LLM that can plan, call tools, query knowledge bases, and use MCP servers to complete multi-step tasks.

What does the AI Agent node do?#

The AI Agent node turns an LLM into an autonomous executor. Unlike the LLM node — which produces a single response from a prompt — the Agent reasons over your instructions, decides which tools, datasources, or MCP servers to invoke, observes the results, and iterates until the goal is reached. It returns a single text answer once it considers the task complete.

Common use cases:

• Multi-step research that combines web search, scraping, and summarization in one node.
• Question-answering grounded in a private knowledge base via RAG (datasources).
• Driving external systems through MCP servers (e.g. internal APIs, databases) without writing dedicated nodes.
• Data enrichment workflows that mix document context, web tools, and structured reasoning.

Quick setup#

Follow these steps to add and configure the AI Agent node in your workflow:

Save and update the prompt#

From the canvas, open the Agent node and click Edit instructions at the bottom of the panel to write the prompt that defines the agent’s task and behavior on each run.

Edit Instructions#

Enhance Instructions#

The Enhance Instructions feature (BETA badge) turns a minimal prompt into structured, detailed instructions tailored to the task and the variables already present in the node. For example, start with something as simple as generate an SEO-optimized article with YourText.Guru — the assistant produces a full prompt (persona, steps, format constraints) while preserving connected variables ({{ytt_data}}, {{target_keyword}}, etc.).

While generation is running, Stop & Revert instructions cancels the process and restores the previous prompt:

Once generation completes, the enriched prompt appears in the editor and remains fully editable. You can tweak it manually, click Rollback previous instructions to revert, or run Enhance Instructions again for a new proposal:

Guide the agent: Tools, RAG, and MCP#

Attaching capabilities in Agent Settings is not enough — the agent needs to know when, how, and how far to use them. Without explicit framing in the prompt, it may ignore a tool, loop on the same call, or exceed a reasonable budget.

Principles to include in your instructions:

• Name each attached capability and its role in the task (“use RAG to…”, “call the CRM MCP server to…”).
• Set a priority order: for example RAG first, then Web Search only if the answer is missing from sources.
• Set limits: maximum tool calls, RAG queries, or MCP function invocations per run.
• Specify failure behavior: continue with partial data, report missing information, or stop.
• State the expected output format once capabilities have been used (text, JSON, list of cited sources).

Instruction examples — RAG only

Attached capabilities: “Product docs” datasource (PDF, MARKDOWN).

• Query the knowledge base before drafting your answer.
• Answer only from attached RAG documents; if information is missing, state “Not documented in available sources”.
• Cite the source document title for each key claim.
• Limit yourself to 3 RAG queries maximum, then synthesize.

Instruction examples — Tools (Web Search + Web Scraper)

Attached capabilities: Web Search, Web Scraper.

• Use Web Search to identify the official website from the {{lead_email}} domain.
• Scrape only the homepage and the “About” page — no other URLs without justification.
• Perform at most 5 tool calls in total; if a page is unreachable, move to the next step.
• Return JSON with keys company_name, website, summary.

Instruction examples — MCP (Fathom server)

Attached capabilities: Fathom MCP server (list_meetings, get_meeting_transcript).

• Call list_meetings to retrieve meetings from the last 7 days related to {{contact_email}}.
• Invoke get_meeting_transcript only when a meeting explicitly matches the user request.
• Do not exceed 3 MCP calls; summarize action items at the end of the response.
• If no meeting is found, respond without inventing content.

Instruction examples — Tools + RAG + MCP combined

Attached capabilities: RAG “Product docs”, Haloscan tool, CRM MCP server, Web Search.

• Step 1 — RAG: consult “Product docs” for product positioning and sales arguments.
• Step 2 — Haloscan: one SEO analysis per target keyword ({{target_keyword}}); do not rerun the tool on close variants.
• Step 3 — CRM MCP: check whether account {{company_domain}} already exists; perform only one read call.
• Step 4 — Web Search: only for recent market data absent from RAG.
• Global budget: 10 tool/MCP calls maximum, then produce the final synthesis and stop.

Configuration parameters#

Configuring the node means picking a model, writing clear instructions, and exposing the right capabilities — nothing else is mandatory.

LLM Settings#

Agent Settings#

Open the node settings and switch to the Agent Settings tab to attach tools, RAG sources, MCP servers, and the agent system message.

What does the node output?#

The node outputs the agent’s final text answer as a string — once it decides the task is complete. Tool calls, intermediate reasoning, and observations are not part of the output: only the answer.

How to use the output#

In Draft & Goal you don’t need to look up a system-generated variable name. To use the result:

1. Draw a connection from the AI Agent node’s output.
2. Connect it to the next node’s input.
3. In that next node, create and name your own variable (e.g. agent_answer). The agent’s final response is injected into it automatically.

Usage examples#

Example 1: Grounded Q&A over a private knowledge base#

You want the agent to answer support questions strictly from your documentation.

Configuration:

• Model name: a reasoning-capable LLM (e.g. GPT-4 class).
• 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: select your “Product docs” datasource.
• Tools / MCP Servers: none — the agent must rely on RAG only.

Example 2: Multi-step research with tools and MCP#

You want the agent to enrich a lead by combining web tools and an internal CRM exposed 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: your internal CRM server.
• Temperature: 0.3 for reproducible tool selection.

Common issues#

The node fails validation with 'Agent requires instructions to be configured'

Cause: The prompt field is empty or whitespace-only.

Solution: Open the node settings and fill in the prompt field with the task to perform. The validator strips whitespace, so a single space is not enough.

The agent loops, retries the same tool, or never terminates

Cause: The instructions don’t define a clear stopping condition, or the model is too weak to plan reliably.

Solution: Add an explicit budget in the prompt (“Use at most N tool calls”, “If you cannot find X, say so and stop”). Switch to a stronger reasoning model. Lower Temperature to 0.2–0.4.

The final answer is truncated

Cause: Max output tokens is too low for the requested format, or the agent spent its budget on intermediate reasoning.

Solution: Increase Max output tokens. Ask the agent in the prompt to produce a shorter, more structured answer. For reasoning models, also raise Thinking Budget if the truncation happens during thinking.

Connecting a File input fails with a file-type error

Cause: The Agent node only accepts Structured Documents (csv, xlsx, json, xml) and Unstructured Documents (pdf, txt, md, docx, pptx) coming from a File input node. Other file types are rejected at connection time.

Solution: Change the File node’s type to a supported document type, or pre-process the file with a converter node before feeding it into the agent.

The agent ignores my datasources or MCP servers

Cause: The instructions don’t mention them, so the agent doesn’t realize they’re available — or it judged them irrelevant for the current task.

Solution: Reference the capability explicitly in the prompt (“Use the knowledge base to answer”, “Call the CRM MCP server to verify the account”). Provide the datasource name in the system message.

Best practices and pitfalls#

How does it fit into a workflow?#

The AI Agent typically replaces a chain of LLM + tool nodes when reasoning between steps is required. Here’s a typical integration pattern for a research-then-act workflow:

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]

Related nodes#