How to build AI Agents with Vercel and the AI SDK

AI agents are systems that observe their environment, make decisions, and take actions to achieve goals. You can think of an agent as a loop that interprets inputs using a large language model (LLM), selects a tool, executes it, and then updates its context before the next decision. Vercel provides the infrastructure, tools, and SDKs to build, deploy, and scale these agents.

This guide will walk you through the process of building an agent using the AI SDK. You will learn how to call an LLM, define tools, and create an agent that can perform tasks based on user input.

Before you begin, make sure you have:

• A Vercel account.
• Basic knowledge of TypeScript and Next.js.
• An AI Gateway key created from your dashboard. See step three in the AI Gateway getting started guide.
• The ai and zod packages installed in your project.
• The Vercel CLI installed (optional for deployment from the command line).

The first step in building an agent is to call an LLM. The AI SDK provides an API for generating text using various models. The following example uses OpenAI, but you can also use Anthropic, Google, Mistral, and other providers..

You can use the generateText function to call an LLM and get a response. The function takes a prompt and returns the generated text.

1
import { generateText } from 'ai';
2

3
export async function getWeather({location}: string) {
4
  const { text } = await generateText({
5
    model: 'openai/gpt-5',
6
    prompt: `What is the weather like today in ${location}?`,
7
  });
8

9
  console.log(text);
10
}

This basic example demonstrates a single LLM call, but it can't yet take actions or use tools.

Tools are functions that the model can call to perform specific tasks. An agent can use tools to extend its capabilities and perform actions based on the context of the conversation. For example, a tool could be a function that queries an external API, performs calculations, or triggers an action.

When you provide tools to the model, it can decide to use them based on the user's input. If the model chooses to use a tool, it will return a structured response indicating which tool to call and the necessary arguments, which are inferred from the context:

1
{
2
  "tool": "weather",
3
  "arguments": { "location": "San Francisco" }
4
}

The AI SDK automatically handles:

• Extracting the tool call from the model output
• Validating the arguments against the tool schema
• Executing the function
• Storing both the call and the result in the conversation history

The AI SDK provides a way to define tools using the tool function. This function takes a description, inputSchema (defined with zod), and an execute function that performs the action.

1
import { generateText, tool } from 'ai';
2
import { z } from 'zod';
3

4
export async function getWeather({location}: string) {
5
  const { text } = await generateText({
6
    model: 'openai/gpt-5',
7
    prompt: `What is the weather in ${location}?`,
8
    tools: {
9
      weather: tool({
10
        description: 'Get the weather in a location',
11
        inputSchema: z.object({
12
          location: z.string().describe('The location to get the weather for'),
13
        }),
14
        execute: async ({ location }) => ({
15
          location,
16
          temperature: 72 + Math.floor(Math.random() * 21) - 10,
17
        }),
18
      }),
19
      activities: tool({
20
        description: 'Get the activities in a location',
21
        inputSchema: z.object({
22
          location: z
23
            .string()
24
            .describe('The location to get the activities for'),
25
        }),
26
        execute: async ({ location }) => ({
27
          location,
28
          activities: ['hiking', 'swimming', 'sightseeing'],
29
        }),
30
      }),
31
    },
32
  });
33
  console.log(text);
34
}

In this example, the AI SDK:

• Extracts the tool call from the model output.
• Validates the arguments against the tool schema (defined in the inputSchema).
• Executes the function, and stores both the call and its result in toolCalls and toolResults, which are also added to the message history.

The description field is crucial as it tells the model when and how to use the tool. Write clear, specific descriptions that include:

• What the tool does.
• When it should be used.
• What kind of results it returns.

The more specific your descriptions, the better the model will be at choosing the right tool for the task.

At the moment, your agent only consists of a single call to the LLM and then stops. Because the AI SDK defaults the number of steps used to 1, the model will make a decision based on the user's input to decide:

• If it should directly return a text response.
• If it should call a tool, and if so, which one.

Either way, once the model has completed its generation, that step is complete. To continue generating results, whether that involves using additional tools or responding to the user with the tool's results, you need to trigger another request.

This can be done by configuring a loop using the stopWhen and stepCountIs parameters to specify the maximum number of steps the agent can take before stopping. The AI SDK automatically handles orchestration by appending each response to the conversation history, executing tool calls, and triggering additional generations until either the maximum number of steps is reached or a text response is received.

A typical agent flow looks like this:

1. You (the developer) send a prompt to the LLM.
2. The LLM decides to either generate text or call a tool (returning the tool name and arguments).
3. If a tool is called, the AI SDK executes the tool and receives the result.
4. The AI SDK appends the tool call and result to the conversation history.
5. The AI SDK automatically triggers a new generation based on the updated conversation history.
6. Steps 2-5 repeat until either reaching the maximum number of steps (defined by stopWhen) or receiving a text response without a tool call.
7. The final text response is returned.

1
import { generateText, tool, stepCountIs } from 'ai';
2
import { z } from 'zod';
3

