Repository navigation
Releases
v0.14.0 - Vendor Modes, a CLI for Agents & Four New Search Backends
Choose how each backend runs and know what it cost, and let coding agents use WebRouter from their terminal.
Upgrade with pip install -U "webrouter[all]". Then read Behaviour Change: some defaults changed.
🚀 What's New
Vendor modes (#315, #324, #327, #343, #347)
- Get the speed or depth you need from one backend: pin one of its own tiers, such as Exa's instant search or Tavily's ultra-fast tier, by naming it in
provider. Works on search, extract, answer and browse, and insideautochains - Know what each call really cost: it is priced at its mode's published rate, in
cost_usdand against any spending limit you set. A mode with no published price never runs under a spending limit - Let a router pick the mode for you: opt in with
route_modes=True, and a mode the backend refuses falls through to the next one at no charge. Vendor modes lists every mode
from web_router import WebRouter
router = WebRouter()
router.search("...", provider="exa:exa-instant") # Exa's instant search type
router.search("...", provider="exa:exa-instant+lite") # the same, at the lite depth
router.search("...", provider="tavily:tavily-ultra-fast")CLI for agents (#330)
- Coding agents with a terminal, such as Claude Code, Codex and Cursor, can now search, read pages and get answers through WebRouter with one shell command, with no MCP server to set up
- Agents can read every result and handle every failure: each method is a
webroutercommand that prints one JSON object, with exit codes to branch on: 1 the call failed, 2 refused before anything was sent, 3 a key or an extra is missing. Try it with no install and no key throughuvx. See CLI
uvx --from "webrouter[search,extract]" webrouter search "rust async runtimes" -n 5 | jq -r '.results[].url'More features
- Four more search backends for
autoto fall back on and for you to compare: Valyu, Seltz, Octen and Keirolabs. Call Valyu, Seltz and Octen withsearch(provider=...);call_vendor()no longer lists them (#257, #258, #259, #264) - Run one MCP server for your whole team:
web-router-mcp --transport httpserves it over HTTP, local by default and on other addresses only withWEB_ROUTER_MCP_TOKEN, and aDockerfileships with it (#348) - Find the right scraper faster: live data search ranks by site, kind of page and country, so "amazon product" finds product pages first. And
extract()tells you which data API (YouTube, GitHub, Wikipedia and others) serves a page's site, so you can call it directly (#256, #280)
🐛 Fixes
timeout=now holds on the syncWebRouter: a slow response no longer runs past your deadline (#348)- When every URL in an extract fails, you get one error with each URL's reason, so you know which to retry (#348)
- Docs: the MCP guide loads again, at /mcp-server, and several pages were corrected (#291, #338, #340)
🔄 Behaviour Change
- Agent tools are safer by default (Claude, OpenAI, LangChain): a model can no longer point them at your internal network, a stuck call ends after 60 s, and a failed call comes back to the model as a message it can act on instead of crashing your agent. Pass
url_policy=Noneortimeout=Noneto undo either (#348) - MCP
load_envreads only.envfiles, so a prompt can't make it read another file on your machine.webrouter[mcp]now installs the browser tools too, so every MCP tool works out of the box (#348) - Keenable now works with spending limits: when you cap spend with
Budget(max_cost_usd=...), WebRouter used to skip Keenable because it had no price. It now has one ($4 per 1,000 requests), so it runs, and its cost counts toward your limit (#349) - If you look up prices by mode, use the new names:
":ultra-fast"is now"tavily-ultra-fast". The old name still works this release, with a warning (#289)
🙌 New Contributors
Full Changelog: v0.13.0...v0.14.0
v0.13.0 - Vendor Data, Live Data & Cost on Every Call
Your agent can now pull data from 372 vendor APIs, from your own ad and log accounts to public data, run ready-made scrapers from four vendors without picking one, and see what every call cost. With Nimble among the keyless providers, you get more free usage before your first API key, and search can go through the LiteLLM proxy your team already runs.
Upgrade with pip install -U "webrouter[all]". If you use the MCP live data tools or plan() and run(), read Behaviour Change first.
🚀 What's New
Vendor data (#132, #133, #134, #249, #281)
call_vendor()calls a vendor's own API with your credentials (your Google Ads reports, your Datadog logs, public data such as FRED) and returns its answer untouched. The catalog lists 372 vendors and 2,708 endpoints inVENDORS.md- Every endpoint is listed as a read, and some reads spend your vendor credits. A write goes through
vendor_request()and must be allowed explicitly. Your credentials go only to that vendor's own host search()also lists the vendor APIs that match a query, from the local catalog at no cost (#250), and agents get the catalog as MCP tools- Every entry is written from the vendor's own API docs, so tell us on GitHub Issues if one doesn't match what the vendor returns
from web_router import WebRouter
router = WebRouter()
router.find_vendor_endpoints("google ads spend by campaign") # matching endpoints, from the local catalog
response = router.call_vendor(
"google-ads.query",
{
"customer_id": "1234567890",
"query": "SELECT campaign.name, metrics.cost_micros FROM campaign WHERE segments.date DURING LAST_30_DAYS",
},
)
response.data # Google's JSON, untouchedLive data from Apify, Bright Data and Oxylabs (#113, #208, #255, #263)
- Where vendor data calls an API you hold an account with, live data runs a vendor's ready-made scraper for one website (a product page, Google Maps places) and returns records. Apify, Bright Data and Oxylabs join Nimble
- Ask once and every vendor you hold a key for is searched, then run the source you pick on its own vendor. Apify and Bright Data were tested against the live services
from web_router import WebRouter
router = WebRouter()
page = router.live_data_sources(query="amazon product") # every vendor with a key, asked at once
source = router.live_data_source(page.sources[0]) # its schemas and samples, from its own vendor
result = router.live_data(source, source.samples[0].input) # run it there; no provider named
result.recordsNimble joins the keyless providers (#279)
- More free usage before your first API key: Nimble now serves search and extract with no key, within a free daily allowance, beside the free tiers WebRouter already had (Tavily, You.com, Exa, Parallel and Keenable for search; Tavily, Jina Reader, Firecrawl and Keenable for extract)
- With no keys set,
auto(the default when you name no provider) tries Nimble first, then falls back through the other free tiers when its allowance is spent, so a first run keeps working for longer
Search through your LiteLLM proxy (#262)
- Teams that already run a LiteLLM gateway can send Exa, Tavily and Parallel searches through it: the vendor keys stay on the proxy, and every call is billed and tracked under your LiteLLM key
- Each keeps the full set of options it has when called directly, and joins
autoafter the free tiers. Tested against a live proxy
Cost and time on every response (#275, #278)
- Know what each call cost and how long it took: every search, extract, answer, research and browse response carries
cost_usdandelapsed_s, the backend's own figure where it states one, an estimate otherwise, orNonewhen neither is known - Budgets are no longer experimental. A new router tries free backends first, and a spend log sums what you spent by day, backend or method
from web_router import Budget, WebRouter
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
log.report() # what you spent, by day, backend and methodReady for production (#273, #276, #284, #286)
- Run WebRouter in a service without surprises: a timeout on search, extract and answer, a cap on calls in flight, a pause on a backend that answers with a rate limit or runs out of credit, and a log line for each fallback
- Every error says what went wrong (a bad key, a rate limit, a bad request, the page itself, a timeout) and whether a retry may help. Fallback stops when the next backend would fail the same way, so a broken URL is no longer billed across every backend
- A new Running in production page covers one shared router per process, threads, logging and warm-up
A lighter MCP server (#272, #277)
- The tool list costs a model about 15% less context per turn, you can serve only the tools you name, and
answerreturns only the sources it cites - The server is listed in the official MCP Registry and on Glama
- With no router named,
plan()andrun()now route by built-in rules: a URL is read, a request for a report or a comparison runs research (billed per run), anything else is searched. Methods you call directly are unchanged - Point WebRouter at your own router service or any OpenAI-compatible model, try several routers in order, and register your own by name
🐛 Fixes
extract()reports a 404 page, a bot challenge or a login wall as a failure instead of a document, and underautoa batch retries each failed URL on the next backend (#270)pip install "webrouter[all]"now includes the MCP server, which crashed on start without it, and a billed MCP tool is no longer marked read-only, so a client that auto-approves read-only tools asks first (#269)- A router shared across threads no longer leaks open connections (#268)
research(provider="auto")no longer starts a second paid run, and Nimble research ateffort="max"runs again (#197, #242)- A variable set in a
.envthe library did not load is now named in the error (never its value), with how to load it (#271)
🔄 Behaviour Change
run_template(),templates()andtemplate()are nowlive_data(),live_data_sources()andlive_data_source(). The old names still work with aDeprecationWarninguntil a later release, but the MCP tools are renamed with no alias:live_data_sources,live_data_sourceandlive_data, whosetemplateargument is nowsource. Their results userecordsandsourceskeys, and MCPanswercounts uncited sources inuncited_sourcesinstead ofcitation_count(#113, #277)- With no router named,
plan()andrun()can now run research, billed per run, for a prompt that asks for a report or a comparison. Passrouter=Noneto keep the old behaviour (#265) - A method call with an invalid argument raises
InvalidParameterError(still aValueError) instead of pydantic'sValidationError(#273) answer(provider="you", recency="day")is refused before the call, since You.com cited pages several days old for it (#239)
Full Changelog: v0.12.0...v0.13.0
v0.12.0 - Nimble Research Citations & Python 3.11
Research with Nimble now cites the sources it read, and WebRouter now needs Python 3.11 or newer.
🐛 Fixes
research(provider="nimble")leftcitationsempty for a run without trust (Nimble's claim-by-claim citations, off by default), although the run returned its sources. Those sources are now the citations, and a run with trust also gains any source its claims leave out (#126)
🔄 Behaviour Change
- WebRouter now needs Python 3.11 or newer. Python 3.10 reached end of life in October 2026, and the security fixes of some dependencies need 3.11. On Python 3.10, pip and uv keep installing 0.11.0; move to Python 3.11 or newer to get 0.12.0 (#127)
Also new: the package description and the README now say what WebRouter is in one line, "an open source standard that connects your agent to the web" (#125).
Full Changelog: v0.11.0...v0.12.0
v0.11.0 - On PyPI as webrouter & New Home
Install WebRouter from PyPI with one command: pip install "webrouter[all]".
🚀 What's New
On PyPI, as webrouter (#122)
pip install "webrouter[all]"oruv add "webrouter[all]", with the same extras as before- Each release is built from its tag and published through PyPI's trusted publishing, with no upload token
A new home: github.com/Nimbleway/webrouter (#121)
- Old links redirect. Report security issues privately through GitHub's vulnerability reporting (see SECURITY.md)
🔄 Behaviour Change
- The package is now named
webrouter(it wasweb-router): change it in your requirements.import web_router, theweb-router-mcpcommand and the MCP server's name are unchanged (#122)
Full Changelog: v0.10.0...v0.11.0
v0.10.0 - Smart Routing, Benchmark-Ranked Defaults & Search Options
Every prompt goes to the right tool and service, within your budget of time and money, and the default order is now the one that scored best on public benchmarks.
🚀 What's New
Smart routing (#102)
- Send each prompt to the right tool and the best service for it, within the time and money you allow, instead of one fixed order for everything
- Plug in any router that decides where a prompt goes. WebRouter gives it every service that could answer, with its estimated price and latency, runs its pick and falls back to the next one if it fails. Four examples to start from: plain rules (no model, no key), a scikit-learn classifier you train on your own prompts, any OpenAI-compatible LLM, and TypeSafe's Jev, which scores each candidate with a probability
plan()previews a prompt,run()runs it, and aBudgetcaps estimated cost and time. Agents get it through the MCP server'sweb_run
from web_router import Budget, RouteDecision, RouteRequest, WebRouter
def route(req: RouteRequest) -> RouteDecision:
if req.urls: # the http(s) URLs in the prompt
return RouteDecision(tools=["extract"])
return RouteDecision() # no opinion: the default order runs
wr = WebRouter(router=route)
response = wr.run("read https://example.com/pricing", budget=Budget(max_cost_usd=0.05))Defaults ranked by benchmark (#74)
- With no router,
autonow tries services in the order that answered best on public question sets: SealQA (hard) for search and SimpleQA for answers. When two services score within the noise, the cheaper one goes first - The order follows the results, not habit: with Brave and Exa keys, Exa now goes first, at a higher price. Set your own order in
provider_config
Search: recency and effort (#108)
recencykeeps results from the last day, week, month or year;effortpicks a faster or more thorough tier, and higher costs moresearch_depthnow means a size:liteabout 500 characters,fasta few thousand,deepthe whole page
Logged-in pages without a browser (#98)
- The login you save in a browser session (since v0.6.0) now also works for
extract(): pass the same profile id withprovider="browserbase"and read pages as that user, with no browser session to start or release
Also new: WebRouter is now licensed under the Apache License 2.0 (#111).
🐛 Fixes
- The MCP server refuses unknown arguments and private URLs instead of dropping or sending them (#109)
extract()counts an error page with no text as a failure, soautotries the next service (#109)
🔄 Behaviour Change
auto's default search and answer orders changed (see above), so with some keys a different service serves first (#74)- The decider proof of concept (
decider=,classify(),execute()) is removed; routers replace it. Pinweb-router==0.9.0to keep it (#102) - Search refuses a value a service cannot serve before sending it, and Parallel moved to its v1 API, which refuses the beta
processorandexcerptsoptions (#108) - The
mcpextra now needs mcp 2.2 or later (#109)
Full Changelog: v0.9.0...v0.10.0
v0.9.0 - answer() & Template Samples
Ask a question and get a written answer with its source links, in one call. Also: sample runs for templates, and one fix.
🚀 What's New
answer(): a written answer with its sources (#53, #65, #66)
- Six answer services, each with your own key: Perplexity, Exa, You.com, Linkup, Parallel and Brave (Brave reads
BRAVE_ANSWER_API_KEY, not the search key). Install theanswerextra and set one key; the README lists each one - By default, WebRouter tries the services you hold a key for, cheapest list price first, and moves on when one fails or has no answer. Each one it tries bills
- Agents can call it too: the MCP server has an
answertool, and the Claude, OpenAI and LangChain tools offer it when you switch it on (#64)
from web_router import WebRouter
with WebRouter() as router:
response = router.answer("who won the 2022 world cup final")
print(response.answer)
for citation in response.citations:
print(citation.field or "-", citation.url)For adapter authors: AnswerProvider, HttpAnswerProvider and register_answer_provider() add an answer service (#53).
Template samples (#38)
template.samplesholds the runs the vendor recorded: an input the template took and the record it returned, so you can see what it needs before you pay for a run- On Nimble, a template listing now includes each template's inputs and samples, in Python and in the MCP server, so one call is enough
🐛 Fixes
- Errors with no message, such as timeouts, now show their type:
search failed: ReadTimeout(#53)
🔄 Behaviour Change
autonow also moves to the next service when one returns nothing (no results, or only blank pages), not only on an error. Each extra service it tries bills. To stop at the first result, setprovider_config={"auto": {"fallback_on_empty": False}}; the MCP server has no such switch (#41)- Template samples moved from
template.extra["samples"]totemplate.samples(#38) - The
max_resultsdescription now suggests 5 to 10 results to an agent (#54) - The
evalsextra now allows openai 3 (#67)
Full Changelog: v0.8.0...v0.9.0
v0.8.0 - AWS AgentCore Web Search
Search through your own AWS AgentCore Gateway, plus PNG screenshots on Anchor.
🚀 What's New
AWS AgentCore Web Search as a search backend (agentcore) (#35)
- Searches through your own AgentCore Gateway, set in
AGENTCORE_GATEWAY_URL. Requests are SigV4-signed with botocore's usual credential chain, for the region in the gateway's hostname. Install the newawsextra (allincludes it) - Maps
max_results(at most 25),include_domainsandexclude_domains(connector 1.2.0 or later; an older target raises rather than dropping them). Queries up to 200 characters. A date range goes throughprovider_options - AWS's terms apply: show each result's citation, and don't store results in bulk
- Setup and teardown:
docs/agentcore-setup.md
from web_router import Provider, WebRouter
response = WebRouter(Provider.AGENTCORE).search("python 3.13 release", max_results=5, include_domains=["python.org"])
print(response.provider, [result.url for result in response.results])🐛 Fixes
- Screenshots on Anchor are PNG. Anchor answered a PNG request with JPEG bytes, so
Screenshot.pngheld a JPEG,widthandheightwere wrong, and the MCP server labeled itimage/png. A capture that is not PNG is now converted with Pillow, which thebrowserextra now installs (#36) - MCP-based search backends no longer treat a reply carried only in
structuredContentas empty (#35)
Full Changelog: v0.7.0...v0.8.0
v0.7.0 - Smart Routing v0, Extract Templates & Max Extract
Route a query to a method with a swappable decision model (experimental), run a vendor's saved site extractors, and race every extract backend for the fastest page.
🚀 What's New
Smart routing v0 (experimental): classify() and execute() (#20)
- Opt-in with
decider=, and the API may change.classify(query)picks the method (search, extract, research or browse) and returns aRouteon that method's defaultautochain.execute(route)runs it - Pick the model that decides:
"keywords"(built-in keyword rules, no key, offline; it picks search or extract, and research or browse fall back to search),"jev"(TypeSafe's Jev),"llm"(any OpenAI-compatible chat model, needs theevalsextra), or plug in your own withregister_decider() - A failed or low-confidence decision falls back to search, with
Route.fallbacksaying why
from web_router import Provider, WebRouter
router = WebRouter(decider="jev") # TypeSafe's Jev, reads TYPESAFE_API_KEY
route = router.classify("Summarize https://example.com/pricing")
route.method # e.g. "extract"
response = router.execute(route)Extract Templates: run_template() (#28)
run_template(name, inputs, provider=...)runs a vendor's saved, site-specific extraction and returns the parsed record.templates()lists them andtemplate()describes one, with the schemas of its inputs and outputprovideris required: a template name belongs to one vendor, so there is noauto. Nimble is the first backend. The MCP server addstemplates,templateandrun_template- An unknown name raises
TemplateNotFoundError. A failed run or a 4xx/5xx page raisesProviderError, never an empty record
router = WebRouter()
template = router.template("walmart_pdp", provider="nimble")
template.input_schema # what `inputs` takes
response = router.run_template("walmart_pdp", {"product_id": "123456789"}, provider="nimble")
response.data # {'title': ..., 'price': ..., ...}max: every extract backend at once (#29)
WebRouter(Provider.MAX).extract(url)sends the request to every backendautowould try and returns the first document back.response.providernames the one that answered- Every fetch is billed, so it costs up to one extract per configured backend per URL. It is never the default
provider_config={"max": {"hedge": 0.8}}runs the first backend alone for 0.8 s and starts the rest only if it hasn't answered
response = WebRouter(Provider.MAX).extract("https://example.com", format="markdown")
response.provider # whichever backend answered firstAlso new: benchmark_extract() compares extract backends on the same URLs, with a scan script in benchmarks/providers/extract.py (#7).
🐛 Fixes
- Nimble enrichments (
researchwithrecords) work as documented, and combinations Nimble refuses now raise before a run starts (#32) - Browser Use steps carry a real
detail, read from the step's memory, and theactionit took (#24) benchmarks/providers/run.pysaves rows as it goes, so a scan that dies keeps what it paid for (#7)
🔄 Changed
Browser Use now maps output_schema, max_steps and allowed_domains (#24). A browse call through auto that sets any of them was refused before; it now starts a Browser Use task.
Full Changelog: v0.6.0...v0.7.0
v0.6.0 - Kernel Browsers & Logged-In Sessions
Log in once and reuse the login across browser sessions, plus Kernel as a browser backend.
🚀 What's New
Log in once, reuse the login (#22)
control_url()returns a link where a person can drive the session, for example to log in. It's a secret, likecdp_url- With an existing vendor
profile(an id; a name on Anchor) andpersist_profile=True, the login is saved on release, and the next session on thatprofilestarts logged in - Works on Browserbase, Steel, Hyperbrowser, Anchor and Kernel (Kernel needs
headless=False).autorefusesprofileandpersist_profile: name the backend
Kernel for browser sessions (kernel) (#21)
- Set
KERNEL_API_KEY. Supportsidle_timeout,stealth,headlessandviewport. Withoutidle_timeout, Kernel ends a session after 60 s idle timeout,solve_captchasandproxy_countryraise an error: Kernel has no session lifetime,stealthalready solves CAPTCHAs, and a proxy country needs a proxy created first- Tried after the other hosted browsers and before
local, so existing calls keep their backend
🔄 Changed
Steel's, Hyperbrowser's and Anchor's interactive live-view links, before only in raw, are now also returned by control_url(). live_view_url is unchanged.
Full Changelog: v0.5.0...v0.6.0
v0.5.0 - DeepSeek Search & Extract, You.com Research
Two new backends and three fixes.
🚀 What's New
DeepSeek for search and extract (deepseek) (#15)
- Set
DEEPSEEK_API_KEY. Domain and locale filters work as on every other backend - Queries over DeepSeek's 128-character limit are refused before sending, so
autofalls through to the next backend
You.com for research (you) (#12)
- Uses the same
YOU_API_KEYas You.com search. Returns a markdown answer with citations effortmaps onto You.com's tiers.output_schemaandcancel()are not supported yet
For adapter authors: ExtractProvider.min_start_interval spaces out fetch starts for backends with a per-second rate limit (#15).
Both backends are added last in auto, so existing calls keep their backend.
🐛 Fixes
- A research or browse call that times out now raises
ResearchTimeoutError/BrowseTimeoutErrorwith the job id, so you can resume the run (#13) - Empty or padded API keys count as missing, which was breaking Jina (#10)
- Bright Data reports an unreachable URL as a failure, not an empty page (#14)
🔄 Behaviour Change
If YOU_API_KEY is your only key, research() through auto now starts a paid You.com run instead of raising ConfigurationError.
Full Changelog: v0.4.0...v0.5.0