Skip to content
Polytoken

Web Search

Web search lets the model find current information during a turn. When the model calls the web_search tool, Polytoken sends the query to one of your configured search providers and returns the results so the model can reason about them. The model decides when to search. You decide which providers Polytoken can access and how Polytoken picks among them.

Providers

Section titled “Providers”

Polytoken supports six hosted search providers. You can enable one or several. When you enable more than one, Polytoken spreads calls across them according to the strategy you choose.

Section titled “Brave Search”

Brave Search runs its own independent web index. It returns general web results with titles, descriptions, sources, and page ages.

Sign up at the Brave Search API dashboard. New accounts receive a free monthly credit allowance.

Tavily

Section titled “Tavily”

Tavily is a search API built for AI agents and research workflows. It returns results with content snippets and relevance scores, tuned for the kinds of queries an agent makes during a task.

Sign up at app.tavily.com. A new account starts with a free monthly allowance of API credits, and signup does not require a credit card.

Exa

Section titled “Exa”

Exa is an AI-native search engine that finds pages by meaning rather than keyword match. Alongside titles and summaries, Exa can return highlights and published dates, which helps when the model is researching recent or topical material.

Sign up at the Exa dashboard. The free tier allows a high monthly request volume.

Kagi

Section titled “Kagi”

Kagi runs its own independent search index with a strong privacy focus. It returns general web results with titles, snippets, and publication times.

Sign up at the Kagi API Dashboard.

Parallel

Section titled “Parallel”

Parallel provides web search for research workflows. It returns page titles, URLs, excerpts, and publication dates.

Sign up through the Parallel documentation.

You.com

Section titled “You.com”

You.com provides web search with snippets and page-age metadata. You.com offers $100 in free credits, then charges $5 per 1,000 calls. Snippets do not add an extraction charge.

Sign up at you.com.

Section titled “Configuring search”

Configure web search under integrations.search in your configuration file. For each provider you want to use, set integrations.search.providers.<name>.enabled to true and provide an API key. Keys are usually environment references.

integrations:
  search:
    strategy: round_robin
    providers:
      brave:
        enabled: true
        key: ${BRAVE_API_KEY}
      tavily:
        enabled: true
        key: ${TAVILY_API_KEY}
      exa:
        enabled: false
        key: ${EXA_API_KEY}
      kagi:
        enabled: false
        key: ${KAGI_API_KEY}
      parallel:
        enabled: false
        key: ${PARALLEL_API_KEY}
      you:
        enabled: false
        key: ${YOU_API_KEY}

A provider counts as enabled only when integrations.search.providers.<name>.enabled is true and its key resolves to a non-empty value after environment substitution. A provider you list but disable, or one whose key is unset, stays out of the rotation.

Choosing among enabled providers

Section titled “Choosing among enabled providers”

integrations.search.strategy controls how Polytoken picks a provider for each web_search call when you have more than one enabled:

  • round_robin (the default) rotates through your enabled providers in order, so consecutive calls use different providers.
  • random picks one provider per call at random.

With a single provider enabled, both strategies always select that provider.

Provider failover

Section titled “Provider failover”

When a provider fails, Polytoken benches that provider for the rest of the session and tries the next available provider. Polytoken continues this process until a provider succeeds or every enabled provider has failed. A daemon reload clears the bench state and re-enables all configured providers.

The Web Search pane in the interactive configurator (polytoken config ui) lets you toggle each provider on and off, set keys, and switch the strategy without editing the file by hand. See Application Configuration for the full key reference.

Results

Section titled “Results”

Every provider returns results in a consistent shape, so the model works with the same fields regardless of which provider answered. Each result carries a title, a URL, and a snippet. Some providers also supply a published date, a source, and a relevance score. Each search returns a bounded number of results, set by the provider’s own limit.

Section titled “Related pages”