Web search tools

Search the web using multiple provider integrations

The web search tool enables AI agents to search the internet using various search providers including Brave, Perplexity, Parallel, Exa, and Tavily.

Tool overview

import { createWebSearchTool } from "@/core/agent/tools/web-search-tools";

const webSearchTool = createWebSearchTool();
yield* registerTool(webSearchTool);

web_search

Search the web for real-time information.

Parameters:

query · string · required

Search query. Be specific and add context/constraints to narrow results.

Maximum length: 5000 characters

depth · 'standard' | 'deep' · default: "standard"

Search depth:

• standard: Fast, basic search
• deep: Comprehensive search with more results

fromDate · string

Start date filter in ISO 8601 format (YYYY-MM-DD)

Example: "2024-01-01"

toDate · string

End date filter in ISO 8601 format (YYYY-MM-DD)

Example: "2024-12-31"

maxResults · number · default: 50

Maximum results to return (cap: 100)

Returns:

results · array

Search results:

Show Search result object

title · string

Page title

url · string

Page URL

snippet · string

Content excerpt or description

publishedDate · string

Publication date (if available)

source · string

Search provider name

metadata · object

Provider-specific metadata (e.g., relevance score)

totalResults · number

Total results returned

query · string

Search query used

timestamp · string

ISO 8601 timestamp of search execution

provider · 'brave' | 'perplexity' | 'parallel' | 'exa' | 'tavily'

Search provider used

Example:

const result = yield* webSearchTool.handler(
  {
    query: "TypeScript 5.0 new features release notes",
    depth: "standard",
    maxResults: 10,
    fromDate: "2024-01-01",
  },
  context
);

if (result.success) {
  console.log(`Found ${result.result.totalResults} results:`);
  for (const item of result.result.results) {
    console.log(`- ${item.title}: ${item.url}`);
  }
}

Configuration

Web search requires configuration in your Jazz settings:

{
  "web_search": {
    "provider": "brave",
    "brave": {
      "api_key": "YOUR_BRAVE_API_KEY"
    }
  }
}

Supported providers

Brave Search

Provider: brave

Configuration:

{
  "web_search": {
    "provider": "brave",
    "brave": {
      "api_key": "YOUR_BRAVE_API_KEY"
    }
  }
}

Features:

• Fast, privacy-focused search
• No tracking or profiling
• Independent index

Get API key: Brave Search API

Perplexity

Provider: perplexity

Configuration:

{
  "web_search": {
    "provider": "perplexity",
    "perplexity": {
      "api_key": "YOUR_PERPLEXITY_API_KEY"
    }
  }
}

Features:

• AI-powered search
• Summarized results
• Citation tracking

Get API key: Perplexity API

Parallel

Provider: parallel

Configuration:

{
  "web_search": {
    "provider": "parallel",
    "parallel": {
      "api_key": "YOUR_PARALLEL_API_KEY"
    }
  }
}

Features:

• Agentic search mode
• Multi-source aggregation
• Structured excerpts

Get API key: Parallel Web

Exa

Provider: exa

Configuration:

{
  "web_search": {
    "provider": "exa",
    "exa": {
      "api_key": "YOUR_EXA_API_KEY"
    }
  }
}

Features:

• Neural search
• Semantic understanding
• Auto-prompt enhancement
• Date range filtering

Get API key: Exa AI

Tavily

Provider: tavily

Configuration:

{
  "web_search": {
    "provider": "tavily",
    "tavily": {
      "api_key": "YOUR_TAVILY_API_KEY"
    }
  }
}

Features:

• Advanced/basic depth modes
• Date range filtering
• Relevance scoring
• Content extraction

Get API key: Tavily AI

Provider selection

The tool automatically uses the configured provider. To change providers, update your configuration:

import { WEB_SEARCH_PROVIDERS } from "@/core/agent/tools/web-search-tools";

// Available providers
WEB_SEARCH_PROVIDERS.forEach((provider) => {
  console.log(`${provider.name}: ${provider.value}`);
});
// Brave: brave
// Perplexity: perplexity
// Parallel: parallel
// Exa: exa
// Tavily: tavily

Error handling

No provider configured

{
  success: false,
  error: "No external web search provider configured. Please configure an external provider (Parallel, Exa, Tavily, Brave, or Perplexity) in settings."
}

Missing API key

{
  success: false,
  error: "No API key configured for brave. Please configure 'web_search.brave.api_key' in settings."
}

Search failed

{
  success: false,
  error: "Search with brave provider failed. Please check your configuration or try a different provider."
}

Best practices

Write specific queries

// Good: Specific, contextual query
{
  query: "TypeScript 5.0 new features and breaking changes",
  maxResults: 5
}

// Bad: Vague query
{
  query: "typescript",
  maxResults: 100
}

Use date filters for time-sensitive searches

// Search for recent articles
{
  query: "artificial intelligence research papers",
  fromDate: "2024-01-01",
  toDate: "2024-12-31",
  maxResults: 20
}

Choose appropriate depth

// Quick fact-checking: standard depth
{
  query: "Python 3.12 release date",
  depth: "standard",
  maxResults: 5
}

// Research: deep search
{
  query: "quantum computing applications in cryptography",
  depth: "deep",
  maxResults: 50
}

Limit results appropriately

// Quick answer: few results
{
  query: "current weather in San Francisco",
  maxResults: 3
}

// Comprehensive research: many results
{
  query: "machine learning frameworks comparison",
  maxResults: 50
}

Add constraints to narrow results

// Add constraints in query
{
  query: "React hooks tutorial site:react.dev OR site:beta.reactjs.org",
  maxResults: 10
}

Common use cases

Finding documentation

const result = yield* webSearchTool.handler(
  {
    query: "Effect-TS retry policy documentation",
    maxResults: 5,
  },
  context
);

Researching recent news

const result = yield* webSearchTool.handler(
  {
    query: "OpenAI GPT-4 announcements",
    fromDate: "2024-01-01",
    depth: "deep",
    maxResults: 20,
  },
  context
);

Technical problem-solving

const result = yield* webSearchTool.handler(
  {
    query: "TypeScript error TS2322 type string not assignable to type number",
    maxResults: 10,
  },
  context
);

Competitive analysis

const result = yield* webSearchTool.handler(
  {
    query: "AI code editor tools comparison 2024",
    depth: "deep",
    maxResults: 30,
  },
  context
);

Academic research

const result = yield* webSearchTool.handler(
  {
    query: "transformer architecture attention mechanism papers",
    fromDate: "2023-01-01",
    depth: "deep",
    maxResults: 50,
  },
  context
);