Vercel AI SDK

Give your AI agents access to real-time web data and specialized knowledge with Valyu’s DeepSearch API. Add powerful search capabilities to your LLMs in just a few lines of code using the @valyu/ai-sdk package.

Installation

Install the Valyu AI SDK package:

npm install @valyu/ai-sdk

Get your free API key from Valyu Platform - you get $10 in free credits when you sign up!Add your API key to your .env file:

VALYU_API_KEY=your-api-key-here

That’s it! The package automatically reads your API key from the environment.

Quick Start

Get started with web search in seconds:

import { generateText } from "ai";
import { webSearch } from "@valyu/ai-sdk";
import { openai } from "@ai-sdk/openai";

const { text } = await generateText({
  model: openai('gpt-5'),
  prompt: 'What are the latest developments in AI?',
  tools: {
    webSearch: webSearch(),
  },
});

console.log(text);

That’s it! Your AI agent now has access to real-time web search.

Available Search Tools

The @valyu/ai-sdk package includes eight specialized tools for different search domains:

webSearch

General web search for current information, news, and articles.

import { webSearch } from "@valyu/ai-sdk";

const { text } = await generateText({
  model: openai('gpt-5'),
  prompt: 'What happened in AI tech news last week?',
  tools: {
    webSearch: webSearch({ maxNumResults: 5 }),
  },
});

financeSearch

Search financial data including stock prices, earnings reports, and market data.

import { financeSearch } from "@valyu/ai-sdk";

const { text } = await generateText({
  model: openai('gpt-5'),
  prompt: "What are Apple's latest earnings?",
  tools: {
    financeSearch: financeSearch({ maxNumResults: 5 }),
  },
});

paperSearch

Search academic research papers and scholarly articles.

import { paperSearch } from "@valyu/ai-sdk";

const { text } = await generateText({
  model: openai('gpt-5'),
  prompt: 'Find recent research on transformer neural networks',
  tools: {
    paperSearch: paperSearch({ maxNumResults: 5 }),
  },
});

bioSearch

Search biomedical literature, clinical trials, and FDA information.

import { bioSearch } from "@valyu/ai-sdk";

const { text } = await generateText({
  model: openai('gpt-5'),
  prompt: 'Find clinical trials for cancer immunotherapy',
  tools: {
    bioSearch: bioSearch({ maxNumResults: 5 }),
  },
});

patentSearch

Search patent databases for inventions and intellectual property.

import { patentSearch } from "@valyu/ai-sdk";

const { text } = await generateText({
  model: openai('gpt-5'),
  prompt: 'Find patents related to quantum computing',
  tools: {
    patentSearch: patentSearch({ maxNumResults: 5 }),
  },
});

secSearch

Search SEC filings including 10-K, 10-Q, and regulatory documents.

import { secSearch } from "@valyu/ai-sdk";

const { text } = await generateText({
  model: openai('gpt-5'),
  prompt: "Find Tesla's latest 10-K filing",
  tools: {
    secSearch: secSearch({ maxNumResults: 5 }),
  },
});

economicsSearch

Search economic data including BLS, FRED, and World Bank indicators.

import { economicsSearch } from "@valyu/ai-sdk";

const { text } = await generateText({
  model: openai('gpt-5'),
  prompt: 'What is the current US unemployment rate?',
  tools: {
    economicsSearch: economicsSearch({ maxNumResults: 5 }),
  },
});

companyResearch

Generate comprehensive company intelligence reports with business overview, financials, SEC filings, news, and more.

import { companyResearch } from "@valyu/ai-sdk";

const { text } = await generateText({
  model: openai('gpt-5'),
  prompt: 'Research Apple Inc',
  tools: {
    companyResearch: companyResearch(),
  },
});

Note: companyResearch uses the Valyu Answer API which provides AI-synthesized responses with citations. Costs are controlled via the dataMaxPrice parameter (default: $1.00 per section).

Multi-Tool Search

Combine Multiple Search Tools

Use multiple search tools together for comprehensive research across domains:

import { generateText } 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 }),
  },
});

Your AI agent can now intelligently choose which search tool to use based on the query.

Configuration Options

All search tools support these configuration options:

import { webSearch } from "@valyu/ai-sdk";

const { text } = await generateText({
  model: openai('gpt-5'),
  prompt: 'Find high-quality analysis of the latest AI trends',
  tools: {
    webSearch: webSearch({
      // API key (defaults to process.env.VALYU_API_KEY)
      apiKey: "your-api-key",

      // Search type: "proprietary" (premium sources) or "web" (default: "proprietary")
      searchType: "proprietary",

      // Maximum number of results (default: 10)
      maxNumResults: 10,

      // Relevance threshold (0-1) to filter results by quality
      relevanceThreshold: 0.8,

      // Maximum price per query in CPM (cost per thousand retrievals)
      maxPrice: 0.01,

      // Category to focus the search on
      category: "technology",

      // Specific sources to include (dataset identifiers)
      includedSources: ["arxiv", "pubmed"],

      // Flag for agentic integration (default: true)
      isToolCall: true,
    }),
  },
});

