Web Search Service

Provider-agnostic web search for AI agents. Give your agents the ability to search the web with structured queries, spelling correction, and full request logging.

Why It Matters

AI agents are limited to their training data. For current events, real-time pricing, competitor analysis, or market research, agents need web access.

The Web Search Service provides a clean, provider-agnostic API that any agent can use — with structured query support, result normalization, and full observability.

Key Capabilities

• Structured Queries: AND terms, exact phrases, OR terms, exclusions, site filtering, file type filtering
• Provider-Agnostic: Bing Web Search v7 today, designed for Tavily, Brave, Serper, Google
• Normalized Results: Consistent response format regardless of provider — title, URL, snippet, date, site name
• Spelling Correction: Automatic spelling suggestions with option to apply corrections
• Related Searches: Query expansion suggestions to help agents refine their searches
• Request Logging: Fire-and-forget logging for analytics and audit
• MCP Integration: Available as a tool through the MCP Gateway — agents get web search automatically

How It Works

Your agent sends a search request to the Web Search API. The service routes it to the configured provider, normalizes the results into a consistent format, and returns them to your agent — with spelling corrections and related searches included.

Structured Query Support

Go beyond simple string queries. The structured query API lets agents build precise searches with AND/OR logic, exact phrases, exclusions, site filtering, and file type restrictions.

// Simple search
const results = await websearch.search({ query: 'FireFoundry AI agent platform' });

// Structured search with advanced filtering
const results = await websearch.search({
  structured: {
    andTerms: ['machine learning', 'production'],
    exactPhrase: 'model deployment',
    orTerms: ['kubernetes', 'docker'],
    excludeTerms: ['tutorial', 'beginner'],
    siteFilter: { include: ['arxiv.org', 'github.com'] },
    fileType: 'pdf'
  },
  limit: 10,
  market: 'en-US',
  freshness: 'week'
});

// Results are normalized across providers
for (const result of results.results) {
  console.log(`${result.title} — ${result.url}`);
  console.log(`  ${result.snippet}`);
}

Response Format

Every search response includes a normalized results array, metadata, and optional corrections. The format is consistent regardless of which provider is used behind the scenes.

• Results array: Each result includes id, title, url, snippet, datePublished, and siteName
• Metadata: requestId, processingTimeMs, totalResults, provider, and timestamp
• Spelling corrections: Original query, corrected query, and whether the correction was applied
• Related searches: Suggested queries for further exploration

{
  success: true,
  results: [
    {
      id: 'result-0',
      title: 'Machine Learning in Production',
      url: 'https://arxiv.org/abs/example',
      snippet: 'Best practices for deploying ML models...',
      datePublished: '2026-01-10T00:00:00Z',
      siteName: 'arXiv'
    }
  ],
  meta: {
    requestId: '550e8400-e29b-41d4-a716-446655440000',
    processingTimeMs: 150,
    totalResults: 25000
  },
  spellingCorrection: {
    originalQuery: 'machin lerning',
    correctedQuery: 'machine learning',
    appliedCorrection: true
  },
  relatedSearches: ['deep learning production', 'MLOps best practices']
}

Provider Architecture

The Web Search Service currently uses Microsoft Bing Web Search API v7 as its search provider. The service is built with a provider-agnostic abstraction layer, making it straightforward to add new providers as they become available.

Future providers on the roadmap include Tavily, Brave, Serper, and Google. The abstraction ensures your agent code never changes when new providers are added — the service handles provider selection, query translation, and result normalization transparently.

Use Cases