3. The native AI Agent node in production

Description

By the end of this lesson you'll be able to explain what exactly an agent iteration is and why the tenth costs much more than the first, you'll know what Max Iterations does —whose default value is 10— and why moving it doesn't add spend but multiplies it, and you'll be able to choose a ceiling with judgment instead of with a hunch. You'll also know when Return Intermediate Steps is worth what it costs and what to do when an agent hits its own limit.

This matters because the agent's loop is the first of the five leaks from lesson 2 and, by far, the most expensive. It's also the one that explains the case that opened the module: someone at Terra Market bumped Max Iterations from 10 to 30 in ticket-classify to fix some odd cases that were failing, and it worked — it fixed those cases and raised the spending ceiling for the 9,000 monthly executions. That change doesn't show up in any of the metrics you were watching. It shows up on the bill, a month later, when nobody remembers who made it.

Connection to the module: lesson 2 gave you the instrument —cost_log, with the raw tokens and one row per model call. This lesson uses it to make the first real decision: how much ceiling you put on the loop. Lessons 4 and 5 deal with the other two big levers —which model and where it runs—, and 6 and 7 deal with the surfaces from which the loop can go off without you asking for it. A clear boundary: here you're not going to learn how to design an agent. What tools to give it, how to write its contract, when to ask for human approval before an irreversible action — all that is n8n-ai-chatbots-agents-guide, module 4. This lesson deals with operating an agent that already exists, with the question that guide doesn't ask: how much a single execution can end up costing.

What an iteration is, with apples

Let's build the picture from the bottom, because almost everyone has a wrong mental model of the AI Agent node and that model is the root of the problem.

The natural intuition is this: the AI Agent node makes one call to the model. You send it the ticket, the model returns the category, done. With that picture, Max Iterations looks like a technical adjustment with no consequences, and raising it looks as harmless as raising a timeout.

What it actually does is something else.

An agent isn't a translator. It's more like someone you assign an errand to and who goes out to run it. You tell them: "find out whether this order has already shipped and whether the customer qualifies for a return." That person doesn't answer immediately: they get up, go to a window to check the order's status, come back with the answer, read it, realize they also need the customer's history, go to another window, come back, and then they answer you.

Each of those trips to a window and back is an iteration. In n8n terms: a call to the model, the decision to use or not use a tool, the execution of that tool, and the return of the result to the model. The AI Agent node repeats that cycle until the model says "that's it, here's the final answer."

The official documentation puts it precisely: Max Iterations is "the number of times the model should run to try to generate a good response to the user's prompt." Its default value is 10. Verify that number in your version's panel before making decisions about it — what you see on screen overrides whatever any guide says.

Why the cost doesn't grow in a straight line

Now the part you have to understand well, because it's what makes the adjustment dangerous.

Each time the agent talks to the model again, it doesn't send only the new part: it sends the entire conversation history up to that point. The model has no memory between calls; the only way for it to know what already happened is for you to tell it again. So each iteration's input includes the system prompt, the tool descriptions, the original question, and all the previous intermediate steps: which tool was called, with what arguments, and what it returned.

Let's put numbers on that, with Terra Market's ticket-classify:

Iteration 1
  input:   system prompt (320) + tools (180) + ticket (240)          =   740 tokens
  output:  "I'm going to check the order status"                     =    40 tokens

Iteration 2
  input:   the same 740  +  what the model said (40)
           +  the tool result (180)                                  =   960 tokens
  output:  "now I need the customer's history"                       =    45 tokens

Iteration 3
  input:   the previous 960 + 45 + another result (200)              = 1,205 tokens
  output:  the final category                                        =    35 tokens

Notice the input column: 740, 960, 1,205. It grows on each pass, and it grows because it drags along. Now sum the three iterations and compare it with what you'd have paid if the agent had resolved it in a single one:

Three iterations:  input 740 + 960 + 1,205 = 2,905 tokens
One iteration:     input                   =   740 tokens

Three passes don't cost triple: they cost almost four times more.

And that curve steepens. By the time the agent reaches iteration ten, the input of that single call can be three or four times that of the first, because it drags along nine steps of history. Iteration twenty is worse. That's why Max Iterations isn't a linear limit: it's the ceiling of a curve that accelerates.

If the image helps: it's like paying someone by the hour, but also forcing them to reread their whole notebook before each new task. The second task takes a little longer than the first. The tenth takes much longer. And you pay for each reread.

Worked example: measure before deciding

Here's the part Terra Market didn't do, and which is the whole method of this lesson.

The person who bumped Max Iterations from 10 to 30 did the reasonable thing with the information they had: they saw cases that were failing, found a field that seemed related, raised it, and confirmed the cases stopped failing. What they missed was measuring the effect on the rest.

Let's do it right. With cost_log already writing —one row per model call, with execution_id—, the number you need comes from a query:

-- How many iterations does ticket-classify REALLY use?
-- Each cost_log row is a model call, so counting rows
-- by execution_id gives you the iterations of that execution.
SELECT calls_per_execution,
       COUNT(*) AS how_many_executions
FROM (
  SELECT execution_id, COUNT(*) AS calls_per_execution
  FROM cost_log
  WHERE workflow_name = 'ticket-classify'
    AND logged_at >= now() - interval '7 days'
  GROUP BY execution_id
) t
GROUP BY calls_per_execution
ORDER BY calls_per_execution;

What to expect. You'll get a distribution, not a number. Something with this shape:

iterations   executions   cumulative %
     1            1,240         19.7%
     2            3,980         83.0%
     3              780         95.4%
     4              210         98.7%
     5               58         99.6%
     6               14         99.8%
    ...
    28                3         99.99%
    30                4        100.0%

Read it slowly, because that table contains the whole decision.

95% of executions resolve in three iterations or fewer. That's the typical case and it's where the workflow's value lives.

There's a tail. A few executions reach 28 and 30 — that is, they hit the ceiling. And here's the detail that changes the diagnosis: when the ceiling was 10, those same executions hit 10. It's not that they now resolve cases they couldn't before: it's that they now take twenty more passes before giving up. You'd have to review case by case whether they really end well or just end more expensive.

And the arithmetic of the change. If those 7 executions that reach 28-30 had stopped at 10, the savings per execution would be about twenty iterations of the expensive kind — the ones at the end of the curve, which drag along the whole history. Seven executions a day, thirty days, twenty expensive iterations each: that's 4,200 monthly model calls nobody asked for, with the largest input in the range.

The decision, then, writes itself:

Reasonable ceiling = high percentile of the legitimate case  +  margin

  observed p99 (excluding the tail that hits the ceiling) ≈ 5
  safety margin for new cases                             +2
  ─────────────────────────────────────────────────────────────
  Max Iterations = 7

With 7, 99.6% of executions notice no difference. The tail is cut earlier, cheaper, and visibly — because an execution that hits the ceiling is a signal you can count and alert on, while one that takes 30 passes and finishes is invisible.

And the habit to leave installed: that change is tested before it's published. You lower the ceiling in the development environment, run a sample of real tickets —including several of the "odd cases" that motivated the original increase—, and compare two things: the classification quality and the consumption. If the quality holds, you publish. If it drops, you go up a notch and measure again. It's not an intuition decision: it's a two-hour experiment with a number at the end.

The other options that move the needle

Max Iterations is the most expensive, but it's not the only one. Let's look at the ones that appear in the node's options panel and what each one implies in production.

Return Intermediate Steps

What it is. A switch that makes the node include in its final output the intermediate steps the agent took: which tools it called, with what arguments, and what each one returned. With it off, the output is only the final answer.

What it's for. For debugging and for auditing. When an agent returns an odd category and you want to know why, the intermediate steps tell you. It's the agentic equivalent of the structured logging you set up in module 4: without it, you have the result but not the reasoning.

What it costs. Here you have to be precise, because it's often confused. It doesn't increase the number of calls to the model or the tokens sent to it. What it does is inflate the execution data n8n stores, and that has a real cost that isn't about tokens:

• The execution data grows, and with it the instance's database. If you have 4,000 daily executions, that growth is noticeable. Module 6 of this guide covers the management of execution-data growth in depth, and this option is one of the ones that accelerate it.
• The execution panel becomes heavier to load when you open it to debug.
• If the intermediate steps include customer data —and in support they almost always do—, they're now stored in one more place, with the retention and privacy implications that has. Module 5 covers that angle.

The operational recommendation: turn it on in development, and in production turn it on temporarily while you're investigating, not permanently. It's a diagnostic tool, not a default configuration. And if you leave it on in production for a deliberate reason —auditing, for example—, let it be a written decision with its retention policy, not an oversight.

System Message

What it is. The message sent to the agent before the conversation: its instructions, its role, its rules.

Why it's in a cost lesson. Because it travels in full on every iteration. If your agent takes three passes, your system prompt was paid for three times in that single execution. And multiplied by the monthly volume, it's leak 2 from the previous lesson.

