Custom tools - Next.js AI Chatbot

Tools give the model the ability to take actions during a conversation — fetching data, creating documents, and more. Each tool is defined using the tool() helper from the Vercel AI SDK and registered in the chat route.

Tool structure

Every tool has three fields:

Field	Purpose
`description`	Natural language description the model uses to decide when to call the tool
`parameters`	A Zod schema that defines and validates the tool’s input arguments
`execute`	Async function that receives the validated parameters and returns a result

Simple tool example: getWeather

lib/ai/tools/get-weather.ts is the simplest tool in the codebase. It fetches weather data from a public API and returns the JSON result directly to the model.

lib/ai/tools/get-weather.ts

import { tool } from 'ai';
import { z } from 'zod';

export const getWeather = tool({
  description: 'Get the current weather at a location',
  parameters: z.object({
    latitude: z.number(),
    longitude: z.number(),
  }),
  execute: async ({ latitude, longitude }) => {
    const response = await fetch(
      `https://api.open-meteo.com/v1/forecast?latitude=${latitude}&longitude=${longitude}&current=temperature_2m&hourly=temperature_2m&daily=sunrise,sunset&timezone=auto`,
    );

    const weatherData = await response.json();
    return weatherData;
  },
});

The return value from execute is serialized and sent back to the model as the tool result. The model can then use that data to compose its response.

Adding a custom tool

Create the tool file

Create a new file under lib/ai/tools/. Use get-weather.ts as a starting point.

lib/ai/tools/get-stock-price.ts

import { tool } from 'ai';
import { z } from 'zod';

export const getStockPrice = tool({
  description: 'Get the current stock price for a given ticker symbol',
  parameters: z.object({
    ticker: z.string().describe('The stock ticker symbol, e.g. AAPL'),
  }),
  execute: async ({ ticker }) => {
    const response = await fetch(
      `https://your-stock-api.example.com/quote/${ticker}`,
    );
    return response.json();
  },
});

Use .describe() on Zod fields to give the model more context about each parameter. The model reads these descriptions when deciding what values to pass.

Import the tool in the chat route

Open app/(chat)/api/chat/route.ts and import your tool at the top of the file alongside the existing tool imports:

app/(chat)/api/chat/route.ts

import { getWeather } from '@/lib/ai/tools/get-weather';
import { getStockPrice } from '@/lib/ai/tools/get-stock-price';

Add your tool to the tools object passed to streamText:

app/(chat)/api/chat/route.ts

tools: {
  getWeather,
  getStockPrice,
  createDocument: createDocument({ session, dataStream }),
  updateDocument: updateDocument({ session, dataStream }),
  requestSuggestions: requestSuggestions({ session, dataStream }),
},

Add the tool to experimental_activeTools

The experimental_activeTools array controls which tools are offered to the model on each request. Add your tool’s key to the array:

app/(chat)/api/chat/route.ts

experimental_activeTools:
  selectedChatModel === 'chat-model-reasoning'
    ? []
    : [
        'getWeather',
        'getStockPrice',
        'createDocument',
        'updateDocument',
        'requestSuggestions',
      ],

Tools are disabled entirely for the reasoning model (chat-model-reasoning) because it does not support tool calling.

Streaming tools vs. simple tools

Not all tools work the same way. The codebase has two distinct patterns.

Simple tools
Streaming tools

Simple tools like getWeather call tool() directly and return a plain value. The execute function has no side effects beyond the API call.

export const getWeather = tool({
  description: 'Get the current weather at a location',
  parameters: z.object({
    latitude: z.number(),
    longitude: z.number(),
  }),
  execute: async ({ latitude, longitude }) => {
    const response = await fetch(/* ... */);
    return response.json();
  },
});

Tools that create or update artifacts receive a dataStream and session via a factory function. They write structured data events to dataStream as content is generated, which the client picks up in real time.

lib/ai/tools/create-document.ts

import { generateUUID } from '@/lib/utils';
import { DataStreamWriter, tool } from 'ai';
import { z } from 'zod';
import { Session } from 'next-auth';
import {
  artifactKinds,
  documentHandlersByArtifactKind,
} from '@/lib/artifacts/server';

interface CreateDocumentProps {
  session: Session;
  dataStream: DataStreamWriter;
}

export const createDocument = ({ session, dataStream }: CreateDocumentProps) =>
  tool({
    description:
      'Create a document for a writing or content creation activities. This tool will call other functions that will generate the contents of the document based on the title and kind.',
    parameters: z.object({
      title: z.string(),
      kind: z.enum(artifactKinds),
    }),
    execute: async ({ title, kind }) => {
      const id = generateUUID();

      dataStream.writeData({ type: 'kind', content: kind });
      dataStream.writeData({ type: 'id', content: id });
      dataStream.writeData({ type: 'title', content: title });
      dataStream.writeData({ type: 'clear', content: '' });

      const documentHandler = documentHandlersByArtifactKind.find(
        (h) => h.kind === kind,
      );

      if (!documentHandler) {
        throw new Error(`No document handler found for kind: ${kind}`);
      }

      await documentHandler.onCreateDocument({ id, title, dataStream, session });

      dataStream.writeData({ type: 'finish', content: '' });

      return {
        id,
        title,
        kind,
        content: 'A document was created and is now visible to the user.',
      };
    },
  });

In the chat route, streaming tools are instantiated with the dataStream provided by createDataStreamResponse:

app/(chat)/api/chat/route.ts

tools: {
  getWeather,
  createDocument: createDocument({ session, dataStream }),
  updateDocument: updateDocument({ session, dataStream }),
  requestSuggestions: requestSuggestions({ session, dataStream }),
},

Data stream event types

When a tool writes to dataStream, the client-side artifact components listen for specific event type values in their onStreamPart handler. The built-in event types are:

Type	Emitted by	Description
`kind`	`createDocument`	Artifact type being created
`id`	`createDocument`	New document ID
`title`	`createDocument`	Document title
`clear`	`createDocument`, `updateDocument`	Signals the client to clear the artifact panel
`text-delta`	`textDocumentHandler`	Incremental text content chunk
`code-delta`	`codeDocumentHandler`	Incremental code content chunk
`suggestion`	`requestSuggestions`	A single inline suggestion object
`finish`	`createDocument`, `updateDocument`	Signals streaming is complete

If you write a tool that streams custom UI data, define a new type string and handle it in the artifact client’s onStreamPart callback.

​Tool structure

​Simple tool example: getWeather

​Adding a custom tool

​Streaming tools vs. simple tools

​Data stream event types

Tool structure

Simple tool example: getWeather

Adding a custom tool

Streaming tools vs. simple tools

Data stream event types