Browser sessions

browser.* opens a headless browser that an agent drives one action at a time: it reads the page, clicks or types, and reads the page again. Use it for what screenshots can't do, such as working through a form, checking that a sign-up flow still reaches its last page, or finding something behind a search box.

The browser tools are available to every account with nothing to set up, under the browser. prefix. They are meant for an agent's tools list, and they also work in tool steps.

How an agent sees the page

Every action answers with the page as an accessibility snapshot: its headings, links, buttons and fields as a tree, much as a screen reader would read them. Each element the agent can act on carries a ref:

- heading "Sign up" [level=1] [ref=e2]
- textbox "Email" [ref=e5]
- button "Create account" [ref=e6]

The next action names that ref: browser.fill with ref: e5, then browser.click with ref: e6. Refs belong to the snapshot they came from, so an agent always acts on the latest one. An element with no ref can be named with a Playwright selector such as text=Sign in instead.

steps:
  - key: signup
    kind: agent
    model: balanced
    tools: [ browser.* ]
    prompt: |
      Open https://example.com/signup with record_video and trace. Sign up as
      test+{{ run.number }}@example.com and report whether you reach the welcome page.
      Close the session when you are done.

The tools

Inside a run, a tool called without a session uses the run's latest open one, so an agent rarely needs to name it.

Video and traces

record_video keeps a video of every tab the session opened. trace keeps a Playwright trace: each action, the page's DOM before and after it, a filmstrip of screenshots, and every network request. Open one from the session's page in Browser sessions and it loads in Playwright's trace viewer, served by Murmurator itself, so the trace never leaves the account.

Both are written as the session goes and collected when it closes, whether the agent closed it, the run finished, or it sat idle. browser.close returns links to them. A trace can also be cut partway through with browser.export_trace; each export holds what happened since the one before.

A trace holds whatever the pages showed and sent, including what was typed into them. Treat traces like the pages themselves.

Limits

• An account can have 2 sessions open at once.
• A session left idle for ten minutes is closed, and one is closed after 30 minutes whatever it is doing. Its recordings are kept either way.
• An action waits up to 15 seconds for its element by default, and up to a minute with timeout_ms.
• A trace over 100MB is dropped rather than kept.
• Recordings are kept for as long as your plan keeps run history.

What a page can reach

Pages load from the public internet in a fresh browser that is signed out, through the same gateway as screenshots. Private, loopback and link-local addresses are refused, and so is any port other than 80 and 443. A page that is refused fails the action; anything else a page tries to load from one is left out, and listed under the session's refused addresses.

Over MCP

Your own agents can use the same tools over MCP as browser__open, browser__click and the rest. Over MCP, pass the session that browser__open returned to every other call. Sessions opened this way are recorded against the person the token belongs to.