Skip to main content

Documentation Index

Fetch the complete documentation index at: https://chatjs.dev/docs/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

Enable your AI to search the web in real-time and provide answers with inline citations. The tool supports multiple queries per request for comprehensive research.
AI searching the web and returning results with citations

​
Quick Start

Enable web search in chat.config.ts: 
ai: {
  tools: {
    webSearch: {
      enabled: true, // Requires TAVILY_API_KEY or FIRECRAWL_API_KEY
    },
  },
}

​
Environment Variables

Configure one of the supported search providers: 
# Option 1: Tavily (recommended)
TAVILY_API_KEY=your_tavily_key

# Option 2: Firecrawl
FIRECRAWL_API_KEY=your_firecrawl_key
If both keys are set, Tavily is used for regular chat and the provider can be configured per-feature (e.g., deep research).

​
Providers

ProviderBest ForFeatures
TavilyGeneral searchTopic filtering, news mode, domain exclusions
FirecrawlContent extractionHigh-quality markdown from web pages

​
Tavily

Default provider with search-specific optimizations:
  • Topics: general or news (news limits to last 7 days)
  • Search depth: basic or advanced
  • Domain filtering: Exclude specific domains from results

​
Firecrawl

Alternative provider focused on content quality. Returns clean markdown extracted from pages.

​
Features

The tool accepts up to 2 queries per request, executed in parallel: 
{
  search_queries: [
    { query: "latest AI developments 2024", maxResults: 5 },
    { query: "machine learning trends", maxResults: 5 },
  ]
}
Results are automatically deduplicated by domain and URL.

​
Inline Citations

Search results are displayed as collapsible source cards. The AI is instructed to cite sources inline when using retrieved information.

​
Progress Indicators

While searching, the UI shows:
  • Search status (running/completed)
  • Query text being executed
  • Number of sources found

​
Tool Output

Returns search results grouped by query: 
{
  searches: [
    {
      query: { query: "...", maxResults: 5 },
      results: [{ url: "...", title: "...", content: "..." }],
    },
  ]
}

​
UI States

StateShows
input-availableProgress indicator with query
output-availableCollapsible source cards with titles and URLs

​
Customization

​
Tool Definition

The tool is defined in lib/ai/tools/web-search.ts. You can modify:
  • Maximum queries per request (MAX_SEARCH_QUERIES)
  • Default results per query (DEFAULT_MAX_RESULTS)
  • Tool description to adjust AI behavior

​
Provider Selection

To use Firecrawl instead of Tavily for regular chat, modify lib/ai/tools/tools.ts: 
webSearch: firecrawlWebSearch({
  dataStream,
  writeTopLevelUpdates: true,
  costAccumulator,
}),

​
URL Retrieval

A separate retrieveUrl tool is available for fetching structured content from specific URLs (as opposed to searching the web). This tool uses Firecrawl to extract clean markdown from any webpage. Enable in chat.config.ts: 
ai: {
  tools: {
    urlRetrieval: {
      enabled: true, // Requires FIRECRAWL_API_KEY
    },
  },
}
The tool extracts:
  • Page title and description
  • Clean markdown content
  • Source URL and language metadata
Use web search for discovery and URL retrieval for extracting content from known URLs.