docs
Use it from Python
Embed run_task, request schema-validated data, read citations and events, stream frames, and attach over CDP.
Raw Markdown·Source at the pinned commit
Embed it
uv add fastbrowse first, then:
import asyncio
from pydantic import BaseModel
from fastbrowse import run_task
from fastbrowse.models import Limits
class Release(BaseModel):
package: str
version: str
async def main() -> None:
result = await run_task(
"Find the httpx package and report its name and latest released version.",
start="https://pypi.org/",
output_schema=Release,
limits=Limits(max_dollars=0.10),
)
print(result.status, result.data, f"${result.cost.known_dollars:.4f}")
for evidence in result.evidence:
print(f' "{evidence.quote}" from {evidence.url}')
asyncio.run(main())
Choosing the browser. With no browser argument, run_task starts a Browser Use Cloud browser with
BROWSER_USE_API_KEY, or the key in browser_api_key=. The CLI defaults to your own Chrome through the extension.
chrome=LocalChrome() runs local Chrome instead, and
cloud_extensions=[...] loads up to three of your account's Browser Use Cloud extensions into a cloud browser. cdp_url= or cdp_port= drives a browser already running: the run opens and closes its own tab and leaves
the rest, though cookies the task sets can persist. attach=True, target_match= and foreground=True work as
the matching flags do. Passing a cloud key and a CDP address together is an error.
Recipes and recordings. save_recipe=Path("recipe.json") stores the actions of a completed run. A write failure is logged without changing the task status; check the file before replay.
Pass recipe=Path("recipe.json") with the same task to reuse values when Jev selects a matching live action.
A changed page or control falls back to the agent. Reading and completion are always checked live.
Naming the same file for both arguments saves the healed sequence after another completed run.
Recipes can contain personal information from ordinary fields; stored secrets are kept only by name.
fastbrowse.recipes.validate_recipe() checks recipe JSON with the same Rust parser as the file loader;
recipe_schema() exports its JSON Schema for client validation.
record=Path("run.mp4") writes captioned and plain videos, and needs ffmpeg. The action cursor also needs ffprobe; if frame dimensions cannot be read, the cursor is omitted with a warning.
A cloud browser that outlives a run. open_cloud_browser(browser_api_key=...) starts a Browser Use Cloud
browser no run owns and returns a CloudBrowser with its id, cdp_url and live_url. It takes run_task's
cloud options without the cloud_ prefix (profile=, extensions=, timeout_minutes= and the rest). Runs given
its cdp_url with attach=True leave it running, and stop_cloud_browser(browser, browser_api_key=...) stops
it; until then it bills, up to its timeout. A start that fails or is cancelled stops the browser it created.
from fastbrowse import open_cloud_browser, run_task, stop_cloud_browser
async def main() -> None:
browser = await open_cloud_browser(browser_api_key=KEY, profile=PROFILE_ID, timeout_minutes=60)
print("watch at", browser.live_url)
try:
await run_task("Open my inbox.", cdp_url=browser.cdp_url, attach=True)
finally:
await stop_cloud_browser(browser, browser_api_key=KEY)
Your own script on the page. connect_cdp() hands you the attached page without the agent:
from fastbrowse import connect_cdp
async def main() -> None:
async with connect_cdp(9222, target_match="my-project") as page:
print(await page.observe())
Moving from 0.8. The Python modules that 0.9 removed with the Python core have these replacements:
| 0.8 import | Now |
|---|---|
fastbrowse.adapters.browser_use_cloud.BrowserUseCloudBrowser | open_cloud_browser to start one and stop_cloud_browser to stop it, without the http= and allow_resizing= arguments |
fastbrowse.models.BrowserConnection | fastbrowse.CloudBrowser, holding id, cdp_url and live_url |
fastbrowse.clients.environment.Settings | run_task(settings={...}), keyed by the environment variable names |
fastbrowse.adapters.totp (TotpError, one_time_code) | fastbrowse.totp |
Access controls:
allowed_origins=["https://app.example.com"]limits the documents a run may read and control to those exact origins. Navigations, redirects, frames and popups elsewhere are refused before they are sent, so a sign-in that redirects through another origin needs it listed too. It scopes documents, not the network, and a scoped run sends no live frames or screenshots and cannot record. The JavaScript, Go, Java and .NET clients take it asallowedOriginsorAllowedOrigins.check_access=, which only the Python API offers, is an async callback awaited before the browser starts and before every read, navigation and action. If it raises, the run ends with statuserror(connect_cdpraisesBrowserError), naming only the exception's type.
Citations. result.citations holds a Citation per numbered link in result.answer: id, text,
url, quote and deep_link. Each claim cites the notes it states. A count, total, cheapest or largest
value is worked out in code from every note read and cites each record it rests on. A quote is the page's text, a table row as its cells separated by spaces. A deep_link is a text fragment URL that
scrolls to the quote; it may not resolve on a page that changes or needs a session. Each page a quote was read from
is kept as a capture artifact in result.artifacts, holding the masked page text, and the quote's Evidence
names it in capture_artifact; start and end index into that text. Its links lists each link inside the
quote: the link's text, where that text sits as start and end, and the href it leads to. Captures go where downloads go, so pass
downloads or artifact_sink to keep them past the run. A page fetched over HTTP keeps none.
Watching a run.
-
on_event=gets aBrowserEventwith a cloud browser's live-view URL, then aStepEventper step, carrying the facts that step added.Config(step_frames=True)adds a PNG of each step's page. -
A task requesting a final screenshot receives a safe PNG in
result.final_framewithout enabling step frames. JSON clients receive ascreenshotartifact with a base64 data URI. A missing requested image leaves a completed taskunverified. -
Config(step_choices=True)addschoicesto each step Jev decided: the controls it was offered, each with itsid,role, maskedlabelandcontext(the card or row that tells twins apart) andoperations, and the one it picked markedchosen(a drag marks its destination too). It shows whether the element a run should have used was there to pick. Off, a step has nochoiceskey. -
on_frame=gets JPEG frames of the active tab as they render. The handler runs on your event loop, so it must honour cancellation: one that swallowsCancelledErrorkeepsasyncio.runwaiting at shutdown.A cancelled
run_taskraisesfastbrowse.models.RunCancelled, anasyncio.CancelledErrorwith areceiptof reported steps, known cost lines and finished recordings once the browser closes. A cancellation before the core starts may have no receipt. The receipt has no status or answer; unpriced charges stayunknown.ConfigurationErrorandRecordingErroralso carry areceiptwhen they stop a run after work or charges have accrued; otherwise theirreceiptisNone. JSON-RPC preserves this receipt in error data, or in the error result for recording failures. MCP keeps it in_meta["fastbrowse.ai/receipt"]beside the tool error. A callback failure raises the original exception with areceiptattribute when the core retains one, including when the callback fails as the run completes. -
with traced() as events:collects the run's trace in-process, as--tracewrites it.
No frame or screenshot is sent while a resolved secret may show on the page.
run_task(jev=...) and run_task(llm=...) take your own decision model or LLM client; a jev client is asked at
Jev's limits and thresholds. See Jev routing and fastbrowse.llm.
Choosing the model backend without the environment. New in 0.9.1.
run_task(settings={...}) takes the same names as the
environment variables (OPENROUTER_API_KEY, AI_GATEWAY_API_KEY, TYPESAFE_API_KEY, FASTBROWSE_DECISION_SOURCE,
FASTBROWSE_LLM_PROVIDER, FASTBROWSE_LLM_MODEL and the rest) and reads them instead of the environment and
.env, so a service that keeps its credentials elsewhere hands the run exactly the keys it means to:
result = await run_task("Find the latest httpx release", settings={"OPENROUTER_API_KEY": my_key})
The same rules outside a run. New in 0.9.1. fastbrowse.origins (origin_of, parse_origin) parses allowed_origins as the
run does; fastbrowse.safety (secret_allowed, origin_of, ScopedSecrets) answers where a secret may be typed,
*. patterns included; fastbrowse.totp.one_time_code(key) makes the codes an authenticator key gives. Each wraps
the core's own rule, so the answer before a run is the one the run gives.
hosted
Run fastbrowse over an API
The same agent behind an API. Keys, secrets, run history and spend limits live in the console. Free to start.