Limit tool-calling loops
Set a hard upper bound on iterative tool execution.
AI Tools · Function
stepCountIs
Creates a stop condition that ends a tool-calling loop when it reaches a specified number of steps. Use it with stopWhen in generateText or streamText.
How it works
stepCountIs creates a stop condition for tool-calling loops. Pass the desired maximum step count, then provide the resulting condition to stopWhen in generateText or streamText; the condition becomes true when that count is reached.
Syntax
stepCountIs(count: number): StopConditionParameters
| Name | Type | Description |
|---|---|---|
count | number | The maximum number of steps to execute before stopping the tool-calling loop. |
Returns
A StopCondition function that returns true when the step count reaches the specified number.
Key points
- The function builds a stopping rule based on the number of executed steps.
- Its numeric argument defines the upper bound for the tool loop.
- The returned callable evaluates to true once the configured count is reached.
- Use the condition with both text-generation APIs that support tool loops.
Common mistakes
- When stopWhen is an array, execution stops as soon as any supplied condition is satisfied.
Example: Stop after three tool-calling steps
import { generateText, stepCountIs } from 'ai';
const result = await generateText({
model: yourModel,
tools: yourTools,
stopWhen: stepCountIs(3),
});Runs generation with tools and stops the tool-calling loop after three steps.
When to use it
Enable multi-step generation
Allow a model to call tools and process their results for a controlled number of rounds.
Compose stop conditions
Pair a step limit with another stopping rule so whichever occurs first ends execution.
Interview questions
QWhat does stepCountIs do?
stepCountIs creates a StopCondition that returns true when execution reaches the specified step count. It is supplied to stopWhen in generateText or streamText.
Follow-up: How would you stop on either a step limit or a tool call? Use an array such as [stepCountIs(10), hasToolCall('finalAnswer')].
QWhat does the count parameter represent?
The count argument is the maximum number of steps allowed before the tool-calling loop stops. For example, stepCountIs(3) permits up to three steps.
Follow-up: What happens with stepCountIs(1)? It limits the loop to one step, which is also the default behavior for agents.
QHow is stepCountIs used with generation APIs?
Pass the condition through stopWhen, for example stopWhen: stepCountIs(5), in a generateText or streamText call. This enables the model to continue after tool results until the condition is met.
Follow-up: How can multiple stopping rules be expressed? Provide an array of conditions; the loop stops when any condition becomes true.
Related
stopWhengenerateTextstreamTexthasToolCallStopCondition