Vercel AI SDK

For both Vercel integration options, including Vercel Connect, see the Vercel guide.

@search1api/ai-sdk exposes Search1API as ordinary AI SDK tools. Use it with generateText, streamText, or an agent and your preferred model provider. The package uses the official TypeScript SDK for API calls.

Install and configure

npm install @search1api/ai-sdk ai zod

Create a key in the dashboard, then set it in the server's environment:

export SEARCH1API_API_KEY="your-api-key"

The compatibility alias SEARCH1API_KEY is also accepted. An explicit apiKey takes precedence. Keep the key in server code.

AI SDK 5, 6, and 7 are supported with Zod 3.25.76+ or 4.1.8+. Use a Node.js version supported by your AI SDK release; AI SDK 7 requires Node.js 22+.

Search, read, and answer

This example uses Vercel AI Gateway, which needs its own AI_GATEWAY_API_KEY. You can replace the model with any compatible AI SDK provider.

import { gateway, generateText, stepCountIs } from 'ai';
import { search1apiTools } from '@search1api/ai-sdk';

const result = await generateText({
  model: gateway('openai/gpt-5-mini'),
  tools: search1apiTools({ only: ['search', 'crawl'] }),
  stopWhen: stepCountIs(5),
  prompt: 'Find the official AI SDK tool calling docs, read them, and explain how tools work. Cite the URLs you used.',
});

console.log(result.text);

stopWhen lets the model use search results, read a page, and then answer in the same call. The tool set contains:

Each tool returns the SDK's typed response. Source URLs and optional metadata are preserved. Empty results stay empty. Ask the model to cite the returned links; the tools do not emit AI SDK source events automatically.

Configure individual tools

import { search1apiSearch, search1apiNews, search1apiCrawl } from '@search1api/ai-sdk';

const tools = {
  webSearch: search1apiSearch({
    search: { maxResults: 5, includeSites: ['ai-sdk.dev'], timeRange: 'month' },
  }),
  recentNews: search1apiNews({ news: { maxResults: 3, timeRange: 'day' } }),
  readPage: search1apiCrawl({ crawl: { enableFallback: true } }),
};

The application controls settings such as result count, engine, domains, and language. The model supplies only the query or URL. Tool sets accept the same settings under search, news, and crawl.

Search and news default to five results and crawlResults: 0. To include page content in a search response, explicitly set search.crawlResults or news.crawlResults. Each successfully retrieved page is billed separately; see credits and limits.

Client settings and cancellation

Factories and tool sets accept the SDK's apiKey, baseUrl, fetch, headers, timeoutMs, maxRetries, and retryDelayMs settings. You can also inject an existing client:

import { Search1API } from '@search1api/client';

const client = new Search1API({ apiKey: 'your-api-key', timeoutMs: 15_000 });
const tools = search1apiTools({ client });

When client is supplied, other client settings are ignored. Otherwise the tools construct their client on first execution, so module-level tool definitions do not require credentials during a Next.js build.

Pass an abortSignal to generateText or streamText to cancel tool requests. SDK error types, status codes, parsed error bodies, and request IDs are preserved. Retries and timeouts follow the official SDK's configuration.

Next.js route handler

Use the tools on the server and stream UI messages to useChat:

import { search1apiTools } from '@search1api/ai-sdk';
import { convertToModelMessages, gateway, stepCountIs, streamText } from 'ai';
import type { UIMessage } from 'ai';

const tools = search1apiTools({ only: ['search', 'crawl'] });

export async function POST(request: Request) {
  const { messages }: { messages: UIMessage[] } = await request.json();
  const result = streamText({
    model: gateway('openai/gpt-5-mini'),
    system: 'Search and read relevant pages before answering. Cite the URLs you used.',
    messages: await convertToModelMessages(messages),
    tools,
    stopWhen: stepCountIs(5),
    abortSignal: request.signal,
  });
  return result.toUIMessageStreamResponse();
}

The complete Next.js example includes the client chat and renders links from tool outputs.

Source

GitHub · npm · AI SDK tool calling