> ## Documentation Index
> Fetch the complete documentation index at: https://docs.asteragents.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

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

| Parameter       | Type    | Required | Description                                                                                                                                                    |
| --------------- | ------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `code`          | string  | Yes      | The commands to run in the sandbox. In `bash` mode, these are `agent-browser` commands (no need to type the `agent-browser` prefix — it's 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)        |
| `session_id`    | string  | No       | Reuse a browser session from a previous result to continue where you left off. If omitted or expired, a new session is created automatically                   |
| `close_session` | boolean | No       | Set to `true` when finished browsing to close the session (default: false)                                                                                     |

## 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 `scrape` to pull the full page content as markdown.

### 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](/integrations/secrets) 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:

```python theme={null}
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.
* 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](/tools/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)

## Related tools

* [Scrape URL](/tools/scrape_url) - Pull content from a single page or PDF when no interaction is needed
* [Ask Web](/tools/ask_web) - Ask questions about web content using an LLM