Skip to main content
LibreChat’s Web Search feature enables AI agents to search the internet, scrape web pages, and retrieve up-to-date information to answer questions with current data.

​
Overview

Web Search allows agents to:

Real-Time Search

Search the web for current information

Content Scraping

Extract and analyze web page content

Result Reranking

Improve relevance with AI reranking

Source Citations

Provide sources and references

​
Configuration

Configure web search in your librechat.yaml:
librechat.yaml
webSearch:
  # Search Providers
  serperApiKey: '${SERPER_API_KEY}'
  searxngInstanceUrl: '${SEARXNG_INSTANCE_URL}'
  searxngApiKey: '${SEARXNG_API_KEY}'
  
  # Content Scrapers
  firecrawlApiKey: '${FIRECRAWL_API_KEY}'
  firecrawlApiUrl: '${FIRECRAWL_API_URL}'
  
  # Rerankers
  jinaApiKey: '${JINA_API_KEY}'
  cohereApiKey: '${COHERE_API_KEY}'
  
  # Safe search filter
  safeSearch: 'moderate'  # 'off', 'moderate', 'strict'
  
  # Scraper timeout
  scraperTimeout: 7500  # milliseconds
  
  # Firecrawl options
  firecrawlOptions:
    timeout: 10000

​
Components

​
Search Providers

Choose your search engine:
Google Search API through Serper.dev:
webSearch:
  serperApiKey: '${SERPER_API_KEY}'
Setup:
  1. Sign up at serper.dev
  2. Get your API key
  3. Set SERPER_API_KEY environment variable
Features:
  • Google search results
  • Fast and reliable
  • Generous free tier

​
Content Scrapers

Extract content from web pages:
Advanced web scraping with clean content extraction:
webSearch:
  firecrawlApiKey: '${FIRECRAWL_API_KEY}'
  firecrawlApiUrl: '${FIRECRAWL_API_URL}'
  firecrawlOptions:
    timeout: 10000
    formats: ['markdown', 'html']
Setup:
  1. Sign up at firecrawl.dev
  2. Get your API key
  3. Set environment variable
Features:
  • Clean markdown extraction
  • JavaScript rendering
  • Removes ads and clutter
  • Configurable timeouts

​
Result Rerankers

Improve search result relevance:
Neural reranking with Jina AI:
webSearch:
  jinaApiKey: '${JINA_API_KEY}'
  jinaApiUrl: '${JINA_API_URL}'  # Optional
Setup:
  1. Sign up at jina.ai
  2. Get your API key
  3. Set JINA_API_KEY environment variable
Features:
  • Neural reranking models
  • Multilingual support
  • High accuracy

​
For Agents

Enable web search in agent tools: 
{
  name: 'Research Assistant',
  provider: 'openAI',
  model: 'gpt-4o',
  instructions: 'You are a research assistant with web search capabilities.',
  tools: ['web_search', 'file_search'],
  tool_options: {
    web_search: {
      enabled: true
    }
  }
}

​
For Standard Chats

Enable web search in model parameters: 
{
  endpoint: 'openAI',
  model: 'gpt-4o',
  web_search: true  // Enable web search
}

​
Interface Configuration

Control user access to web search:
librechat.yaml
interface:
  fileSearch: true  # Enable file search UI (includes web search)

​
Search Queries

The AI automatically formulates search queries: 
User: What are the latest developments in quantum computing?

Agent: Let me search for recent quantum computing news...
[Uses web_search tool]

Search query: "quantum computing latest developments 2024"

Results:
1. IBM announces new quantum processor...
2. Google achieves quantum advantage in...
3. Breakthrough in quantum error correction...

[Agent synthesizes information with citations]

​
Citation Format

Web search results include citations: 
According to recent reports, quantum computing has made significant 
advances in error correction [1]. IBM's latest processor features 
127 qubits [2], while Google has demonstrated quantum advantage 
in specific tasks [3].

Sources:
[1] Nature: "Breakthrough in Quantum Error Correction"
[2] IBM Research: "New Quantum Processor Announcement"
[3] Google AI Blog: "Quantum Advantage Demonstrated"

​
Search Categories

Web search authentication is organized by categories:
Search engine selection:
  • Serper: Google search via API
  • SearXNG: Metasearch engine
At least one provider must be configured.
Control content filtering:
​
safeSearch
string
default:"moderate"
Filter search results by content safety level
librechat.yaml
webSearch:
  safeSearch: 'moderate'  # 'off', 'moderate', 'strict'
Levels:
  • off: No filtering
  • moderate: Filter explicit content (default)
  • strict: Strict filtering

​
Advanced Configuration

​
Timeout Settings

Configure timeouts for scrapers:
librechat.yaml
webSearch:
  scraperTimeout: 7500  # Default scraper timeout
  
  firecrawlOptions:
    timeout: 10000  # Firecrawl-specific timeout

