Skip to content

Max iterations ​

The most rounds of model call and tool calls an agent may take in one run. When it is reached, the agent stops instead of looping on.

An agent loopAgent loop: The cycle an AI agent repeats: call the model, run the tools it asks for, add the results to the conversation, then call the model again until it answers. has no natural end except the model deciding it is done. Most of the time it is. But a model can also call the same search again and again, retry a tool that keeps failing, or chase a question its tools cannot answer. Each round is another model call, so the cost and the contextContext window: The most text, counted in tokens, that a model can take into account in one call: system prompt, conversation, tool definitions and tool results, plus the answer it writes. grow with it. Max iterations is the hard stop for that case.

One iteration is one model call plus the tool calls that model asked for. A run that answers straight away uses one. A run that looks something up, then answers, uses two.

Picking a value ​

Count the rounds a good run needs, then leave some room:

  • A lookup-then-answer agent needs two or three.
  • An agent that searches, reads a result and maybe searches again needs four to six.
  • A supervisorSupervisor agent: An agent whose tools include other agents: it splits a task, hands each part to a worker agent, and combines the answers into one reply. often spends a round on each delegation and one more to answer, so it usually gets a higher limit than its workers.

A limit that is too low cuts good runs short. A limit that is too high mostly costs money on the runs that were going wrong anyway. When runs keep hitting the limit, raising it is rarely the fix: a shorter tool list or a clearer prompt usually is.

Example ​

An agent with maxIterations: 4 is asked for a parcel's status. On each call the model asks for track_parcel, and the tool returns "carrier timeout". After the fourth round the loop stops and the agent returns what it has, rather than retrying for minutes.

Common confusion ​

Max iterations limits rounds, not money or tokens. Two runs with the same limit can cost very different amounts, depending on the model and the size of the tool results. To cap spend, set a budgetBudget: A cap on model spend or tokens for one scope, such as a project, a user or a client, over a period, which warns or blocks new work when it is reached. as well. A run timeout is different again: it limits wall-clock time for the whole workflow.

In L2M ​

The Agent Orchestrator and Supervisor nodes both have maxIterations. On the Agent Orchestrator it is required: validation rejects a missing value or one below 1. A new Agent Orchestrator starts at 6 and a new Supervisor at 10; a Supervisor whose value has been removed runs with 4. When the limit is reached, the node returns the text of the model's last reply, or "Agent stopped after reaching iteration limit." if that reply had none, and its output has stopReason: "max_iterations" (a normal answer has final_answer), so a later step can check it and route those runs elsewhere. The run trace shows each round as "Step 2 of 6". The Loop / ForEach node also has a maxIterations field, but there it caps how many items the loop runs over. See agent hits max iterations.

Further reading ​

This website (not the L2M product) uses Google Analytics, only after you accept cookies. Cookie settings