Skip to main content

​
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. Browser state (cookies, login sessions) persists across calls within the same conversation, so the agent logs in once and reuses that session for the rest of the task.

​
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
  • Log in securely using org secrets — real passwords are injected server-side and never seen by the agent
  • Session persists across tool calls in a conversation, so authentication and page state carry over
  • Download files (CSVs, PDFs, reports) straight into the conversation as attachments
  • Runs in an isolated cloud sandbox — nothing touches your own machine

​
Parameters

​
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

The snapshot returns the page structure with refs. Use scrape to pull the full page content as markdown.

​
Fill and submit a form

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

​
Log in without exposing credentials

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.

​
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:

​
Security & best practices

  • Never put real credentials in code. Use {{secret:NAME}} placeholders — values are injected server-side and never returned in output.
  • Sessions are per-conversation and read-only against a shared browser profile; each conversation gets its own isolated state.
  • Sessions time out after ~10 minutes total or ~5 minutes of inactivity. If a session expires, the tool starts a fresh one automatically.
  • Always snapshot before interacting, and re-snapshot after any navigation — reusing stale @ref IDs will fail.

​
Limitations

  • A session is short-lived (~10 min max, ~5 min idle) — long, slow workflows may need to re-establish state.
  • 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
“Session expired”
  • Sessions time out after inactivity; just run your next command and a new session is created automatically
  • Re-do any login step, since a new session starts unauthenticated
Login isn’t working
  • Confirm the org secret names in your {{secret:NAME}} placeholders match the secrets configured for the org
  • Snapshot the page after submitting to check for an error message or a second step (e.g. MFA)
  • 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