new·The score now tells you which way it movedA brain's exam only ever grows: its own material writes questions, and so does every question a real caller asked and did not get answered. The score is a percentage over that growing set, so a brain that learned more could post a smaller number — and this week three did. One of them answered two MORE questions than the week before and showed eighteen points less. Printed as a single percentage, that reads as decline to a reader and as punishment to anyone who contributes material.all news →
mozg.beta
Sign in

AI SDK · Core · all subjects

agents

279 notes in this subject, read out of this brain and free to use. This is page 4 of 5.

Agent interface definition requirement

Agents should define their `tools` property, even if empty ({}), for compatibility with SDK utilities.

Using ToolLoopAgent with createAgentUIStream

import { ToolLoopAgent, createAgentUIStream } from "ai"; const agent = new ToolLoopAgent({ ... }); const stream = await createAgentUIStream({ agent, messages: [{ role: "user", content: "What is the weather in NYC?" }] }); for await (const chunk of stream) { console.log(chunk); } This example shows how to create a ToolLoopAgent, pass it to createAgentUIStream, and iterate over the resulting stream.

Agent CALL_OPTIONS generic parameter extensibility

The CALL_OPTIONS generic parameter allows agents to accept additional call-specific options when needed.

AgentCallParameters experimental_sandbox

AgentCallParameters has an optional `experimental_sandbox` field of type Experimental_SandboxSession. This experimental sandbox environment is passed through to tool execution.

ToolExecutionStartEvent callback event structure

The onToolExecutionStart callback receives a ToolExecutionStartEvent with the following properties: callId (string) - unique identifier for the generation call, used to correlate events; toolCall (TypedToolCall<TOOLS>) - the full tool call object containing toolName, toolCallId, input, and metadata; messages (Array<ModelMessage>) - messages that were sent to the language model to initiate the response that contained the tool call (does not include the system prompt nor the assistant response that contained the tool call); toolContext (InferToolContext<TOOLS[toolName]>) - tool-specific context object for the tool call that is about to execute (narrowed to the context type of the individual tool, not the entire tool set).

ToolLoopAgent constructor parameters - stopSequences

stopSequences (type: string[], optional) - Custom token sequences which stop the model output. Passed through to the model.

ToolLoopAgent constructor parameters - seed

seed (type: number, optional) - Seed for deterministic generation (if supported).

ToolLoopAgent constructor parameters - maxRetries

maxRetries (type: number, optional) - How many times to retry on failure. Default: 2.

ToolLoopAgent constructor parameters - providerOptions

providerOptions (type: ProviderOptions, optional) - Additional provider-specific configuration.

ToolLoopAgent constructor parameters - headers

headers (type: Record<string, string | undefined>, optional) - Additional HTTP headers to be sent with the request. Only applicable for HTTP-based providers.

ToolLoopAgent constructor parameters - callOptionsSchema

callOptionsSchema (type: FlexibleSchema<CALL_OPTIONS>, optional) - Optional schema for custom call options that can be passed when calling generate() or stream().

ToolLoopAgent constructor parameters - prepareCall

prepareCall (type: PrepareCallFunction, optional) - Optional function to prepare call-specific settings based on the call options.

ToolLoopAgent constructor parameters - id

id (type: string, optional) - Custom agent identifier.

ToolLoopAgent properties

ToolLoopAgent has two read-only properties: tools (type: Record<string, Tool>) - the tool set configured for this agent; id (type: string | undefined) - the agent identifier, if one was provided in the constructor.

ToolLoopAgent purpose and use case

ToolLoopAgent creates a reusable AI agent capable of generating text, streaming responses, and using tools over multiple steps in a reasoning-and-acting loop. It is ideal for building autonomous, multi-step agents that can take actions, call tools, and reason over the results until a stop condition is reached. Unlike single-step calls like generateText(), an agent can iteratively invoke tools, collect tool results, and decide next actions until completion or user approval is required.

ToolLoopAgent constructor parameters - required

The ToolLoopAgent constructor has one required parameter: model (type: LanguageModel) - the language model instance to use (e.g., from a provider).

