Build a research agent with Vercel AI SDK

Install

npm i ai @ai-sdk/anthropic zod

Already have Vercel AI SDK wired up? TheVercel AI SDK integration pagehas the connection config on its own — this page assumes you have it and gets on with building.

Step by step

1. 1

   Define tools with Zod

   The Zod schema is the tool schema. Describe every parameter — those descriptions are what the model reads when deciding what to pass.

   import { tool } from "ai";
   import { z } from "zod";
   
   const API = "https://api.unlob.com";
   const headers = { "x-api-key": process.env.UNLOB_API_KEY! };
   
   export const webSearch = tool({
     description:
       "Search the web. Returns metadata only — url, title, snippet and " +
       "independent_sources. Never returns page bodies.",
     inputSchema: z.object({
       query: z.string().describe("What to search for"),
       minSources: z
         .number()
         .default(2)
         .describe("Require this many independent sources; use 3 for facts"),
     }),
     execute: async ({ query, minSources }) => {
       const params = new URLSearchParams({
         q: query,
         min_independent_sources: String(minSources),
         limit: "8",
       });
       const res = await fetch(`${API}/search?${params}`, { headers });
       if (!res.ok) return { error: `search failed: ${res.status}` };
       const { results } = await res.json();
       return results;
     },
   });

2. 2

   Let the model loop

   stopWhen with stepCountIs is what turns a single tool call into an agent. Without it the model calls one tool and stops, which is the single most common reason a first attempt "does not work".

   import { anthropic } from "@ai-sdk/anthropic";
   import { generateText, stepCountIs } from "ai";
   import { webSearch, assembleContext } from "./tools";
   
   const { text, steps } = await generateText({
     model: anthropic("claude-opus-5"),
     tools: { webSearch, assembleContext },
     stopWhen: stepCountIs(8), // without this it stops after one tool call
     system:
       "Search before you answer. Prefer claims carried by several independent " +
       "sources, and say so when a claim rests on one. Always cite URLs.",
     prompt: "What changed in the EU AI Act GPAI rules in 2026?",
   });

3. 3

   Stream it into a page

   This is the reason to pick this SDK. Swap generateText for streamText in a route handler and useChat on the client, and the tool calls and answer arrive progressively — including which sources the agent consulted, which is what turns an answer into something a reader can check.

   import { anthropic } from "@ai-sdk/anthropic";
   import { streamText, stepCountIs, convertToModelMessages } from "ai";
   import { webSearch, assembleContext } from "@/lib/tools";
   
   export const maxDuration = 60; // searching takes longer than a plain chat turn
   
   export async function POST(req: Request) {
     const { messages } = await req.json();
   
     const result = streamText({
       model: anthropic("claude-opus-5"),
       messages: convertToModelMessages(messages),
       tools: { webSearch, assembleContext },
       stopWhen: stepCountIs(8),
       system:
         "Search before you answer. Prefer claims carried by several " +
         "independent sources, and say so when a claim rests on one. Cite URLs.",
     });
   
     // sendSources surfaces tool results to the client, so the UI can render
     // the URLs the agent actually consulted rather than just its prose.
     return result.toUIMessageStreamResponse({ sendSources: true });
   }

What happens when it runs

What will go wrong

The failures that cost an afternoon rather than a minute, because they produce something that looks like it is working.

• !

  Without `stopWhen`, the model calls one tool and stops. This is the number one reason a first Vercel AI SDK agent appears broken — it is not looping, and nothing tells you so.

• !

  Return errors from `execute` instead of throwing. A thrown error ends the whole run; a returned `{ error }` lets the model retry or tell the user what went wrong.

• !

  Zod `.describe()` on every field is not optional in practice. It is the parameter documentation the model reads, and omitting it is how you get a whole sentence passed as `minSources`.

• !

  Keep API keys server-side. Tools defined in a route handler are fine; the same tool imported into a client component ships your key to the browser.