Vercel AI SDK Guide: ToolLoopAgent, Loop Control, and Approval

InYourLeague Research · 2026-08-27

Answer in brief

ToolLoopAgent is Vercel AI SDK’s reusable abstraction for typed, multi-step model-and-tool loops, with completed generation, streaming, configurable stopping, step preparation, and lifecycle callbacks. The official API also exposes toolApproval, but the supplied evidence does not establish complete approval-policy, persistence, or resumption semantics.

Key facts at a glance

Failure modes and verification

FAQ

Is ToolLoopAgent the recommended starting point for an AI SDK agent?

Yes. The official Agents overview recommends it for most agent use cases because it manages loops and message arrays, centralizes configuration, and supports reuse. Core functions are more suitable when explicit workflow control is required.

How are tools typed and scoped?

Define each tool with tool(), an inputSchema, and execute. A tool can use contextSchema for its typed context, and toolsContext supplies each tool only its corresponding scoped values.

What does stopWhen control?

stopWhen defines a termination condition for the multi-step loop. The ToolLoopAgent reference accepts one StopCondition or an array, but the supplied evidence does not specify a default or the array-combination rule.

What is prepareStep verified to support?

prepareStep is a constructor hook, and runtimeContext is available within it. The Agents overview also confirms that runtimeContext can be updated between steps, but the supplied excerpts do not contain the hook’s complete return contract.

When should I use generate() instead of stream()?

Use generate() when the caller needs a completed agent result, including final text and step information demonstrated by the official example. Use stream() when the response should be delivered incrementally.

Which callback contains tool output and execution time?

The onToolExecutionEnd event contains toolOutput and toolExecutionMs, according to the ToolLoopAgent reference. These fields should not be attributed generically to onEnd or onFinish.

What approval behavior is guaranteed by the supplied evidence?

The constructor exposes toolApproval, and the documentation recognizes required user approval as a boundary in agent execution. The excerpts do not establish policy matching, approval persistence, user-interface behavior, resumption semantics, or end-to-end prevention guarantees.

Sources and freshness

• Official source
• Official source
• Last verified: 2026-08-27

Extended guide

Verified scope

The official Agents overview describes an agent as a model using tools in a loop, with context management and stopping conditions controlling what the model sees and when work ends. ToolLoopAgent packages that pattern into a reusable class. Its generate() method can invoke tools across multiple steps and return a completed result; the overview demonstrates result.text and result.steps. The class also provides stream() for streamed responses.

Vercel recommends starting with ToolLoopAgent for most agent use cases because it manages the loop and message arrays, centralizes configuration, and supports reuse. The overview instead recommends core functions such as generateText and streamText when an application needs explicit branching, error handling, or deterministic workflow control.

Configuration map

Practical implementation sequence

1. Construct one ToolLoopAgent with a provider-backed model, stable instructions, and a named tools record. Keep reusable behavior in this definition and request-specific values in call or runtime context.
2. Give every tool a narrow inputSchema and an execute function. When a tool needs credentials or scoped permissions, declare its contextSchema and provide only its corresponding toolsContext values.
3. Add an intentional stopWhen boundary and test it with representative multi-step paths. Do not assume an undocumented default or array-combination rule.
4. Use prepareStep only for behavior supported by its complete API contract. The supplied evidence confirms access to runtimeContext, but not every permitted return value or step mutation.
5. Select generate() or stream() according to the delivery contract. Attach lifecycle callbacks for observation, while distinguishing tool-execution callbacks from the agent-level onEnd and onFinish hooks.
6. Configure toolApproval where an action requires user authorization. Treat policy matching, approval storage, interface behavior, and continuation after approval as application concerns until their contracts are verified separately.

Evidence boundaries

The two supplied official pages establish the configuration surfaces above, but they do not establish approval persistence, resume behavior, end-to-end prevention guarantees, the full streaming result shape, or the complete prepareStep return contract. They also do not publish a selectable model ID for vercel-ai-sdk. The xai/grok-4.6 string is a provider model setting used in an official example, not a model ID belonging to the SDK product.

Model availability note: The official source does not specify a selectable model ID.