Streaming Results

Use with streamText for real-time responses:

import { streamText } from "ai";
import { paperSearch } from "@valyu/ai-sdk";
import { anthropic } from "@ai-sdk/anthropic";

const result = streamText({
  model: anthropic('claude-3-5-sonnet-20241022'),
  prompt: 'Summarize recent quantum computing research',
  tools: {
    papers: paperSearch(),
  },
});

for await (const chunk of result.textStream) {
  process.stdout.write(chunk);
}

Create Your Own Tool

Create Your Own Custom Search Tool

Want to build a custom search tool beyond the pre-built ones? Use the Valyu DeepSearch API directly with the Vercel AI SDK tool() function:

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 specific domain/use case]",
    inputSchema: z.object({
      query: z.string().describe("The search query"),
    }),
    execute: async ({ query }) => {
      const response = await fetch("https://api.valyu.ai/v1/deepsearch", {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          "x-api-key": apiKey,
        },
        body: JSON.stringify({
          query,
          max_num_results: 5,
          search_type: "all", // or "web", "proprietary"
          included_sources: ["your-custom-sources"], // optional
          // Add more parameters as needed
        }),
      });

      const data = await response.json();
      return data;
    },
  });
}

Check out the Valyu API Documentation for all available parameters and data sources.

Best Practices

System Prompting

Guide your LLM to use search tools effectively:

const result = await generateText({
  model: openai('gpt-5'),
  messages: [
    {
      role: 'system',
      content: `You are an AI research assistant with access to specialized search tools.

      - Use webSearch for current events and general web content
      - Use paperSearch for academic research and scientific papers
      - Use financeSearch for stock prices, earnings, and market data
      - Use bioSearch for medical research and clinical trials
      - Always cite sources using Markdown links: [Title](URL)
      - Combine multiple tools when researching complex topics`
    },
    // ... user messages
  ],
  tools: {
    web: webSearch(),
    papers: paperSearch(),
    finance: financeSearch(),
    bio: bioSearch(),
  },
});

Cost Control

Control costs with configuration options:

webSearch({
  maxPrice: 0.01,              // Maximum cost per query
  maxNumResults: 5,            // Limit number of results
  relevanceThreshold: 0.8,     // Only high-quality results
})

Valyu uses a CPM (cost per thousand retrievals) pricing model, making it easy to predict and control costs.

API Key Security

Always use environment variables for VALYU_API_KEY
Never commit API keys to version control
Use .env.local files for local development

TypeScript Support

Full TypeScript types are included:

import {
  webSearch,
  ValyuWebSearchConfig,
  ValyuSearchResult,
  ValyuApiResponse
} from "@valyu/ai-sdk";

const config: ValyuWebSearchConfig = {
  maxNumResults: 10,
  searchType: "proprietary",
  relevanceThreshold: 0.7,
};

const search = webSearch(config);

Available Types

ValyuBaseConfig - Base configuration for all tools
ValyuWebSearchConfig - Web search configuration
ValyuFinanceSearchConfig - Finance search configuration
ValyuPaperSearchConfig - Research paper search configuration
ValyuBioSearchConfig - Biomedical search configuration
ValyuPatentSearchConfig - Patent search configuration
ValyuSecSearchConfig - SEC filings search configuration
ValyuEconomicsSearchConfig - Economics search configuration
ValyuCompanyResearchConfig - Company research configuration
ValyuSearchResult - Individual search result
ValyuApiResponse - API response structure

Next Steps

Explore the Valyu API Documentation for advanced features
Get your API key at Valyu Platform
View the source code on GitHub
Check out more examples in our documentation

Agents & MCP

Framework SDKs

LLM Providers

Vercel AI SDK

Installation

Quick Start

Available Search Tools

webSearch

financeSearch

paperSearch

bioSearch

patentSearch

secSearch

economicsSearch

companyResearch

Combine Multiple Search Tools

Configuration Options

Streaming Results

Create Your Own Custom Search Tool

Best Practices

System Prompting

Cost Control

API Key Security

TypeScript Support

Available Types

Next Steps

Agents & MCP

Framework SDKs

LLM Providers

​Installation

​Quick Start

​Available Search Tools

​webSearch

​financeSearch

​paperSearch

​bioSearch

​patentSearch

​secSearch

​economicsSearch

​companyResearch

​Combine Multiple Search Tools

​Configuration Options

​Streaming Results

​Create Your Own Custom Search Tool

​Best Practices

​System Prompting

​Cost Control

​API Key Security

​TypeScript Support

​Available Types

​Next Steps

Installation

Quick Start

Available Search Tools

webSearch

financeSearch

paperSearch

bioSearch

patentSearch

secSearch

economicsSearch

companyResearch

Combine Multiple Search Tools

Configuration Options

Streaming Results

Create Your Own Custom Search Tool

Best Practices

System Prompting

Cost Control

API Key Security

TypeScript Support

Available Types

Next Steps