Skip to main content

Web Search

Your agents can search the web and read pages to answer questions about current events, look up facts, or check a website. It's built in and works right away, with no sign-up or API key (a password from a search company). If you want better results, you can add a search service of your own or use Osaurus's premium search.

Get started​

Web search already works. Ask an agent something that needs the web, like "What's the weather forecast for Paris this weekend?" or "Summarize the latest release notes for Safari."

For one of your own agents, check that web search is on:

  1. Open Settings… (⌘ ,) → Agents and pick the agent.
  2. Make sure the Web Search ability is turned on.

How it searches​

Osaurus tries the best option you have first, and falls back automatically if it doesn't work:

  1. Premium search. If you're signed in to Osaurus Router, searches can use Osaurus's hosted search, paid for with your credits. If it can't answer, Osaurus moves on to the next option and notes why.

  2. A search service you add. For higher-quality results, sign up with one of these and paste its key:

    ServiceCost
    Tavily (recommended)Free for 1,000 searches a month
    Exa (recommended)Free for 1,000 searches a month
    Brave Search APIPaid: $5 per 1,000 searches
    Serper (Google results)Free trial credits, then paid
    ParallelPaid: $5 per 1,000 searches
    Google Custom SearchFree for 100 searches a day
    KagiPaid, pay as you go
    You.comFree trial, then paid

  3. Free built-in search. Brave and Bing work with no setup. DuckDuckGo is the last resort, because it sometimes gives automated searches fake results.

Each set of results notes which option provided it.

Adding a search service​

  1. Open Settings… → Web Search.
  2. Pick a service. Its card explains how to sign up and get a key.
  3. Paste the key. Osaurus stores it encrypted.

You can also define your own custom search service; see Under the hood.

Searching vs. reading pages​

Agents have two web tools:

  • Search finds pages: titles, addresses, and short snippets.
  • Search and read opens the top results (or an address you give it) and reads the actual text. It also keeps spreadsheets and data files intact, so an agent can chart them.

Agents are guided to search first, then read a page, instead of rephrasing the same search again and again.

To have an agent click around and use a website, rather than just read it, see Browser Use.

Troubleshooting​

Nothing was found. Osaurus tells you which services it tried, with a tip. Try a broader question, remove limits like a specific site or date range, or add a search service in Settings… → Web Search.

Replaces the osaurus.search plugin

Web search replaces the old osaurus.search plugin. If you had it installed, its card stays in Settings… → Tools & MCP → Plugins with a "Built into Osaurus" banner, but it no longer does anything. Manage search services and keys in Settings… → Web Search.

Under the hood​

The two tools​

ToolWhat it does
web_searchDiscover sources: ranked titles, URLs, and snippets from your configured providers with automatic fallback. It does not fetch page bodies.
search_and_extractSearch plus content extraction. Fetches the top results and returns their readable text (or raw CSV/JSON data). Also accepts direct URLs. This is the fetch tool.

Both tools are in the agent's tool list whenever web search is enabled for it (the Web Search ability on custom agents), and both are removed when it's off. search_and_extract ships alongside web_search rather than behind a capabilities load, so a model that has found a source can read it right away.

Providers​

Osaurus races and falls back across three tiers (premium Router search, API providers you configure, built-in keyless providers) and stamps every result set with the tier that served it. Custom providers use the same declarative request/response schema as the bundled ones; there's no privileged built-in path.

web_search parameters​

web_search takes one required parameter, query. Optional refinements:

ParameterMeaning
max_resultsHow many results (1–50, default 10)
time_rangeRecency: d day, w week, m month, y year
siteRestrict to a domain, e.g. arxiv.org
filetypeRestrict to a file type, e.g. pdf
regionRegion code like us-en
offsetPagination
categoryweb, news, or images, offered only when your enabled providers support more than web search

The tools are forgiving with small local models: an unknown category falls back to web with a warning instead of an error, string numbers are accepted, time-range synonyms ("day", "week", …) are normalized, and unknown fields are ignored. Snippets are capped in length so local models aren't drowned in tokens.

search_and_extract​

  • Query mode. Searches, then extracts the readable main content of the top results (default 3) as markdown, using a Readability-style extractor.
  • Direct-URL mode. Pass one or more url values to skip search and extract those pages directly.
  • Structured data stays raw. CSV, TSV, and JSON endpoints are extracted untouched. Large payloads are kept out of the model's context and referenced by a data_ref handle that tools like render_chart read directly, so charting a 10,000-row CSV never round-trips the data through the model.
  • With premium search, a single hosted request covers search and text extraction together; pages the hosted path can't serve fall back to local extraction per URL.

No results​

A no-results outcome is reported as a structured failure listing the providers attempted, with an actionable hint: broaden the query, drop site:/filetype:/time filters, or configure an API provider.

Related: