Files

@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 42 namespaced tools for navigation, accessibility snapshots with stable element refs, clicking, form filling, semantic element finding, waiting, screenshots, JavaScript evaluation, tab management, and network and console inspection. Their names, descriptions, and input schemas come from the agent-browser mcp tool catalog of the matching CLI version, so they stay in sync with the CLI.

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__open, 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 uses one default browser session per sandbox; 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,
  useSystemCa: true, // OS trust store for the CLI's own HTTPS requests, such as read
  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, or replace an older default install
  installSpec: undefined, // npm spec; must install this package's agent-browser minor (default: the matching version)
  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

The 28 tools in the CLI's core MCP profile are listed to the model every turn. The other 14, marked deferred, stay out of the list and the model finds them with eve__search, so they add no context until used.

Tool Purpose
back Back
check Check element
click Click element
close Close browser
console Console logs (deferred)
dblclick Double-click element (deferred)
drag Drag and drop (deferred)
errors Page errors (deferred)
eval Evaluate JavaScript
fill Fill input
find Find element (deferred)
forward Forward
get_attr Get attribute (deferred)
get_box Get box (deferred)
get_count Get count (deferred)
get_html Get HTML (deferred)
get_styles Get styles (deferred)
get_text Get text
get_title Get title
get_url Get URL
get_value Get value (deferred)
hover Hover element (deferred)
network_requests Network requests (deferred)
open Open page
press Press key
read Read URL
reload Reload
screenshot Take screenshot
scroll Scroll page
select Select options
snapshot Snapshot page
tab_close Tab close
tab_list Tab list
tab_new Tab new
tab_switch Tab switch
type Type text
uncheck Uncheck element
upload Upload files (deferred)
wait_for_load Wait for load state
wait_for_selector Wait for selector
wait_for_text Wait for text
wait_ms Wait milliseconds

Cookie, storage, and saved-auth-state commands are not exposed as tools because 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/eval.ts — require approval for raw JS
import { eval as 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 runs agent-browser mcp call <tool> '<arguments>' inside the sandbox from ctx.getSandbox(), using an isolated browser session named after the sandbox id, and returns the data payload of the CLI response. Every call is its own short-lived process, so nothing outlives the tool call; the browser and its state live in the session daemon inside the sandbox. The extension sets session, allowedDomains, and the CA options from its config and hides them from the model. If the sandbox runs a different agent-browser minor version than this package, tools fail with an install hint instead of sending arguments the CLI may not accept.

Example

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

License

Apache-2.0