24 KiB
Building Agents
The Agent class provides a structured way to encapsulate LLM configuration, tools, and behavior into reusable components. It handles the agent loop for you, allowing the LLM to call tools multiple times in sequence to accomplish complex tasks. Define agents once and use them across your application.
Why Use the ToolLoopAgent Class?
When building AI applications, you often need to:
- Reuse configurations - Same model settings, tools, and prompts across different parts of your application
- Maintain consistency - Ensure the same behavior and capabilities throughout your codebase
- Simplify API routes - Reduce boilerplate in your endpoints
- Type safety - Get full TypeScript support for your agent's tools and outputs
The ToolLoopAgent class provides a single place to define your agent's behavior.
Creating an Agent
Define an agent by instantiating the ToolLoopAgent class with your desired configuration:
import { ToolLoopAgent } from 'ai';
__PROVIDER_IMPORT__;
const myAgent = new ToolLoopAgent({
model: __MODEL__,
instructions: 'You are a helpful assistant.',
tools: {
// Your tools here
},
});
Configuration Options
The Agent class accepts all the same settings as generateText and streamText. Configure:
Model and System Instructions
import { ToolLoopAgent } from 'ai';
__PROVIDER_IMPORT__;
const agent = new ToolLoopAgent({
model: __MODEL__,
instructions: 'You are an expert software engineer.',
});
Tools
Provide tools that the agent can use to accomplish tasks:
import { ToolLoopAgent, tool } from 'ai';
__PROVIDER_IMPORT__;
import { z } from 'zod';
const codeAgent = new ToolLoopAgent({
model: __MODEL__,
tools: {
runCode: tool({
description: 'Execute Python code',
inputSchema: z.object({
code: z.string(),
}),
execute: async ({ code }) => {
// Execute code and return result
return { output: 'Code executed successfully' };
},
}),
},
});
Loop Control
By default, agents run for 20 steps (stopWhen: stepCountIs(20)). In each step, the model either generates text or calls a tool. If it generates text, the agent completes. If it calls a tool, the AI SDK executes that tool.
To let agents call multiple tools in sequence, configure stopWhen to allow more steps. After each tool execution, the agent triggers a new generation where the model can call another tool or generate text:
import { ToolLoopAgent, stepCountIs } from 'ai';
__PROVIDER_IMPORT__;
const agent = new ToolLoopAgent({
model: __MODEL__,
stopWhen: stepCountIs(20), // Allow up to 20 steps
});
Each step represents one generation (which results in either text or a tool call). The loop continues until:
- A finish reasoning other than tool-calls is returned, or
- A tool that is invoked does not have an execute function, or
- A tool call needs approval, or
- A stop condition is met
You can combine multiple conditions:
import { ToolLoopAgent, stepCountIs } from 'ai';
__PROVIDER_IMPORT__;
const agent = new ToolLoopAgent({
model: __MODEL__,
stopWhen: [
stepCountIs(20), // Maximum 20 steps
yourCustomCondition(), // Custom logic for when to stop
],
});
Learn more about loop control and stop conditions.
Tool Choice
Control how the agent uses tools:
import { ToolLoopAgent } from 'ai';
__PROVIDER_IMPORT__;
const agent = new ToolLoopAgent({
model: __MODEL__,
tools: {
// your tools here
},
toolChoice: 'required', // Force tool use
// or toolChoice: 'none' to disable tools
// or toolChoice: 'auto' (default) to let the model decide
});
You can also force the use of a specific tool:
import { ToolLoopAgent } from 'ai';
__PROVIDER_IMPORT__;
const agent = new ToolLoopAgent({
model: __MODEL__,
tools: {
weather: weatherTool,
cityAttractions: attractionsTool,
},
toolChoice: {
type: 'tool',
toolName: 'weather', // Force the weather tool to be used
},
});
Structured Output
Define structured output schemas:
import { ToolLoopAgent, Output, stepCountIs } from 'ai';
__PROVIDER_IMPORT__;
import { z } from 'zod';
const analysisAgent = new ToolLoopAgent({
model: __MODEL__,
output: Output.object({
schema: z.object({
sentiment: z.enum(['positive', 'neutral', 'negative']),
summary: z.string(),
keyPoints: z.array(z.string()),
}),
}),
stopWhen: stepCountIs(10),
});
const { output } = await analysisAgent.generate({
prompt: 'Analyze customer feedback from the last quarter',
});
Define Agent Behavior with System Instructions
System instructions define your agent's behavior, personality, and constraints. They set the context for all interactions and guide how the agent responds to user queries and uses tools.
Basic System Instructions
Set the agent's role and expertise:
const agent = new ToolLoopAgent({
model: __MODEL__,
instructions:
'You are an expert data analyst. You provide clear insights from complex data.',
});
Detailed Behavioral Instructions
Provide specific guidelines for agent behavior:
const codeReviewAgent = new ToolLoopAgent({
model: __MODEL__,
instructions: `You are a senior software engineer conducting code reviews.
Your approach:
- Focus on security vulnerabilities first
- Identify performance bottlenecks
- Suggest improvements for readability and maintainability
- Be constructive and educational in your feedback
- Always explain why something is an issue and how to fix it`,
});
Constrain Agent Behavior
Set boundaries and ensure consistent behavior:
const customerSupportAgent = new ToolLoopAgent({
model: __MODEL__,
instructions: `You are a customer support specialist for an e-commerce platform.
Rules:
- Never make promises about refunds without checking the policy
- Always be empathetic and professional
- If you don't know something, say so and offer to escalate
- Keep responses concise and actionable
- Never share internal company information`,
tools: {
checkOrderStatus,
lookupPolicy,
createTicket,
},
});
Tool Usage Instructions
Guide how the agent should use available tools:
const researchAgent = new ToolLoopAgent({
model: __MODEL__,
instructions: `You are a research assistant with access to search and document tools.
When researching:
1. Always start with a broad search to understand the topic
2. Use document analysis for detailed information
3. Cross-reference multiple sources before drawing conclusions
4. Cite your sources when presenting information
5. If information conflicts, present both viewpoints`,
tools: {
webSearch,
analyzeDocument,
extractQuotes,
},
});
Format and Style Instructions
Control the output format and communication style:
const technicalWriterAgent = new ToolLoopAgent({
model: __MODEL__,
instructions: `You are a technical documentation writer.
Writing style:
- Use clear, simple language
- Avoid jargon unless necessary
- Structure information with headers and bullet points
- Include code examples where relevant
- Write in second person ("you" instead of "the user")
Always format responses in Markdown.`,
});
Using an Agent
Once defined, you can use your agent in three ways:
Generate Text
Use generate() for one-time text generation:
const result = await myAgent.generate({
prompt: 'What is the weather like?',
});
console.log(result.text);
Stream Text
Use stream() for streaming responses:
const stream = myAgent.stream({
prompt: 'Tell me a story',
});
for await (const chunk of stream.textStream) {
console.log(chunk);
}
Respond to UI Messages
Use createAgentUIStreamResponse() to create API responses for client applications:
// In your API route (e.g., app/api/chat/route.ts)
import { createAgentUIStreamResponse } from 'ai';
export async function POST(request: Request) {
const { messages } = await request.json();
return createAgentUIStreamResponse({
agent: myAgent,
messages,
});
}
End-to-end Type Safety
You can infer types for your agent's UIMessages:
import { ToolLoopAgent, InferAgentUIMessage } from 'ai';
const myAgent = new ToolLoopAgent({
// ... configuration
});
// Infer the UIMessage type for UI components or persistence
export type MyAgentUIMessage = InferAgentUIMessage<typeof myAgent>;
Use this type in your client components with useChat:
'use client';
import { useChat } from '@ai-sdk/react';
import type { MyAgentUIMessage } from '@/agent/my-agent';
export function Chat() {
const { messages } = useChat<MyAgentUIMessage>();
// Full type safety for your messages and tools
}
Loop Control
You can control both the execution flow and the settings at each step of the agent loop. The loop continues until:
- A finish reasoning other than tool-calls is returned, or
- A tool that is invoked does not have an execute function, or
- A tool call needs approval, or
- A stop condition is met
The AI SDK provides built-in loop control through two parameters: stopWhen for defining stopping conditions and prepareStep for modifying settings (model, tools, messages, and more) between steps.
Stop Conditions
The stopWhen parameter controls when to stop execution when there are tool results in the last step. By default, agents stop after 20 steps using stepCountIs(20).
When you provide stopWhen, the agent continues executing after tool calls until a stopping condition is met. When the condition is an array, execution stops when any of the conditions are met.
Use Built-in Conditions
The AI SDK provides several built-in stopping conditions:
import { ToolLoopAgent, stepCountIs } from 'ai';
__PROVIDER_IMPORT__;
const agent = new ToolLoopAgent({
model: __MODEL__,
tools: {
// your tools
},
stopWhen: stepCountIs(20), // Default state: stop after 20 steps maximum
});
const result = await agent.generate({
prompt: 'Analyze this dataset and create a summary report',
});
Combine Multiple Conditions
Combine multiple stopping conditions. The loop stops when it meets any condition:
import { ToolLoopAgent, stepCountIs, hasToolCall } from 'ai';
__PROVIDER_IMPORT__;
const agent = new ToolLoopAgent({
model: __MODEL__,
tools: {
// your tools
},
stopWhen: [
stepCountIs(20), // Maximum 20 steps
hasToolCall('someTool'), // Stop after calling 'someTool'
],
});
const result = await agent.generate({
prompt: 'Research and analyze the topic',
});
Create Custom Conditions
Build custom stopping conditions for specific requirements:
import { ToolLoopAgent, StopCondition, ToolSet } from 'ai';
__PROVIDER_IMPORT__;
const tools = {
// your tools
} satisfies ToolSet;
const hasAnswer: StopCondition<typeof tools> = ({ steps }) => {
// Stop when the model generates text containing "ANSWER:"
return steps.some(step => step.text?.includes('ANSWER:')) ?? false;
};
const agent = new ToolLoopAgent({
model: __MODEL__,
tools,
stopWhen: hasAnswer,
});
const result = await agent.generate({
prompt: 'Find the answer and respond with "ANSWER: [your answer]"',
});
Custom conditions receive step information across all steps:
const budgetExceeded: StopCondition<typeof tools> = ({ steps }) => {
const totalUsage = steps.reduce(
(acc, step) => ({
inputTokens: acc.inputTokens + (step.usage?.inputTokens ?? 0),
outputTokens: acc.outputTokens + (step.usage?.outputTokens ?? 0),
}),
{ inputTokens: 0, outputTokens: 0 },
);
const costEstimate =
(totalUsage.inputTokens * 0.01 + totalUsage.outputTokens * 0.03) / 1000;
return costEstimate > 0.5; // Stop if cost exceeds $0.50
};
Prepare Step
The prepareStep callback runs before each step in the loop and defaults to the initial settings if you don't return any changes. Use it to modify settings, manage context, or implement dynamic behavior based on execution history.
Dynamic Model Selection
Switch models based on step requirements:
import { ToolLoopAgent } from 'ai';
__PROVIDER_IMPORT__;
const agent = new ToolLoopAgent({
model: 'openai/gpt-4o-mini', // Default model
tools: {
// your tools
},
prepareStep: async ({ stepNumber, messages }) => {
// Use a stronger model for complex reasoning after initial steps
if (stepNumber > 2 && messages.length > 10) {
return {
model: __MODEL__,
};
}
// Continue with default settings
return {};
},
});
const result = await agent.generate({
prompt: '...',
});
Context Management
Manage growing conversation history in long-running loops:
import { ToolLoopAgent } from 'ai';
__PROVIDER_IMPORT__;
const agent = new ToolLoopAgent({
model: __MODEL__,
tools: {
// your tools
},
prepareStep: async ({ messages }) => {
// Keep only recent messages to stay within context limits
if (messages.length > 20) {
return {
messages: [
messages[0], // Keep system instructions
...messages.slice(-10), // Keep last 10 messages
],
};
}
return {};
},
});
const result = await agent.generate({
prompt: '...',
});
Tool Selection
Control which tools are available at each step:
import { ToolLoopAgent } from 'ai';
__PROVIDER_IMPORT__;
const agent = new ToolLoopAgent({
model: __MODEL__,
tools: {
search: searchTool,
analyze: analyzeTool,
summarize: summarizeTool,
},
prepareStep: async ({ stepNumber, steps }) => {
// Search phase (steps 0-2)
if (stepNumber <= 2) {
return {
activeTools: ['search'],
toolChoice: 'required',
};
}
// Analysis phase (steps 3-5)
if (stepNumber <= 5) {
return {
activeTools: ['analyze'],
};
}
// Summary phase (step 6+)
return {
activeTools: ['summarize'],
toolChoice: 'required',
};
},
});
const result = await agent.generate({
prompt: '...',
});
You can also force a specific tool to be used:
prepareStep: async ({ stepNumber }) => {
if (stepNumber === 0) {
// Force the search tool to be used first
return {
toolChoice: { type: 'tool', toolName: 'search' },
};
}
if (stepNumber === 5) {
// Force the summarize tool after analysis
return {
toolChoice: { type: 'tool', toolName: 'summarize' },
};
}
return {};
};
Message Modification
Transform messages before sending them to the model:
import { ToolLoopAgent } from 'ai';
__PROVIDER_IMPORT__;
const agent = new ToolLoopAgent({
model: __MODEL__,
tools: {
// your tools
},
prepareStep: async ({ messages, stepNumber }) => {
// Summarize tool results to reduce token usage
const processedMessages = messages.map(msg => {
if (msg.role === 'tool' && msg.content.length > 1000) {
return {
...msg,
content: summarizeToolResult(msg.content),
};
}
return msg;
});
return { messages: processedMessages };
},
});
const result = await agent.generate({
prompt: '...',
});
Access Step Information
Both stopWhen and prepareStep receive detailed information about the current execution:
prepareStep: async ({
model, // Current model configuration
stepNumber, // Current step number (0-indexed)
steps, // All previous steps with their results
messages, // Messages to be sent to the model
}) => {
// Access previous tool calls and results
const previousToolCalls = steps.flatMap(step => step.toolCalls);
const previousResults = steps.flatMap(step => step.toolResults);
// Make decisions based on execution history
if (previousToolCalls.some(call => call.toolName === 'dataAnalysis')) {
return {
toolChoice: { type: 'tool', toolName: 'reportGenerator' },
};
}
return {};
},
Manual Loop Control
For scenarios requiring complete control over the agent loop, you can use AI SDK Core functions (generateText and streamText) to implement your own loop management instead of using stopWhen and prepareStep. This approach provides maximum flexibility for complex workflows.
Implementing a Manual Loop
Build your own agent loop when you need full control over execution:
import { generateText, ModelMessage } from 'ai';
__PROVIDER_IMPORT__;
const messages: ModelMessage[] = [{ role: 'user', content: '...' }];
let step = 0;
const maxSteps = 10;
while (step < maxSteps) {
const result = await generateText({
model: __MODEL__,
messages,
tools: {
// your tools here
},
});
messages.push(...result.response.messages);
if (result.text) {
break; // Stop when model generates text
}
step++;
}
This manual approach gives you complete control over:
- Message history management
- Step-by-step decision making
- Custom stopping conditions
- Dynamic tool and model selection
- Error handling and recovery
Learn more about manual agent loops in the cookbook.
Configuring Call Options
Call options allow you to pass type-safe structured inputs to your agent. Use them to dynamically modify any agent setting based on the specific request.
Why Use Call Options?
When you need agent behavior to change based on runtime context:
- Add dynamic context - Inject retrieved documents, user preferences, or session data into prompts
- Select models dynamically - Choose faster or more capable models based on request complexity
- Configure tools per request - Pass user location to search tools or adjust tool behavior
- Customize provider options - Set reasoning effort, temperature, or other provider-specific settings
Without call options, you'd need to create multiple agents or handle configuration logic outside the agent.
How It Works
Define call options in three steps:
- Define the schema - Specify what inputs you accept using
callOptionsSchema - Configure with
prepareCall- Use those inputs to modify agent settings - Pass options at runtime - Provide the options when calling
generate()orstream()
Basic Example
Add user context to your agent's prompt at runtime:
import { ToolLoopAgent } from 'ai';
__PROVIDER_IMPORT__;
import { z } from 'zod';
const supportAgent = new ToolLoopAgent({
model: __MODEL__,
callOptionsSchema: z.object({
userId: z.string(),
accountType: z.enum(['free', 'pro', 'enterprise']),
}),
instructions: 'You are a helpful customer support agent.',
prepareCall: ({ options, ...settings }) => ({
...settings,
instructions:
settings.instructions +
`\nUser context:
- Account type: ${options.accountType}
- User ID: ${options.userId}
Adjust your response based on the user's account level.`,
}),
});
// Call the agent with specific user context
const result = await supportAgent.generate({
prompt: 'How do I upgrade my account?',
options: {
userId: 'user_123',
accountType: 'free',
},
});
The options parameter is now required and type-checked. If you don't provide it or pass incorrect types, TypeScript will error.
Modifying Agent Settings
Use prepareCall to modify any agent setting. Return only the settings you want to change.
Dynamic Model Selection
Choose models based on request characteristics:
import { ToolLoopAgent } from 'ai';
__PROVIDER_IMPORT__;
import { z } from 'zod';
const agent = new ToolLoopAgent({
model: __MODEL__, // Default model
callOptionsSchema: z.object({
complexity: z.enum(['simple', 'complex']),
}),
prepareCall: ({ options, ...settings }) => ({
...settings,
model:
options.complexity === 'simple' ? 'openai/gpt-4o-mini' : 'openai/o1-mini',
}),
});
// Use faster model for simple queries
await agent.generate({
prompt: 'What is 2+2?',
options: { complexity: 'simple' },
});
// Use more capable model for complex reasoning
await agent.generate({
prompt: 'Explain quantum entanglement',
options: { complexity: 'complex' },
});
Dynamic Tool Configuration
Configure tools based on runtime context:
import { openai } from '@ai-sdk/openai';
import { ToolLoopAgent } from 'ai';
__PROVIDER_IMPORT__;
import { z } from 'zod';
const newsAgent = new ToolLoopAgent({
model: __MODEL__,
callOptionsSchema: z.object({
userCity: z.string().optional(),
userRegion: z.string().optional(),
}),
tools: {
web_search: openai.tools.webSearch(),
},
prepareCall: ({ options, ...settings }) => ({
...settings,
tools: {
web_search: openai.tools.webSearch({
searchContextSize: 'low',
userLocation: {
type: 'approximate',
city: options.userCity,
region: options.userRegion,
country: 'US',
},
}),
},
}),
});
await newsAgent.generate({
prompt: 'What are the top local news stories?',
options: {
userCity: 'San Francisco',
userRegion: 'California',
},
});
Provider-Specific Options
Configure provider settings dynamically:
import { openai, OpenAIProviderOptions } from '@ai-sdk/openai';
import { ToolLoopAgent } from 'ai';
import { z } from 'zod';
const agent = new ToolLoopAgent({
model: 'openai/o3',
callOptionsSchema: z.object({
taskDifficulty: z.enum(['low', 'medium', 'high']),
}),
prepareCall: ({ options, ...settings }) => ({
...settings,
providerOptions: {
openai: {
reasoningEffort: options.taskDifficulty,
} satisfies OpenAIProviderOptions,
},
}),
});
await agent.generate({
prompt: 'Analyze this complex scenario...',
options: { taskDifficulty: 'high' },
});
Advanced Patterns
Retrieval Augmented Generation (RAG)
Fetch relevant context and inject it into your prompt:
import { ToolLoopAgent } from 'ai';
__PROVIDER_IMPORT__;
import { z } from 'zod';
const ragAgent = new ToolLoopAgent({
model: __MODEL__,
callOptionsSchema: z.object({
query: z.string(),
}),
prepareCall: async ({ options, ...settings }) => {
// Fetch relevant documents (this can be async)
const documents = await vectorSearch(options.query);
return {
...settings,
instructions: `Answer questions using the following context:
${documents.map(doc => doc.content).join('\n\n')}`,
};
},
});
await ragAgent.generate({
prompt: 'What is our refund policy?',
options: { query: 'refund policy' },
});
The prepareCall function can be async, enabling you to fetch data before configuring the agent.
Combining Multiple Modifications
Modify multiple settings together:
import { ToolLoopAgent } from 'ai';
__PROVIDER_IMPORT__;
import { z } from 'zod';
const agent = new ToolLoopAgent({
model: __MODEL__,
callOptionsSchema: z.object({
userRole: z.enum(['admin', 'user']),
urgency: z.enum(['low', 'high']),
}),
tools: {
readDatabase: readDatabaseTool,
writeDatabase: writeDatabaseTool,
},
prepareCall: ({ options, ...settings }) => ({
...settings,
// Upgrade model for urgent requests
model: options.urgency === 'high' ? __MODEL__ : settings.model,
// Limit tools based on user role
activeTools:
options.userRole === 'admin'
? ['readDatabase', 'writeDatabase']
: ['readDatabase'],
// Adjust instructions
instructions: `You are a ${options.userRole} assistant.
${options.userRole === 'admin' ? 'You have full database access.' : 'You have read-only access.'}`,
}),
});
await agent.generate({
prompt: 'Update the user record',
options: {
userRole: 'admin',
urgency: 'high',
},
});
Using with createAgentUIStreamResponse
Pass call options through API routes to your agent:
import { createAgentUIStreamResponse } from 'ai';
import { myAgent } from '@/ai/agents/my-agent';
export async function POST(request: Request) {
const { messages, userId, accountType } = await request.json();
return createAgentUIStreamResponse({
agent: myAgent,
messages,
options: {
userId,
accountType,
},
});
}
Next Steps
- Learn about loop control for execution management
- Explore workflow patterns for complex multi-step processes