Browser Automation

Every Egg tab speaks the Chrome DevTools Protocol natively. Three ways to drive a tab from outside Egg: raw CDP for clients that already speak it, ~120 stable micro-commands callable over HTTP, or the agent tool catalog the LLM uses. Each is a complete entry point on its own; they share the underlying engine and overlap in implementation.

Chrome DevTools Protocol

Method coverage matches the Chromium version WebView2 ships. Send any method, subscribe to any event.

The methods and events are the standard Chrome DevTools Protocol; Egg does not duplicate the protocol reference. See chromedevtools.github.io/devtools-protocol for the full method and event catalog.

# Send a CDP method to a tab
curl -s -X POST "http://127.0.0.1:$PORT/api/browser/tabs/$TAB/cdp" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"method":"Page.navigate","params":{"url":"https://eggbrowser.com"}}'

# Subscribe to CDP events as Server-Sent Events
curl -N "http://127.0.0.1:$PORT/api/browser/cdp/events" \
  -H "Authorization: Bearer $TOKEN"
# → data: {"tab_id":"...","event":"Page.frameNavigated","params":{...}}

Alternatively, launch with --remote-debugging-port=9222 and attach Playwright, Puppeteer, or any CDP client to http://127.0.0.1:9222.

Micro-commands

Micro-commands are a stable, named-operation surface for driving a tab. Each is a small verb (click, fill, wait, snapshot, set viewport) that wraps the underlying engine work behind a name that does not change between Chromium versions. The shape will be familiar to anyone who has used Playwright or Puppeteer, but the surface is HTTP-native: every command is one POST, returns JSON, and is callable from any language. There is no SDK to install.

The intended audience is anyone who wants browser automation without writing CDP by hand. Script writers in shell, Python, Node, Go, or Rust call the endpoints with their HTTP library of choice. CI pipelines run them as one-shots against a headless egg. The agent harness dispatches its tool calls to the same surface, so what you script by hand is what the agent runs internally. Compared to raw CDP, micro-commands give you stability across engine versions, accessibility-first locators (@e refs), wait conditions that match how pages actually load, and a batch endpoint that runs a sequence and stops on first error.

The catalog has ~120 commands across 16 categories. Each is callable as a single POST or composed in a batch.

# Single command
curl -s -X POST "http://127.0.0.1:$PORT/api/browser/cmd" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"tab_id":"'$TAB'","command":"click","args":{"selector":"@e4"}}'

# Batch (sequential, stop on error)
curl -s -X POST "http://127.0.0.1:$PORT/api/browser/batch" \
  -H "Authorization: Bearer $TOKEN" \
  -d '[
    {"command":"open","args":{"url":"https://example.com"}},
    {"command":"wait","args":{"for":"load","state":"networkidle"}},
    {"command":"snapshot","args":{}}
  ]'

Navigation

Interaction

Find & query

Wait conditions

Network

Storage & cookies

Emulation & settings

Capture & debug

State & auth

Tabs & frames

@e refs

Run snapshot to get the page’s accessibility tree with sequential refs (@e1, @e2, …) attached to interactive nodes. Subsequent commands accept refs anywhere a selector is allowed.

[document] Egg: the browser that works for you
  [navigation] Main Menu
    [link @e1] Product
    [link @e2] Developers
    [link @e3] Pricing
  [main]
    [heading @e4] Build with Egg.
    [textbox @e5] Search...
    [button @e6] Submit

• Refs are session-scoped: valid until the page navigates or you call snapshot again.
• Refs map to backend node IDs server-side, not CSS strings. They survive non-structural CSS changes.

Agent tools

Agent tools are the LLM-facing automation surface. When the agent harness opens a conversation it advertises this small, grouped catalog to the language model rather than the full ~120-verb micro-command list. The grouping mirrors an observation/action loop: separate tools for observing a page, acting on it, navigating, waiting, finding, extracting, screenshotting, and emulating. Tool names and argument shapes are tuned for clarity in tool-call output, so a session is readable when an operator audits what the model did and why.

Agent tools are not a public surface for external automation. Scripts and HTTP clients should call micro-commands directly. The catalog exists so the model sees a curated set: enough to do what it needs, few enough to reason about cleanly, and named in terms of intent rather than mechanism. Each tool dispatches to one or more micro-commands under the hood, so anything the LLM does through this catalog can be reproduced verbatim by hand against the same HTTP endpoints.