ToolLoopAgent constructor parameters - instructions

instructions (type: Instructions, optional) - Instructions for the agent, usually used for system prompt/context.

ToolLoopAgent constructor parameters - allowSystemInMessages

allowSystemInMessages (type: boolean, optional) - Whether role: 'system' messages are allowed in the prompt or messages fields. When unset, system messages are rejected because they can create a prompt injection attack risk. Ideally, use the instructions option instead. Set to true to allow system messages, or false to explicitly reject them.

ToolLoopAgent constructor parameters - tools

tools (type: Record<string, Tool>, optional) - A set of tools the agent can call. Keys are tool names. Tools require the underlying model to support tool calling.

ToolLoopAgent constructor parameters - toolChoice

toolChoice (type: ToolChoice, optional) - Tool call selection strategy. Options: 'auto' | 'none' | 'required' | { type: 'tool', toolName: string }. Default: 'auto'.

ToolLoopAgent constructor parameters - stopWhen

stopWhen (type: StopCondition | StopCondition[], optional) - Condition(s) for ending the agent loop. Default: isStepCount(20). Use isLoopFinished() to let the agent run until all tool calls have completed, but beware of potential runaway loops.

ToolLoopAgent constructor parameters - activeTools

activeTools (type: ActiveTools<TOOLS>, optional) - Limits the tools that are available for the model to call without changing the tool call and result types in the result. All tools are active by default. Tool names are restricted to the string keys of the tool set.

ToolLoopAgent constructor parameters - toolOrder

toolOrder (type: ToolOrder<TOOLS>, optional) - Controls the order in which tools are sent to the provider. The list can be partial. Tools not listed in toolOrder are sent after the listed tools, sorted alphabetically. Tool names are restricted to the string keys of the tool set.

ToolLoopAgent constructor parameters - toolApproval

toolApproval (type: ToolApprovalConfiguration<TOOLS, RUNTIME_CONTEXT>, optional) - Approval configuration for the agent. Pass a GenericToolApprovalFunction to handle all tool calls in one callback with toolCall, tools, toolsContext, messages, and runtimeContext, or pass a per-tool object where each key can be a status ('not-applicable', 'approved', 'denied', or 'user-approval'), an object form such as { type: 'denied', reason: 'blocked by policy' }, or a SingleToolApprovalFunction that receives the tool input and options toolCallId, messages, toolContext, and runtimeContext. The RUNTIME_CONTEXT type parameter matches the agent's runtimeContext. A GenericToolApprovalFunction or SingleToolApprovalFunction may return undefined for the same effect as 'not-applicable'. 'not-applicable' is the default execution path and runs the tool without approval metadata. Use 'approved', 'denied', or their object forms when you want explicit automatic approval request/response parts in the output. Automatic approvals and denials can include a reason, which is forwarded to the emitted approval response. This setting takes precedence over a tool's needsApproval default.

ToolLoopAgent constructor parameters - experimental_toolCallers

experimental_toolCallers (type: Experimental_ToolCallers<TOOLS>, optional) - Configures which caller tools may invoke each tool. Pass an object keyed by callee tool name whose values list caller-capable tool names. Include DIRECT_TOOL_CALL from @ai-sdk/code-mode to keep a configured tool directly callable by the model. Local-only callees are hidden from direct model calls and bound to their local caller for each agent step. Provider caller names are translated to provider-native allowed-caller options.

ToolLoopAgent constructor parameters - output

output (type: Output, optional) - Optional structured output specification, for parsing responses into typesafe data.

ToolLoopAgent constructor parameters - prepareStep

prepareStep (type: PrepareStepFunction, optional) - Optional function to mutate step settings or inject state for each agent step, including per-step model call settings such as temperature, maxOutputTokens, sampling controls, penalties, stop sequences, seed, and reasoning. Model call setting overrides apply only to the current step.

ToolLoopAgent constructor parameters - include

