Tool is Invoked Multiple Times Based on maxSteps Value

[Nishchit14]

Description

I am using the latest version of ai-sdk and noticed that a tool is being executed multiple times corresponding to the maxSteps value. For example, when setting maxSteps: 5, the tool is invoked 5 times, which is unexpected behavior.

Expected Behavior

The tool should only be called as necessary, rather than being triggered exactly maxSteps times.

Actual Behavior

• When setting maxSteps: 5, the tool is called 5 times.
• The number of tool executions matches the maxSteps value, even when it shouldn’t.

Steps to Reproduce

1. Use the latest version of ai-sdk.
2. Set maxSteps: 5 in the configuration.
3. Observe that the tool is invoked exactly 5 times.

Environment

• AI-SDK Version: "ai": "^4.1.60", @ai-sdk/openai": "^1.2.4"
• Node.js Version: v22
• OS: Mac

Code example

    messages,
    toolChoice,
    abortSignal: req.signal,
    tools,
    maxSteps: 5

AI provider

@ai-sdk/openai": "^1.2.4"

Additional context

when is set maxStep: 2

this is what message.parts look like

[
  {
    "text": "",
    "type": "text"
  },
  {
    "type": "tool-invocation",
    "toolInvocation": {
      "args": {
        "query": "explain this file"
      },
      "step": 0,
      "state": "result",
      "result": {
        "data": "Your receipt from ...",
        "time": 898
      },
      "toolName": "file_search",
      "toolCallId": "call_DJDvNKV3Qvj8XKKTE4FVktZf"
    }
  },
  {
    "text": "",
    "type": "text"
  },
  {
    "type": "tool-invocation",
    "toolInvocation": {
      "args": {
        "query": "receipt from Mailo February 4, 2025"
      },
      "step": 1,
      "state": "result",
      "result": {
        "data": "Your receipt from ...",
        "time": 868
      },
      "toolName": "file_search",
      "toolCallId": "call_nzCraUvAnk2DfVx9Q75Rbw2Z"
    }
  }
]

[lgrammel]

Can you provide your full generateText call? Do you force a tool choice?

[Nishchit14]

@lgrammel toolChoice decision is a long custom logic. you mean it would work if toolChoice set auto, right?

[lgrammel]

yes auto should work, forcing tool calls will cause the observed looping

[Nishchit14]

@lgrammel when I set toolChoice to auto and if I ask question with uploaded file (storing in vector db), the model (gpt-4o-mini here) always pretend that the file is not uploaded (means the tool is not being executed here). any clue or best practices on search from files/vectors? thanks for your help.

note: I have tried short and long detailed tool description but the behaviour is same each time.

// user message with file upload
please explain this file

// tool
{
  file_search: {
    execute: [AsyncFunction: execute],
   ...
    description: 'search the knowledge base or files for the answer'
  }
} 

//toolChoise:
auto

// message.parts
{
  role: 'assistant',
  id: 'msgs-pW633i13kqTCOU6N',
  createdAt: 2025-03-13T16:31:01.672Z,
  content: "Please upload the file you'd like me to explain, and I'll take a look at it for you!",
  reasoning: undefined,
  toolInvocations: [],
  parts: [
    {
      type: 'text',
      text: "Please upload the file you'd like me to explain, and I'll take a look at it for you!"
    }
  ]
}

[barenko]

I have the same issue,

when I set the toolChoice to 'auto', sometimes the LLM does not call the tool. So I have to put a mini-llm only to categorize the user solicitation and if it is the subject of my tool, I set toolChoice to != 'auto'.

If I set toolChoice to 'required' or set { type: 'tool', toolName: 'tool_name' }, both loop the maxSteps and return empty string with finishReason=tool-calls.

I'm using gemini-flash, but the problem occurs with gemini-pro too.

Why the 'required' or set toolName triggers indefinitelly until maxSteps? This is feature or bug?

If is feature, how can I force a tool call only one time and have the LLM contextualized answer after it? (the only option that I tough was add a hand-made tool message in the chat history (messages) of the generateText, but it will force me to break the library encapsulation, is not?

[Nishchit14]

@lgrammel any thought on it? I think the clarity on toolChoise would help a lot here .

[Nishchit14]

@barenko I found this multi step stream solution useful in this case. https://sdk.vercel.ai/cookbook/next/stream-text-multistep

[barenko]

@Nishchit14 toolChoice had only 2 behaviors in my tests with only one tool:

• auto: never calls the tool
• required, {type:tool ...}: loop calls until finishReason=tool-calls

I tried to follow the code (but I have some personal limitations here, and several times I felt lost in the tracking).

My solution was to give up and replace the library with the official "@google/generative-ai" (they have native tools support). With this choice I lost some functionalities, but I won a very simple and functional way to handle multi-call tools, with the most important thing being that I had the control again.

I'll test this library in the future, because I think that this is a very promising project.

[Jaikant]

@lgrammel the OpenAI Agents SDK does this:
TLDR - automatically reset tool_choice to "auto" after a tool call

To prevent infinite loops, the framework automatically resets tool_choice to "auto" after a tool call. This behavior is configurable via agent.reset_tool_choice. The infinite loop is because tool results are sent to the LLM, which then generates another tool call because of tool_choice, ad infinitum.

If you want the Agent to completely stop after a tool call (rather than continuing with auto mode), you can set [Agent.tool_use_behavior="stop_on_first_tool"] which will directly use the tool output as the final response without further LLM processing.

https://openai.github.io/openai-agents-python/agents/#forcing-tool-use

[Jaikant]

@Nishchit14 toolChoice had only 2 behaviors in my tests with only one tool:

• auto: never calls the tool
• required, {type:tool ...}: loop calls until finishReason=tool-calls

I tried to follow the code (but I have some personal limitations here, and several times I felt lost in the tracking).

My solution was to give up and replace the library with the official "@google/generative-ai" (they have native tools support). With this choice I lost some functionalities, but I won a very simple and functional way to handle multi-call tools, with the most important thing being that I had the control again.

I'll test this library in the future, because I think that this is a very promising project.

@barenko your issue with the tool not calling in auto mode is because your prompt + instruction were not sufficient to trigger a tool call, this is better explained in detail here

[Nishchit14]

@Jaikant I don't see any value in the blog. It's too much theory. I tried with more than 10 prompts (with large context and enough instruction), and the behaviour is still unpredictable.

do you have any practical system prompts which you're confident that I'd work best with common tools like web_search, knowledgebase, research etc?

[Jaikant]

@Nishchit14 First tune your system prompt to always call the tool. If you are able to do that, then add the ambiguity so that it knows when to call and when not to. In any case, what you observe is the model behaviour, not ai-sdk. The models take the args of "auto" or "required". Hope this documentation helps.