Skip to main content
Glama

Developer preview: the API may change before 1.0. Share feedback on Discord.

Every web API for agents has its own SDK, parameter names and response shape. WebRouter puts one interface in front of all of them, so switching provider is one argument, a failing provider falls back to the next, and your agent code never changes.

from web_router import WebRouter

with WebRouter() as router:  # no API key needed to start
    results = router.search("what is retrieval augmented generation", max_results=5, timeout=10)
    pages = router.extract(results.urls[:3], timeout=30)  # markdown, whichever backend serves it

print(results.provider, [doc.url for doc in pages.documents])

Why WebRouter

  • One call shape, every provider. The same request and the same typed response from Tavily, Exa, Brave, Perplexity, Firecrawl, Nimble and the rest. Nothing is lost: unmapped fields stay in extra and the raw payload in raw.

  • Never silently weaker. An option a provider cannot honour raises UnsupportedParameterError instead of being dropped, so a call never runs under looser constraints than you asked for.

  • Routing based on published benchmarks. auto tries the providers you hold keys for in the order committed benchmark results rank them, and falls back on an error or an empty answer. response.provider always says who answered.

  • Cost control. Every response says what it cost and how long it took. Cap a call or a whole session in dollars and seconds, try the free backends first, and keep a log of what you spent (budgets).

  • Keyless to start. Search, extract and a local browser work with no API key. Every key you add unlocks more providers and fallbacks.

  • Built for agents. An MCP server, plus ready-made tools for LangChain, Claude and OpenAI agents.

  • Measure, don't guess. benchmark() and evaluate() compare providers on your own queries and score their accuracy against known answers.

  • Yours to run. Apache 2.0, runs in your process with your own keys, and sends each key only to its own provider.

Related MCP server: nimble-js-mcp

Install

pip install "webrouter[all]"     # or: uv add "webrouter[all]"

Python 3.11 or later. Extras per method (search, extract, research, answer, browser, mcp, ...) keep the install small; see the Quickstart.

Keys are read from the environment. Copy .env.example, which names every variable and where to get it, and fill in the ones you hold.

Methods

Method

What it does

Keyless

search

Web results for a query

Yes

extract

Page contents for URLs, in markdown, html or text

Yes

answer

A written answer with its sources, in one call

No

research

A multi-step research run, as prose or a schema you give

No

live_data

A vendor's ready-made scraper for one site, returning records

No

open_browser

A browser session you drive, local or in the cloud

Yes (local)

browse

A task handed to a hosted browser agent

No

call_vendor

A vendor's own API (Google Ads, Datadog, ...) with your credentials

No

with WebRouter() as router:
    router.answer("who won the 2022 world cup final")  # .answer, .citations
    router.research("how did nvidia's datacenter mix shift in 2025", output_schema=MySchema)
    router.live_data("amazon_products", {"url": product_url}, provider="brightdata")

    with router.open_browser() as browser:  # a local Chromium, no key
        browser.goto("https://example.com")

Every method has an async twin on AsyncWebRouter.

Providers

Method

Providers

Search

Nimble, Tavily, Exa, Brave, Perplexity, Parallel, Linkup, You.com, WebIQ, Keenable, DeepSeek, AWS AgentCore, Valyu, Seltz, Octen, Keirolabs, plus the keyless You.com, Exa and Parallel MCP endpoints

Extract

Nimble, Tavily, Firecrawl, Exa, Linkup, Oxylabs, Bright Data, Jina Reader, WebIQ, Keenable, DeepSeek, Browserbase

Answer

Perplexity, You.com, Linkup, Parallel, Exa, Brave

Research

Nimble, Parallel, Perplexity, Linkup, You.com

Live data

Nimble, Apify, Bright Data, Oxylabs

Browser sessions

Local Chromium, Browserbase, Steel, Hyperbrowser, Anchor, Kernel

Browser agents

Browserbase, Browser Use, Skyvern

Providers has each provider's key, the options it maps and how it was verified. Adding one is two methods: see Adding a provider.

Routing and fallback

For search, extract, answer, research and the browser methods, name no provider and auto serves the call: every provider you hold a key for, in the order committed benchmark results rank them, then the free tiers. A member that fails, is rate-limited or answers empty passes the call to the next. A member that cannot honour an option you set is skipped for that call, and if none can, the call raises rather than running without it. Live data has no fallback, since a source belongs to one vendor: live_data_sources() with no provider searches every vendor you hold a key for, and each source it returns names its own, which live_data() runs it on. Vendor calls always name their vendor, since an account belongs to one.

from web_router import Provider, WebRouter

WebRouter(Provider.TAVILY).search("...")  # one provider, by name
WebRouter().search("...", provider="exa")  # or per call

router = WebRouter(provider_config={"auto": {"chain": {"extract": ["nimble", "firecrawl"]}}})
router.extract(url)  # Nimble, then Firecrawl if Nimble fails

A named provider is never quietly swapped for another: a missing key raises an error naming the variable to set. In a service, share one router per process, set timeout= on each call and turn on the web_router logger: see Running in production. The auto order lists each method's order and how it is generated.

Budgets and cost control

from web_router import Budget, WebRouter, prices

router = WebRouter(router="cheapest_first")  # free backends first, then the cheapest paid ones
log = router.log_spend("spend.jsonl")  # from here on, every answered call is logged
response = router.answer("...", budget=Budget(max_cost_usd=0.01, time_limit_s=10))
response.provider, response.cost_usd, response.cost_source, response.elapsed_s

with router.budget(Budget(max_cost_usd=3.0, time_limit_s=600)) as b:
    b.search("...")
    b.research("...")
    b.status()  # spent, reserved, remaining, time left

log.report()  # what you spent, by day, backend and method
prices.estimate("tavily", "search")  # 0.008: list price of one request

Every response carries cost_usd: the backend's own figure where it states one (cost_source="reported"), else an estimate. Unless a router ranks the backends itself (the default rules router does not), a cost cap makes auto try the cheaper of the backends that score alike first.

Each attempt is checked against what is left before it starts, so parallel calls never overspend together, and a backend that does not fit is skipped with the reason recorded. Estimates come from the list prices shipped in web_router.prices, not your bill. Only search (its keyless backends) and open_browser (local) have a $0 backend; Cost and budgets has the table per method, a fall-back for a batch that runs out, and the spend log. An experimental router can also pick the method and provider for each prompt, and url_policy="public_only" keeps a planned call off private and cloud-metadata hosts. See Smart routing.

Use it from an agent

MCP server. Every method as a tool, running on your machine with your keys:

claude mcp add web-router -- uvx --from "webrouter[mcp]" web-router-mcp

The MCP guide covers Claude Desktop, Cursor and other clients, credentials, tool costs and browser guards.

Agent frameworks. Ready-made web_search and web_extract tools, with a compact rendering for the model and the full response kept for you:

from web_router import WebRouter
from web_router.integrations.langchain import web_router_tools

tools = web_router_tools(WebRouter(), max_results=5)  # LangChain

web_router.integrations.anthropic and web_router.integrations.openai give Claude and OpenAI agents the same tools as plain tool definitions. See Agent integrations.

Compare providers on your own queries

report = router.benchmark("nvidia q3 earnings", providers=["nimble", "tavily", "you-mcp"])
for run in report.runs:
    print(run.provider, run.latency, run.count if run.ok else run.error)

benchmark_extract() does the same for extract, and evaluate() scores each provider's accuracy on a question set with known answers (SimpleQA, FRAMES, SealQA or your own CSV) with an LLM judge. See Benchmarks and evaluation, and benchmarks/ for the published runs behind the default order.

WebRouter or calling each provider directly

Each provider's SDK

WebRouter

Switching provider

Rewrite the call, options and parsing

One argument

Response shape

Different per provider

One typed model, raw payload kept

An unsupported option

Varies by provider

Raises, naming who can serve it

A provider fails

Your retry code

Falls back to the next you hold a key for

Which provider to use

Guesswork

Order from published benchmarks, benchmark() on your queries

Spend

Per-vendor dashboards

Per-call and per-session caps, list prices in the package

Agent tools

One integration per provider

One MCP server and one set of tools

Documentation

Contributing

Contributions are welcome, and the most useful one is small: map one more of a provider's options, or add a provider.

make install  # every extra, dev tools and pre-commit hooks
make check    # lint, typecheck and the offline unit tests; no keys needed

CONTRIBUTING.md has the workflow and the provider checklist, STYLE_GUIDE.md the review standards, and AGENTS.md the rules for AI coding agents working on this repo.

Community

License

