Vercel AI SDK

AI SDK tools for Valyu search API, built for Vercel AI SDK v5.

Best for: building Valyu into your product / agents. Wire Valyu search tools into a Vercel AI SDK app.

Paste into your AI assistant to wire Valyu tools into a Vercel AI SDK project.

Want to try without writing any code? Test our search tools and see results in our AI SDK Playground.

Installation

Install the Valyu AI SDK package:

npm install @valyu/ai-sdk

Get your free API key from Valyu Platform - $10 free credits ($20 with a work email) when you sign up!Add it to your .env file:

VALYU_API_KEY=your-api-key-here

The package reads it automatically.

Quick Start

Get started with web search in seconds:

import { generateText } from "ai";
import { webSearch } from "@valyu/ai-sdk";
// Available specialised search tools: financeSearch, paperSearch,
// bioSearch, patentSearch, secSearch, economicsSearch, companyResearch
// Discovery tools: datasources, datasourcesCategories
import { openai } from "@ai-sdk/openai";

const { text } = await generateText({
  model: openai('gpt-5'),
  prompt: 'Latest data center projects for AI inference workloads?',
  tools: {
    webSearch: webSearch(),
  },
});

console.log(text);

Your AI agent now has access to real-time web search.

Available Search Tools

Available search tools

Each tool is called the same way - tools: { name: toolName() }. Route each query to the most specific tool:

Tool	Best for
`webSearch`	Real-time news, current events, general web content
`financeSearch`	Stock prices, earnings, statements, market data
`paperSearch`	Academic papers across PubMed, arXiv, bioRxiv, medRxiv
`bioSearch`	Clinical trials, FDA labels, ChEMBL, PubChem, Open Targets, ICD codes
`patentSearch`	USPTO patents, prior art, IP
`secSearch`	SEC filings (10-K, 10-Q, 8-K), Form 4 insider transactions
`economicsSearch`	BLS, FRED, World Bank, USAspending indicators
`companyResearch`	Synthesized company intelligence reports with citations

Discovery tools (datasources, datasourcesCategories) let an agent list the available sources and categories before searching.

import { generateText, stepCountIs } from "ai";
import { financeSearch } from "@valyu/ai-sdk";
import { openai } from "@ai-sdk/openai";

const { text } = await generateText({
  model: openai('gpt-5'),
  prompt: 'What was the stock price of Apple from the start of 2020 to 14 Feb?',
  tools: {
    financeSearch: financeSearch(),
  },
  stopWhen: stepCountIs(10),
});

companyResearch auto-detects whether a company is public or private and pulls from filings, financials, news, and funding accordingly. It supports section filtering (summary, leadership, products, funding, competitors, filings, financials, news, insiders).

Combine multiple tools

import { generateText, stepCountIs } from "ai";
import { paperSearch, bioSearch, financeSearch } from "@valyu/ai-sdk";
import { openai } from "@ai-sdk/openai";

const { text } = await generateText({
  model: openai('gpt-5'),
  prompt: 'Research the commercialization of CRISPR technology',
  tools: {
    papers: paperSearch({ maxNumResults: 3 }),
    medical: bioSearch({ maxNumResults: 3 }),
    finance: financeSearch({ maxNumResults: 3 }),
  },
  stopWhen: stepCountIs(3),
});

For streaming, swap generateText for streamText and iterate result.textStream.

Configuration and best practices

Tool configuration options

webSearch({
  apiKey: "your-api-key",        // defaults to process.env.VALYU_API_KEY
  maxNumResults: 10,
  relevanceThreshold: 0.8,       // 0-1 quality filter
  maxPrice: 0.01,                // CPM cost cap per query
  category: "technology",
  includedSources: ["arxiv", "pubmed"],
  fastMode: false,               // faster, shorter (webSearch only)
})

Lower maxPrice/maxNumResults and raise relevanceThreshold to control cost. Valyu prices on CPM (cost per thousand retrievals).

System prompting

Guide the model to route to the right tool, cite sources as Markdown links [Title](URL), combine tools for complex topics, and use natural-language queries (not operators). See the Prompting Guide.

Build a custom tool

Call the Search API directly with the AI SDK tool() helper:

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

export function myCustomSearch(config = {}) {
  const apiKey = config.apiKey || process.env.VALYU_API_KEY;
  return tool({
    description: "Search for [your domain]",
    inputSchema: z.object({ query: z.string() }),
    execute: async ({ query }) => {
      const response = await fetch("https://api.valyu.ai/v1/search", {
        method: "POST",
        headers: { "Content-Type": "application/json", "x-api-key": apiKey },
        body: JSON.stringify({ query, max_num_results: 5, search_type: "all" }),
      });
      return response.json();
    },
  });
}

TypeScript types

Full types ship with the package: ValyuBaseConfig, ValyuWebSearchConfig, and per-tool config types (ValyuFinanceSearchConfig, ValyuPaperSearchConfig, etc.), plus ValyuSearchResult and ValyuApiResponse.

Next Steps

Valyu Platform - Get your API keys
Valyu Documentation - Full API documentation
Valyu Website - Learn more about Valyu
GitHub Repository - View source code

Agents & MCP

Automation Platforms

Work Platforms

Framework SDKs

Community SDKs

LLM Providers

Vercel AI SDK

Installation

Quick Start

Available search tools

Combine multiple tools

Configuration and best practices

Next Steps

​Installation

​Quick Start

​Available search tools

​Combine multiple tools

​Configuration and best practices

​Next Steps

Installation

Quick Start

Available search tools

Combine multiple tools

Configuration and best practices

Next Steps