n8n AI agent to production: the hardening playbook

Turn an n8n AI agent that works in a demo into one you can leave running. It scales, it fails safely, a person signs off risky actions, and you can see and replay every run.

By the AY Automate team · Updated Nov 21, 2026 · 16 min read

Hardening time
About 1 to 2 weeks
Level
Advanced
Built in
n8n 2.45 (self-hosted)
Main risk
Silent failures

Inside this playbook

  • 6prompts, templates and code to copy
  • 4diagrams and real screenshots
  • 8steps, start to finish
n8n · Agent, production version
n8n canvas of a production agent: webhook, input validation, agent with chat model and output schema, success and error outputs, needs review check, Slack approval, HTTP action with retry, Postgres log and responses

Swipe to see the whole workflow.

The hardened agent from this playbook in n8n 2.45. Note the agent's separate Error output and the approval step before the action.

In short

  • Write a one-page spec and prove the workflow by hand before you automate it. Most demo agents fail in production because nobody defined what done means.
  • Run n8n in queue mode with Postgres and Redis, or on n8n Cloud, with a pinned version. Never SQLite and "latest" in production.
  • Make the agent return JSON against a schema, then validate it in a Code node. Anything outside the contract fails loudly.
  • Retry external calls, send agent errors to a fallback path, and set an error workflow that alerts a channel someone reads.
  • Put a person in front of irreversible actions, log every run with its execution id, and export workflows to git every night.

Who it is for: Engineers and automation leads who already have an n8n agent working on test data and need it to survive real traffic. Self-hosted or n8n Cloud.

Overview

What changes between demo and production

n8n is our main orchestration layer at AY. If a workflow connects tools, moves data or runs an agent on a trigger, it usually lives in n8n. The full backend of our customer support chatbot runs in three n8n workflows with no separate server. So we have seen most of the ways an agent that looked great in a demo breaks once real traffic arrives.

Demo agent vs. production agent
  • Input

    Demo
    Clean test data
    Production
    Empty fields, wrong types, other languages, duplicates
  • Output

    Demo
    Free text that looked right
    Production
    JSON against a schema, validated
  • Failure

    Demo
    You see it in the editor
    Production
    Alert, fallback for the user, run logged
  • Risky actions

    Demo
    It just does them
    Production
    A person approves first
  • Load

    Demo
    One run at a time
    Production
    Bursts; queue mode and workers
  • Changes

    Demo
    Edited live
    Production
    Tested on dev, exported to git, then promoted

Diagram

The hardened agent, end to end

  1. Request in

    webhook, schedule or app trigger

  2. Validate input

    reject bad requests with a clear error

  3. Agent with structured output

    retries on fail; errors go to their own output

  4. Error output

    Fallback reply + alert

    user is told a person will follow up

    Success, needs review

    Human approval in Slack

    approve or decline

    Success, safe action

    Do the action

    HTTP call with retry and timeout

  5. Log the run

    execution id, action, outcome, tokens

Trigger or inputYour systemsModel stepStop or fallbackPerson decidesResult

Step 1

Write the spec and prove it by hand

Our rule on every build: map the workflow by hand, prove it, then build the n8n version. If nobody can do the job manually with the same inputs, the agent cannot either. The spec is the authority. When someone asks for a change mid-build, it goes into the spec first.

Template

One-page agent spec

AGENT SPEC  {{name}}            owner: {{person}}     version: {{v1}}

Job (one sentence): {{what it does, for whom}}
Trigger: {{webhook | schedule | app event}}      Expected volume: {{runs per day}}
Inputs: {{fields and where they come from}}
Output: {{exact JSON shape or the action taken}}
Systems it may WRITE to: {{list}}     Systems it may only READ: {{list}}
Needs a human yes when: {{conditions}}
Never does: {{hard limits}}
Done means: {{measurable result}}
On failure: {{fallback for the user}} + alert {{channel}}
Test set: {{link to 50-100 real examples with expected results}}

Step 2

Set up hosting for real load

The default single-process setup is fine for building. In production, two things go wrong: one slow agent run blocks the others, and SQLite struggles with many executions. Queue mode fixes both. The main instance takes triggers and webhooks and puts executions on a Redis queue; workers pull and run them. Postgres stores workflows and execution data.

Config

Queue mode with Docker Compose