4
export async function getWeather({location}: string) {
5
  const { text } = await generateText({
6
    model: 'openai/gpt-5',
7
    prompt: `What is the weather in ${location}?`,
8
    stopWhen: stepCountIs(5), // Allow up to 5 steps
9
    tools: {
10
      weather: tool({
11
        description: 'Get the weather in a location',
12
        parameters: z.object({
13
          location: z.string().describe('The location to get the weather for'),
14
        }),
15
        execute: async ({ location }) => ({
16
          location,
17
          temperature: 72 + Math.floor(Math.random() * 21) - 10,
18
        }),
19
      }),
20
      activities: tool({
21
        description: 'Get the activities in a location',
22
        parameters: z.object({
23
          location: z
24
            .string()
25
            .describe('The location to get the activities for'),
26
        }),
27
        execute: async ({ location }) => ({
28
          location,
29
          activities: ['hiking', 'swimming', 'sightseeing'],
30
        }),
31
      }),
32
    },
33
  });
34
  console.log(text);
35
}

To deploy your agent on Vercel, create an API route with the following code. The agent will loop through the steps until it reaches a stopping condition, which is when it receives a text response. Once deployed, your API route will be using Fluid compute, which is ideal for AI agents because it:

• Minimizes cold starts for faster response times.
• Allows tasks to run in the background after responding to users.
• Enables considerably longer function durations, perfect for agents that run for extended periods.
• Supports concurrent workloads without the typical timeouts of traditional serverless environments.
• Automatically scales with increased usage.

Depending on your plan, the default maximum duration will be between 60 and 800 seconds. You can also set a custom maximum duration for your agent by using the `maxDuration` variable in your API route. This will allow you to specify how long the agent can run before timing out.

1
import { generateText, tool, stepCountIs } from 'ai';
2
import { z } from 'zod';
3

4
// Set the maximum duration for this function
5
export const maxDuration = 60; // 60 seconds
6

7
export async function POST(request: Request) {
8
  const { prompt }: { prompt?: string } = await request.json();
9

10
  if (!prompt) {
11
    return new Response('Prompt is required', { status: 400 });
12
  }
13

14
  const result = await generateText({
15
    model: 'openai/gpt-5',
16
    prompt,
17
    stopWhen: stepCountIs(5),
18
    tools: {
19
      weather: tool({
20
        description: 'Get the weather in a location',
21
        inputSchema: z.object({
22
          location: z.string().describe('The location to get the weather for'),
23
        }),
24
        execute: async ({ location }) => ({
25
          location,
26
          temperature: 72 + Math.floor(Math.random() * 21) - 10,
27
        }),
28
      }),
29
      activities: tool({
30
        description: 'Get the activities in a location',
31
        inputSchema: z.object({
32
          location: z
33
            .string()
34
            .describe('The location to get the activities for'),
35
        }),
36
        execute: async ({ location }) => ({
37
          location,
38
          activities: ['hiking', 'swimming', 'sightseeing'],
39
        }),
40
      }),
41
    },
42
  });
43

44
  return Response.json({
45
    steps: result.steps,
46
    finalAnswer: result.text,
47
  });
48
}

Depending on your plan, the default maximum duration will be between 300 and 800 seconds. You can set a custom maximum duration for your agent by using the maxDuration variable in your API route. This allows you to specify how long the agent can run before timing out.

Choose a duration based on your agent's complexity:

• Simple agents (1-3 tool calls): 30-60 seconds
• Moderate agents (multiple sequential operations): 60-180 seconds
• Complex agents (extensive reasoning chains): 180-900 seconds

With Fluid compute, you have significantly more time for your agent to complete complex multi-step workflows.

Deply your agent using the Vercel CLI:

1
vercel deploy

Once deployed, you can test your agent using curl:

1
curl -X POST https://your-project.vercel.app/api/agent \
2
  -H "Content-Type: application/json" \
3
  -d '{"prompt":"What is the weather in Tokyo?"}'

The response will include both the steps of the agent and the final answer:

1
{
2
  "steps": [
3
    {
4
      "stepType": "initial",
5
      "toolCalls": [
6
        {
7
          "type": "tool-call",
8
          "toolCallId": "call_7QGq6MRbq0L3lLwpN23OMDKm",
9
          "toolName": "weather",
10
          "args": { "location": "Tokyo" }
11
        }
12
      ],
13
      "toolResults": [
14
        {
15
          "type": "tool-result",
16
          "toolCallId": "call_7QGq6MRbq0L3lLwpN23OMDKm",
17
          "toolName": "weather",
18
          "result": {
19
            "location": "Tokyo",
20
            "temperature": 77,
21
            "condition": "cloudy"
22
          }
23
        }
24
      ]
25
    },
26
    {
27
      "stepType": "tool-result",
28
      "text": "The weather in Tokyo is currently cloudy with a temperature of 77°F."
29
    }
30
  ],
31
  "finalAnswer": "The weather in Tokyo is currently cloudy with a temperature of 77°F."
32
}

Once deployed, you can observe your agent's behavior using the Observability and Logs tabs in the Vercel dashboard.

The Observability tab provides insights into:

• The number of requests over time.
• Response times and latency metrics.
• Error rates and patterns
• Performance trends

If you've added logging to your agent (using console.log, console.error, etc.), you can view the logs in the Logs tab. This is helpful for:

• Debugging tool execution
• Understanding the agent's decision making process
• Tracking token usage
• Identifying errors and edge cases

To learn more about building AI agents, see the following resources:

• AI SDK documentation
• AI SDK examples
• AI SDK cookbook
• Fluid compute documentation