That gives it a practical consequence almost nobody works out: the cost of a word in the system prompt is its length × iterations × volume. A 30-token sentence you added "just in case," in a workflow that averages 2.5 iterations and runs 9,000 times a month, costs 675,000 tokens a month. For one sentence.

It's not an argument for writing cryptic prompts —a bad prompt produces agents that take more passes, which is worse. It's an argument for reviewing it periodically and trimming what no longer applies, the same way you review any configuration that accumulates.

Enable Streaming

What it is. It makes the agent return the response in real time, as it generates it, instead of waiting to have it complete.

What it implies in production. It's a user-experience option, not a cost one: the tokens are the same. It makes sense in a chat where someone is watching the screen, and none in an automated workflow where the result goes to a database. In Terra Market, ticket-classify doesn't need it. A conversational assistant for the support team does.

Tracing Metadata

What it is. It lets you attach your own key-value pairs to the agent's tracing events.

Why it's useful. If you have an AI observability tool connected, this is the door to tag each execution with your own data —the customer, the ticket type, the environment— and then be able to segment the spend by those tags. It's the same principle as tags in any metrics system: without them you have a total, with them you have a breakdown.

Automatically Passthrough Binary Images

What it is. It controls whether the binary images that enter the workflow are automatically passed to the agent as image-type messages.

Why it matters here. Because images are charged, and they're not cheap. A screenshot a customer attaches to a ticket can cost as much as several pages of text. If this option is on and your workflow receives attachments, you're paying to process images that maybe contribute nothing to the classification. And since the default can change between versions, check in your panel how it's set before assuming it. If your agent doesn't need to see images, turn it off.

What happens when the agent hits the ceiling

This part deserves its own section because it has an operational trap.

When an agent reaches Max Iterations without having finished, it stops. So far, as expected. The operational question is: which output does that node exit through? The success output, with a half-finished answer, or the error output, where your module 2 error handling will catch it?

And here's an honest warning: this behavior has been reported as inconsistent between versions, with cases where the iteration limit exits through the success output instead of the error one. Don't take it for granted in either direction. Verify it yourself, in your version, with a thirty-second test:

1. Duplicate your workflow in development.
2. Set Max Iterations to 1 or 2.
3. Give it a task you know needs more passes.
4. Look at the execution panel: did it come out green or red? What does the output contain?

That result decides how you build the rest. Because the two possibilities have very different consequences:

The second is the dangerous one, and it deserves a paragraph: if an agent that came up short exits green, its half-finished result enters your ERP, or your support queue, or the customer's email. In Terra Market that would be a ticket classified with an empty or made-up category. Nobody finds out, because the execution came out fine.

The defense is worth it even if your version exits through error, because it's cheap and also protects against other forms of malformed response:

// Node: Code — "Validate agent output"
// Mode: Run Once for Each Item
// It goes after the agent, BEFORE its output touches any real
// system. It verifies the response has the shape the business
// expects, instead of trusting that it came out green.

const VALID_CATEGORIES = [
  'returns',
  'late_shipping',
  'payment_issue',
  'general',
];

const data = $input.item.json;
const category = (data.category ?? '').trim();

// An agent that came up short usually returns empty, or free text
// where you expected a closed label. Both cases are detected the same way.
const isValid = VALID_CATEGORIES.includes(category);

return {
  json: {
    ...data,
    category: isValid ? category : 'needs_human_review',
    // This flag is the one you later count and alert on: if it rises,
    // the agent is hitting its ceiling more than normal.
    agent_output_valid: isValid,
  },
};

Notice what that node does when the output isn't valid: it doesn't throw an error, it redirects to human review. In a support flow that's the right thing — an unclassified ticket that goes to a human queue is an inconvenience; a wrongly classified ticket that's answered automatically is a problem with the customer. The decision of where to send the doubtful cases depends on your business, but the decision to detect them isn't optional.

And the agent_output_valid flag is a metric: if the percentage of false rises, your ceiling came up short or something changed in the input data. It's exactly the kind of signal module 4 taught you to alert on.

The timeout, which is the other ceiling

Max Iterations bounds how many times the agent talks to the model. It doesn't bound how long it takes. They're two different limits and it's worth having both.

The case that separates them: an agent with Max Iterations at 7, whose third iteration calls a tool that queries an external service, and that service hangs. The agent isn't iterating — it's waiting. Max Iterations doesn't protect it from that.

The time limit lives in the workflow settings, not in the agent node, and it's worth setting it with the same logic: measure how long the typical case takes, add a margin, and put it in. An AI workflow with no time limit is a workflow that can keep occupying an execution slot indefinitely, and in an instance with 4,000 daily executions that has effects beyond cost — it's capacity you take away from everything else. Module 6 of this guide covers concurrency and throughput in depth; here the rule is enough: if the workflow has an agent, it has a time limit.

