What is max iterations in an AI agent?
Quick answer
Max iterations is a setting that caps how many rounds an AI agent may take for one request. Each round, the model thinks, may call a tool and reads the result. When the cap is reached, the agent stops. In n8n it is an option on the AI Agent node, with a default of 10.
Last updated
Take the free module →Module 11 of the free n8n Jump Start course, about 11 minutes. No account needed.
Updated · By Robert Breen
Why it matters for a small business
An agent decides its own steps, which also means it can get stuck: calling the same tool again and again, or chasing a question it cannot answer. Each round uses time and model tokens. A step limit turns a runaway agent into a short, visible failure instead of a slow, costly one.
It is also a quiet safety rail. A booking agent should need two or three tool calls; if it is on round nine, something is wrong. Setting a sensible cap, plus clear rules in the system message about when to stop, is part of the same guardrails that keep an agent predictable.
Where you'll use it: on n8n's AI Agent node, open Options and add Max Iterations. Other agent builders have a similar step or loop limit. If an agent often hits the cap, read its execution log to see which tool it kept calling before you raise the number.
In a real lesson: n8n AI Agent with Tools: Check Google Calendar, Book It and Log It
In the free Book Appointments from Chat lesson, Maple Street Dog Grooming's agent has three tools: check the calendar, create the event and log the booking. A normal booking uses about three rounds: check the hour, book it, write the row.
The lesson keeps the AI Agent's default options. If you added more tools later, a cap of around 10 would still leave room for a customer who changes their mind, while stopping an agent that keeps re-checking the same hour.
Try this lesson free or read the step-by-step guide.
Common confusions
Max iterations vs Loop Over Items
Loop Over Items processes many records in batches. Max iterations limits one agent's rounds on one request.
Max iterations vs max tokens
Max tokens limits the length of one answer. Max iterations limits how many think-and-act rounds the agent takes.
Tips
- Count how many tool calls a normal request needs, then allow a few more.
- Tell the agent in its system message when to stop and hand off.
- Check the execution log when an agent hits the cap.
Related terms
More AI agents terms
Where you use it: free lessons
- n8n AI Agent with Tools: Check Google Calendar, Book It and Log It (n8n, 11 min)
- n8n AI Agent Tutorial: Save Social Media Ideas to Google Sheets (n8n, 12 min)
- A Support Agent That Answers from Your Own Docs (n8n, 13 min)
Frequently asked questions
- What happens when an n8n agent hits max iterations?
- It stops and returns an error or partial answer instead of running on. Handle that like any other failed step.
- Should I raise the limit if my agent hits it?
- Find out why first. Usually a vague tool description or missing rule causes the loop.