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

# Browser

A real browser the agent drives, on [Agent Browser](https://developers.telnyx.com/docs/agent-browser.md): an isolated Chromium session the platform runs, opened for the run and closed after it. The model opens a page, reads it as a text tree, and acts on what it read: click a link, fill a form, press Enter, pick an option, scroll, take a screenshot. Nothing to install and no key to add; the session runs over the account's credential.

```bash theme={null}
telnyx-acp add tool browser
telnyx-acp add tool browser --lifetime 600 --idle 120
```

The entry in `agent.json`:

```json theme={null}
{ "type": "browser", "lifetimeS": 600, "idleTimeoutS": 120 }
```

Both fields are optional. The agent may open any site; there is no domain list to keep. `lifetimeS` (60 to 1800, default 900) is how long a session may live and `idleTimeoutS` (30 up to the lifetime, default 300) how long it lives without an action.

## What the Model Gets

`telnyx-acp tools` lists the seven names, which `approvals` and the log lines use.

| Tool | Does |
| - | - |
| `browser_open(url)` | Opens the page and returns its title, URL and a text tree of everything on it: headings, text, links, inputs. Interactive elements carry a ref, `[ref=e13]`, the other tools act on. Opening the page the browser is already on reads it again instead of reloading it. |
| `browser_click(ref)` | Clicks an element and returns the page that results. |
| `browser_fill(ref, value)` | Types a value into an input, replacing what was there. |
| `browser_select(ref, value)` | Chooses an option of a dropdown. |
| `browser_press(key)` | Presses a key: `Enter`, `Tab`, `Escape`, `Backspace`, the arrows, `PageUp`, `PageDown`, `Home`, `End`. Enter submits the focused form. |
| `browser_scroll(dy)` | Scrolls down (positive) or up and returns the page. |
| `browser_screenshot()` | Takes a screenshot and returns a download URL for a person; the model keeps reading the tree. |

A page's tree is cut at 20,000 characters and 300 refs, so one call never floods the context. The observation the platform wants with every click, fill and select is kept by the loop, not the model: a stale one is refreshed once before the action is retried, and a ref that is gone because the page re-rendered comes back as an error that carries the page read again, so the model picks a new ref without another call.

## Sessions

One active session at a time per run, opened on the first `browser_open` and closed when the run ends, so `GET /v2/browser_sessions?status=ready` shows nothing left once the agent has answered; a run paused for approval and a later run on the same conversation hold their own sessions, pages and budgets. The platform wants a domain policy for every session and takes no wildcard, so each site the model opens gets a session on that host and its subdomains (and the bare host when it opened `www.`); opening another site closes it and opens one there, and a link that leads off the site answers the model "that link leads to another site; browser\_open its URL to go there", which the model then does. No apex is guessed from the host, since `*.github.io` would be every Pages site and `co.uk` has no single answer. A session the platform ended is reopened once; a site that refuses automated visitors answers "the site refused to load in the browser".

The journal has one line per call with the URL or ref and the time it took, and one for each session opened and closed. A `browser_fill` line never carries the value, which may be a credential.

```text theme={null}
{"browser":"opened","session":"bsess_0aaf…","domains":["duckduckgo.com","*.duckduckgo.com"],"ms":19277}
{"toolCall":"browser_open","url":"https://duckduckgo.com/","ms":20960,"ok":true}
{"toolCall":"browser_fill","ref":"f31e30","ms":914,"ok":true}
{"toolCall":"browser_press","key":"Enter","ms":1252,"ok":true}
{"browser":"closed","session":"bsess_0aaf…"}
```

A new session takes about twenty seconds to be ready, so the first `browser_open` of a run is slow, as is each switch to another site, and the rest are fast. `limits.browserActions` caps the actions of a run, 40 by default: past it every browser tool answers that the run has used its actions.

## Approvals

Mark a browser tool `ask` to have a human decide before it runs; `browser_fill` is the usual one, since a fill may submit a form or carry a credential. [Approvals](https://developers.telnyx.com/docs/agents/tools.md#approvals) has the flow, which works under `telnyx-acp dev` today.

```bash theme={null}
telnyx-acp set approvals.browser_fill ask
```

For reading the web without a browser, [Web Search](https://developers.telnyx.com/docs/agents/tools/web-search.md) is faster: a page as Markdown in one call, no session.