📄 ai-sdk/docs/agents/overview

LLMs process input and decide the next action
Tools extend capabilities beyond text generation (reading files, calling APIs, writing to databases)
Loop orchestrates execution through:
- Context management - Maintaining conversation history and deciding what the model sees (input) at each step
- Stopping conditions - Determining when the loop (task) is complete

Agent Class

The Agent class handles these three components. Here's an agent that uses multiple tools in a loop to accomplish a task:

import { Experimental_Agent as Agent, stepCountIs, tool } from 'ai';import { z } from 'zod';
const weatherAgent = new Agent({  model: 'openai/gpt-4o',  tools: {    weather: tool({      description: 'Get the weather in a location (in Fahrenheit)',      inputSchema: z.object({        location: z.string().describe('The location to get the weather for'),      }),      execute: async ({ location }) => ({        location,        temperature: 72 + Math.floor(Math.random() * 21) - 10,      }),    }),    convertFahrenheitToCelsius: tool({      description: 'Convert temperature from Fahrenheit to Celsius',      inputSchema: z.object({        temperature: z.number().describe('Temperature in Fahrenheit'),      }),      execute: async ({ temperature }) => {        const celsius = Math.round((temperature - 32) * (5 / 9));        return { celsius };      },    }),  },  stopWhen: stepCountIs(20),});
const result = await weatherAgent.generate({  prompt: 'What is the weather in San Francisco in celsius?',});
console.log(result.text); // agent's final answerconsole.log(result.steps); // steps taken by the agent

The agent automatically:

Calls the weather tool to get the temperature in Fahrenheit
Calls convertFahrenheitToCelsius to convert it
Generates a final text response with the result

The Agent class handles the loop, context management, and stopping conditions.

Why Use the Agent Class?

The Agent class is the recommended approach for building agents with the AI SDK because it:

Reduces boilerplate - Manages loops and message arrays
Improves reusability - Define once, use throughout your application
Simplifies maintenance - Single place to update agent configuration

For most use cases, start with the Agent class. Use core functions (generateText, streamText) when you need explicit control over each step for complex structured workflows.

Structured Workflows

Agents are flexible and powerful, but non-deterministic. When you need reliable, repeatable outcomes with explicit control flow, use core functions with structured workflow patterns combining:

Conditional statements for explicit branching
Standard functions for reusable logic
Error handling for robustness
Explicit control flow for predictability

Explore workflow patterns to learn more about building structured, reliable systems.

Next Steps

**Building Agents ** - Guide to creating agents with the Agent class
**Workflow Patterns ** - Structured patterns using core functions for complex workflows
**Loop Control ** - Execution control with stopWhen and prepareStep

On this page

Agents

Agent Class

Why Use the Agent Class?

Structured Workflows

Next Steps

Deploy and Scale AI Apps with Vercel.

Vercel delivers the infrastructure and developer experience you need to ship reliable AI-powered applications at scale.

Trusted by industry leaders:

OpenAI
Photoroom

Talk to an expert