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:

Configuration parameters

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

Required fields

Optional fields

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