# web-router

Adopt this skill: https://proskills.md/skills/other/nimbleway-webrouter-skills-web-router

Page: https://proskills.md/skills/other/nimbleway-webrouter-skills-web-router
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: skills/web-router/SKILL.md
size: 4260
sha: 24226afca1d8b3013613baf686b8d4999eeab766
upstream: https://github.com/nimbleway/webrouter/blob/main/skills/web-router/SKILL.md

```text
---
name: web-router
description: >
  Search, read and research the web through web-router's MCP tools, choosing
  the cheapest method that answers. Use when a task needs live web data —
  finding pages, reading a known URL, multi-step research, or driving a
  browser — and the web-router MCP server is connected. Covers method
  selection, cost awareness, job polling, and browser-session hygiene.
---

# web-router

One typed interface over many web backends, six methods. The tools describe
*your* install: their `provider` enums list only backends this machine holds
keys for, and `search`/`extract` work with no key at all. Read the
`web-router://capabilities` resource once to learn what is configured before
planning around a paid method.

## Choose the cheapest method that answers

Work up this ladder and stop at the first rung that serves the task:

1. **`search`** — find pages. Ranked links with page text, about a second,
   free on the keyless tier. Most questions end here.
2. **`extract`** — read pages you already have URLs for, about a second.
   Prefer `search` + `extract` over anything below: two cheap calls that you
   compose beat one expensive call you wait on.
   **`live_data`** sits beside it: when `live_data_sources` lists a vendor's
   ready-made scraper for the site and item at hand (pass `query` to search
   the catalogue), one run fetches the site now and returns its fields as
   records, one billed run. All three live data tools need `provider` named.
   Read `live_data_source` first — its `input_schema` says exactly what
   `inputs` to pass, a URL for some sources and an id or a search term for
   others.
3. **`research`** — an agentic run that searches, reads and cross-checks over
   many turns. **Minutes, and it bills.** Use only when the question genuinely
   needs synthesis across many sources that iterative `search`/`extract`
   cannot reach in a few calls.
4. **`browse`** — a hosted browser agent drives a real browser through a task.
   **Minutes, and it bills.** Use when the answer is behind interaction —
   forms, pagination, dynamic pages — and you can state the task in one
   sentence.
5. **`browser_*`** — you drive the browser yourself. `local` is free; a cloud
   session **bills per minute until closed**. Use when the interaction needs
   your judgment step by step rather than a delegated task.

## Cost rules

- Never start a second `research` or `browse` run for a question whose first
  run is still going: `research`/`browse` return a handle after ~25 seconds —
  poll `research_status`/`browse_status` (free) instead of calling the method
  again, which starts and bills a second run.
- `fetch_raw` is free and instant: every result carries a `handle`, and the
  backend's full payload is already held for it. Reach for `fetch_raw` before
  re-calling a tool for more detail.
- Close every browser session with `browser_close` the moment you are done.
  Prefer `provider="local"` unless the task needs stealth, a proxy country or
  CAPTCHA solving, which only billed cloud vendors serve.
- Leave `provider` unset (`auto`) unless you have a reason: it prefers the
  backends configured here and falls back to the keyless tier.
- `extract` with `provider="max"` reads the page through every configured
  backend at once and returns the first answer -- the fastest read possible,
  at one fetch per backend. Use it only when the user has asked for speed
  over cost, never by default.

## What the tools will and will not do

- A parameter a backend cannot serve is refused by name, never silently
  dropped — on a refusal, drop the option or pick another provider; do not
  retry the same call unchanged.
- Results are shaped to fit a context window and say when they were cut; the
  handle gets you the rest. Do not treat a truncation note as missing data.
- Browser tools open only `http:`/`https:` pages and `about:blank`; refs from
  `browser_snapshot` go stale on the next snapshot or navigation — take a
  fresh snapshot after the page changes rather than retrying a stale ref.
- The server never shows you a CDP URL, live-view URL or credential, and
  redacts them from every browse and browser output. Do not ask for them or
  try to reconstruct them.
