Skip to main content
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.

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

Installation

​
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.
2

Quick Start

​
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.
3

Available Search Tools

​
Available search tools

Each tool is called the same way - tools: { name: toolName() }. Route each query to the most specific tool:
ToolBest for
webSearchReal-time news, current events, general web content
financeSearchStock prices, earnings, statements, market data
paperSearchAcademic papers across PubMed, arXiv, bioRxiv, medRxiv
bioSearchClinical trials, FDA labels, ChEMBL, PubChem, Open Targets, ICD codes
patentSearchUSPTO patents, prior art, IP
secSearchSEC filings (10-K, 10-Q, 8-K), Form 4 insider transactions
economicsSearchBLS, FRED, World Bank, USAspending indicators
companyResearchSynthesized 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).
4

Combine multiple tools

​
Combine multiple tools

Register several tools so the agent chooses per query:
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.
5

Configuration and best practices

​
Configuration and best practices

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).
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.
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();
    },
  });
}
Full types ship with the package: ValyuBaseConfig, ValyuWebSearchConfig, and per-tool config types (ValyuFinanceSearchConfig, ValyuPaperSearchConfig, etc.), plus ValyuSearchResult and ValyuApiResponse.

​
Next Steps