vercel-labs--agent-browser/packages/@agent-browser/eve

@agent-browser/eve

An eve extension that gives your agent a full browser automation tool set, backed by agent-browser running inside the agent's sandbox.

Mount it once and the agent gets ~20 namespaced tools — navigation, accessibility snapshots with stable element refs, clicking, form filling, semantic element finding, waiting, screenshots, JavaScript evaluation, tab management, network and console inspection — without writing a single tool by hand.

Install

npm install @agent-browser/eve

eve is a peer dependency; the extension runs on the eve installed in your app.

Mount

Create a mount file under agent/extensions/. The file name becomes the tool namespace:

// agent/extensions/browser.ts
import browser from "@agent-browser/eve";

export default browser({});

That's it. The agent now has browser__navigate, browser__snapshot, browser__click, and the rest, plus an instructions fragment teaching the model the snapshot-refs workflow.

On first tool use in a fresh sandbox, the extension installs agent-browser (and Chromium plus its system libraries) automatically. For production, pre-install in your sandbox bootstrap instead so sessions start from a warm template:

// agent/sandbox.ts
import { agentBrowserRevalidationKey, installAgentBrowser } from "@agent-browser/eve/sandbox";
import { defineSandbox } from "eve/sandbox";
import { vercel } from "eve/sandbox/vercel";

export default defineSandbox({
  backend: vercel({ resources: { vcpus: 2 } }),
  revalidationKey: () => agentBrowserRevalidationKey(),
  async bootstrap({ use }) {
    const sandbox = await use();
    await installAgentBrowser(sandbox);
  },
});

@agent-browser/eve/sandbox also exports runAgentBrowser for calling agent-browser from a hand-written eve tool. It derives a short, stable session name from the eve sandbox id; pass session when multiple independent browser sessions should share one sandbox.

Configuration

All fields are optional:

export default browser({
  // Safety
  allowedDomains: ["example.com", "*.example.com"], // restrict navigation and sub-resources
  caCert: "/etc/ssl/certs/proxy-ca.pem",
  clearCaCert: false,
  contentBoundaries: true, // wrap page output in markers the model can recognize
  maxOutputChars: 50_000, // truncate page output

  // Output
  inlineScreenshots: true, // embed screenshots in tool output as data URLs for channels/UIs
  // (hidden from the model via toModelOutput; capped at 4 MB per image)

  // Install behavior
  autoInstall: true, // install agent-browser on first use when missing
  installSpec: "agent-browser@0.31.2", // defaults to the version matching this package
  installBrowser: true, // download Chromium during auto-install
  installSystemDependencies: true, // apt/dnf Chromium libraries during auto-install

  // Session & runtime
  session: undefined, // fixed session name; defaults to one derived from the sandbox id
  sessionPrefix: "eve", // prefix for the derived session name
  binary: "agent-browser", // binary name or path inside the sandbox
  proxy: undefined, // proxy server URL
});

Tools

Tool	Purpose
navigate	Open a URL, or go back/forward/reload
snapshot	Accessibility tree with @eN element refs (the primary way to see a page)
read	Page as agent-friendly text/markdown, llms.txt aware
click	Click or double-click an element
fill	Type into an input (clearing first by default)
press_key	Press a key or combination (Enter, Control+a)
hover	Hover an element
select_option	Pick a <select> option
set_checked	Check/uncheck a checkbox or radio
scroll	Scroll the page, a container, or an element into view
drag	Drag and drop
upload	Attach sandbox files to a file input
wait_for	Wait for an element, text, URL pattern, load state, JS condition, or delay
get	Read text/html/value/attribute/title/url/count/box/styles
find	Semantic locator: act on an element by role, label, text, placeholder, or test id
screenshot	Capture the page (full-page and annotated modes); output includes an inline data URL for UIs
evaluate	Run JavaScript in the page
tabs	List/open/switch/close tabs (stable ids and labels)
console	Read console messages and uncaught page errors
network_requests	List tracked requests or fetch one request's full detail
close	Close the browser session

Cookie, storage, and saved-auth-state commands are intentionally not exposed as tools — they make credential material visible to the model. If you need them, add a scoped tool in your own agent (or an override) with the guardrails your app requires.

Overrides

Standard eve extension overrides apply. Mount as a directory to gate or replace individual tools:

// agent/extensions/browser/extension.ts
import browser from "@agent-browser/eve";

export default browser({});

// agent/extensions/browser/tools/evaluate.ts — require approval for raw JS
import { evaluate } from "@agent-browser/eve/tools";
import { defineTool } from "eve/tools";
import { always } from "eve/tools/approval";

export default defineTool({ ...evaluate, approval: always() });

// agent/extensions/browser/tools/upload.ts — or drop a tool entirely
import { disableTool } from "eve/tools";

export default disableTool();

How it works

Each tool shells out to the agent-browser CLI inside the sandbox from ctx.getSandbox(), using an isolated browser session named after the sandbox id, and returns the parsed --json payload. The browser and its state live entirely in the sandbox; the app runtime only relays commands.

Example

See examples/eve for a complete Next.js eve app with this extension mounted.

License

Apache-2.0