Apache License 2.0. The SimpleQA grader prompt vendored at src/web_router/evals/prompts/ keeps its own MIT license, in LICENSE-simple-evals beside it.

Available Tools

18 tools
answerAnswer a question (billed)A

Answer one closed question in a sentence or two: the backend searches and writes the answer, with the sources it cites, each by its marker (e.g. '[2]'). A few seconds. Unset, provider tries the configured backends in ranked order, and each one tried bills. Unedited: check it against the sources when it matters. search returns the pages themselves. NOTHING IS CONFIGURED FOR THIS METHOD on this machine, so every call will fail. A key in one of BRAVE_ANSWER_API_KEY, EXA_API_KEY, LINKUP_API_KEY, PARALLEL_API_KEY, PERPLEXITY_API_KEY, YOU_API_KEY turns it on: see load_env.

Inputs: query (required), snippets, all_sources. Returns: note, answer, handle, provider, +2 more

browseStart a browser-agent task (billed)A
Destructive

Hand a task to a hosted browser agent that clicks and types until done: MINUTES, billed per task. For forms, a site's own search, pages behind interaction; a URL you have is extract's. After 25s it returns a handle: poll browse_status, since calling this again pays for a second task. NOTHING IS CONFIGURED FOR THIS METHOD on this machine, so every call will fail. A key in one of BROWSERBASE_API_KEY, BROWSER_USE_API_KEY, SKYVERN_API_KEY turns it on: see load_env.

Inputs: task (required), provider, max_steps, start_url, +2 more.

browse_statusPoll a browser-agent taskA
Read-only

Poll a task browse started: its state, or the answer and the agent's steps once it has one. Free, about a second.

Inputs: handle (required).

budget_startStart a task budgetA

Start a task budget, max_cost_usd at list prices and time_limit_s from now, that every billed tool spends from; a call that does not fit is refused before it bills. It replaces the previous one, and the operator's ceiling still caps it.

Inputs: max_cost_usd (required), time_limit_s (required).

budget_statusShow the budgetA
Read-only

Where the current budget stands: dollars spent, reserved for calls still running and left, and seconds elapsed and left; and the operator's ceiling, if one is set. Free: it calls nothing.

Inputs: no named parameters.

call_vendorCall a vendor's API with your credentialsA
Destructive

Call a vendor's API with the user's credentials (never shown) and return its answer as sent. Writes are refused unless 'allow_writes' is true and the server allows them. A large answer stays behind the handle for 'fetch_raw'.

Inputs: body, host, path, query, +5 more.

extractRead pages by URLA
Read-only

Read pages you have URLs for, as markdown, HTML or text, in a few seconds. It reads, it does not find: URLs come from search, the user or a page. A page behind a login or clicks is browser_open's. provider='max' races every backend, one fetch each: only when the user wants speed over cost. data_apis: its site's vendor APIs, for call_vendor.

Inputs: urls (required), format, provider, data_apis, +1 more. Returns: note, handle, provider, documents, +1 more

fetch_rawFetch a result's full payloadA
Read-only

The backend's full, unshaped payload for a handle: instant, but can be very large. Use it when a result was cut and you need the rest. Session URLs and credentials in browser payloads are redacted.

Inputs: handle (required).

live_dataRun a live data source (billed)A

Run a live data source and get structured records, scraped for this call. Seconds, up to minutes; bills one run at the vendor's rate. Pass the provider live_data_sources named (optional with one vendor configured); inputs come from live_data_source. For a page no source covers use extract. A failed run is an error, never an empty answer. NOTHING IS CONFIGURED FOR THIS METHOD on this machine, so every call will fail. A key in one of APIFY_TOKEN, BRIGHTDATA_API_TOKEN, NIMBLE_API_KEY, OXYLABS_WEB_API_KEY turns it on: see load_env.

Inputs: source (required), inputs.

live_data_sourceDescribe a live data sourceA
Read-only

Describe one live data source: its input_schema (what live_data passes as inputs), output_schema and recorded sample runs. About a second; free. Read it before a source's first run here. NOTHING IS CONFIGURED FOR THIS METHOD on this machine, so every call will fail. A key in one of APIFY_TOKEN, BRIGHTDATA_API_TOKEN, NIMBLE_API_KEY, OXYLABS_WEB_API_KEY turns it on: see load_env.

Inputs: name (required).

live_data_sourcesList live data sourcesA
Read-only

