Configure web search

web_search discovers current public sources. It returns titles, URLs, snippets, optional publication dates, and provider metadata; it does not fetch the full page. Follow a result with web_fetch for readable web content or http_request for an API.

Choose a provider

Jazz supports seven search backends:

Choose a provider you have an account with, then configure its key below.

Configure globally

Set the provider and its key:

jazz config set web_search.provider brave
jazz config set web_search.brave.api_key

When the value is omitted, Jazz prompts without echoing the secret. The wizard stores it in the system keyring when one is available. In CI or containers, inject the matching environment variable instead.

Equivalent non-secret configuration:

{
  "web_search": {
    "provider": "brave"
  }
}

Override per agent

Set config.webSearchProvider in an agent definition when one agent should use a different backend:

{
  "config": {
    "webSearchProvider": "exa"
  }
}

The agent-specific selection wins over web_search.provider; its key still resolves through Jazz secret storage or EXA_API_KEY.

treg: free first, paid fallback

Select treg and provide a treg token using jazz config set web_search.treg.api_key or TREG_TOKEN. Each search calls TinyFish’s free endpoint directly. If it errors or finds no results, Jazz tries the routed endpoint once, excluding TinyFish, with a $0.05 treg-metered cost cap per fallback call. Owned provider keys can incur upstream charges outside treg’s cap. A failed or over-cap fallback returns an error; it does not retry. Other agents’ providers are unchanged.

TinyFish receives query and date hints; routed fallback uses only query and maxResults. Depth, source-type, and alternative-query hints are not enforced, and fallback cannot guarantee date filtering. Check treg’s catalog for current routes and prices.

Routed results keep their provider’s source text: Jazz uses a snippet when present, otherwise content or joined excerpts/highlights. Publication dates may come from date or publish_date; an absent or unrecognized date is omitted.

Search contract

The model may supply:

• query: required research goal, up to 5,000 characters;
• searchQueries: up to five short alternative phrases;
• searchDepth: fast, standard, or deep;
• fromDate and toDate: ISO dates in YYYY-MM-DD form;
• sourceType: web, news, academic, company, people, or financial;
• maxResults: 1–100, default 20.

These are normalized hints. Some providers ignore depth, date, source type, or alternative-query fields. A returned publication date may also be absent. Workflows that depend on recency must verify dates from the fetched source rather than assuming the search filter was enforced.

Security and failure behavior

Search is classified read-only but sends the model’s query to the configured provider. Do not put secrets or private document excerpts in a search query.

If no provider or key is configured, web_search returns an error to the agent. Jazz does not silently switch configured providers or invent results. The treg provider is an explicit exception within its own backend: it tries TinyFish, then a capped paid treg route on failure or empty results. Result volume is capped, and the agent should fetch and cite primary sources before treating snippets as evidence.

Verify the setup

Start the intended agent and ask for a time-bounded search that requires current information:

jazz agent chat <agent-name>

Find the three most recent official releases for Bun. Give me the release date and direct release URL for each. State when a date cannot be verified.

Confirm the agent invokes web_search, follows relevant results, and cites direct sources. The weekly research radar shows a bounded scheduled workflow built on this contract.

See Secrets and egress for query disclosure and Model providers for the separate LLM configuration.