AIArticle
Stop chasing agentic magic. Vercel AI SDK 6 formalizes multi-step LLM interactions as structured, observable while loops.
The software industry loves a grand abstraction, and right now, "agent" is the industry's favorite word. It conjures images of autonomous digital entities navigating the web, making executive decisions, and solving complex problems. But if you strip away the marketing gloss and look at the actual execution environment, an agent is something far more mundane. It is a while
loop.
In May 2026, Vercel released AI SDK 6, building on its v3 Language Model Specification. The headline addition is the ToolLoopAgent
class, a first-class TypeScript abstraction designed to manage multi-step tool execution. By introducing this class alongside features like human-in-the-loop approvals, strict schema enforcement, and native OpenTelemetry hooks, the SDK does something important. It stops treating agents as magic and starts treating them as bounded, deterministic systems.
For TypeScript teams building production systems, this release marks a shift from ad-hoc, hand-rolled orchestration loops to a structured, maintainable harness.
The Anatomy of the Loop #
To understand what ToolLoopAgent
actually does, it helps to look at how the SDK handles tools under the hood.
If you pass a tool to a standard generateText
call without any additional configuration, it is a one-shot operation. The model analyzes the prompt, decides to call a tool, and stops. The SDK executes the tool, but the result is never sent back to the model, and the model never gets a second turn to formulate a final answer. The step count is exactly one, and the final text output is empty.
To make it "agentic," you have to tell the SDK to loop. In the underlying architecture, this is controlled by the stopWhen
option. If you set stopWhen: stepCountIs(5)
, the SDK changes its behavior. It calls the model, executes the requested tool, appends the tool's output to the conversation history, and calls the model again. It repeats this cycle until the model produces a final text response or the step limit is reached.
ToolLoopAgent
is a thin wrapper that formalizes this exact cycle. Instead of forcing you to manually manage message arrays and write custom loop logic in every Next.js route handler or background worker, the agent class bundles the model, instructions, and tools into a single reusable object.
Crucially, ToolLoopAgent
ships with a default safety cap of stopWhen: stepCountIs(20)
. In production, you should treat 20 steps as an absolute ceiling, not a starting point. For most customer support, data extraction, or triage workflows, you should explicitly lower this cap to four or eight steps. If an agent cannot solve a problem in five turns, it is likely stuck in an expensive, recursive loop that will drain your API budget without producing a useful result.
Hardening the Tool Boundary #
An agent is only as safe as the tools it is allowed to call. When you expose database queries, email APIs, or payment gateways to a probabilistic planner like a large language model, you are introducing a massive error surface.
AI SDK 6 addresses this by treating tools as strict public contracts. By defining tool inputs with Zod or standard JSON schemas, you establish the first line of defense against malformed inputs and runaway agent behavior.
Here is how to define a bounded, production-ready toolset using the new SDK patterns:
import { ToolLoopAgent, stepCountIs, hasToolCall, tool } from "ai";
import { z } from "zod";
const searchDocs = tool({
description: "Search approved internal documentation for technical details.",
inputSchema: z.object({
query: z.string().min(5).max(120),
limit: z.number().int().min(1).max(5).default(3),
}),
execute: async ({ query, limit }) => {
// Perform deterministic vector search
const results = await databaseVectorSearch({ query, limit });
return {
results: results.map(r => ({ title: r.title, excerpt: r.excerpt }))
};
},
});
const requestRefund = tool({
description: "Initiate a customer refund. Requires human operator approval.",
inputSchema: z.object({
userId: z.string(),
amountInCents: z.number().int().positive(),
reason: z.string().min(10),
}),
needsApproval: true,
execute: async ({ userId, amountInCents, reason }) => {
const transaction = await processRefund(userId, amountInCents, reason);
return { success: true, transactionId: transaction.id };
},
});
Notice the needsApproval: true
flag on the refund tool. This is a crucial addition in AI SDK 6. For actions that mutate state, spend money, or cross tenant boundaries, the SDK provides a native mechanism to execution and await human confirmation. This keeps the loop bounded and prevents autonomous models from making costly mistakes in isolation.
Furthermore, even with strict schemas, models will occasionally generate invalid tool calls. The SDK exposes repair patterns to handle these syntactic failures, but your code must still validate business rules. If a tool execution fails, your code should return a concise, model-readable error message, allowing the agent to attempt a recovery within its remaining step budget.
Type-Safe Context Injection #
In real-world applications, agents cannot run on static system instructions. An agent needs to know who the current user is, what tier they belong to, and what organization context they operate within.
Historically, developers handled this by dynamically constructing the system prompt on every request, or by creating short-lived agent instances inside the request lifecycle. AI SDK 6 introduces callOptionsSchema
and prepareCall
to solve this cleanly at the class level.
export const supportAgent = new ToolLoopAgent({
model: "anthropic/claude-sonnet-4.5",
callOptionsSchema: z.object({
userId: z.string(),
accountTier: z.enum(["free", "pro", "enterprise"]),
}),
prepareCall: ({ options, ...settings }) => ({
...settings,
instructions: `You are a support agent.
- User ID: ${options.userId}
- Account Tier: ${options.accountTier}
- Enterprise users get priority routing. Do not offer refunds to free tier users.`,
}),
tools: { searchDocs, requestRefund },
});
By defining a strict schema for call options, you ensure that whoever invokes the agent must supply the required contextual metadata. This keeps your agent definitions reusable across different entry points (such as API routes, background queues, and CLI tools) while maintaining complete type safety.
The Developer Angle: When to Loop #
Just because ToolLoopAgent
exists does not mean every LLM interaction should use it. Introducing an autonomous loop adds latency, unpredictability, and cost.
When deciding on your architecture, use this simple rule: if you do not need the model to observe the output of a tool and make a subsequent decision, do not use an agent.
| Workload | Recommended Primitive | Rationale |
|---|---|---|
| Classification & Triage | generateText / streamText |
|
| Single-step, deterministic output. No feedback loop required. | ||
| Data Extraction & RAG | generateText with Output.object |
|
| Structured output schemas are cheaper and faster than multi-step reasoning. | ||
| Multi-step Troubleshooting | ToolLoopAgent |
|
| Model must query state, inspect errors, and decide on the next diagnostic step. | ||
| Human-in-the-Loop Workflows | ToolLoopAgent with needsApproval |
|
| Requires pausing execution state to wait for external validation. |
For teams migrating from AI SDK 5, the transition is relatively straightforward. You can run npx @ai-sdk/codemod v6
to handle basic breaking changes. If you are rendering tool calls in a React frontend, the SDK provides createAgentUIStreamResponse
and InferAgentUIMessage
to stream typed tool states directly to the client, allowing you to render custom UI components based on the specific tool being executed.
Building Bounded Systems #
The most successful AI implementations in production are not those that attempt to build fully autonomous, open-ended digital workers. They are the ones that treat LLMs as probabilistic engines wrapped in rigid, deterministic guardrails.
By formalizing the agent as a bounded while
loop, Vercel AI SDK 6 gives developers the tools to build these guardrails. It forces you to define explicit step limits, enforce strict input schemas, inject context type-safely, and insert human approval gates at critical boundaries. The magic isn't in the loop itself; it's in how tightly you control it.
Sources & further reading #
Vercel AI SDK 6: An Agent Is Just a while Loop— dev.to - Vercel AI SDK 6: Production Patterns for Autonomous Loops— dev.to - AI SDK 6 - Vercel— vercel.com - Vercel AI SDK 6: Building Production Agents with ToolLoopAgent and MCP | xplodivity— xplodivity.com
Rachel Goldstein· Dev Tools Editor
Rachel has been embedded in the developer tooling ecosystem for nearly eight years, covering everything from IDE wars and package-manager drama to the quiet rise of AI-assisted coding. She has a soft spot for open-source maintainers and an unhealthy number of terminal emulators installed on a single laptop.
Discussion 0 #
No comments yet
Be the first to weigh in.