Common mistakes

Raising Max Iterations to fix a failing case (practical). What happens: a few odd cases don't resolve, someone raises the ceiling, the cases resolve, and the ceiling stays up forever affecting every execution. Why it happens: it's the first reasonable hypothesis —"it needs more space to think"— and it works, so it's confirmed. How to detect it: run the iterations-per-execution query and look at the distribution. If 95% resolves in three passes and the ceiling is at 30, the ceiling isn't protecting the typical case: it's allowing the tail. How to fix it: almost always the odd case doesn't need more passes, it needs better information — a clearer prompt, a tool that returns cleaner data, or a less ambiguous tool description. If after fixing that the case still needs fifteen passes, it probably shouldn't be resolved by an agent. And if you really need to raise the ceiling, raise it only for that path: split the odd cases into a sub-workflow with its own configuration, instead of raising the ceiling for the 9,000 monthly executions.

Believing Max Iterations is a linear limit (conceptual). What happens: someone reasons "10 to 30 is triple, so at worst I pay triple," budgets with that, and the bill comes out quite a bit worse. Why it happens: the mental model of "each iteration costs the same" is the intuitive one and it's false, because each iteration drags along the history of the previous ones. How to detect it: look in cost_log at the cost of the calls of a single execution_id, ordered. You'll see they rise. How to fix it: when you estimate the worst case, don't multiply the cost of one iteration by the ceiling. Take a real execution that reached the ceiling and look at what it actually cost. That's your worst case, and it usually surprises.

Leaving Return Intermediate Steps on in production without deciding it (practical). What happens: it's turned on to debug a problem, the problem is solved, and it stays on. Months later the execution database grew much faster than expected and nobody knows why. Why it happens: the effect is invisible the first day and cumulative. How to detect it: check which agent workflows have it active and contrast that with the growth of your execution data. How to fix it: treat it as a diagnostic flag — it's turned on to investigate and turned off when done. If you leave it on on purpose, write down why and with what retention policy, and check that the intermediate steps aren't storing customer data that shouldn't stay there.

Trusting the execution's green when there's an agent inside (conceptual). What happens: the success-rate metric says 99.8% and the team is calm, while some tickets reach customers with incomplete classifications because the agent came up short and exited green anyway. Why it happens: in a deterministic system "no error" and "correct" are almost the same. With an agent, they're not. How to detect it: do the Max Iterations = 1 test in development and look at which output the node exits through in your version. And in production, count how many agent outputs don't have the expected shape. How to fix it: validate the output explicitly with a node after the agent, and track that validation as its own metric. With AI, "it didn't fail" and "it went well" are two different questions and you have to answer both.

Putting a ceiling without putting a time limit (practical). What happens: the agent has Max Iterations at 7 and still an execution hangs for two hours, because a tool called an external service that didn't respond and nobody set a maximum time. Why it happens: Max Iterations feels like "the agent's limit," and it covers only one of the two ways of going out of control. How to detect it: sort your executions by duration and look at the top tail. If there are hours-long executions in a workflow that should take seconds, you found it. How to fix it: both limits, always. Iterations in the node, maximum time in the workflow settings. And if the agent consumes tools that call third parties, also a timeout on those calls — which is exactly the topic of lesson 7.

Exercises

Exercise 1 — Choose the ceiling with the distribution. You measured reply-draft for a week and got this distribution of iterations per execution:

iterations   executions
     1              90
     2           1,610
     3             580
     4             140
     5              38
     6              11
     7               4
    12               2
    20               5   ← the current ceiling is at 20

(a) What percentage of executions resolves in 4 iterations or fewer? (b) What ceiling would you propose and why? (c) What stands out to you about the 5 executions that reach exactly 20, and what would you do with them before lowering the ceiling? (d) If you lower the ceiling from 20 to 6, how many weekly executions are affected, and what happens to them?

2,420 / 2,480 = 97.6%

Exercise 2 — Estimate the worst case for real. A coworker tells you: "a normal execution of ticket-classify costs about 800 input tokens. With Max Iterations at 30, the worst case is 30 × 800 = 24,000 tokens. Let's budget with that."