# docker-compose.yml: n8n in queue mode (main + worker + Postgres + Redis)
# Pin image versions you have tested. Never "latest" in production.
x-n8n-env: &n8n-env
  DB_TYPE: postgresdb
  DB_POSTGRESDB_HOST: postgres
  DB_POSTGRESDB_DATABASE: n8n
  DB_POSTGRESDB_USER: n8n
  DB_POSTGRESDB_PASSWORD: ${POSTGRES_PASSWORD}
  EXECUTIONS_MODE: queue
  QUEUE_BULL_REDIS_HOST: redis
  QUEUE_BULL_REDIS_PORT: 6379
  N8N_ENCRYPTION_KEY: ${N8N_ENCRYPTION_KEY}   # same value on every n8n container; back it up
  EXECUTIONS_DATA_PRUNE: "true"
  EXECUTIONS_DATA_MAX_AGE: 336                # hours (14 days)
  GENERIC_TIMEZONE: Europe/Amsterdam
  WEBHOOK_URL: https://n8n.example.com/

services:
  postgres:
    image: postgres:16
    environment:
      POSTGRES_USER: n8n
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: n8n
    volumes: [pg_data:/var/lib/postgresql/data]
    restart: unless-stopped

  redis:
    image: redis:7
    restart: unless-stopped

  n8n-main:
    image: n8nio/n8n:{{tested_version}}
    environment: *n8n-env
    ports: ["5678:5678"]
    depends_on: [postgres, redis]
    restart: unless-stopped

  n8n-worker:
    image: n8nio/n8n:{{tested_version}}
    command: worker --concurrency=10
    environment: *n8n-env
    depends_on: [postgres, redis]
    restart: unless-stopped
    # scale with: docker compose up -d --scale n8n-worker=3

volumes:
  pg_data:

Every n8n container must share the same N8N_ENCRYPTION_KEY, or workers cannot read credentials. Lose that key and you lose every stored credential.

Cloud or self-hosted?
  • Ops work

    n8n Cloud
    n8n runs it
    Self-hosted
    You run updates, backups, monitoring
  • Data location and network

    n8n Cloud
    n8n's hosting
    Self-hosted
    Your servers, your VPC
  • Scaling

    n8n Cloud
    By plan
    Self-hosted
    Add workers
  • Best when

    n8n Cloud
    No one on the team wants to run servers
    Self-hosted
    Data must stay in your network, or volume is high

For a full cost comparison, read self-hosted n8n vs n8n Cloud. If you self-host, keep up with security releases; our notes on the n8n sandbox escape vulnerability and the n8n 3.0 upgrade guide cover the recent ones.

Step 3

Force structured output and validate it

Free text from an agent is fine for a chat reply and dangerous for anything that drives an action. Attach the Structured Output Parser sub-node to the AI Agent with a JSON schema, so the agent must return a fixed shape. Then check the business rules in a Code node right after. The parser checks the shape; your code checks that the content is allowed.

Schema

Output schema for the Structured Output Parser

{
  "type": "object",
  "properties": {
    "action":       { "type": "string", "enum": ["reply", "create_ticket", "update_record", "none"] },
    "payload":      { "type": "object" },
    "needs_review": { "type": "boolean" },
    "reason":       { "type": "string" }
  },
  "required": ["action", "needs_review", "reason"],
  "additionalProperties": false
}

Code

Validation Code node

// n8n Code node after the agent: refuse anything outside the contract.
const out = $json.output ?? {};
const allowed = ["reply", "create_ticket", "update_record", "none"];

if (!allowed.includes(out.action)) {
  throw new Error(`Agent returned unknown action: ${out.action}`);
}
if (out.action === "update_record" && !out.payload?.record_id) {
  throw new Error("update_record without record_id");
}
// Money, deletes and anything external always go to a person.
if (out.payload?.amount || out.action === "update_record") {
  out.needs_review = true;
}
return [{ json: { ...$json, output: out } }];

A thrown error here sends the run to your error handling, which is what you want: no unknown action ever reaches another system.

Step 4

Handle errors on three levels

Model APIs time out. Rate limits hit. A tool returns a 500. In production these are normal, so the workflow needs an answer for each, on three levels.

Three levels of error handling in n8n
  • Node

    Where you set it
    Node settings: Retry On Fail, Max Tries, Wait Between Tries; timeouts in options
    What it does
    Absorbs short failures: timeouts, 429s, brief outages
  • Branch

    Where you set it
    Node settings: On Error → Continue (using error output)
    What it does
    Gives the agent an Error output, so you can send a fallback reply instead of a dead request
  • Workflow

    Where you set it
    Workflow settings: Error workflow → a workflow that starts with Error Trigger
    What it does
    Catches anything that still fails: alert with a link to the execution, and a log row
