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. When no provider is configured, the system prompt tells the model, so it will not attempt the tool and will let you know if you ask it to search.

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.

Brave Search

Brave Search runs an independent web index and 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

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

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

Kagi maintains its own search index with a strong privacy focus. General web results include titles, snippets, and publication times.

Sign up at the Kagi API Dashboard.

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

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

Sign up at you.com.

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}

Polytoken includes a provider in the rotation only when integrations.search.providers.<name>.enabled is true and integrations.search.providers.<name>.key contains at least one non-whitespace character after resolving environment references. Every provider block requires an integrations.search.providers.<name>.key value.

Polytoken resolves environment references throughout the configuration file before considering whether providers are enabled. A reference to an unset variable therefore causes the configuration load to fail, even for a disabled provider.

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.

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

When a search provider fails, Polytoken stops using that provider for the rest of the session and tries the next available provider. The search attempts continue until a provider succeeds or every enabled provider has failed. Reloading Polytoken makes the configured search providers available again.

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. The model can set the maximum result count for each web_search call through max_results. Polytoken uses a default count when the model omits max_results and caps larger requests.

See Tool Reference for the web_fetch tool to read a page from a search result.