How to build an AI agent with n8n and Claude: the complete technical guide

AI Agent vs Regular Automation: What Is Actually Different

Before building anything, you need a precise answer to the question: what makes an AI agent different from a regular automation workflow? The distinction matters because it determines whether you need an AI agent at all, and it defines the additional architectural requirements that regular workflows do not need.

A regular automation workflow executes predefined, rule-based logic. If the form has field X, do Y. If the CRM property equals Z, send email A. The logic is explicit, deterministic, and does not change based on the content of the data only on its structure.

An AI agent includes a language model as a reasoning component that processes natural language and makes decisions based on meaning, not structure. An AI agent can read a free-text message from a customer and classify its intent. It can evaluate a contract clause and identify whether it contains unusual risk provisions. It can synthesise a long email thread and extract the four action items buried in the conversational text. These tasks are impossible for rule-based logic and trivial for a capable LLM.

The architectural difference is that AI agents require additional infrastructure that regular workflows do not: a memory system (so the agent remembers what happened in previous steps or previous conversations), a tool-use framework (so the agent can take actions search a database, send an email, update a CRM record in response to what it reasons), a confidence and escalation system (so the agent hands off to a human when it is not confident enough to act autonomously), and a structured output layer (so the agent's responses are machine-parseable rather than free text).

This guide walks through every component of this architecture, using n8n as the orchestration platform and Claude as the LLM inference engine.

Prerequisites: What You Need Before Building

Before writing a single node, ensure you have the following in place.

An n8n instance running (self-hosted or n8n Cloud) with version 1.0 or later, which includes the native Anthropic node. An Anthropic API key with access to Claude obtain one at console.anthropic.com. A clear, specific use case with a defined input, a defined success criterion, and a confidence threshold below which you want human review rather than autonomous action. A Postgres database (or at minimum, a structured data store) for agent memory and audit logging. A Slack workspace for human escalation notifications.

Do not start building without a defined use case. The most common failure pattern in AI agent projects is beginning with the technology ("let's build an AI agent") rather than the problem ("we need to classify 200 inbound support tickets per day by issue type and urgency without manual triage"). The latter framing makes every subsequent architecture decision easier.

Architecture Design: The Four Layers of a Production AI Agent

Production AI agents in n8n have four architectural layers, each responsible for a distinct function. Understanding these layers before building prevents the most common architectural mistakes.

Layer 1 Orchestration Layer

The orchestration layer is the n8n workflow itself. It defines the sequence of operations: what triggers the agent, what data is prepared and passed to the LLM, what happens with the LLM's response, and how errors and edge cases are handled. The orchestration layer is where all the workflow logic lives the LLM is just one node within it, not the workflow itself.

Layer 2 Intelligence Layer

The intelligence layer is the Claude API call. It receives a structured prompt containing the current task, the relevant context, and the available tools, and returns a structured response containing the agent's reasoning output and any tool calls it wants to make. The intelligence layer has no persistent state it processes one context window at a time. Persistent memory is provided by the orchestration layer, not the LLM.

Layer 3 Memory Layer

The memory layer provides the agent with context about what has happened before. Short-term memory (the current conversation or task context) is passed directly in the Claude prompt as the messages array. Long-term memory (information from previous conversations, historical decisions, stored customer data) is retrieved from a database and injected into the prompt context. Without an explicit memory layer, every Claude call starts from zero the agent has no knowledge of previous interactions.

Layer 4 Tool Layer

The tool layer defines what actions the agent can take in response to its reasoning. Tools are functions that the LLM can call by name, using Claude's native tool-use (function calling) API feature. Each tool has a name, a description (which the LLM uses to decide when to call it), and a parameter schema. When Claude decides to call a tool, it returns a structured tool-call object rather than a text response. The n8n workflow receives this tool call, executes the corresponding action (query a database, send an email, update a CRM record), and returns the result to Claude for further reasoning.

Setting Up Claude in n8n: Step-by-Step Configuration

To add Claude to an n8n workflow, add an "Anthropic Chat Model" node from the node library. This requires n8n version 1.0+ with the AI nodes enabled.

Create an Anthropic credential in n8n's credential store: navigate to Credentials, add a new credential of type "Anthropic," and enter your API key. The key is stored encrypted in n8n's database.

In the Anthropic Chat Model node, configure: Model (select claude-opus-4 for complex reasoning, claude-haiku-3-5 for high-volume classification), Max Tokens (set based on expected response length 1,024 for short classifications, 4,096 for detailed analyses), Temperature (0.0-0.3 for structured tasks requiring consistency, 0.7-1.0 for creative or varied output tasks).

For structured output, use n8n's AI Agent node rather than the raw Anthropic node. The AI Agent node wraps the Claude API call with a tool-use framework and provides hooks for memory integration. This is the recommended pattern for production AI agent workflows.

Building the Memory System

Memory is the component that most AI agent tutorials omit, and its absence is why most demo agents fail in production. Without memory, every interaction starts from scratch. An agent answering customer support questions has no knowledge that this customer contacted support yesterday about the same issue. An agent that classifies leads has no memory of the classification decisions it made for the same company six weeks ago.

Implement a two-tier memory system using Postgres as the persistent store.

Short-Term Memory: The Conversation Context

For agents handling multi-turn conversations (where the user and agent exchange multiple messages to complete a task), short-term memory is the conversation history. Store each message in a Postgres table with columns: session_id, role (user or assistant), content, timestamp, and metadata.

At the start of each agent interaction, query the memory table for all messages belonging to the current session_id, sorted by timestamp. Format these as the messages array in the Claude API call. Claude receives the full conversation history and can respond contextually to what was said earlier in the conversation.

For long conversations, implement a summarisation step: when the conversation exceeds 20 turns, pass the full history to Claude with a summarisation prompt, store the summary as a single system-level memory entry, and start fresh with the summary as context. This prevents context window overflow while preserving the essential historical context.

Long-Term Memory: Historical Knowledge Retrieval

Long-term memory retrieves relevant historical information from a vector database or structured Postgres queries. When an agent processes a customer enquiry, it queries the customer's CRM record and interaction history. When an agent classifies a support ticket, it retrieves the five most similar previously resolved tickets as examples. When an agent evaluates a contract clause, it retrieves relevant precedents from the clause library.

For vector-based semantic search (finding content by meaning rather than exact keywords), use pgvector (a Postgres extension) or a dedicated vector database like Pinecone or Weaviate. Generate embeddings for your knowledge base content using Anthropic's embeddings API or OpenAI's text-embedding-ada-002. At query time, generate an embedding for the current input and retrieve the top-K most similar stored entries by cosine similarity. Inject these as context in the Claude prompt.

This retrieval pattern RAG (Retrieval Augmented Generation) is the architecture behind every production AI agent that needs to reason about large knowledge bases without fitting the entire knowledge base into a single context window.

Implementing Tool-Use: Giving Your Agent the Ability to Act

Tool-use (called function calling in OpenAI terminology) is the feature that transforms a language model from a text generator into an agent that can interact with external systems. Claude decides when to call a tool based on the task at hand, and the tool definition (name + description + parameters) tells Claude what the tool does and when to use it.

Defining Tools in n8n

In n8n's AI Agent node, tools are defined in the Tools section. Each tool specifies: name (camelCase, descriptive), description (one or two sentences explaining what the tool does and when Claude should call it this description is critical and directly affects tool-use accuracy), and parameters (a JSON Schema defining the input fields the tool accepts).

For a customer support AI agent, you might define tools including: lookupCustomerRecord (retrieves a customer's CRM record by email address), searchKnowledgeBase (searches the support knowledge base for relevant articles), createSupportTicket (creates a new support ticket with the provided details), sendEmailToCustomer (sends an email from the support team address to the specified customer), and escalateToHuman (routes the conversation to the human support queue with a summary of the issue).

Handling Tool Calls in the Workflow

When Claude decides to call a tool, it returns a structured response containing the tool name and the parameter values it wants to pass. The n8n AI Agent node intercepts this response, routes it to the corresponding tool action, executes the action, and returns the result to Claude.

From Claude's perspective, a tool call looks like an additional message in the conversation: the assistant message contains the tool call request, and the tool response message contains the result. Claude then continues reasoning with the tool result as new context. This can happen multiple times in a single agent invocation Claude calls a tool, receives the result, decides to call another tool, receives that result, and finally produces its final response.

Tool-Use Best Practices from Production Deployments

Descriptions matter more than you expect. An inaccurate or ambiguous tool description causes Claude to call the wrong tool or fail to call the right one. Write descriptions as if explaining the tool to a knowledgeable colleague who has never seen it before.

Keep tool counts reasonable. An agent with 15+ tools tends to get confused about which tool to call in ambiguous situations. Five to eight well-designed tools is the productive range for most use cases. If you need more, consider splitting into multiple specialized agents rather than loading a single agent with too many capabilities.

Always include an escalateToHuman tool. Every production AI agent should have a tool that routes to human review. Claude will use it when the task is genuinely ambiguous or when it lacks the information needed to act confidently. Design the escalation tool to capture a structured summary of what the agent knows, what it tried, and why it is escalating this summary is what the human reviewer needs to pick up where the agent left off.

Designing the Confidence and Human-in-the-Loop System

The confidence system is what makes an AI agent safe to deploy in production. Without it, you are deploying an agent that will act with equal confidence on tasks it can handle reliably and tasks it is likely to get wrong.

Structured Confidence Output

Configure every Claude call to return a confidence_score field in its structured output. This score (0.0-1.0) represents Claude's self-assessed confidence in its response. Define the confidence interpretation for your specific use case: for a support ticket classification agent, 0.90+ means highly confident classification, route automatically. 0.75-0.89 means moderate confidence, route to the channel but flag for verification. Below 0.75 means low confidence, escalate to human review immediately.

In the n8n workflow, add an If node after the Claude response that branches on the confidence score. The high-confidence branch executes the automated action. The low-confidence branch routes to the human review queue.

Implementing Human Review Queues

A human review queue for an AI agent is not just a Slack notification it is a structured handoff that gives the human reviewer everything they need to make the decision efficiently.

Design the review notification to include: the agent's assessment of the situation (what it understood about the task), the specific reason for escalation (confidence too low, conflicting signals, missing required information), the agent's recommended action if forced to choose, the raw input that triggered the agent, and a one-click action button for the most likely human response.

The last point is critical. If the human reviewer has to click through to a system to take action, they will not do it consistently. A Slack notification with an Approve / Reject / Escalate button that executes via Slack's interactive components API completes the human-in-the-loop flow without requiring the reviewer to leave Slack.

Prompt Engineering for Production AI Agents

Prompt quality is the factor that most directly determines agent performance, and it is the factor most under-invested in production deployments. A mediocre n8n workflow configuration with an excellent prompt outperforms an excellent n8n configuration with a mediocre prompt every time.

The Production System Prompt Structure

Every production Claude system prompt should contain four sections in this order: role definition (what the agent is, what its purpose is, what organisation it represents), behavioural rules (what the agent should always do, what it should never do, how it should handle uncertainty), output format specification (the exact structure of the response field names, types, constraints), and escalation criteria (precisely when to use the escalateToHuman tool rather than proceeding autonomously).

The escalation criteria section is the most important and most commonly omitted. Define it explicitly: "Use the escalateToHuman tool when: the customer's request involves a refund over £500; the customer mentions legal action or regulatory complaints; your confidence_score is below 0.80; the request requires information not available in the provided customer record or knowledge base."

Dynamic Prompt Construction

In n8n, construct prompts dynamically using expressions that inject current context. The customer's name, account status, previous interaction history, and current request are all injected at runtime from the workflow data. A static prompt that says "help the customer" is useless. A dynamic prompt that says "You are assisting [customer_name], a [plan_type] subscriber since [account_creation_date], who has submitted [support_ticket_count] previous tickets. Their current request is: [current_request]" gives Claude the context it needs to reason correctly.

For prompt engineering principles applied to business automation specifically, think in terms of: what does Claude need to know to make the right decision, and what would cause it to make the wrong one? Answer both questions in the prompt.

Real-World AI Agent Examples: What We've Built in Production

Example 1: Healthcare Appointment Intent Classifier

A four-location dental group receives 150-200 inbound messages per day via SMS, email, and web chat. The AI agent reads each message, classifies the intent (new patient enquiry, existing patient scheduling request, insurance query, billing question, clinical question requiring a dentist response), and routes to the appropriate workflow: scheduling automation for booking requests, billing department for billing queries, clinical staff queue for clinical questions.

Claude returns structured output with intent_category, urgency_level (routine/urgent/emergency), and patient_type (new/existing). The routing logic in n8n branches on these fields. Emergency clinical questions (a patient describing acute pain or a dental emergency) trigger an immediate SMS to the on-call clinical coordinator. The agent handles 94% of messages autonomously; 6% escalate to human review.

Example 2: Real Estate Lead Qualification Agent

A real estate agency receives enquiries through multiple channels: Rightmove, Zoopla, direct website forms, and WhatsApp. Each enquiry contains freeform text with varying amounts of qualification information. The AI agent reads each enquiry, extracts structured qualification data (budget range mentioned, timeline expressed, area preference, property type preference, buyer or renter), enriches with property data from the agency's own database, assigns a lead score, and drafts a personalised first response for the agent to review and send.

The draft response is 85-90% complete and requires only minimal editing by the estate agent. This reduces the average time spent on initial response qualification from 12 minutes to 3 minutes per enquiry, while increasing the personalisation quality of the response.

Example 3: Agency Client Report Summariser

A marketing agency generates weekly performance reports for 45 clients. Each report is a data export from multiple platforms (Google Ads, Meta, Google Analytics, HubSpot) that requires human interpretation to produce a narrative summary. The AI agent receives the raw data, identifies the three most significant performance changes (positive and negative), drafts a plain-language summary paragraph for the client, and flags any metrics that require a human explanation before sending.

The agent processes one client report in under 30 seconds. The account manager reviews the flagged items (typically 2-3 per week across all clients), approves or edits, and the summary is incorporated into the report template. Time spent on report writing dropped from 25 minutes per client per week to 6 minutes, recovering 14 hours of account manager time weekly across the 45-client portfolio.

Testing Your AI Agent Before Production Deployment

AI agent testing requires a different approach from regular workflow testing because the agent's behaviour is probabilistic, not deterministic. The same input can produce different outputs across different runs, and the goal is not perfect determinism but reliable quality across the distribution of inputs.

Create a test set of at least 50 representative inputs covering: the most common case (50%), edge cases that require unusual handling (30%), and adversarial cases designed to trigger incorrect behaviour (20%). Run the full test set through the agent and evaluate outputs against your defined success criteria. A classification agent should achieve at least 90% accuracy on the common cases and at least 80% on edge cases before production deployment.

For ongoing quality monitoring, log every production agent output alongside the ground truth (the correct answer, evaluated retrospectively by a human reviewer on a sample). Calculate accuracy metrics weekly and alert if accuracy drops below your defined threshold. This is how we catch model drift in production not by waiting for complaints, but by measuring continuously.

Deploying Your AI Agent to Production

Production deployment of an AI agent involves five steps beyond the build itself.

First, implement comprehensive logging. Every Claude API call should be logged with: the full prompt sent, the full response received, the confidence score, the action taken, the execution ID, and the timestamp. This log is your audit trail and your debugging resource when unexpected behaviour occurs.

Second, implement cost monitoring. Claude API calls have a per-token cost. An agent processing 200 messages per day at 2,000 tokens per call costs approximately £8-15/day depending on model selection. This is typically well within budget, but unexpected volume spikes (a viral social media post sending 10x normal traffic) can cause unexpected cost spikes. Set up API spend alerts in the Anthropic console.

Third, configure production error handling. Add an error trigger to the agent workflow that routes any unhandled exception to your operations Slack channel with full context. Follow the architecture from our 24/7 error handling guide.

Fourth, run a shadow period. For the first week, run the agent in parallel with your existing manual process. Compare agent outputs to human outputs. Identify cases where the agent's response was significantly different from what a human would have done. Use these cases to refine the prompt and adjust confidence thresholds before cutting over to autonomous operation.

Fifth, establish a feedback loop. Collect structured feedback on agent performance from the team members who review escalations and interact with agent outputs. This qualitative signal surfaces failure modes that quantitative metrics miss.

AI Agent FAQ

How much does running a Claude AI agent cost?

Claude pricing is per token. For claude-haiku-3-5 (best for high-volume classification), cost is approximately $0.001 per 1,000 input tokens and $0.005 per 1,000 output tokens. An agent processing 500 messages per day at 1,500 tokens per call costs approximately $0.75-1.50 per day. For claude-opus-4 (best for complex reasoning), multiply by approximately 10x. Most business AI agents have a running cost of £30-200 per month well below the value they create.

How do I prevent my AI agent from making mistakes?

The most effective mechanisms are: structured output (use Claude's tool-use API to constrain response format), confidence thresholds (route low-confidence outputs to human review rather than acting autonomously), test sets (validate accuracy before production deployment), and continuous monitoring (measure output quality in production and alert on degradation). No AI agent is perfect; the goal is a system that makes errors rarely, catches them reliably, and routes them to human correction before they cause downstream problems.

Can I build an AI agent without coding experience?

n8n's AI Agent node handles most of the agent infrastructure without code. Basic Claude integration, memory from a database, and tool-use are all configurable in the visual editor. However, production-grade AI agents require some ability to write n8n expressions, configure Postgres queries, and debug JSON schemas. If you have no technical background, engaging an automation specialist for the initial architecture and build, then maintaining it yourself, is the most cost-effective path.

What is the difference between an AI agent and a chatbot?

A chatbot responds to user messages with predefined responses or simple conditional logic. An AI agent uses a language model to reason about the current context and decide what action to take, including calling external tools and taking actions in other systems. A chatbot follows a script; an AI agent follows a goal. For more on what AI agents can genuinely deliver in production in 2026, read our article: AI agents in 2026: what actually works.

How long does it take to build a production AI agent with n8n and Claude?

A focused, single-purpose AI agent (one input type, one classification or extraction task, one output action, with confidence-based escalation) takes 2-5 days to build, test, and deploy to production when built by someone familiar with n8n. A multi-tool agent with memory, multiple tool types, and complex routing logic takes 1-3 weeks. The testing and shadow period adds 1 week in both cases. If this is your first AI agent, budget 50% more time than these estimates to account for the learning curve on the prompt engineering and tool-use configuration.