include (type: { requestBody?: boolean; requestMessages?: boolean; responseBody?: boolean; rawChunks?: boolean }, optional) - Settings for controlling what data is included in step results. requestBody, requestMessages, and responseBody apply to generate(); requestBody, requestMessages, and rawChunks apply to stream().

ToolLoopAgent constructor parameters - repairToolCall

repairToolCall (type: ToolCallRepairFunction, optional) - Optional callback to attempt automatic recovery when a tool call cannot be parsed.

ToolLoopAgent constructor parameters - experimental_refineToolInput

experimental_refineToolInput (type: ToolInputRefinement<TOOLS>, optional) - Optional mapping of tool names to functions that refine parsed tool inputs. Each function receives the typed input for its tool and must return the same input type shape. The refined input is used for tool execution, output parts, lifecycle callbacks, and telemetry in both generate() and stream().

ToolLoopAgent constructor parameters - onStepStart callback

onStepStart (type: GenerateTextOnStepStartCallback, optional) - Callback that is called when a step (LLM call) begins, before the provider is called. Each step represents a single LLM invocation. If also specified in generate() or stream(), both callbacks are called (constructor first).

ToolLoopAgent constructor parameters - onToolExecutionStart callback

onToolExecutionStart (type: OnToolExecutionStartCallback, optional) - Callback that is called right before a tool's execute function runs. If also specified in generate() or stream(), both callbacks are called (constructor first).

ToolLoopAgent constructor parameters - onToolExecutionEnd callback

onToolExecutionEnd (type: OnToolExecutionEndCallback, optional) - Callback that is called right after a tool's execute function completes (or errors). The toolOutput field is a discriminated union: when toolOutput.type is 'tool-result', the output field contains the tool result; when toolOutput.type is 'tool-error', the error field contains the error. If also specified in generate() or stream(), both callbacks are called (constructor first).

ToolLoopAgent constructor parameters - onEnd callback

onEnd (type: GenerateTextOnEndCallback, optional) - Callback that is called when all agent steps are finished and the response is complete. Receives step results, total usage, shared runtimeContext, and toolsContext. If also specified in generate() or stream(), both callbacks are called (constructor first).

ToolLoopAgent constructor parameters - onFinish callback

onFinish (type: GenerateTextOnEndCallback, optional) - Deprecated alias for onEnd.

ToolLoopAgent constructor parameters - runtimeContext

runtimeContext (type: CONTEXT, optional) - User-defined shared runtime context object passed to prepareStep and lifecycle callbacks.

ToolLoopAgent constructor parameters - toolsContext

toolsContext (type: InferToolSetContext<TOOLS>) - Per-tool context map keyed by tool name. Required when at least one tool defines contextSchema; not accepted when no tools need context.

ToolLoopAgent constructor parameters - telemetry

telemetry (type: TelemetryOptions, optional) - Optional telemetry configuration. Supports includeRuntimeContext for specifying top-level runtime context properties that should be included in telemetry (default excluded unless explicitly set to true), and includeToolsContext for specifying top-level tool context properties per tool (default excluded unless explicitly set to true). Runtime context properties and tool context properties are excluded from telemetry unless explicitly enabled, though lifecycle callbacks and returned results still receive the full runtimeContext and toolsContext.

ToolLoopAgent constructor parameters - experimental_download

experimental_download (type: DownloadFunction | undefined, optional) - Experimental: Custom download function for fetching files/URLs for tool or model use. By default, files are downloaded if the model does not support the URL for a given media type.

ToolLoopAgent constructor parameters - maxOutputTokens

maxOutputTokens (type: number, optional) - Maximum number of tokens the model is allowed to generate.

ToolLoopAgent constructor parameters - temperature

temperature (type: number, optional) - Sampling temperature, controls randomness. Passed through to the model.

ToolLoopAgent.generate() method

The generate() method generates a response and triggers tool calls as needed, running the agent loop and returning the final result. It returns a promise resolving to a GenerateTextResult.

ToolLoopAgent.stream() method

The stream() method streams a response from the agent, including agent reasoning and tool calls, as they occur. It returns a StreamTextResult.

