Web search

Your agent can search the web for current information and use source links in its answers. Web search is enabled by default with Exa's keyless service. Enable the AI Agent, then try:

Search the web for the latest Node.js release announcement and include the source.

The agent calls web_search with a text query. Search results use the existing tool activity and conversation storage. Queries are sent to your selected external search provider; the integration does not send application authentication headers or conversation history.

Configure or disable search

Open packages/agent/tools/websearch/config.ts:

export const config: WebSearchConfig = {
	// Exa works without a key. Set false to disable web_search.
	enabled: true,
	maxOutputCharacters: 20_000,
};

Set enabled to false and restart the API to disable search. The tool is already registered in apps/api/src/index.ts; you do not need to change that registration. Web search does not enable the agent runtime itself.

maxOutputCharacters accepts integers from 1,000 to 50,000. Longer results are shortened with a visible truncation marker; saved tool details include truncated: true. Provider-specific search depth and requested result counts live in each adapter. Parallel's anonymous service manages its own search settings, so these are not shared configuration options.

Choose a provider

Select one provider in packages/agent/tools/websearch/provider/index.ts, following the same pattern as payments and RAG:

export * from "./exa";

Replace "./exa" with "./parallel", "./firecrawl", or "./tavily" to switch. Keep one export active, add any required key to the root .env.local, and restart the API. Each adapter implements SearchWeb from websearch/types.ts and reads its credentials when called.

Exa

The default uses Exa's hosted search service. You can start without an account or API key. For authenticated usage and your account's limits, add:

EXA_API_KEY="your-api-key"

The adapter requests five results and preserves Exa's reference text and source URLs. The key is sent in the x-api-key header.

Parallel

Parallel Search also supports keyless access. To use your account's limits, add:

PARALLEL_API_KEY="your-api-key"

The adapter sends the question as a search objective and query, then returns titles, URLs, and excerpts in provider order. Anonymous searches use Parallel's server-managed settings. An optional key is sent as a Bearer token.

Exa and Parallel use hosted MCP endpoints internally over HTTP. They are still exposed to the agent as one native tool; you do not need to configure an MCP server. Web search is not added to this starter's MCP Server catalog.

Free access is rate limited by each provider and is intended for exploration and light usage. Add your own key for your account's plan and limits. A configured key that fails authentication is not silently replaced with anonymous access, and rate limits do not trigger retries or a switch to another provider.

Firecrawl

Firecrawl Search returns web results with query-relevant passages in their descriptions. The adapter requests five web results without full-page scraping.

Firecrawl documents keyless access, but may require a key based on your requesting IP. If anonymous requests return HTTP 403, create an account and add:

FIRECRAWL_API_KEY="your-api-key"

The adapter sends the key as a Bearer token. Search and account limits are controlled by Firecrawl.

Tavily

Tavily Search requires an API key, including when using its free credit allowance:

TAVILY_API_KEY="your-api-key"

The adapter uses basic search with five results, returning source titles, URLs, and content. It does not request a generated answer, images, or raw page content. Check Tavily's current credit allowance and pricing for your usage needs.

Results and limits

The tool returns reference text with source links. Exa's source text is preserved; the other adapters format titles, URLs, and excerpts in provider order. The agent uses these references to write its answer and cite sources. Search snippets may be incomplete, and passing engine tests does not measure answer quality.

Queries are limited to 4,000 characters. Each request has a 25-second deadline including response reading, and a 512 KiB upstream response limit. Cancelling a run cancels its search request. Oversized upstream responses fail; the output-character setting only shortens successfully received reference text.

Troubleshooting

• Tool unavailable: check the agent is enabled and websearch/config.ts has enabled: true, then restart the API.
• Missing Tavily key: set TAVILY_API_KEY. Other providers do not need that key.
• HTTP 401 or 403: check the selected provider's key. Firecrawl can require a key for an IP that cannot use anonymous access.
• HTTP 429 or quota failure: check your provider's rate limits and account allowance. The tool does not retry automatically or switch providers.
• No results: try a more specific question. A valid empty result is a successful search, not an error.
• Invalid response or provider error: check service availability and the provider's current API contract. Raw provider diagnostics are excluded from saved results.
• Timed out or response too large: try a narrower query. Adjust requested results in your provider adapter if needed; changing the output-character budget does not change the upstream byte limit.

Verify your changes

Run the deterministic agent suite from the repository root:

pnpm --filter @repo/agent test

The provider tests use local HTTP fixtures and controlled settings; they do not use your API keys or depend on your selected provider. After switching services, also try a public-topic question in chat to verify your network access, account limits, and returned sources. See Testing for the broader agent checks.