How does an agent loop decide when to stop?
Advertisement
🧩 Scenario
Concept Walkthrough
The loop is a while loop you already know
An agent loop is roughly this:
while (true) {
const step = await callModel(messages, tools);
if (!step.toolCalls.length) break; // model answered in text
const results = await runTools(step.toolCalls);
messages.push(step.message, results);
}
Any while (true) in production needs exit conditions you control. The model is one exit, but not a reliable one.
Natural stops: the model or the setup ends it
The AI SDK documents four reasons a tool loop ends:
- The model stops asking for tools. Its finish reason is something other than
tool-calls, usually because it wrote a final answer. - A tool with no
executeis called. The server cannot run it, so the loop pauses and hands the call to the client (or to a human). - A tool call needs approval. The loop returns an approval request instead of running the tool.
- A stop condition returns true. This is where your guardrails live.
A neat trick uses reason 2 on purpose: give the agent a finalAnswer tool with an input schema and no execute. When the model calls it, you get structured output and the loop ends.
Guardrail stops: you end it
Through stopWhen you can pass one condition or an array. If any returns true, the loop stops.
isStepCount(n): a hard cap on steps, like a max retry count.hasToolCall('name'): stop as soon as a specific tool is called.- A custom function that receives
{ steps }and returns a boolean. Each step hastoolCalls,toolResults,finishReasonandusage, so you can stop on token budget, on repeated calls, or on elapsed time.
Why one limit is not enough
A step cap protects you from infinite loops, but not from a few very expensive steps. A token budget protects cost, but not latency. A "same call twice" check catches the stuck agent early. Production agents usually combine all three, plus an abortSignal so the user can cancel.
The UI side
When a guardrail stops the loop, the last step may be a tool result with no text. Check the final finishReason and steps, and show a helpful partial answer instead of an empty message.
Key Code Explained
import { ToolLoopAgent, isStepCount, hasToolCall, tool, type StopCondition } from 'ai';
import { z } from 'zod';
// Stop when the total tokens across all steps pass a budget
const tokenBudget = (max: number): StopCondition<any> => ({ steps }) =>
steps.reduce((sum, s) => sum + (s.usage.totalTokens ?? 0), 0) > max;
// Stop when the agent repeats the exact same tool call twice in a row
const repeatedCall: StopCondition<any> = ({ steps }) => {
if (steps.length < 2) return false;
const key = (i: number) =>
JSON.stringify(steps[i].toolCalls.map((c) => [c.toolName, c.input]));
return key(steps.length - 1) === key(steps.length - 2);
};
export const supportAgent = new ToolLoopAgent({
model: 'anthropic/claude-sonnet-5.5', // example id
instructions: 'Answer support questions. Call finalAnswer when done.',
tools: {
searchDocs: tool({
description: 'Search the help centre articles.',
inputSchema: z.object({ query: z.string() }),
execute: async ({ query }) => searchHelpCentre(query), // your own function
}),
// No execute: calling this ends the loop with structured output
finalAnswer: tool({
description: 'Give the final answer to the user.',
inputSchema: z.object({ answer: z.string(), sources: z.array(z.string()) }),
}),
},
// Any condition returning true stops the loop
stopWhen: [isStepCount(8), hasToolCall('finalAnswer'), tokenBudget(30_000), repeatedCall],
});
const result = await supportAgent.generate({ prompt: 'How do I reset my password?' });
const last = result.steps.at(-1);
console.log(last?.finishReason, result.steps.length);
Note that finalAnswer is listed in hasToolCall as well. A tool without execute already ends the loop, so the extra condition makes the intent explicit for whoever reads the code next. The numbers here are placeholders: pick yours from real traces.
Tradeoffs
| Stop strategy | Protects against | Weakness |
|---|---|---|
| Model decides (no tool calls) | Nothing, it is the happy path | Can loop or wander |
isStepCount(n) | Infinite loops | Expensive steps still slip through |
hasToolCall / no-execute tool | Unclear endings | Model may never call it |
| Token budget | Runaway cost | Needs usage data from every step |
| Repeated-call check | Stuck agents | Can stop a legitimate retry |
What Interviewers Actually Check
- Whether you know the model's own decision to stop is not enough
- Whether you can name more than one stop mechanism
- Whether you think about cost and latency, not only correctness
- Whether you handle the forced-stop case in the UI
- Whether you would pick limits from data rather than guessing
Follow-Up Questions
- How would you let the user cancel a running agent from the UI?
- Why might the model call the same tool repeatedly, and how would you fix the cause rather than just the symptom?
- How would you change the available tools between steps, for example removing search after three uses?
- What would you log per step to debug a loop that stopped too early?
- How does a step limit interact with streaming responses?
Common Candidate Mistakes
- Answering "the model stops when it is done" and nothing else.
- Setting
isStepCount(100)as a safety net, which still allows very expensive runs. - Forgetting that a capped loop can end on a tool result with no text.
- Not knowing that
generateTextandstreamTextrun only one step by default. - Mixing up a stop condition (ends the loop) with
toolChoice: 'none'(prevents tool calls).
Interview Readiness Checklist
Before you leave this question, make sure you can answer:
- Can you list the natural reasons an AI SDK tool loop ends?
- Can you combine
isStepCount,hasToolCalland a custom condition? - Can you write a token budget stop condition from
steps[].usage? - Can you explain the "finalAnswer tool without execute" pattern?
- Can you describe what the user sees when a guardrail stops the agent?
Summary
An agent loop alternates between calling the model and running the tools it requests. It ends naturally when the model stops asking for tools, when it calls a tool that has no server-side execute, or when a call needs approval. Because the model's judgement is not a guarantee, you add your own exits through stopWhen: a step cap, a stop-on-tool rule, and custom checks like a token budget or repeated-call detection. Combine them, pick limits from real traces, and make sure the UI explains a forced stop instead of showing an empty reply.
What is the default step limit in the AI SDK?
For generateText and streamText the default stop condition is isStepCount(1), so there is no loop unless you set stopWhen. ToolLoopAgent defaults to isStepCount(20). Check the docs for the version you use, because defaults can change between major versions.
Is stopWhen checked after every step?
The AI SDK docs say stopWhen is only evaluated when the last step contains tool results. If the model answers in plain text, the loop ends on its own and your stop conditions are not needed.
What happens to the user when a step limit is hit?
The loop ends with whatever the last step produced, which may be a tool result and no final text. The UI should detect that and show a clear message, for example "I could not finish this, here is what I found so far", instead of an empty bubble.
Advertisement
Stay Updated
Get the latest frontend challenges, interview questions and tutorials delivered to your inbox.
Advertisement