```

## File: README.md
upstream: https://github.com/nimbleway/webrouter/blob/main/README.md

````text
<p align="center">
  <img src="https://raw.githubusercontent.com/Nimbleway/webrouter/main/docs/assets/webrouter-mascot.png" alt="WebRouter" width="360">
</p>

<h1 align="center">WebRouter</h1>

<p align="center"><strong>The open source standard for agent web access.</strong></p>

<p align="center">
  <a href="https://pypi.org/project/webrouter/"><img src="https://img.shields.io/pypi/v/webrouter?color=202c26&label=pypi" alt="PyPI"></a>
  <a href="https://github.com/Nimbleway/webrouter/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-202c26" alt="License: Apache 2.0"></a>
  <a href="https://pypi.org/project/webrouter/"><img src="https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13-202c26" alt="Python 3.11 to 3.13"></a>
  <a href="https://github.com/Nimbleway/webrouter/actions/workflows/ci.yml"><img src="https://github.com/Nimbleway/webrouter/actions/workflows/ci.yml/badge.svg?branch=main" alt="CI"></a>
  <a href="https://discord.gg/MGztFWSjZh"><img src="https://img.shields.io/badge/Discord-5865F2?logo=discord&logoColor=white" alt="Join WebRouter on Discord"></a>
</p>

<p align="center">
  <a href="https://docs.webrouter.net"><strong>Documentation</strong></a> ·
  <a href="https://docs.webrouter.net/quickstart">Quickstart</a> ·
  <a href="https://docs.webrouter.net/providers">Providers</a> ·
  <a href="https://github.com/Nimbleway/webrouter/tree/main/examples">Examples</a>
</p>

WebRouter connects agents to search, extract, live data, answer, research and
browsers through one typed interface, across many providers.

- **Agent web primitives.** Find pages, read them, ask for an answer, run
  deep research, call a site's structured scraper, or drive a browser.
- **Smart routing.** Static fallback and optional routers trade off cost,
  latency and coverage for each task and the providers you have keys for.
- **No vendor lock-in.** Calls and results keep the same shape when you switch
  providers. WebRouter is Apache 2.0 and runs with your own keys.
- **Providers and vendor APIs.** Use one call shape across web providers, then
  use the curated catalog for provider-specific APIs.
- **Governance and security.** Control provider selection and routing, keep
  keys scoped to their provider, reject unsupported constraints, and require
  explicit opt-in for vendor writes.

<p align="center"><em>Useful? Star the repo so more agent developers can find it.</em> ⭐</p>

> **Developer preview:** the API may change before 1.0. Share feedback on [Discord](https://discord.gg/MGztFWSjZh).

## Quickstart

Install WebRouter and make a search with no API key:

```bash
pip install "webrouter[all]"
```

```python
from web_router import WebRouter

response = WebRouter().search("what is retrieval augmented generation", max_results=5)

for result in response.results:
    print(result.title, result.url)

print(response.provider)  # which backend actually answered

pages = WebRouter().extract(response.urls[:3], format="markdown")
for document in pages.documents:
    print(document.url, len(document.content))