​
Custom Firecrawl Options

Configure Firecrawl behavior:
librechat.yaml
webSearch:
  firecrawlOptions:
    timeout: 10000
    formats: ['markdown', 'html']
    onlyMainContent: true
    includeMetadata: true
    removeScripts: true

​
Authentication Types

Web search supports different authentication modes:
API keys configured in environment:
SERPER_API_KEY=your-key-here
FIRECRAWL_API_KEY=your-key-here
JINA_API_KEY=your-key-here
Shared across all users.

​
Example Configurations

​
Basic Setup

Minimal configuration with Serper:
librechat.yaml
webSearch:
  serperApiKey: '${SERPER_API_KEY}'
.env
SERPER_API_KEY=your-serper-key
Complete configuration with all services:
librechat.yaml
webSearch:
  # Search
  serperApiKey: '${SERPER_API_KEY}'
  
  # Scraping
  firecrawlApiKey: '${FIRECRAWL_API_KEY}'
  firecrawlOptions:
    timeout: 15000
    onlyMainContent: true
  
  # Reranking
  jinaApiKey: '${JINA_API_KEY}'
  
  # Settings
  safeSearch: 'moderate'
  scraperTimeout: 10000
.env
SERPER_API_KEY=your-serper-key
FIRECRAWL_API_KEY=your-firecrawl-key
JINA_API_KEY=your-jina-key

​
Self-Hosted Setup

Using SearXNG with basic scraper:
librechat.yaml
webSearch:
  searxngInstanceUrl: '${SEARXNG_INSTANCE_URL}'
  searxngApiKey: '${SEARXNG_API_KEY}'
  scraperTimeout: 7500
  safeSearch: 'moderate'
.env
SEARXNG_INSTANCE_URL=https://searx.example.com
SEARXNG_API_KEY=your-instance-key

​
Model Integration

​
OpenAI Models

Web search as a tool: 
{
  model: 'gpt-4o',
  tools: [{ type: 'web_search' }],
  web_search: true
}

​
OpenRouter

Special handling for OpenRouter: 
{
  model: 'openrouter/model',
  plugins: {
    web_search: true  // OpenRouter uses plugins parameter
  }
}

​
Anthropic Claude

Native tool integration: 
{
  model: 'claude-4.5-sonnet',
  web_search: true,
  tools: ['web_search']
}

​
Best Practices

Combine Services: Use Serper for search + Firecrawl for scraping + Jina for reranking
Timeout Configuration: Set appropriate timeouts based on your use case (longer for deep scraping)
Rate Limits: Monitor API usage to avoid hitting provider rate limits
Cost Management: Web search APIs have usage costs - configure wisely

​
Troubleshooting

Check:
  • API keys are correctly set in environment
  • At least one search provider is configured
  • web_search is enabled in agent tools or model parameters
  • No rate limiting or API quota issues
Solutions:
  • Enable a reranker (Jina or Cohere)
  • Adjust safe search settings
  • Use more specific search queries
  • Try different search provider
Solutions:
  • Increase scraperTimeout
  • Use Firecrawl for JavaScript-heavy sites
  • Check firewall/network restrictions
  • Verify target site allows scraping
Optimizations:
  • Reduce scraperTimeout for faster fails
  • Skip reranking for speed
  • Use basic scraper instead of Firecrawl
  • Cache frequent searches

​
Environment Variables

Complete list of web search environment variables: 
SERPER_API_KEY=your-serper-key
SEARXNG_INSTANCE_URL=https://searx.example.com
SEARXNG_API_KEY=your-searxng-key

​
Example Use Cases

{
  name: 'Research Assistant',
  provider: 'anthropic',
  model: 'claude-4.5-sonnet',
  instructions: `
    You are a research assistant. When users ask questions:
    1. Search the web for current information
    2. Analyze multiple sources
    3. Provide well-cited, accurate answers
    4. Always include source links
  `,
  tools: ['web_search', 'file_search']
}

{
  name: 'News Aggregator',
  provider: 'openAI',
  model: 'gpt-4o',
  instructions: `
    You aggregate and summarize news on requested topics.
    Always search for the latest news and provide:
    - Key headlines
    - Brief summaries
    - Source citations
    - Publication dates
  `,
  tools: ['web_search']
}

{
  name: 'Fact Checker',
  provider: 'openAI',
  model: 'gpt-4o',
  instructions: `
    You verify claims by:
    1. Searching for authoritative sources
    2. Cross-referencing multiple sources
    3. Providing evidence-based verdicts
    4. Rating claim accuracy
  `,
  tools: ['web_search']
}

Agents

Use web search with autonomous agents

File Search

Search uploaded documents

Actions

Call external APIs for data

MCP

Custom tool integrations

Build docs developers (and LLMs) love

Get started for freeTalk to us