n8n error handler workflow: Error Trigger node, a Set node that formats the alert, then a Slack alert to ops and a Postgres row
Real n8n 2.45 canvas. One error workflow can serve every production workflow: set it once in each workflow's settings.
Download the error handler (n8n JSON)Import it, add your Slack and Postgres credentials, then pick it as the Error workflow in your agent's settings.

Step 5

Put a person in front of irreversible actions

When the stakes are high, the AI suggests and a person decides. In n8n the simplest way is the Slack (or Gmail, Teams) node with the send and wait for response operation: the run pauses until someone clicks approve or decline. A Wait node resumed by webhook works for custom approval screens.

What needs approval
  • Reply drafted from your own docs

    Approval?
    No, after testing
    Why
    Low risk, logged, reviewed weekly
  • Updating a CRM or database record

    Approval?
    Yes at first
    Why
    Hard to notice when wrong
  • Anything with money: refunds, credits, invoices

    Approval?
    Always
    Why
    Irreversible
  • Deleting or merging records

    Approval?
    Always
    Why
    Irreversible
  • Email or message to a customer or prospect

    Approval?
    Yes until trust is built
    Why
    Your name is on it

Cap throughput where people receive the output. On one build we limited an agent to 20 tasks a day so the team on the other end was not flooded. The Limit node does this in one step.

Step 6

Log every run and prune what you do not need

n8n keeps execution data, which helps you debug. As a reporting tool it is weak, and keeping every execution forever fills your database. Write your own small log row per run, linked by execution id, and let n8n prune old executions.

SQL

Run log table

create table agent_runs (
  id             bigint generated always as identity primary key,
  created_at     timestamptz not null default now(),
  workflow       text not null,
  execution_id   text not null,          -- {{ $execution.id }} links back to n8n
  input_hash     text,                   -- dedupe and replay without storing personal data
  action         text,
  needs_review   boolean,
  approved_by    text,
  outcome        text,                   -- 'done' | 'rejected' | 'failed' | 'fallback'
  model          text,
  input_tokens   int,
  output_tokens  int,
  latency_ms     int
);
n8n workflow showing the agent node with Success and Error outputs, Needs review check, Human approval in Slack, Do the action HTTP node, Log run Postgres node and Respond OK
Log run writes the row before the response goes out. The error path answers with HTTP 202 and a fallback message.
Download the hardened agent (n8n JSON)Replace the example API URL and Slack channel. No credentials are included.

Step 7

Version workflows and separate dev from prod

Editing a live agent in the production editor is how a Friday change breaks Monday. Keep a dev instance, test there, then promote. n8n's built-in source control with Git environments is available on its higher plans. On any plan, the CLI export into a git repo gives you history and a way back.

Code

Nightly export to git

# Nightly: export workflows to git (works on any plan)
docker compose exec -T n8n-main n8n export:workflow --all --separate --output=/home/node/backup/workflows/
docker compose cp n8n-main:/home/node/backup/workflows ./workflows
git add workflows && git commit -m "n8n export $(date +%F)" && git push

# Restore one workflow on another instance
n8n import:workflow --input=./workflows/<file>.json
  • Credentials stay out of git. Each instance has its own credentials; workflows reference them by name.
  • Document each node's why in its notes field. The next person who opens the workflow will thank you.
  • Pin the n8n version and upgrade on dev first. Read the release notes for breaking changes.

Step 8

Test with real data, then load test

Real data hardens prompts. Run the test set from step 1 and fix what breaks. Then simulate load: send about twice your expected peak through the webhook and watch the Redis queue, worker CPU, model rate limits and error rate. Most agents hit the model provider's rate limit before n8n struggles.

Timeline

Hardening an existing agent, in working days

  1. Spec and test setDay 1-2

    One-page spec, 50 to 100 real examples.

  2. HostingDay 2-3

    Queue mode or Cloud, pinned version, key backed up.

  3. Output and errorsDay 3-6

    Schema, validation, retries, error output, error workflow.

  4. Approvals and logsDay 6-8

    Approval steps, run log, pruning, git export.

  5. Test and loadDay 8-10

    Real test set, 2x peak load, fixes.

For one engineer on one agent. A second agent on the same setup takes much less, because hosting, error workflow and logging are shared.

