Web search

Web search is the capability that lets the chat app pull in current or externally verified information instead of relying only on model memory. In TurboStarter AI, that capability lives behind a shared provider contract so the tool layer can stay stable while the search backend changes.

This is especially useful for:

• current events and recent announcements
• source-backed answers that need citations or fresh data
• niche lookups where static model knowledge may be incomplete
• assistant flows that benefit from explicit retrieval before generating a response

Where it lives

The shared implementation is in packages/ai/chat/src/tools/web-search.

That module currently includes:

• a tool entrypoint used by the chat flow
• input schemas for multi-query web search requests
• shared normalization utilities for results, images, domains, and dates
• provider strategies for Tavily, Brave Search, Exa, and Firecrawl
• provider-specific SDK wrappers under packages/ai/chat/src/tools/sdk/*

The overall shape follows the same pattern as the rest of the AI package: keep the chat app code focused on behavior, and isolate third-party integrations behind typed boundaries.

Provider architecture

The web-search tool does not talk to a single provider API directly. Instead, it uses a provider strategy layer. Each provider implementation maps its own SDK response into the same result shape:

• results: normalized search hits
• images: normalized image candidates

That makes it easier to:

• swap the default provider
• compare providers during development
• keep the UI independent from provider-specific response formats
• add provider-specific options without rewriting the whole tool surface

Implemented providers

TurboStarter AI currently includes the following web-search providers:

Environment variables

If you want to enable these providers, add the corresponding server-side keys in apps/web/.env.local or your deployment environment:

BRAVE_SEARCH_API_KEY=""
EXA_API_KEY=""
FIRECRAWL_API_KEY=""
TAVILY_API_KEY=""

Only configure the providers you actually plan to use. Keeping multiple providers available can be useful during development, but it is not required.

How it fits into chat

The Chat app uses web search as a tool rather than as a separate product surface. That means the model decides when browsing is necessary based on the request and the tool instructions.

The shared chat package handles:

• deciding when the tool is relevant
• executing the normalized web-search flow
• streaming the tool status back into the conversation UI
• passing structured search results back into the model loop

For the user, this shows up as a normal tool-driven assistant interaction rather than a separate search screen.

Related documentation