Vercel AI SDK
Give AI SDK agents web search, news, webpage reading, and agentic search with the official Search1API tools package.
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.
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 for API calls.
Install and configure
npm install @search1api/ai-sdk ai zodCreate 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 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. 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.
Agentic search with ask
ask sends a natural-language request to POST /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.
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
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.
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.