n8n-agents-official

n8n Agents

The n8n Agent node (@n8n/n8n-nodes-langchain.agent) is a multi-turn LLM driver with sub-nodes for the model, memory, tools, and optional output parser.

When to use the Agent node vs raw chat completion

Decision:

• Need tool calls, multi-turn reasoning, or memory? Agent. Also a fine default when you don't want to think about it: standardizing on Agent across the workflow is reasonable and makes the path to upgrade simpler.
• Want the lightest possible single-shot text-out call? Basic LLM Chain (@n8n/n8n-nodes-langchain.chainLlm) with a chat-model sub-node (OpenRouter Chat Model, OpenAI Chat Model, Anthropic Chat Model, etc.). No agent loop, no tool/memory/parser slots, easier to debug. Note: chat-model nodes are sub-nodes, and they don't run standalone. They wire into a chain or agent. Agent works here too if you'd rather standardize.
• Routing to one of N output branches based on natural-language input (the AI's job is to pick the branch)? Use the Text Classifier node (@n8n/n8n-nodes-langchain.textClassifier). N output handles, one per category, and downstream paths wire directly into each. Every category needs both a name AND a description (the description is what the model picks against, names alone aren't enough). Set options.enableAutoFixing: true for robustness on edge inputs. Pair with a chat-model sub-node (OpenRouter Chat Model, OpenAI Chat Model, etc.). Don't reach for Agent + Switch for this. Text Classifier is one node and purpose-built.
• Structured output but no tools? Agent is the easier default with future expansion in mind. Basic LLM Chain also accepts an outputParserStructured sub-node and works fine where you want the lighter node.
• Image / audio / video generation? The native single-call node for that provider when calling them directly (OpenAI Image, Gemini Image, ElevenLabs, etc.). HTTP Request when routing through an aggregator (OpenRouter, Together, etc.), because no native aggregator node exists and the native nodes hardcode their provider's base URL on the media operation. Don't wrap media generation in an Agent, see "Binary and the agent boundary" below.

There are other LangChain "chain" / utility nodes for narrow tasks: Information Extractor (pull structured fields from text), Sentiment Analysis (3-way branch), Summarization Chain, Basic LLM Chain.

Agent is a reasonable default for most LLM steps. Reach for Basic LLM Chain when you specifically want the leaner node for a one-shot text call with no tools, memory, or iteration. Reach for Information Extractor / Sentiment Analysis / Summarization Chain / Text Classifier when one of those purpose-built nodes matches the task exactly.

Non-negotiables

1. Tool names and descriptions are part of the prompt. The model picks tools by name and description. Vague tool node names like (doStuff) or weak descriptions ("does things with the data") cause silent failure: the model skips your tool, mis-selects it, or hallucinates parameters. Treat both like API design. See references/TOOLS.md.
2. Structured output: parse AND autoFix. outputParserStructured with autoFix: true and a coding-capable fixer model (e.g., Claude Sonnet 4.6) is the production pattern.

Strong defaults

• Tool descriptions are modular prompt fragments. Anything specific to how to call this tool belongs in the tool's description, not the system prompt. Keeps the system prompt focused, and tools become reusable across agents. See references/SYSTEM_PROMPT.md.
• Sub-workflow tools (toolWorkflow) for anything multi-step. Any workflow becomes a tool with typed fromAi() inputs, and composes with branching, error handling, sub-workflows. See references/SUBWORKFLOW_AS_TOOL.md.
• Wrap tools with user-visible side effects in human review. Sends, payments, refunds, account changes. Gate them behind a Slack / Chat / Discord / Telegram approval node so a human signs off before the tool runs. See references/HUMAN_REVIEW.md.

The sub-node pattern

The Agent node has a main input (the prompt or user message) and sub-node inputs:

const aiAgent = node({
    type: '@n8n/n8n-nodes-langchain.agent',
    config: {
        name: 'Customer Support Agent',
        parameters: {
            promptType: 'define',
            text: '={{ $json.userMessage }}',
            options: {
                systemMessage: '...',
                passthroughBinaryImages: true,    // for vision / multimodal
            },
        },
        subnodes: {
            model: openRouterModel,
            memory: simpleMemory,
            tools: [generateImage, editImage, searchKnowledgeBase],
            outputParser: structuredParser,    // optional
        },
    },
})

The four sub-node slots:

• model (required): the language model. OpenAI, Anthropic, OpenRouter, etc. Use chat-model variants, not completion variants.
• memory (optional): conversation memory. Without it, every call is stateless. See references/MEMORY.md.
• tools (optional, but the point of using an agent): tools the agent can call. See references/TOOLS.md.
• outputParser (optional): forces structured JSON output. See references/STRUCTURED_OUTPUT.md.

Triggers

Different triggers shape the input differently:

• Chat Trigger (@n8n/n8n-nodes-langchain.chatTrigger) with availableInChat: true: powers the canvas chat tester so you can poke at an agent while building it. Input is { chatInput, sessionId, files[] }. sessionId is what memory keys on, so pass it through wherever conversation continuity is needed. Files come in via files[], see binary section below. Not a production surface, use Slack / Discord / Teams / Telegram / webhook for that.
• Webhook: arbitrary input shape, no session by default. Manage continuity by passing a session/conversation ID through the request body and forwarding it to the memory node.

• External chat surface (Slack, Discord, Teams, Telegram): every chat-triggered workflow that posts replies MUST filter out the bot's own user ID, or it loops forever potentially crashing n8n. Prefer trigger-level filtering when the surface supports it (Slack's options.userIds is an exclusion list); otherwise filter in the first node after the trigger. Semantics differ per surface, see references/CHAT_AGENT_PATTERNS.md. Beyond the anti-loop filter, a simple bot (trigger → agent → reply) is fine in one workflow. Split into a "shell" workflow + agent-core sub-workflow once you need loading UX, sub-agents, reuse across surfaces, or robust error handling.
• Manual / Schedule: ad-hoc invocations. Memory rarely useful unless explicitly continuing a previous run.
• Execute Workflow Trigger (sub-workflow): when an agent is itself a tool of another agent. Treat the trigger's declared inputs as the contract.

Binary and the agent boundary

The model can see uploaded files (vision) via passthroughBinaryImages: true. But tools cannot receive binary, and fromAi() parameters are JSON only. Base64 is also not accepted by tools, even through non-AI bindings.

Workaround: pre-stage uploads to storage before the agent runs, inject the storage keys into the system prompt, tools accept the key as a string parameter and re-fetch internally. Full pattern in n8n-binary-and-data-official references/AGENT_TOOL_BINARY.md.

On the output side: the Agent's output formatter is text-shaped (or structured-text when an outputParser is wired). When a model returns binary (image bytes, audio bytes, video), the Agent doesn't surface it at all. There's nothing to dig out downstream, and trying to recover it via a Code or Set node after the Agent does not work. For one-shot media generation, use the provider's native single-call node directly such as @n8n/n8n-nodes-langchain.googleGemini or @n8n/n8n-nodes-langchain.openAi.

The exception: when a media step genuinely belongs in an agent (one tool among several, picked based on conversation context, or editing a previously-generated image), the workaround is a tool sub-workflow that uploads the result to storage and returns a key or URL. Pattern in n8n-binary-and-data-official references/AGENT_TOOL_BINARY.md. Don't reach for this by default. The upload + key + re-fetch path adds nodes and a storage dependency you don't otherwise need. Only when the orchestration actually requires an agent's tool selection.

What goes in the system prompt vs the tool description

Benefit: tools become reusable. A well-described tool works in any agent that drops it in. The system prompt stays focused on role and shared behavior.

For deeper guidance and worked examples, see references/SYSTEM_PROMPT.md and references/TOOLS.md.

Tool selection: the four types

Pick the lightest option that covers the job:

• Native n8n tool node exists? (e.g., slackTool, gmailTool, calculatorTool) Use it. Lowest config overhead.
  • Native node is missing an operation or needs custom params (e.g., a Notion endpoint the node doesn't expose, a non-standard header, a different pagination shape)? HTTP Request Tool with the service's "Predefined Credential Type". Reuses the existing OAuth / API-key credential, gives full API access, no custom auth code.
• Multi-step logic, or reusing a sub-workflow already in the project? Sub-workflow as tool (toolWorkflow). Anything you can build as a workflow becomes a tool with typed fromAi() inputs. The most powerful option in n8n, so default here when in doubt. See references/SUBWORKFLOW_AS_TOOL.md.
• Calling an external HTTP API the agent should orchestrate directly? HTTP Request Tool. Also good for slow async work via long-poll callback.
• Tool already exists as a published, MCP-accessible workflow? MCP tool. Useful for cross-workflow agent capabilities. See n8n-extending-mcp-official.

See references/TOOLS.md for deeper guidance on each option and how to wire fromAi() parameters.

Human review

Before adding or skipping human review on a tool, check with the user. Whether sign-off is needed is a product / policy call (blast radius, audit requirements, how much they trust the model) that the user is better positioned to make than you. Surface the question, recommend based on the criteria below, and let them decide.

When a tool's effects need human approval before execution (sends, payments, refunds, account changes, customer-facing actions), wrap it with a review tool node: slackHitlTool, discordHitlTool, telegramHitlTool, gmailHitlTool, etc. (n8n's node names use Hitl for the human-in-the-loop pattern, and "human review" is what it's called in the UI.) The review node sits between the wrapped tool and the agent on the ai_tool connection: the wrapped tool's ai_tool output wires into the review node, and the review node's ai_tool output wires into the Agent. The agent calls through, the review node pauses for approval, on approve, the wrapped tool runs.

Default to / recommend human review when:

• The tool sends, pays, refunds, or otherwise mutates user-visible state.
• The approver is different from the chatter (manager-approves-customer-action, support team approves a customer-triggered refund).
• The trigger is non-interactive (order, form, schedule) but the tool's effect needs human sign-off.

Approval messages should display the actual parameters the wrapped tool will receive, not text the model paraphrases. Use $tool.parameters.<name> directly, or iterate over $tool.parameters to list every param. Don't fill the approval text via fromAi(). You'd be approving a paraphrase, not the literal call. Customize button labels with the actual values, e.g. Approve {{ $tool.parameters.amount }} refund.

Full config patterns, per-platform setup, and the multi-channel approver pattern in references/HUMAN_REVIEW.md.

Output parsing: when and how

Add an outputParser sub-node when downstream needs structured data, not free-form text.

const parser = outputParser({
    type: '@n8n/n8n-nodes-langchain.outputParserStructured',
    config: {
        parameters: {
            schemaType: 'manual',
            inputSchema: JSON.stringify({
                type: 'object',
                properties: {
                    score: { type: 'integer', minimum: 1, maximum: 5 },
                    category: { type: 'string', enum: ['bug', 'feature', 'question'] },
                    reason: { type: 'string' },
                    tags: { type: 'array', items: { type: 'string' } },
                },
                required: ['score', 'category', 'reason'],
            }),
            autoFix: true,
            customizeRetryPrompt: true,
            prompt: '...retry instructions...', // generally leave as default
        },
        subnodes: {
            languageModel: fixerModel,    // coding-capable model, e.g. Claude Sonnet 4.6
        },
    },
})

1. Use schemaType: 'manual' with a real JSON schema, not jsonSchemaExample. An example can't express optional fields, enums, value ranges, or array constraints, so you outgrow it the first time the shape gets non-trivial. A schema lets you mark fields required vs optional, define enums, constrain numbers and string formats, and gives the model clearer rules to follow. Reach for schemaType: 'fromJson' with an example only for one-off shapes you're certain will never grow constraints.
2. autoFix: true adds retry on parse failure. Wire a coding-capable model as the fixer sub-node (e.g., Claude Sonnet 4.6 or similar). Fixing malformed JSON against a schema is a structured-output / coding task, and a weak or generic model often produces another malformed retry, defeating the point.

For the full pattern including custom retry prompts, see references/STRUCTURED_OUTPUT.md.

Memory: brief mental model

• No memory: stateless. Right for one-shot tasks (classify, summarize).
• memoryBufferWindow: keeps the last N messages per memory key and persists across executions via n8n's internal store. The key is whatever expression you bind to sessionKey. Chat triggers fill sessionId automatically, but you can key on anything (Slack thread_ts, a webhook conversation ID, a multi-tenant composite). The default for chat memory. The "window" is the sliding cap on how many messages stay in context, not a scope on persistence.
• memoryPostgres / memoryRedis / similar: reach for these when you need to query or read memory outside the agent: displaying conversation history in your own UI, analytics on past chats, or sharing memory with another system. Otherwise memoryBufferWindow is enough.

Plumb a stable key from the trigger to memory consistently, or conversations get crossed. See references/MEMORY.md.

RAG (retrieval augmented generation)

n8n has the LangChain RAG primitives: document loaders, text splitters, embeddings, vector stores, retrievers, rerankers. The pieces work, but opinionated end-to-end recipes ("which vector store, which chunking, when to rerank") depend heavily on data shape and scale.

This skill keeps RAG opinions thin on purpose. See references/RAG.md for more details on RAG.

Reference files

Anti-patterns