Build your first AI agent in n8n: a lead-triage workflow end-to-end
A complete walk-through of building a real AI agent in n8n — one that triages incoming leads, enriches them, scores them, and routes them. Every node, every prompt, every gotcha.
Outcome: Design a lead-triage agent with explicit tools, schemas, routing rules, logging, and human review.
The most underrated capability in n8n is the AI agent node. It turns a static workflow ("when X happens, do Y") into something more flexible: a workflow where the AI model decides which actions to take based on the situation.
In this article we build a real, working agent end-to-end: a lead triage system that receives new leads, enriches them, scores them, drafts a personalised response, and routes them to the right place. By the end you will understand both the mechanics of n8n agents and the design patterns that separate a useful agent from a fragile demo.
We assume you have n8n installed (self-hosted on a server or via n8n.cloud) and a working API key for Claude or OpenAI. If you're new to n8n, work through their basic tutorial first.
Do not let the first version auto-send replies to real leads. Route drafts to human review until you have logs, idempotency, score thresholds, and enough reviewed runs to know the workflow behaves under messy inputs.
What we're building
The workflow:
- A new lead arrives via a webhook (from a form, an event, a CRM, etc.).
- The agent enriches the lead with company information (using web search).
- It scores the lead on three dimensions: fit, intent, urgency.
- It drafts a personalised response.
- Based on the score, it either: - Auto-replies and creates a CRM record (for high-confidence high-fit leads), - Drafts a reply for a human to review and sends a Slack notification (for medium leads), - Or just logs and notifies without responding (for low-fit leads).
This pattern generalises. Replace "lead triage" with "support ticket triage," "candidate screening," "press inquiry handling," "customer feedback routing" — the structure is the same.
The companion JSON schema linked from this article defines the intake payload. Use it to validate the webhook input before the agent node sees it.
Add a pre-agent validation gate
The webhook should not pass arbitrary form data straight into the agent. Put a validation step between the trigger and the agent:
| Field | Rule | Failure behavior | | --- | --- | --- | | email | Required, valid email, normalized lowercase | Reject and notify owner | | message | Required, non-empty, maximum length | Reject or route to manual review | | source | Required enum such as website-form, event, crm | Reject unknown source | | timestamp | Required ISO timestamp or generated by webhook | Use receive time and flag | | lead_id | Required stable ID or generated idempotency key | Deduplicate before processing |
This gate protects the workflow from malformed submissions, duplicate webhook retries, and prompt-injection content hidden in form fields. The agent can still read the message, but the workflow decides whether the record is valid enough to process.
The mental model: agent = LLM + tools + loop
Before we build, the concept.
An "agent" in 2026 means an LLM that can use tools. Instead of producing a single response, the model decides which actions (called "tools") to call. After each tool returns, the model sees the result and decides what to do next — another tool, another step, or a final answer.
n8n's AI Agent node implements this loop. You give the model:
- A system prompt (its instructions and personality).
- A user prompt (the input for this run).
- A set of tools (other n8n nodes or sub-workflows the model can call).
The model decides which tools to call, in what order, with what arguments. After each tool returns, the model reconsiders. When it decides it has done enough, it returns a final answer.
This is fundamentally different from a static workflow because the order of steps is determined by the model, not by you. The skill of agent design is in:
- Giving the model the right tools (not too few, not too many).
- Writing a system prompt that scopes its behavior.
- Adding guardrails so it doesn't go off-rails.
- Designing the output so downstream nodes can use it reliably.
Step 1: The trigger
Open n8n and create a new workflow. The trigger:
- Node: Webhook
- HTTP Method: POST
- Response Mode: "When last node finishes"
- Path: something like
/lead-triage
This webhook will receive lead submissions. n8n gives you a URL you can configure as the destination for your form submissions or your CRM's outbound webhook.
For testing, save the workflow once so the webhook URL becomes active, and have a sample payload ready. A typical lead webhook payload might be:
{
"name": "Anna Lehtinen",
"email": "anna@somecompany.fi",
"company": "Some Company OÜ",
"role": "Head of Marketing",
"message": "Interested in your AI consulting services. We have a team of 10 and need help with prompt engineering training.",
"source": "website-form",
"timestamp": "2026-05-15T14:30:00Z"
}Click "Test step" and submit the test payload to see the data flowing in.
Step 2: The AI Agent node
Add an AI Agent node after the webhook. Configure it:
- Agent Type: Conversational (or "Tools Agent" in newer versions — pick the variant that supports tool calling).
- Chat Model: Claude (Anthropic) or OpenAI. For an agent workflow, Claude Sonnet 4.5 or GPT-5 are good defaults. Reasoning models work but are slower for agent loops.
- Memory: None for stateless triage (each lead is independent). For multi-turn agent conversations, use a memory node.
- System Message: This is where the agent's behaviour lives. Use the template below.
- User Message: Pull the lead data from the webhook.
The system message:
You are a lead-triage agent for [Your Company Name], an AI consulting firm.
Your job is to process incoming leads and produce a structured triage decision.
For each lead, you must:
1. Use the `enrich_lead` tool to gather context about the company.
2. Score the lead on three dimensions:
- Fit: does the lead match our ideal customer profile?
- Companies of 10-200 people in B2B, manufacturing, or professional services.
- Roles in marketing, operations, engineering leadership, or executive.
- Intent: how serious is the inquiry?
- "Just curious" vs "actively evaluating" vs "ready to buy."
- Urgency: is there a stated or implied timeline?
3. Use the `score_lead` tool to record the scores.
4. Use the `draft_response` tool to produce a personalised reply.
5. Use the `route_lead` tool with one of: "auto_reply", "human_review", "log_only".
Routing rules:
- "auto_reply" if Fit >= 7/10 AND Intent >= 7/10. The reply will be sent automatically.
- "human_review" if Fit >= 5/10 OR Intent >= 5/10. A human will check before sending.
- "log_only" if Fit < 5/10 AND Intent < 5/10. We just track and move on.
Never invent information. If something is unclear, mark [unclear] in your scoring rationale.
Always end by returning a JSON object with:
{
"fit_score": <1-10>,
"intent_score": <1-10>,
"urgency_score": <1-10>,
"reasoning": "<2-3 sentences>",
"drafted_response": "<the email body>",
"routing": "<auto_reply|human_review|log_only>"
}Notice the structure. We have:
- A clear job statement.
- An explicit process (steps 1-5).
- Explicit scoring criteria.
- Explicit routing logic.
- A required output format.
The agent will not always follow this perfectly. But the more concrete the system message, the more reliably it executes the same shape every time.
The JSON object is not enough by itself. Add a validation step after the agent node and reject runs where scores are missing, routing is outside the allowed enum, or the drafted response is empty.
Step 3: The tools
The agent needs tools to call. In n8n, tools are configured under the agent node and can be:
- Sub-workflows.
- HTTP requests.
- Built-in tool nodes.
Let's build four tools for our agent.
Tool 1: enrich_lead
A sub-workflow that:
- Takes a company name and email domain as input.
- Uses an HTTP node to call a web search API (Perplexity, Serper, Brave Search, Tavily) for the company.
- Returns a 3-sentence summary: what the company does, rough size, any notable recent news.
The tool's description (which the agent reads to decide when to call it):
Enriches a lead by looking up the company. Input: the company name and email domain. Output: a short summary of what the company does, its rough size, and any notable recent context.
Tool 2: score_lead
A simple tool that takes the agent's scores and writes them somewhere. This could be:
- A Google Sheets row.
- A database insert.
- A CRM API call.
For testing, a Google Sheets append is the easiest. The tool's description:
Records the lead scores. Input: fit_score, intent_score, urgency_score, reasoning. Output: confirmation.
Tool 3: draft_response
A sub-workflow that takes the lead context and the scores and produces a personalised email draft. This sub-workflow internally calls another AI node with a specific drafting prompt:
Draft a personalised response to a B2B inquiry. Inputs: the original lead message, the company enrichment summary, the fit/intent/urgency scores.
>
Voice: warm, direct, no corporate filler. Acknowledge the specific request. Reference something from the company enrichment (not generically). End with a concrete next step (e.g., "would 15 minutes next week work?").
>
Length: 80-120 words.
The tool's description:
Drafts a personalised email reply to the lead. Input: the lead message, enrichment summary, and scores. Output: an email draft.
Tool 4: route_lead
The final routing action. Based on the route argument, this tool either:
- Sends the email + creates a CRM record (auto_reply).
- Saves the draft + sends a Slack notification (human_review).
- Just logs and creates a CRM record (log_only).
This is implemented as a sub-workflow with a switch node that routes to three different branches based on the argument.
The tool's description:
Routes the lead based on the triage decision. Input: routing decision ("auto_reply", "human_review", "log_only") and the drafted response. Output: confirmation.
Step 4: Test the agent
With the agent configured and the four tools attached, run a test using the sample payload.
What you should see in n8n's execution view:
- Webhook receives the payload.
- AI Agent starts.
- Agent calls
enrich_lead— you see the tool execute and return. - Agent selects the next step (you may or may not see intermediate traces depending on model and settings).
- Agent calls
score_lead. - Agent calls
draft_response. - Agent calls
route_leadwith one of the three routing options. - Agent returns final JSON.
If something goes wrong, n8n's debug panel shows you the messages between the agent and its tools. The most common issues:
- Tool description not specific enough. The model cannot infer when the tool is appropriate. Make descriptions more concrete.
- Tool input/output schema mismatched. The agent can't pass the right arguments. Be explicit about the schema.
- Agent loops forever. It keeps calling tools without resolving. Add a max-iterations limit and re-examine your system prompt.
Step 5: Add guardrails
A bare agent is unsafe in production. Five guardrails to add before you trust it with real traffic:
1. Max iterations. Set the agent's max iterations to a reasonable number (10-20). This prevents runaway loops where the agent keeps calling tools without finishing.
2. Approval gate for auto_reply. Even if your agent decides "auto_reply," route through a human-approval queue for the first few weeks. Verify that the agent's auto-reply decisions are actually good before letting them go to customers without review.
3. Allowlist for outbound actions. Configure your CRM tool and email tool to only act on records that match your expected pattern. Prevents the agent from sending email to the wrong address or creating records for non-leads.
4. Logging. Log every agent run — input, all tool calls, final output. Use n8n's built-in execution logs or push to a dedicated logging service. When something goes wrong, the logs are how you debug.
5. Cost limits. Set a daily token budget. AI agents can run away — a misconfigured loop can spend $50 in API calls in a single bad run. n8n cloud has this built in; for self-hosted, monitor your API key's usage.
6. Decision ownership. The model can recommend auto_reply, human_review, or log_only, but the workflow should enforce the final rule. Keep the routing enum, score thresholds, and approval requirements outside the prompt so they are testable and visible.
Step 6: Production hardening
A few patterns that turn a working prototype into something you can trust:
Idempotency. Make sure that if the same lead is processed twice (because of a webhook retry or a manual re-run), it doesn't create duplicate records. Add a check at the start of the workflow: "has this lead been processed before?"
Error handling. Wrap each tool call in error handling. If the enrichment API is down, the agent shouldn't crash — it should proceed with reduced information and flag the missing data.
Observability. Track key metrics: average run time, tool call frequency, percentage routed to each path. Anomalies are signals.
Run review. For the first 50 real leads, review every run against the source lead. Track wrong company enrichment, wrong score, wrong route, missing deadline, and poor draft quality. Do not relax human review until those failure modes are rare and understood.
A "kill switch." Have a way to turn the agent off without redeploying. A simple env variable or a workflow toggle that the agent checks first. Useful when you spot a bad decision in production and want to pause.
The most important design decision: what tools to give the agent
The biggest determinant of agent quality is the tool set. Two failure modes:
Too few tools. The agent can't do its job. It tries to fake its way around missing capabilities, often by hallucinating.
Too many tools. The agent gets confused, picks the wrong tool, or wastes iterations exploring. Quality degrades.
A good rule: start with the minimum viable tool set, and only add tools when the agent demonstrably needs them.
For lead triage, the four tools we chose are roughly right. You might add:
- A "lookup_existing_customer" tool to check if the lead is already a customer.
- A "schedule_meeting" tool that integrates with your calendar.
- A "translate" tool if leads come in multiple languages.
But every new tool is a new decision the agent has to make. Each one should genuinely earn its place.
Patterns that generalise
What you built for lead triage works for many other use cases:
Support ticket triage. Replace enrichment with "lookup_customer_history," and routing with "auto_solve / escalate / categorise."
Candidate screening for jobs. Replace enrichment with "parse_cv," scoring with role-fit criteria, and routing with "interview / reject / flag for human review."
Press inquiry handling. Replace enrichment with "lookup_publication," and routing with priority-based response.
Customer feedback routing. Replace enrichment with sentiment analysis and product categorization.
Procurement requests. Replace enrichment with vendor lookups, scoring with policy compliance, and routing with approval flows.
The underlying pattern is always the same: an inbound event → enrich → score/classify → draft response → route. The agent makes the decisions; the tools execute them.
When NOT to use an agent
Some workflows don't benefit from an agent. If the logic is fully deterministic — "always do A, then B, then C" — a regular n8n workflow without an agent is faster, cheaper, and more reliable.
The agent earns its place when:
- The number of possible paths is large.
- The right path depends on judgement, not strict rules.
- Some decisions require synthesising information across multiple sources.
If your decision tree is a few if-then-else statements, just use if-then-else nodes. Save the agent for cases where the if-then-else gets unmanageable.
The takeaway
An AI agent in n8n is a workflow where the model decides which actions to take, in what order, given a set of tools. Built well, it handles the kind of judgement-heavy, multi-step work that used to require a human in the loop.
The lead triage workflow we built is around two hours of work for someone new to n8n agents, plus a few weeks of tuning on real data. The payoff: every lead that comes in gets enriched, scored, drafted-against, and routed within minutes, with human review only where it actually adds value.
Build it once on a real workflow you care about. The next agent you build will take half the time, and the third will feel routine. The agent design pattern is one of the most leveraged skills in 2026 AI work.