(a) Explain why that estimate is wrong and in which direction. (b) Reconstruct the correct estimate, knowing that in each iteration about 220 tokens are added to the history (the model's decision plus the tool result). (c) What query to cost_log would give you the real worst case, without estimating anything?

iteration 1:   800
iteration 2:   800 +  220  = 1,020
iteration 3:   800 +  440  = 1,240
...
iteration n:   800 + 220 × (n − 1)
iteration 30:  800 + 220 × 29 = 7,180

total = 30 × 800  +  220 × (0 + 1 + 2 + ... + 29)
      = 24,000    +  220 × (29 × 30 / 2)
      = 24,000    +  220 × 435
      = 24,000    +  95,700
      = 119,700 input tokens

-- The real worst case of the last week, per execution
SELECT execution_id,
       COUNT(*)            AS iterations,
       SUM(input_tokens)   AS total_input,
       SUM(output_tokens)  AS total_output,
       SUM(cost_total)     AS execution_cost
FROM cost_log
WHERE workflow_name = 'ticket-classify'
  AND logged_at >= now() - interval '7 days'
GROUP BY execution_id
ORDER BY execution_cost DESC
LIMIT 10;

Exercise 3 — Design the change plan. You're tasked with fixing the Max Iterations of ticket-classify at Terra Market: it's at 30 and the evidence says it should be at 7. The workflow runs 300 times a day in production and classifies real customers' tickets. Write the complete change plan: what you do before, what you do during, what you measure, and under what condition you'd revert it. At least six steps.

Summary and next step

Now you know what's inside the AI Agent node. An iteration is a complete cycle: call to the model, decision to use a tool, execution, and return of the result. The agent repeats that cycle until it finishes or until it hits Max Iterations, whose default value is 10 — verify it in your version.

And you know why that number is the most dangerous multiplier of the module: each iteration sends the whole accumulated history again, so the input grows on each pass and the cost of a loop grows roughly with the square of the number of iterations. Doubling the ceiling doesn't double the worst case: it quadruples it. Three passes don't cost triple one: they cost almost four times more.

You have the method for choosing the ceiling, and it's not a hunch: measure the real distribution of iterations per execution with cost_log, find where it flattens, put the ceiling there plus a margin, and open the executions that hit the current ceiling — because an execution that ends exactly at the limit almost never needed that number: it ran out of passes.

You saw the other options and what they move: Return Intermediate Steps doesn't cost tokens but inflates the execution data, and it's a diagnostic flag, not a permanent configuration. The System Message travels in full on every iteration, so its real cost is length × iterations × volume. Enable Streaming is user experience, not cost. Tracing Metadata lets you segment the spend. And Automatically Passthrough Binary Images might be making you pay for images you don't need.

And you take away the operational warning that avoids the most incidents: verify in your version which output the node exits through when it hits the ceiling. The behavior has been reported as inconsistent, and if it exits through success, your success-rate metric lies and a half-finished result reaches your systems. The defense is to validate the output explicitly with a node after the agent, redirect the doubtful cases to human review, and count that flag as a metric. Plus the other ceiling that's needed: a time limit in the workflow settings, because Max Iterations bounds how many times the agent talks, not how long it can wait.

Before moving on you should be able to: explain why the tenth iteration costs more than the first; pull from cost_log the iteration distribution of a workflow and propose a ceiling with it; say what Return Intermediate Steps costs and what it doesn't; and describe what happens to an incomplete result that exits green.

Lesson 4 goes up a level and touches the other big lever: which model handles the call. You'll see it's not an aesthetic decision but two things at once — a line on the bill that can vary a lot between models from the same provider, and a risk that your workflow stops working without warning, because providers retire models on an announced date and the identifier you have written stops existing. You'll learn the procedure to verify yours is still alive, and the criterion to stop using the same model to classify tickets and to draft replies.

Resources

• AI Agent node — n8n Docs — the node's reference, with its connections and its place on the canvas.
• Tools Agent — n8n Docs — the full list of options with their default values, including Max Iterations (10), Return Intermediate Steps, System Message, Tracing Metadata, Enable Streaming, and Automatically Passthrough Binary Images. Verify here what you see in your version.
• How tools work — n8n Docs — the mechanism by which the agent decides which tool to call, which is what produces the iterations you're counting.
• Workflow settings — n8n Docs — where the workflow's time limit lives, the other ceiling an agent needs.
• Module 2 of this guide — error handling, error branches, and Continue On Error, which is what catches an agent that hits its ceiling if your version exits it through the error output.
• Module 6 of this guide — management of execution-data growth, which is what Return Intermediate Steps accelerates when it's left on.
• Sibling guide n8n-ai-chatbots-agents-guide, module 4 (this same ecosystem) — the agent's design: what tools to give it, how to write its contracts, and where to put human approval. It's where you take the findings when you discover the agent iterates too much because of a design problem.