Browser Use Tool

Drive a real browser to navigate sites, click buttons, fill forms, log in, scrape content, and download files

What it does

The Browser Use tool gives your agent a secure, sandboxed web browser. Unlike a simple scraper, it can actually interact with a page — click buttons, fill and submit forms, log in behind authentication, and work through multi-step flows — then read the result. Use it when the information you need lives behind a login, a search box, a “Load more” button, or any workflow a person would click through by hand.

Each conversation has one browser that every call continues in: same page, same tabs, same login. You can watch it live from the chat, and when a site needs something only you can do (signing in, a 2FA code, a CAPTCHA), the agent hands you the browser. Sign-ins you complete are saved to your browser logins, so your agents start signed in next time, including in your scheduled tasks.

Key features

• Navigate to any page, then click, type, and submit like a real user
• Accessibility-tree snapshots give the agent stable element references to act on
• Hand off to you: the agent gives you the live browser to sign in, and it never sees what you type
• Saved logins: sites you sign into stay signed in for future conversations and scheduled tasks
• Watch live: open the agent’s browser from any browser step in the chat
• Screenshots: the agent can look at the page itself, and you see the same image in the chat
• Log in with org secrets: real passwords are filled in server-side and never seen by the agent
• Download files (CSVs, PDFs, reports) straight into the conversation as attachments
• Runs in an isolated cloud sandbox — nothing touches your own machine

Parameters

Parameter	Type	Required	Description
code	string	Yes*	The commands to run. In bash mode, these are agent-browser commands (the agent-browser prefix is added automatically)
language	string	No	bash (default) for the simple navigate/click/fill commands, or python / node for Playwright APIs (required for downloads and advanced automation)
handoff	string	No	Give you control of the live browser after the code runs, with this instruction shown to you (for example “Sign in to Aspire”). The agent then waits for you. Not available in scheduled tasks
screenshot	boolean	No	Capture the page after the code runs (or on its own, without code). The agent sees the image, and so do you
new_session	boolean	No	Close this conversation’s browser and start a fresh one first. Saved logins still load
close_session	boolean	No	Close the browser when finished (default: false)
timeout	number	No	Seconds the code may run before it’s stopped (default 30, max 600)
skill, function, payload		No	Run a function a skill publishes instead of code, passing data rather than a script

* Not needed with screenshot alone, or when running a skill function.

The core workflow

Every browser task follows the same loop: navigate → snapshot → interact → re-snapshot.

1. open <url> — go to a page
2. snapshot — get the page’s accessibility tree with @ref IDs (@e1, @e2…) for each interactive element
3. Act on those refs — click @e1, fill @e2 'text'
4. Re-snapshot after anything that navigates or changes the page — old refs are invalidated

Each tool call runs a single command; commands are not chained with &&.

Common use cases

Navigate and read a page

open https://example.com/pricing
snapshot

The snapshot returns the page structure with refs. Use read to pull the page’s readable text.

Fill and submit a form

open https://example.com/search
snapshot
fill @e3 'quarterly report'
click @e5

Always snapshot first to get fresh refs, then re-snapshot after the submit to read the results.

Log in without exposing credentials

open https://portal.example.com/login
snapshot
fill @e1 '{{secret:PORTAL_USERNAME}}'
fill @e2 '{{secret:PORTAL_PASSWORD}}'
click @e3

Reference an org secret by name. The real value is injected server-side just before execution and redacted from the output — the agent never sees it.

Let the user sign in

When a site needs a person (a personal login, a 2FA code, a CAPTCHA), the agent opens the page and hands it over:

open https://portal.example.com/login

with handoff: "Sign in to the portal". The chat shows the live browser with a Your turn banner. Sign in, click Done, and the agent continues. Sites whose cookies changed while you had control are saved to your browser logins, so you won’t need to sign in there again.

Look at the page

Pass screenshot: true to capture the page as an image after a command. Use it to read charts, check a layout, or confirm a step worked; for text, snapshot and read are cheaper.

Download a file

Use language: "python" with Playwright’s download API and emit the file with the __DOWNLOAD__ marker so it’s saved as an attachment:

import base64
resp = await page.request.get("https://example.com/report.csv")
data = base64.b64encode(await resp.body()).decode()
print(f'__DOWNLOAD__{{"filename":"report.csv","data":"{data}"}}__DOWNLOAD__')

Security & best practices

• Never put real credentials in code. Use {{secret:NAME}} placeholders — values are injected server-side and never returned in output.
• Each conversation’s browser belongs to the person who ran it. Only they can watch it live or take it over.
• Saved logins are personal: each person’s agents use their own, and other members (admins included) can’t see or use them.
• A browser closes after 5 minutes idle or 1 hour in total. The next call starts a new one with your saved logins, and the result says the page state was reset.
• Always snapshot before interacting, and re-snapshot after any navigation — reusing stale @ref IDs will fail.

Limitations

• A browser lasts up to 1 hour, and closes after 5 minutes idle. Saved logins come back in the next one, but the page you were on doesn’t.
• Calls in one conversation run one at a time. A call made while another is running returns “another execution is in progress”.
• Logins made with secrets aren’t saved; only sign-ins you complete through a handoff are.
• Very large command output is capped inline; overflow is saved as a .log attachment the agent can read with Read File.
• Each call runs one command — no chaining with &&.

Troubleshooting

“Element not found” / stale ref

• Take a fresh snapshot — refs (@e1, @e2) are invalidated whenever the page changes
• Re-snapshot after every click that navigates or updates the DOM

“The browser had shut down”

• The browser idled out. Your saved logins were restored in the new one; navigate back to where you were

Login isn’t working

• A wrong secret name fails with “Secret NAME doesn’t exist”. Check the names in Settings → Secrets
• If the site needs a person (MFA, a CAPTCHA), have the agent hand you the browser instead
• Snapshot the page after submitting to check for an error message or a second step (e.g. MFA)

Related tools

• Scrape URL - Pull content from a single page or PDF when no interaction is needed
• Ask Web - Ask questions about web content using an LLM