List live data sources: ready-made scrapers that turn one site's pages (a product, a job listing) into records with fixed fields. About a second. Pass query with the site or page kind; page with limit and offset. Leave provider out to search every configured vendor: each row names its provider, and failures names a vendor that could not answer. Each lists its required_inputs and sample_inputs; live_data_source has the full schemas. NOTHING IS CONFIGURED FOR THIS METHOD on this machine, so every call will fail. A key in one of APIFY_TOKEN, BRIGHTDATA_API_TOKEN, NIMBLE_API_KEY, OXYLABS_WEB_API_KEY turns it on: see load_env.

Inputs: limit, query, offset.

load_envLoad API keys from a .env fileA
Idempotent

Load API keys from a .env file the user names, so their backends work at once. Ask where it is; never ask for a key. Only provider credentials are read, an already-set variable wins, and only names are returned. Set remember (read it on every start) only when the user asks.

Inputs: path (required), remember.

researchStart a research run (billed)A

Start an agentic research run: many turns of searching and reading, which takes MINUTES and bills for the run. For comparisons, datasets or enriching records; a lookup is search's. After 25s it returns a handle: poll research_status, since calling this again pays for a second run. NOTHING IS CONFIGURED FOR THIS METHOD on this machine, so every call will fail. A key in one of LINKUP_API_KEY, NIMBLE_API_KEY, PARALLEL_API_KEY, PERPLEXITY_API_KEY, YOU_API_KEY turns it on: see load_env.

Inputs: query (required), effort, provider, output_schema.

research_statusPoll a research runA
Read-only

Poll a run research started: its state, or the answer once it has one. Free, about a second.

Inputs: handle (required).

vendor_endpointDescribe a vendor API endpointA
Read-only

Describe one vendor endpoint: every input with where it goes and an example, the notes a caller gets wrong without (units, paging, quirks), and the credentials it needs. Read it before 'call_vendor'.

Inputs: endpoint (required).

vendorsFind a vendor API endpointA
Read-only

Find a vendor API (Google Ads, Datadog, ...) to call with the user's own credentials. With 'query', matching endpoints, best first; without, the vendors. Then 'vendor_endpoint' and 'call_vendor'.

Inputs: limit, query, vendor, category, +1 more.

web_runRoute and run a requestA
Destructive

Hand a request in plain words to web-router's router, which picks the method and backends and runs it (by default: a URL is read, a report or comparison researched -- billed, minutes long, so set max_cost_usd -- anything else searched). Call a tool directly for its options. dry_run=true returns the plan and bills nothing.

Inputs: prompt (required), dry_run, max_cost_usd, time_limit_s.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 18 tools

    Disambiguation4/5

    The core retrieval tools are well separated: search finds links, extract reads known URLs, answer returns a sentence, research/browse are long async jobs, and each description explicitly redirects to the right sibling. The main friction is web_run, a meta-tool that overlaps every other tool, plus the near-identical live_data_sources / live_data_source / live_data triple that requires careful reading to distinguish list vs describe vs run.

    Naming Consistency3/5

    Everything is snake_case and readable, but conventions are mixed: verb-first (search, extract, call_vendor, load_env) alongside noun-first status/descriptor names (budget_status, research_status, browse_status, vendor_endpoint, vendors). The live_data / live_data_source / live_data_sources cluster differs only by a suffix, which is a naming hazard even though it is technically consistent.

    Tool Count3/5

    18 tools is in the heavy band for what is essentially a web retrieval router, and several exist only as async status pollers or thin vendor lookups. Each has a defensible role given the multi-backend, budget-aware design, but the surface feels padded by the web_run meta-tool and the three-tool live-data family.

    Completeness4/5

    Coverage is broad and lifecycle-aware: sync search/extract, async research and browse with polling, structured live data, vendor API calls, budget start/status, credential loading, and fetch_raw for truncated payloads. Minor gaps remain: no cancel/abort for long-running research or browse runs, and no way to clear or forget a loaded .env once remembered.

    Maintenance

    ActivityActive
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI assistants to interact with the Nimble REST API, allowing them to explore endpoints, make test requests, and use documentation to help integrate this SDK into your application.
      17,885 npm
      Apache 2.0
    • A
      license
      Not graded
      quality
      D
      maintenance
      A peer-to-peer protocol for AI agents to call tools on each other over HTTP, with cross-provider translation, file transfer, batching, rate limiting, and audit logging.
      MIT