InferAgentUIMessage type utility

InferAgentUIMessage is a type utility that infers the UI message type for a given agent instance. It is useful for type-safe UI and message exchanges. It can be called with a single type argument (the agent instance) or with two type arguments, where the second provides a type for message metadata.

ToolLoopAgent basic example with tools

import { ToolLoopAgent, isStepCount } from 'ai'; import { weatherTool, calculatorTool } from './tools'; const assistant = new ToolLoopAgent({ model: __MODEL__, instructions: 'You are a helpful assistant.', tools: { weather: weatherTool, calculator: calculatorTool, }, stopWhen: isStepCount(3), }); const result = await assistant.generate({ prompt: 'What is the weather in NYC and what is 100 * 25?', }); console.log(result.text); console.log(result.steps); // Array of all steps taken by the agent This example demonstrates creating a basic ToolLoopAgent with two tools (weather and calculator), configuring it to stop after 3 steps, and calling generate() to get a result with the agent's text response and all steps taken.

ToolLoopAgent streaming example

const agent = new ToolLoopAgent({ model: __MODEL__, instructions: 'You are a creative storyteller.', }); const stream = agent.stream({ prompt: 'Tell me a short story about a time traveler.', }); for await (const chunk of stream.textStream) { process.stdout.write(chunk); } This example demonstrates streaming a response from an agent that generates a creative story, reading text chunks as they arrive from the stream.

ToolLoopAgent output parsing example

import { z } from 'zod'; const analysisAgent = new ToolLoopAgent({ model: __MODEL__, output: { schema: z.object({ sentiment: z.enum(['positive', 'negative', 'neutral']), score: z.number(), summary: z.string(), }), }, }); const result = await analysisAgent.generate({ prompt: 'Analyze this review: "The product exceeded my expectations!"', }); console.log(result.output); // Typed as { sentiment: 'positive' | 'negative' | 'neutral', score: number, summary: string } This example demonstrates creating a ToolLoopAgent with structured output parsing using Zod schema, then generating a response that is automatically parsed into the specified schema.

ToolLoopAgent tool approval example

import { ToolLoopAgent, ModelMessage, ToolApprovalResponse, tool } from 'ai'; import { z } from 'zod'; const agent = new ToolLoopAgent({ model: __MODEL__, instructions: 'You are an agent with access to a weather API.', tools: { weather: tool({ description: 'Get the weather in a location', inputSchema: z.object({ location: z.string(), }), execute: async ({ location }) => ({ location, temperature: 72, }), }), }, toolApproval: { weather: 'user-approval', }, }); const messages: ModelMessage[] = [ { role: 'user', content: 'Is it raining in Paris today?' }, ]; const result = await agent.generate({ messages }); const approvals: ToolApprovalResponse[] = []; for (const part of result.content) { if (part.type === 'tool-approval-request') { approvals.push({ type: 'tool-approval-response', approvalId: part.approvalId, approved: true, }); } } messages.push(...result.responseMessages); messages.push({ role: 'tool', content: approvals }); const approvedResult = await agent.generate({ messages }); console.log(approvedResult.text); This example demonstrates creating a ToolLoopAgent with tool approval enabled, where tool execution requires user approval. The agent generates a response, extracts approval requests, sends approvals back, and continues execution.

ToolLoopAgent runtimeContext note

For agents, runtimeContext is the shared runtime state that flows through the loop. Refer to the Runtime and Tool Context documentation for guidance on runtimeContext, toolsContext, tool context, and sensitive context filtering.

ToolLoopAgent experimental_sandbox note

Pass experimental_sandbox to generate() or stream() when tools need access to a command or code execution environment.

ToolExecutionEndEvent callback event structure

The onToolExecutionEnd callback receives a ToolExecutionEndEvent with the following properties: callId (string) - unique identifier for the generation call; toolCall (TypedToolCall<TOOLS>) - the full tool call object; toolExecutionMs (number) - the wall-clock duration of the tool execution in milliseconds; messages (Array<ModelMessage>) - messages sent to the language model to initiate the response that contained the tool call; toolContext (InferToolContext<TOOLS[toolName]>) - tool-specific context object for the tool call that just completed (narrowed to the individual tool context type); toolOutput (ToolOutput<TOOLS>) - discriminated union representing the tool execution result where type 'tool-result' has an output field with the tool's return value, and type 'tool-error' has an error field containing the error.

