You can use “agent-browser” with Python in two different ways: install the hosted AgentBrowser service’s Python SDK for a direct Python interface, or run the vercel-labs agent-browser CLI from Python with subprocess. They are separate products. The hosted service runs a managed browser; the CLI is a local browser-automation tool. The right choice depends on where you want the browser to run and whether you need Python objects or command-line control.
First, which “agent-browser” do you mean?
The name can refer to products that are not interchangeable. Identify the one your project intends to use before installing anything:
- vercel-labs agent-browser: a native Rust command-line browser-automation tool for AI agents. You ordinarily control it by running CLI commands; Python can orchestrate those commands, but the cited project documentation does not describe it as a Python SDK. Project repository
- AgentBrowser hosted service: a hosted browser with an official Python client. Its documented Python package is
agent-browser-control, while the Python import name isagentbrowser. Service documentation · Python SDK documentation - PyPI’s
agentbrowserproject: a separate Playwright-based package documenting functions such asinit_browser,create_page, andnavigate_to. Do not assume it is either of the products above. PyPI project page
If you want to write Python against a hosted browser, use the official SDK. If you want the vercel-labs tool, install its CLI and invoke it from Python. For a Python library that directly exposes browser APIs, Playwright is another separate option; its browser API documentation covers Chromium, Firefox, and WebKit. Playwright Python Browser API
Use the hosted AgentBrowser service from Python
The hosted service is the Python-first option: install the SDK, supply an API key, open a browser session, then call the session’s screenshot method. The SDK documentation says it supports Python 3.8+ and uses only the Python standard library as a dependency. Official Python SDK documentation
Recommended Free Tools
#1 Best Overall
Install the SDK
python -m pip install agent-browser-controlThe package name you install is not the same as the import name. Import AgentBrowser from agentbrowser:
from agentbrowser import AgentBrowser
ab = AgentBrowser(api_key="gbk_REPLACE_WITH_YOUR_API_KEY")
with ab.session(url="https://example.com", record=True) as session:
png = session.screenshot()
with open("example.png", "wb") as image_file:
image_file.write(png)Replace the example key with the key for your hosted-service account. The documented screenshot() result is PNG bytes, so open the destination in binary mode when saving it. The context manager scopes the session to the with block; save or otherwise process the bytes inside that block if you need the session while doing so.
Use Playwright with a hosted session
If you need Playwright’s page APIs while the hosted service manages the browser session, the SDK documentation shows connecting Playwright to the session’s CDP URL. This is not the same as controlling a local Chrome installation: Playwright connects to the hosted session exposed by s.cdp_url.
from agentbrowser import AgentBrowser
from playwright.sync_api import sync_playwright
ab = AgentBrowser(api_key="gbk_REPLACE_WITH_YOUR_API_KEY")
with ab.session(url="https://example.com", record=True) as session:
with sync_playwright() as playwright:
browser = playwright.chromium.connect_over_cdp(session.cdp_url)
page = browser.contexts[0].pages[0]
print(page.title())This pattern assumes the session provides a usable page in the connected browser context. If your automation needs different Playwright operations, use Playwright’s documented APIs rather than treating the session screenshot method as a full replacement for those APIs.
Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minutePC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Run the vercel-labs CLI from Python
Use this route when you want the vercel-labs CLI workflow, including local browser control, and are comfortable with Python calling external commands. Install the CLI and its Chrome for Testing browser with the documented commands:
npm install -g agent-browser
agent-browser installThe repository also documents Homebrew and Cargo installation channels. Building from source has additional prerequisites: Node.js 24+, pnpm 11+, and Rust. Use the installation method appropriate to the machine and consult the repository for current instructions; install requirements can change.
A small Python wrapper
This integration pattern uses Python’s standard subprocess module to invoke the installed executable. It is inferred from the documented CLI, not a vendor-provided Python API. Save it as capture_page.py and run it with Python after installing the CLI and browser:
import subprocess
def run_agent_browser(*args: str) -> str:
result = subprocess.run(
["agent-browser", *args],
check=True,
text=True,
capture_output=True,
)
return result.stdout
try:
run_agent_browser("open", "https://example.com")
snapshot = run_agent_browser("snapshot", "-i")
print(snapshot)
run_agent_browser("screenshot", "example.png")
finally:
run_agent_browser("close")check=True raises subprocess.CalledProcessError when a command exits unsuccessfully. For debugging, catch that exception and inspect its stderr and returncode attributes. The wrapper returns standard output; the screenshot command writes its image to the named path.
Quick wins for a faster PC:
Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Clear out junk files and repair common Windows errorsFree Scan →Scan for outdated or missing drivers - takes under a minuteDriver Scan →Interact using the snapshot-driven workflow
The CLI quick start describes a workflow of opening a page, taking a snapshot, interacting with an element, and taking another snapshot. A representative command sequence is:
agent-browser open https://example.com
agent-browser snapshot -i
agent-browser click @e2
agent-browser snapshot -i
agent-browser get text @e1
agent-browser screenshot page.png
agent-browser closeIn this example, @e2 and @e1 stand for refs shown in the current interactive snapshot. The actual refs depend on the page; inspect the output and choose the intended target rather than copying those example refs blindly. After clicking or otherwise changing the page, take a fresh snapshot before using refs again. The CLI also supports CSS selectors and semantic role locators. See the quick start and project documentation.
Call the same sequence from Python
Use the wrapper above when you want to inspect output between actions. For example, this version opens the page, prints its current interactive snapshot, and captures a screenshot. It avoids hard-coding a transient element ref:
import subprocess
def run_agent_browser(*args: str) -> str:
result = subprocess.run(
["agent-browser", *args],
check=True,
text=True,
capture_output=True,
)
return result.stdout
try:
run_agent_browser("open", "https://example.com")
print(run_agent_browser("snapshot", "-i"))
run_agent_browser("screenshot", "page.png")
finally:
run_agent_browser("close")For an interaction, inspect the printed snapshot, select a current ref or locator, issue the relevant CLI command, then request another snapshot before choosing a subsequent ref. If a consent banner or modal covers the target, follow the CLI’s reported target, dismiss the obstruction, and refresh the snapshot before retrying.
Choose the hosted SDK or local CLI
| Decision point | Hosted AgentBrowser SDK | vercel-labs agent-browser |
|---|---|---|
| Where the browser runs | Hosted browser session, according to the service documentation. | Local browser workflow after installing the CLI and Chrome for Testing. |
| How Python controls it | Direct Python SDK objects and session methods. | Python can call the CLI through subprocess; this is an integration pattern, not a documented Python API. |
| Credential approach | The service documents a credential vault; the SDK example also initializes with an API key. | The cited CLI installation and quick-start material does not establish an equivalent hosted credential-vault feature. |
| Operational setup | Install the Python package and use a hosted account and API key. | Install the command-line tool and browser on the machine that will run it. |
The hosted route is the cleaner fit when your application should use Python session objects and a managed browser. The CLI route fits projects that already standardize on shell tooling or specifically need local browser control. Those are architecture differences, not a claim that one product supports every workload better.
Keep versions and package names straight
Package and installation details are time-sensitive. At the time of the cited npm listing in 2026, agent-browser was shown as version 0.38.1. That listing also reported Apache-2.0 licensing, zero dependencies, and 1,671,424 weekly downloads; these are npm listing values, not performance or reliability measurements. Check the current npm package page before pinning a version or repeating those figures in deployment documentation.
For reproducible builds, pin the version your project has validated instead of assuming a floating global install will remain unchanged. Also keep the names distinct in dependency files: agent-browser-control is the hosted Python SDK distribution; agentbrowser is its import name and also the name of a separate PyPI project; agent-browser is the CLI package name.
Troubleshoot common failures
Python says it cannot import agentbrowser
For the hosted SDK, the likely mismatch is installing or importing the wrong name. Install agent-browser-control in the same Python environment that runs your script, then import AgentBrowser from agentbrowser. The standalone PyPI project with that import name is not a substitute for the hosted SDK. If using a virtual environment, invoke pip through the same interpreter, for example python -m pip install agent-browser-control.
Do these 3 things before closing this tab:
1Scan for outdated or missing drivers - takes under a minute2Repair Windows errors before they cause bigger problems3Fix the driver behind crashes, sound loss and screen glitchesPython raises “No such file or directory” for agent-browser
This indicates that the executable is not available to the process under that name. Confirm the CLI installation completed and that the shell or Python process has the executable on its PATH. If it was installed globally, check the global npm binary location for the user running Python; an interactive shell and a service process may have different paths.
The browser will not launch
For the local CLI path, run agent-browser install after installing the CLI so its documented Chrome for Testing browser is downloaded. Check the CLI’s output for installation or launch errors. If building the project from source, verify the documented Node.js, pnpm, and Rust prerequisites rather than assuming the prebuilt installation requirements apply unchanged.
A click fails or an element ref no longer works
Refs such as @e1 describe the current accessibility snapshot. Navigation, a click, or a substantial page update can make them stale. Take a fresh agent-browser snapshot -i, select the target in the new output, and retry. When a consent banner or modal blocks a control, dismiss it first and refresh the snapshot.
The subprocess call fails but the terminal command works
Capture and print the exception’s standard error and return code. Common environmental differences include a different executable PATH, a different working directory for output files, or a different user account. Do not silence subprocess errors while diagnosing; check=True is useful because it surfaces nonzero exit status rather than letting the script continue as though the browser action succeeded.
The hosted SDK example cannot create a session
Check that the API key is the one for the hosted AgentBrowser service and that the environment running Python can reach that service. Confirm the installed distribution is agent-browser-control, not the similarly named PyPI project. For service-specific account or session errors, use the official documentation; the available SDK example does not establish exact dashboard labels or detailed error-code meanings.
Or skip the browser setup
If your goal is simply to capture a website image or PDF—not to automate a browser interaction—ScreenshotNeo offers a screenshot API. For example, this Python call saves the response body as an image; see the API documentation for parameters and response details:
import requests
r = requests.get(
"https://api.screenshotneo.com/v1/shot",
params={"access_key": "YOUR_API_KEY", "url": "https://example.com"},
timeout=90,
)
open("shot.webp", "wb").write(r.content)ScreenshotNeo removes cookie banners, popups, and chat widgets before the screenshot; bot checks, blank pages, and failed loads are never billed. Its MCP server lets AI agents take screenshots. The free plan includes 1,000 screenshots per month with no card, and paid plans start at $5 for 3,000.
Sign up for ScreenshotNeo and get 1,000 free screenshots a month with no card.
The Tool Desk
Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Frequently Asked Questions
Can I install the hosted SDK and the local CLI in the same project?
Yes, they are distinct tools with different package names and execution models. Keep their dependencies and setup instructions explicit so teammates know which browser path a script uses.
Is the Python subprocess wrapper an official agent-browser Python library?
No. It is Python code that invokes the documented CLI. The hosted AgentBrowser service, by contrast, publishes a Python SDK.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
