WebRouter
一個適用於所有 Web API 的 MCP 伺服器。智慧路由會在您的成本與時間預算內,為每個請求(搜尋、擷取、回答、研究、即時資料或瀏覽器)選擇合適的方法與供應商(涵蓋二十多家供應商),並自動切換備援。即時資料會透過 Nimble、Apify、Bright Data 和 Oxylabs 的現成爬蟲,傳回結構化記錄。可使用您自己的金鑰在本機執行;搜尋與擷取無需金鑰。
文件
WebRouter
The open source standard for agent web access.
One typed interface for search, extract, answer, research, live data and browsers, across two dozen providers.
Documentation · Quickstart · Providers · Examples · Discord
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
extraand the raw payload inraw. - Never silently weaker. An option a provider cannot honour raises
UnsupportedParameterErrorinstead of being dropped, so a call never runs under looser constraints than you asked for. - Routing based on published benchmarks.
autotries 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.provideralways says who answered. - Cost control. Search, extract, answer, research and browse responses say how long they took and, where the backend's price is known, what they cost. 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()andevaluate()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.
Install
pip install "webrouter[all]" # or: uv add "webrouter[all]"
Or try the command line with no install and no key:
uvx --from "webrouter[search,extract]" webrouter search "rust async runtimes" -n 5
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, SpecStream, 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, SpecStream |
| 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.
Command line. The same methods from a shell, printing JSON, for scripts and agents that run commands rather than speak MCP:
webrouter search "rust async runtimes" -n 5 | jq -r '.results[].url'
See Command line for every command and its exit codes.
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.
Data flow
WebRouter runs inside your process, or as an MCP server you start yourself. There is no WebRouter service in between, and nothing to sign up for.
- Each call goes straight from your machine to the backend that serves it, carrying your query or URL and that backend's own key. A key is sent only to its own provider.
- Which backends: the ones you hold a key for, and, when
autohas none left for a method, the free tiers listed in Working with no credentials. Name a provider to keep a call on that backend alone. - Beyond the backends:
call_vendorreaches the vendor API you name, with that vendor's credentials;WEB_ROUTER_MCP_ROUTER=remotesends a prompt to the router service at the URL you set; andevaluate()downloads the question set you pick and calls the judge model you configure. - No telemetry. The package sends no usage data and does not call home.
- Keys stay in the process. They are read from the environment (and, for
the MCP server, from a
.envit is pointed at), held in memory, and kept out of logs and tool results. The server writes no key to disk:load_env'srememberrecords the file's path, never its contents.
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
- Discord: questions in #help, and what you built in #showcase.
- GitHub Issues: bugs and gaps in a provider's support.
- GitHub Discussions: proposals and design ideas.
- SECURITY.md: vulnerabilities. Never in a public channel.
Useful? Star the repo so more agent developers can find it. ⭐
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.