# Vercel AI SDK

> Give AI SDK agents web search, news, webpage reading, and agentic search with the official Search1API tools package.

Canonical URL: https://s1.dev/docs/integrations/vercel-ai-sdk

For both Vercel integration options, including Vercel Connect, see the [Vercel guide](https://s1.dev/docs/integrations/vercel).

`@search1api/ai-sdk` exposes Search1API as ordinary AI SDK tools. Use it with
`generateText`, `streamText`, or an agent and your preferred model provider.
One package covers search across engines such as Google, Reddit, GitHub, and
YouTube, plus `crawl` for reading the full page behind a result, so the agent
can search, read, and cite without a separate scraping service. The package
uses the official [TypeScript SDK](https://s1.dev/docs/integrations/sdks) for API calls.

## Install and configure

```bash
npm install @search1api/ai-sdk ai zod
```

Create a key in the [dashboard](https://app.s1.dev), then set it in the server's
environment:

```bash
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.

```ts
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 full tool set contains:

| Tool | Model input | Result |
| --- | --- | --- |
| `search` | `query`, optional `search_service`, `page`, `max_results`, `include_sites`, `exclude_sites`, `time_range` | Titles, links, snippets, and other search response fields |
| `news` | Same fields as `search` except `page`, with news engines | News articles and source links |
| `crawl` | `{ url: string }` | A webpage's title, source URL, and readable content |
| `ask` | `{ query: string }` | Up to 10 results ranked by relevance, plus the engines and time window used |

The model-facing parameters match the [MCP server](https://s1.dev/docs/integrations/mcp). The model
can choose an engine (`google`, `bing`, `bingcn`, `duckduckgo`, `yahoo`,
`yandex`, `x`, `reddit`, `github`, `youtube`, `arxiv`, `wechat`, `bilibili`,
`imdb`, `wikipedia`, `grokipedia`; news supports `google`, `bing`,
`duckduckgo`, `yahoo`, and `hackernews`), return 1–50 results, request a later
results page (only `bing`, `bingcn`, `baidu`, and `grokipedia` paginate), scope
or exclude domains, and limit results to the past day, week, month, or year.
Result page crawling is not exposed to the model. Unknown arguments are ignored
rather than failing the call.

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. When an answer
uses `grokipedia` results, credit them as "Powered by xAI"; see
[Improving search results](https://s1.dev/docs/guides/improving-search-results).

## Agentic search with ask

`ask` sends a natural-language request to [`POST /ask`](https://s1.dev/docs/basic/ask). Search1API
chooses up to five engines and a time window, drops off-topic results, and
returns at most 10 results ranked by relevance. Like the MCP server's `ask`
tool, it is included in `search1apiTools()` by default. Each call costs 5
credits, compared with 1 credit for `search`, and has a 45-second timeout.

```ts
import { search1apiAsk, search1apiTools } from '@search1api/ai-sdk';

// The previous three-tool set, without ask
const withoutAsk = search1apiTools({ only: ['search', 'news', 'crawl'] });

// ask on its own
const askOnly = { ask: search1apiAsk() };
```

`ask` is not available with pay-per-request payments.

## Configure individual tools

```ts
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 } }),
};
```

Settings passed in code are defaults. When the model supplies the same
parameter, its value is used for that call; anything it omits falls back to your
settings. Tool sets accept the same settings under `search`, `news`, and `crawl`.

Search and news default to ten 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](https://s1.dev/docs/essentials/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:

```ts
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`:

```ts
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](https://github.com/superagents-lab/search1api-ai-sdk/tree/main/examples/nextjs)
includes the client chat and renders links from tool outputs.

## Source

[GitHub](https://github.com/superagents-lab/search1api-ai-sdk) ·
[npm](https://www.npmjs.com/package/@search1api/ai-sdk) ·
[AI SDK tool calling](https://ai-sdk.dev/docs/ai-sdk-core/tools-and-tool-calling)