ToolLoopAgent constructor parameters - frequencyPenalty

frequencyPenalty (type: number, optional) - Frequency penalty parameter. Passed through to the model.

ToolLoopAgent constructor parameters - presencePenalty

presencePenalty (type: number, optional) - Presence penalty parameter. Passed through to the model.

ToolLoopAgent constructor parameters - topK

topK (type: number, optional) - Top-k sampling parameter. Passed through to the model.

ToolLoopAgent constructor parameters - topP

topP (type: number, optional) - Top-p (nucleus) sampling parameter. Passed through to the model.

ToolLoopAgent class import

Import ToolLoopAgent from the 'ai' package using: import { ToolLoopAgent } from 'ai';

WorkflowAgent class

WorkflowAgent is a class that creates durable AI agents with tool calling, streaming, and workflow integration capabilities.

WorkflowAgent runtimeContext and toolsContext serialization requirement

WorkflowAgent supports runtimeContext for shared agent state and toolsContext for per-tool context. Because these values can cross workflow and step boundaries, they must be serializable durable data. Do not place functions, class instances, symbols, database clients, or SDK clients in context; pass identifiers or configuration and recreate non-serializable resources inside step functions.

WorkflowAgent constructor parameters

WorkflowAgent constructor accepts: id (string, optional), model (LanguageModel, required - string compatible with Vercel AI Gateway or provider instance), instructions (Instructions, optional, used as system prompt), tools (Record<string, Tool>, optional, keys are tool names), toolChoice (ToolChoice, optional, default 'auto', options: 'auto' | 'none' | 'required' | { type: 'tool', toolName: string }), stopWhen (StopCondition | StopCondition[], optional, default stop condition for agent loop), activeTools (ActiveTools<TTools>, optional, default set of active tools), output (OutputSpecification, optional, default structured output specification), repairToolCall (ToolCallRepairFunction, optional, default function to repair failed tool calls), experimental_download (DownloadFunction, optional, default custom download function), experimental_sandbox (Experimental_SandboxSession, optional, default sandbox session), prepareStep (PrepareStepCallback, optional, called before each step), prepareCall (PrepareCallCallback, optional, called once before agent loop starts), runtimeContext (Context, optional, default shared runtime context, must be serializable), toolsContext (InferToolSetContext<TTools>, optional, default per-tool context map, must be serializable), telemetry (TelemetryOptions, optional, telemetry configuration), experimental_onStart (WorkflowAgentOnStartCallback, optional, called when agent starts streaming), experimental_onStepStart (WorkflowAgentOnStepStartCallback, optional, called before each step begins), onToolExecutionStart (WorkflowAgentonToolExecutionStartCallback, optional, called right before tool execute function runs), onToolExecutionEnd (WorkflowAgentonToolExecutionEndCallback, optional, called right after tool execute function completes or errors), onStepEnd (WorkflowAgentOnStepEndCallback, optional, called after each agent step completes), onStepFinish (WorkflowAgentOnStepFinishCallback, optional, deprecated - use onStepEnd instead), onEnd (WorkflowAgentOnEndCallback, optional, called when all agent steps finished), maxOutputTokens (number, optional), temperature (number, optional), topP (number, optional), topK (number, optional), presencePenalty (number, optional), frequencyPenalty (number, optional), stopSequences (string[], optional), seed (number, optional), maxRetries (number, optional, default 2), headers (Record<string, string | undefined>, optional, for HTTP-based providers), providerOptions (ProviderOptions, optional, provider-specific configuration).

WorkflowAgent properties

WorkflowAgent has two read-only properties: id (string | undefined, used for telemetry identification) and tools (Record<string, Tool>, the tool set configured for this agent).

Give your agent this brain