Runtime API

The runtime API is the agent-facing surface. It lets an app register one or more browser backends and then work through stable browser, tab, and locator methods.

Create A Runtime

import { createAgentBrowserRuntime } from "@cmmd-center/agent-browser";
import { PlaywrightBackend } from "@cmmd-center/agent-browser/playwright";

const runtime = createAgentBrowserRuntime({
  backends: {
    playwright: new PlaywrightBackend({ headless: true })
  }
});

const browser = await runtime.browsers.get("playwright");
await browser.nameSession("docs smoke");

const tab = await browser.tabs.new();
await tab.goto("https://example.com");

const snapshot = await tab.playwright.domSnapshot();

await runtime.close();

Browser And Tab Flow

Use the runtime for backend lookup and session-level lifecycle:

const browsers = await runtime.browsers.list();
const browser = await runtime.browsers.get(browsers[0].id);

const tab = await browser.tabs.new({ url: "https://docs.cmmd.ai" });
const selected = await browser.tabs.selected();
const tabs = await browser.tabs.list();

await selected.reload();
await selected.screenshot({ fullPage: true });
await selected.close();

Lookup failures are intentional errors. Consumers should treat unknown browser IDs, missing tabs, and cross-runtime locator usage as integration bugs.

Locator Actions

The Browser-like locator surface is backend-neutral:

const save = tab.playwright.getByRole("button", { name: "Save" });

await save.click();
await tab.playwright.getByLabel("Email").fill("alex@example.com");
await tab.playwright.getByTestId("prompt").type("Summarize this page");

Locators support composition through the package’s locator AST, including nested locators, filters, and, or, first, last, and nth. Prefer role, label, text, placeholder, and test-id locators before raw CSS selectors.

AgentBrowser Controller

AgentBrowser wraps a backend with action recording, result/error recording, safety policy, screenshots, clipboard, logs, CUA, DOM CUA, and locator action helpers.

import { AgentBrowser, DefaultSafetyPolicy } from "@cmmd-center/agent-browser";
import { PlaywrightBackend } from "@cmmd-center/agent-browser/playwright";

const browser = new AgentBrowser({
  backend: new PlaywrightBackend({ headless: false }),
  safety: new DefaultSafetyPolicy({
    confirm: async (request) => request.category === "safe"
  })
});

await browser.goto("https://example.com");
await browser.click("text=More information");

The default safety policy distinguishes safe actions from risky selectors, sensitive values, handoff categories, and denied categories. Production hosts should attach user/project context and confirmation UX at the app boundary.