Browser

A real browser the agent drives, on Agent Browser: 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.

telnyx-acp add tool browser
telnyx-acp add tool browser --lifetime 600 --idle 120

The entry in agent.json:

{ "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.

{"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 has the flow, which works under telnyx-acp dev today.

telnyx-acp set approvals.browser_fill ask

For reading the web without a browser, Web Search is faster: a page as Markdown in one call, no session.