```

The [full Quickstart](https://docs.webrouter.net/quickstart) adds a named
provider, API keys, async usage, install extras and source setup.

[Runnable examples](https://github.com/Nimbleway/webrouter/tree/main/examples)
cover each core method, routing, integrations and common errors. Most need no
credentials.

## Documentation

The docs site is the canonical guide for getting started and for the core
methods. This README keeps the advanced and contributor-facing surfaces that
have not moved there yet.

| Start here | Core methods | Reference |
| --- | --- | --- |
| [Introduction](https://docs.webrouter.net) | [Search](https://docs.webrouter.net/search) | [Configuration](https://docs.webrouter.net/configuration) |
| [Quickstart](https://docs.webrouter.net/quickstart) | [Extract](https://docs.webrouter.net/extract) | [Errors](https://docs.webrouter.net/errors) |
| [How it works](https://docs.webrouter.net/how-it-works) | [Answer](https://docs.webrouter.net/answer) | [Providers](https://docs.webrouter.net/providers) |
| [Examples](https://github.com/Nimbleway/webrouter/tree/main/examples) | [Research](https://docs.webrouter.net/research) | [MCP server](https://github.com/Nimbleway/webrouter/blob/main/docs/mcp.md) |
|  | [Browser sessions and agents](https://docs.webrouter.net/browser) |  |

## Provider support

Twelve search backends, seven extract backends, a live data catalogue, five
answer backends, three agentic research backends (plus Exa's, retired upstream), five
browser-session backends and three browser agents. One call each. Switching
between them is one argument.

A provider name serves the methods it serves and no others: `brave` searches
and cannot extract, `oxylabs` extracts and cannot search, `nimble` searches,
extracts, runs live data and researches, and `browserbase` opens
sessions, runs browse tasks and extracts.
Ask a method for another's backend and it says so, naming the backends that
method does serve.

### Search

`[search]` installs all of these but AgentCore, which needs `[aws]`. The first column is what you pass to
`WebRouter(...)` to pick one at runtime. The string beside it is the same value,
and what `response.provider` and `configured_providers()` report back.

| Pass | Name | Provider | Backed by | Options mapped |
| --- | --- | --- | --- | --- |
| `Provider.NIMBLE` | `nimble` | [Nimble](https://nimbleway.com) | `nimble-python` | all but `effort` |
| `Provider.TAVILY` | `tavily` | [Tavily](https://tavily.com) | `tavily-python` | all but `effort` |
| `Provider.YOU` | `you` | [You.com](https://you.com/platform) | direct HTTP | all but `effort` |
| `Provider.BRAVE` | `brave` | [Brave](https://brave.com/search/api/) | direct HTTP | all but `effort`; `search_depth` at `lite` only |
| `Provider.EXA` | `exa` | [Exa](https://exa.ai) | direct HTTP | all but `locale` |
| `Provider.PARALLEL` | `parallel` | [Parallel](https://parallel.ai) | direct HTTP (`/v1/search`, `mode=fast` unless `effort` sets it) | all but `locale`; `search_depth` at `lite` and `fast` |
| `Provider.PERPLEXITY` | `perplexity` | [Perplexity](https://docs.perplexity.ai) | direct HTTP | all of them; `search_depth` at `lite` and `fast` |
| `Provider.LINKUP` | `linkup` | [Linkup](https://www.linkup.so) | direct HTTP | `max_results`, `include_domains`, `exclude_domains`, `recency`, `effort` |
| `Provider.WEBIQ` | `webiq` | [WebIQ](https://api.microsoft.ai) (Microsoft AI Web Search) | direct HTTP | all but `recency` and `effort` |
| `Provider.KEENABLE` | `keenable` | [Keenable](https://docs.keenable.ai) | direct HTTP; keyless with `allow_keyless=True` (rate-limited per IP) | `max_results`, `search_depth` (`lite`, `fast`), `include_domains` (one), `recency`, `effort` |
| `Provider.DEEPSEEK` | `deepseek` | [DeepSeek Search](https://api-docs.deepseek.com/guides/search) | direct HTTP | `max_results` (at most 50), `search_depth` (`lite`, `deep`), `include_domains`, `exclude_domains`, `locale`, `recency`, the last four sent inside the query, which must fit 128 characters |
| `Provider.AGENTCORE` | `agentcore` | [AWS AgentCore Web Search](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway-target-connector-web-search-tool.html), through your own AgentCore Gateway ([setup](docs/agentcore-setup.md)) | MCP over HTTP, SigV4 via `botocore` (`[aws]`) | `max_results` (at most 25), `include_domains`, `exclude_domains`, `recency` (connector 1.2.0 or later). An end date is AgentCore's own `provider_options={"filters": {"publishedDateFilter": {"to": ...}}}`. Queries up to 200 characters. AWS's terms: show each result's citation, and do not store results in bulk |
| `Provider.YOU_MCP` | `you-mcp` | [You.com MCP](https://api.you.com/mcp) | direct HTTP, **no key** | all but `effort` |
| `Provider.EXA_MCP` | `exa-mcp` | [Exa MCP](https://exa.ai/docs/reference/exa-mcp), its `web_search_advanced_exa` tool | direct HTTP, **no key** | all but `locale` |
|
````
