Agent Tool Calls Stuck in Infinite Loops: Maximum Iteration Settings + Exit Condition Prompt Design Logic
Agent infinite loops typically manifest as: repeatedly calling the same tool, continuously requesting irrelevant parameters, or bouncing back and forth between “no results found — try again.” This problem both wastes costs and severely impacts user experience.
The good news is that this problem already has publicly confirmed control mechanisms in Dify. The official Agent documentation clearly provides key configuration items including Maximum Iterations, tool descriptions, Instruction, and Memory; the environment variable documentation also publicly provides MAX_ITERATIONS_NUM and similar upper limit controls. This indicates that “infinite loops” are not a black-box problem that can only be solved through experience — at least a portion can be constrained through platform configuration and prompt boundaries working together.
1. Control Mechanisms Confirmed from Public Sources
1. Agents Publicly Support Maximum Iterations
The official documentation clearly states that Agent nodes have a Maximum Iterations configuration, used to limit how many steps a single Agent execution can take. The significance of this setting is very straightforward: it prevents runaway costs and also prevents infinite loops.
2. Tool Description Quality Directly Affects Call Behavior
The official Agent documentation repeatedly emphasizes that tool descriptions are not just documentation — they are important inputs for model decision-making. In other words, the more vaguely a tool is defined, the more likely the Agent is to repeatedly call it incorrectly.
3. Exit Conditions Are Not Auto-Generated by the Platform — They Must Be Written into the Instruction
The public documentation only provides capability slots, but when to stop, when to ask follow-up questions, and when to transfer to a human must still be explicitly written out in prompts and business rules. The infinite loop problem is fundamentally a case where “platform upper limits + prompt boundaries + tool design” have not been completed together.
2. Why Infinite Loops Occur
Common causes include:
- Tool descriptions are unclear, so the model does not know when to stop
- No fallback after failure
- Maximum iterations not set
- The prompt only says “do your best to solve it” without saying “when to exit”
3. Why Maximum Iterations Must Be Set
Maximum iterations are not meant to limit capability, but to limit runaway costs. For standard customer service or query tasks, too many rounds of tool calls are typically unnecessary; complex tasks should also have explicit upper limits.
4. How to Write Exit Condition Prompts
The system prompt should clearly state:
- If a tool returns empty results more than N times, stop calling it
- If critical parameters are missing, ask the user first
- If consecutive calls still cannot complete the task, transfer to a human or output a failure explanation
- Do not repeatedly call a tool that has clearly failed
5. Recommended Fallback Path
- Retry the same type of tool once more
- Switch to a clarification question
- Fall back to a knowledge base explanation
- Transfer to a human
6. What to Look at During Debugging
Prioritize Agent logs:
- Which tool is being called repeatedly
- Whether the parameters remain unchanged
- Whether the previous failure result was correctly understood
- Whether exit conditions were actually written into the system prompt
7. Conclusion
Agent infinite loops are usually not because “the model is too dumb,” but because “the system never taught it when to stop.” The truly effective approach is to design maximum iterations, failure fallback paths, and exit conditions together.
Public Source References
note.com
- Part 1: [Dify] Basic Structure of ReAct Agents and the “Think-Act-Observe” Loop | https://note.com/niti_technology/n/nb8640f15a899
zenn.dev / Official Documentation / Other Public Pages
- Agent | https://docs.dify.ai/ja/use-dify/nodes/agent
- Agent | Dify | https://legacy-docs.dify.ai/guides/workflow/node/agent
- Environment Variables - Dify Docs | https://docs.dify.ai/getting-started/install-self-hosted/environments
Verified Information from Public Sources for This Article
- Dify Agent nodes publicly support Maximum Iterations for limiting execution steps per run
- Platform-level environment variables also publicly include maximum iteration limits
- Tool descriptions and Instruction boundaries directly affect whether repeated calls and runaway behavior occur