Production readiness checklist

  • Spec written and signed off by the person who owns the outcome.
  • Queue mode (or n8n Cloud) sized for peak volume; image version pinned.
  • N8N_ENCRYPTION_KEY stored in your secret manager and backed up.
  • Agent output parsed against a JSON schema and validated in a Code node.
  • Retry on fail set on every external call; timeouts set on model and HTTP nodes.
  • Agent node errors go to an error output with a user-facing fallback.
  • Error workflow set in workflow settings; alerts reach a channel someone reads.
  • Human approval on every irreversible action (money, deletes, external sends).
  • Every run logged with execution id, action, outcome and token counts.
  • Execution data pruning on; no personal data kept longer than needed.
  • Workflows exported to git nightly; prod changes only after a test on dev.
  • Load test at 2x expected peak; throughput capped where people receive the output.

Watch out

Failure modes we see most

  • Silent failures

    The workflow fails, nobody knows, customers wait. Fix: error output, error workflow, alerts to an owned channel.

  • Free text drives actions

    The agent writes "I will update the record" and something else parses it. Fix: schema plus validation.

  • Lost encryption key

    A rebuild with a new key and every credential is unreadable. Fix: store and back up N8N_ENCRYPTION_KEY.

  • Database fills up

    Years of execution data in Postgres. Fix: pruning on, plus your own small run log.

  • Hotfix in production

    A quick edit breaks a node mapping. Fix: dev instance, git export, promote.

  • Hardcoded secrets

    An API key in a Code node or an HTTP header field. Fix: always use n8n credentials.

Time and money

Time and cost

Hardening one existing agent takes about 1 to 2 weeks of one engineer's time, as in the plan above. Running costs are the n8n plan or your servers (Postgres, Redis, the main instance and workers), plus model tokens, which usually grow fastest. To keep the model side in check, use the LLM cost control playbook. To compare platform costs, try the n8n vs Zapier vs Make cost calculator.

Running cost drivers
  • n8n Cloud plan or servers

    Scales with
    Executions, workers
    Keep it down by
    Batch small items into one execution; prune data
  • Model tokens

    Scales with
    Runs x prompt size x loops
    Keep it down by
    Route steps to small models; cap iterations
  • Your time on alerts

    Scales with
    Error rate
    Keep it down by
    Fix the top error each week

Results

How to measure it

Weekly agent health
  • Runs that ended done

    From
    agent_runs.outcome
    Target direction
    Up
  • Runs that hit the error workflow

    From
    Error log
    Target direction
    Down; every one has a ticket
  • Approval rate on reviewed actions

    From
    approved_by not null
    Target direction
    Up as prompts improve
  • p95 run time

    From
    latency_ms
    Target direction
    Stable under load
  • Tokens per run

    From
    input_tokens + output_tokens
    Target direction
    Flat or down
  • Test set score after each change

    From
    Evaluations run
    Target direction
    Never down

Take a baseline in the first week live, then review every week with the person who owns the outcome. One fix per week, starting with the most common error, beats a big rewrite every quarter.

Questions

FAQ

Can n8n run AI agents in production?

Yes. n8n's AI Agent node, with structured output, retries, error workflows and human approval steps, runs production agents. For real load, self-host in queue mode with Postgres and Redis, or use n8n Cloud.

What is n8n queue mode?

Queue mode splits n8n into a main instance that receives triggers and webhooks and workers that run executions from a Redis queue. You set EXECUTIONS_MODE to queue, use Postgres, share one encryption key, and add workers to scale.

How do I handle errors in an n8n AI agent?

On three levels: Retry On Fail on nodes that call external services, the Continue (using error output) setting so the agent has an error branch with a fallback, and an error workflow that starts with the Error Trigger node to alert and log.

How do I add human approval to an n8n workflow?

Use the send and wait for response operation on the Slack, Gmail or Teams node, or a Wait node resumed by a webhook from your own approval screen. The run pauses until a person approves or declines.

How do I version control n8n workflows?

n8n offers Git-based source control and environments on its higher plans. On any plan, export workflows with the n8n CLI to a git repository every night, test changes on a dev instance and import them into production.

Sources

AI Engineers

Want your n8n agents hardened by people who run them daily?

n8n is the main orchestration layer on our client builds. An AY engineer can join your team, harden the agents you have, and leave you with the spec, the error handling, the logs and the runbook.

From €5,000 a month per engineer. Starting price, your quote may be higher. First month money-back.