agent-browser tools

agent-browser is Vercel Labs' browser command line for agents: it reads pages as compact snapshots with @e refs and acts on them. @mayurajs/browser-agent-browser turns a short list of its commands into tools on a mayura/browser browser. The command line drives the same browser alongside Mayura over the browser's CDP endpoint (browser.cdp), so the browser's origins, lifetime and limits still hold.

The package has no dependency of its own, but it starts the agent-browser command line as a child process, so it runs on Node only. You install agent-browser yourself.

#Install

npm install mayura @mayurajs/browser-agent-browser
npm install -g agent-browser

The package looks for agent-browser on the PATH; give cli to run it from elsewhere. It needs no credentials.

#Use it

import { createRuntime, defineAgent, z } from 'mayura';
import { browserPerRun, browserTools, createBrowsers } from 'mayura/browser';
import { localBrowsers } from 'mayura/browser/local';
import { agentBrowserTools } from '@mayurajs/browser-agent-browser';

const browsers = createBrowsers(localBrowsers(), {
  maxBrowsers: 2,
  maxLifetimeMs: 30 * 60_000,
  origins: ['https://example.com'],
});
const perRun = browserPerRun(browsers);

const tools = [
  // web.goto opens pages, kept to the origins; agent-browser reads and acts on them.
  ...browserTools(perRun.source, { name: 'web' }),
  ...agentBrowserTools(perRun.source, { act: true }),
];

const assistant = defineAgent({
  id: 'site.assistant',
  version: '1',
  instructions: 'Open pages with web.goto. Read them with agent.read (snapshot -i) and act on @refs with agent.act.',
  input: z.object({ task: z.string() }),
  output: z.object({ result: z.string() }),
  tools,
  model,
});

const runtime = createRuntime({
  profile: 'ephemeral',
  permissions: {
    allow: [
      'model:openai.responses',
      'tool:web.goto', 'browser:web:read',
      'tool:agent.read', 'agent-browser:agent:read', 'effect:read',
      'tool:agent.act', 'agent-browser:agent:act', 'effect:write',
    ],
  },
});
// Release each run's browser when it ends, with perRun.release(runId) in an onFinally hook (see the browser guide).

source may be one browser, or a function giving the run's browser, such as browserPerRun(...).source.

#Tools and commands

Each tool takes { command, args }, with at most 10 arguments.

<name>.read reads (effect:read); <name>.act and <name>.eval write (effect:write).

• Only these commands run, with only the flags listed. No other argument may start with -. Nothing that writes files, reaches credentials, cookies or the network setup, or starts other servers is available.
• Navigation stays with the browser. Open pages with the browser's own goto, or the browserTools goto tool, which keep to the origins. agent-browser's read <url> fetches from your machine directly, outside the browser, and its open did not complete over CDP in testing (agent-browser 0.38.2 on Windows), so neither is offered.
• Whatever a command does in the page, the page's requests are still checked against the browser's origins.

#Options

#How commands run

• The command line runs without a shell, as agent-browser --cdp <browser.cdp.url> --session <id> --json <command>.
• Each browser gets an agent-browser session of its own (mayura-<uuid>), so refs from a snapshot hold for the next command. Once the browser has ended, the next call closes its session.
• A timeout or cancellation stops the command.
• Results are agent-browser's own JSON, as { ok: true, ... }, without its bookkeeping (lifecycle). What agent-browser could not do comes back as { ok: false, error }, so the model can try something else.
• A result over maxResultBytes is cut: a snapshot is shortened and marked truncated: true; anything else comes back as { ok: false, error } saying it was too large.

#Which browsers

agent-browser needs to reach this very browser, alone, with a CDP connection that needs no headers. It works with browsers from mayura/browser/local and hosted browsers that are yours alone, such as Browserbase or Kernel. It does not work with BrowserView or Cloudflare Browser Run (headers), Browserless (every connection starts a browser of its own), or a browser shared through cdpBrowsers, where it could act on others' pages.

#Errors

Configuration mistakes, such as an empty cli or a timeout under a second, fail with INVALID_CONFIG when you call agentBrowserTools().

#How it is tested

• Unit tests run the tools against a stand-in command line that records its arguments and answers in agent-browser's JSON: the CDP endpoint and one session per browser, commands and flags refused outside the list (without running anything), failures reported, results bounded, timeouts, a missing command line, refused browsers, the session closed once its browser ended, and a call blocked without its permission.
• An integration test runs the real agent-browser (0.38.2) on a browser launched from the Chrome installed on the test machine: a snapshot with refs, fill and press in the same session, get and is, a page fetch to another origin kept blocked, and no session left behind.
• It has not been run against a hosted browser yet.

#Related

• Browsers: limits, origins, per-run browsers and the built-in browser tools.
• Stagehand tools: natural-language extract, observe and act on a Mayura browser.
• Permissions: how tool:, effect: and capability grants combine.