AI Agents & Tool Calling

Relevant source files

The following files were used as context for generating this wiki page:

• packages/@n8n/ai-workflow-builder.ee/src/prompts/agents/discovery.prompt.ts
• packages/cli/src/modules/agents/builder/agents-builder-prompts.ts
• packages/@n8n/workflow-sdk/src/prompts/best-practices/guides/data-analysis.ts
• packages/@n8n/workflow-sdk/src/prompts/best-practices/guides/knowledge-base.ts
• packages/@n8n/ai-workflow-builder.ee/src/code-builder/prompts/index.ts
• packages/frontend/editor-ui/src/experiments/readyToRunWorkflowsV2/workflows/ai-workflow-v6.ts

AI Agents in n8n are specialized nodes that leverage Large Language Models (LLMs) to perform reasoning, text analysis, and complex decision-making. Unlike standard nodes with fixed logic, agents use tool calling to interact with external services, databases, and sub-processes dynamically based on user intent.

The system distinguishes between "AI Agent" nodes used within workflows and first-class "n8n Agents," which are standalone artifacts. Agents utilize a "Reasoning and Acting" pattern to determine which tools to invoke and how to process the results into structured or conversational outputs.

Sources: packages/cli/src/modules/agents/builder/agents-builder-prompts.ts:1-20, packages/@n8n/ai-workflow-builder.ee/src/prompts/agents/discovery.prompt.ts:55-65

Agent Architecture and Components

The n8n AI Agent architecture relies on four primary components connected via specialized AI connection types. The Agent node acts as the central orchestrator, receiving logic from a Chat Model and memory context from a Memory node.

Core Component Structure

Component	Node Type	Purpose
Orchestrator	AI Agent	Executes reasoning loops and manages tool execution.
Brain	Chat Model	Provides the LLM logic (e.g., OpenAI, Anthropic, Gemini).
Context	Memory	Persists conversation history across multiple turns.
Capabilities	Tools	Specialized nodes that allow the Agent to interact with the world.

Sources: packages/@n8n/ai-workflow-builder.ee/src/prompts/agents/discovery.prompt.ts:65-75, packages/frontend/editor-ui/src/experiments/readyToRunWorkflowsV2/workflows/ai-workflow-v6.ts:100-140

Connection Logic Diagram

The following diagram illustrates how components attach to the main AI Agent node.

This diagram shows the standard multi-connection pattern where a single AI Agent aggregates various specialized sub-nodes.
Sources: packages/@n8n/ai-workflow-builder.ee/src/prompts/agents/discovery.prompt.ts:80-90, packages/frontend/editor-ui/src/experiments/readyToRunWorkflowsV2/workflows/ai-workflow-v6.ts:145-200

Tool Calling Mechanisms

Tools provide AI Agents with the ability to perform actions or retrieve data. Tools are distinct from regular nodes; while a regular node executes every time the workflow reaches it, a tool is only executed if the AI Agent decides its capability is required.

Types of Tools

1. Native Node Tools: Standard n8n nodes ending in "Tool" (e.g., Calculator Tool, Gmail Tool).
2. Vector Store Tools: Connect a Vector Store node in retrieve-as-tool mode to allow the agent to query a knowledge base.
3. Sub-Agent Tools: The Agent Tool contains an embedded AI Agent, enabling multi-agent "Supervisor" patterns.
4. Workflow Tools: Existing workflows can be attached as tools to perform complex multi-step automation.

Sources: packages/@n8n/ai-workflow-builder.ee/src/prompts/agents/discovery.prompt.ts:250-265, packages/cli/src/modules/agents/builder/agents-builder-prompts.ts:25-35

Multi-Agent Systems

Multi-agent systems use a hierarchy where a "Main Agent" calls "Sub-Agents" as tools. Each sub-agent requires its own Chat Model to function independently.

Knowledge Bases & RAG

Knowledge Base (Retrieval-Augmented Generation) workflows allow agents to access private data. This involves two distinct phases: Ingestion and Retrieval.

Ingestion vs. Retrieval

• Ingestion: Processes files (PDFs, CSVs) using a Document Loader, splits them with a Text Splitter, and stores them in a Vector Store node in insert mode.
• Retrieval: The AI Agent queries the Vector Store (in retrieve-as-tool mode). The agent decides when to query the knowledge base based on the tool description.

Configuration Best Practices

• Chunk Size: 500-1000 characters is optimal for preserving context.
• Embeddings: You must use the same embedding model (e.g., text-embedding-3-small) for both indexing and querying to ensure semantic matches.
• Top-K: Retrieval should be limited to 3-5 results to prevent model hallucination or token overflow.

Sources: packages/@n8n/workflow-sdk/src/prompts/best-practices/guides/knowledge-base.ts:10-50, packages/@n8n/ai-workflow-builder.ee/src/prompts/agents/discovery.prompt.ts:270-280

Implementation Patterns

Data Analysis Pattern

For analysis tasks, agents are often part of an Input → Transform → Output pipeline. The agent handles the "Transform" layer by examining data for patterns or anomalies.

Structured Output Parsing

When an agent's result must be used by a downstream node (like a Switch node or a database), a Structured Output Parser is required. This enforces a JSON schema on the LLM's response.

const structuredParser = outputParser({
  type: '@n8n/n8n-nodes-langchain.outputParserStructured',
  version: 1.3,
  config: {
    parameters: {
      schemaType: 'fromJson',
      jsonSchemaExample: '{ "sentiment": "positive", "confidence": 0.95 }'
    }
  }
});

const aiAgent = node({
  type: '@n8n/n8n-nodes-langchain.agent',
  config: {
    parameters: { hasOutputParser: true },
    subnodes: { outputParser: structuredParser }
  }
});

Sources: packages/@n8n/ai-workflow-builder.ee/src/code-builder/prompts/index.ts:380-410, packages/@n8n/ai-workflow-builder.ee/src/prompts/agents/discovery.prompt.ts:285-290

Summary

AI Agents and Tool Calling transform n8n from a static automation engine into a dynamic reasoning system. By combining LLMs with a rich library of tools, memory context, and vector databases, developers can build systems capable of independent research, data extraction, and multi-agent coordination. Proper configuration of embeddings, chunk sizes, and output parsers is essential for maintaining accuracy and reliability in agentic workflows.