How to limit the number of tool calls made by Dify's new Agent?

[00yuyi00]

Self Checks

• I have searched for existing issues search for existing issues, including closed ones.
• I confirm that I am using English to submit this report (我已阅读并同意 Language Policy).
• [FOR CHINESE USERS] 请务必使用英文提交 Issue，否则会被关闭。谢谢！:)
• Please do not modify this template :) and fill in all the required fields.

Content

I'm using the new Agent in Dify. I've noticed that when the Agent thinks a tool hasn't returned its output in time, it keeps calling the tool repeatedly. However, the tool is actually just slow because one of its LLM nodes takes too long to think/generate, and it will eventually return a successful result. I'd like to limit the number of times the Agent can call tools. How can I do this? Is there a configuration option or parameter to set a maximum tool call limit?

[dosubot[bot]]

Hi @00yuyi00! I'm Dosu and I'm helping the Dify team.

It depends on which Agent you're using:

• New Agent V2: There isn't a configurable maximum tool-call count in the current implementation. The backend sets a fixed limit of 500 LLM requests per run, which is not the same as 500 tool calls. That limit is hardcoded, not a user-facing parameter. [1] [2]
• Agent node with the Function Calling or ReAct strategy: Lower Maximum Iterations in the strategy settings. Both strategies expose this parameter, with a default of 3 and a range of 1–500. It limits agent rounds rather than individual tool invocations; Function Calling can execute multiple tool calls within one round. [3] [4] [5]

For the repeated calls, check whether the preceding tool result contains a timeout/error or whether the model requests duplicates in the same round. That distinction would help separate a timeout problem from repeated model decisions.

Which Dify version are you running, and could you share the Agent settings and one execution trace showing the repeated calls?

To reply, just mention @dosu.

---

Docs are dead. Just use Dosu.

[00yuyi00]

I have two questions about the new Agent (Agent V2):

What is the underlying mechanism/principles of tool calling in Agent V2? For example, how does the Agent decide to invoke a tool, how does it handle the tool's response?

For the same tool, what is the timeout threshold that triggers a retry? Specifically, if a tool does not return a response within a certain period of time, how long does the Agent wait before it considers the call as failed and retries? Is this timeout configurable, and if so, which parameter or environment variable controls it?

[dosubot[bot]]

Agent V2 uses an LLM-driven function-calling loop, not a timer that automatically asks the model to call a slow tool again. For workflow tools, the current code returns timeout failures to the model as a tool observation; another call is then a model decision, not an automatic retry in that tool wrapper. [1] [2]

1. How tool calling works

Dify sends the model each available tool’s name, description and JSON parameter schema. The model can return a structured tool call containing the tool name and arguments. Pydantic AI handles dispatch, and Dify maps the result back into a tool message associated with that call ID for the next model turn. This lets the model use the result to answer or request another tool. [3] [4] [1] [5]

2. Timeout and retry behavior

For your workflow-as-tool case, Agent V2 waits on an HTTP request to Dify’s internal tool-invocation endpoint. The current backend’s relevant settings are:

Environment variable	Default	Meaning
DIFY_AGENT_OUTBOUND_HTTP_READ_TIMEOUT	600 seconds	Maximum wait for incoming response data, not a total tool-execution deadline
DIFY_AGENT_OUTBOUND_HTTP_CONNECT_TIMEOUT	10 seconds	Connection establishment timeout

These settings belong to the agent_backend service and are shared by its internal API and plugin-daemon HTTP clients. They are not per-tool settings. The values above are from the current source; your release may differ. [6] [7] [8]

When that workflow-tool request times out, the wrapper returns:

Tool is temporarily unavailable. Please continue without it if possible.

Despite the internal retryable flag, this path does not automatically resend the request. The model receives that observation and may choose to call the tool again. So increasing the read timeout can help if this particular timeout is what causes your repeated calls. [6] [2]

Separately, DIFY_AGENT_RUN_TIMEOUT_SECONDS limits the whole agent run, while AGENT_BACKEND_STREAM_READ_TIMEOUT_SECONDS controls the API’s SSE connection. Neither is a tool retry interval. [9] [10]

Which Dify version are you using, and what tool result or error appears immediately before the repeated call? That would identify whether this HTTP timeout or a different execution limit is firing.

To reply, just mention @dosu.

---

Share context across your team and agents. Try Dosu.

[00yuyi00]

Hi Dify team,

I've observed a behavior in Agent V2 where the same tool can be called up to 3 times within a single second. I'd like to understand the root cause and whether there's a way to limit or prevent this.

Observed Behavior
When the Agent decides to invoke a tool, sometimes it fires multiple identical or near-identical tool calls almost simultaneously (within ~1 second). The tool itself may still be executing or has already returned a result, yet the Agent appears to re-trigger the same call.

[dfbustosus]

The knob you're looking for is Max Iterations in the Agent's execution settings — it's the documented safety limit that caps how many reasoning/tool cycles the agent runs per task ("sets a safety limit to prevent infinite loops"; guidance is 3–5 for simple tasks, 10–15 for complex ones — Agent node docs).

Where it lives depends on which "new Agent" you're on:

• Classic Agent node (Workflow/Chatflow): select the Agent node → the strategy panel (Function Calling / ReAct) → Execution Controls → Max Iterations.
• New Agent node (beta, Workflow apps): the node itself only carries the task; the agent's configuration — including the iteration cap — lives with the agent. Click Edit in Agents on the node and adjust it in the agent's own settings (or edit it from the Agents section directly). A one-time copy (Make a copy) lets you change it for that step only.

Two notes on the specific loop you're seeing, since capping iterations treats the symptom:

1. An agent strategy re-invokes a tool when it doesn't have a usable result in context — with a genuinely slow tool (your inner LLM node), each retry burns an iteration until the cap, then the run ends without the answer. So beyond the cap, it's worth making the wait productive: put the iteration ceiling high enough for the slow tool to finish once (e.g., 8–10), and add an instruction to the agent's prompt like "call this tool once and wait for its result — it may take several minutes; do not re-invoke it" — strategies follow that reliably and it stops the retry churn without lowering the cap.
2. The Agent node's outputs include Iteration Count and Agent Logs — after one capped run you can check exactly how many cycles were tool retries vs. reasoning, which tells you whether to raise the cap or fix the prompt.

And if the slow tool is a workflow-type tool you control, another structural option is to split it out: let the outer agent call a thin tool that triggers the slow part asynchronously and returns a job handle, then a second step retrieves the finished result — keeps the agent's iteration budget cheap regardless of latency.