# How AI Agents Interact with the ego-lite Browser Using the Helper System

> Discover how AI agents interact with the ego-lite browser via its helper system. Learn about the Playwright-style API for page interaction and browser management within agent scripts.

- Repository: [CitroLabs/ego-lite](https://github.com/citrolabs/ego-lite)
- Tags: how-to-guide
- Published: 2026-07-31

---

**The helper system in ego-lite provides AI agents with a Playwright-style API through the `helperContext()` function, which injects facades for page interaction, browser management, and task-space isolation directly into agent scripts.**

The **ego-lite** browser ([citrolabs/ego-lite](https://github.com/citrolabs/ego-lite)) exposes a high-level abstraction layer that eliminates the need for agents to handle raw Chrome DevTools Protocol (CDP) commands. By assembling a context object that maps to underlying driver modules, the helper system enables agents to perform complex browser automation using familiar method calls like `page.goto()` and `locator.click()`.

## Understanding the Helper System Architecture

At runtime, the ego-lite browser constructs a **helper context** that becomes the execution environment for agent scripts. This architecture delegates low-level CDP interactions to specialized driver modules while exposing a unified, Promise-based API to the agent.

### The helperContext() Factory

The entry point for all agent-browser interaction is the [`helperContext()`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/helpers.ts) function defined in [[`helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/helpers.ts)](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/helpers.ts). According to the source code, this factory assembles multiple facades—`page`, `browser`, `taskSpaces`, `site`, `fetch`, and `cdp`—into a single object that gets injected into the agent's scope. When an agent script executes via `runMain()` in [`src/run.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/run.ts), it receives this context without requiring any import statements, allowing immediate access to browser automation primitives.

### Facade Pattern Implementation

Each facade serves as a thin abstraction over concrete driver implementations. For example, the **page facade** delegates navigation to [[`driver/nav.ts`](https://github.com/citrolabs/ego-lite/blob/main/driver/nav.ts)](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/driver/nav.ts), pointer actions to [[`driver/pointer.ts`](https://github.com/citrolabs/ego-lite/blob/main/driver/pointer.ts)](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/driver/pointer.ts), and keyboard input to [[`driver/keyboard.ts`](https://github.com/citrolabs/ego-lite/blob/main/driver/keyboard.ts)](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/driver/keyboard.ts). This separation ensures that agents interact with semantic APIs (e.g., `await element.click()`) while the system handles CDP command serialization, snapshot management, and event queue coordination behind the scenes.

## Core Facades for Browser Automation

The helper system exposes six primary facades that cover the full spectrum of browser interaction, from DOM manipulation to network interception.

### Page Facade and Locator API

The **page facade** provides Playwright-compatible methods including `page.goto()`, `page.screenshot()`, and `page.locator()`. When agents call `page.locator(selector)`, they receive a strict locator object that supports chained actions like `click()`, `fill()`, and `innerText()`. Internally, these methods route through [[`driver/locator.ts`](https://github.com/citrolabs/ego-lite/blob/main/driver/locator.ts)](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/driver/locator.ts) for element resolution and [[`driver/waits.ts`](https://github.com/citrolabs/ego-lite/blob/main/driver/waits.ts)](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/driver/waits.ts) for automatic waiting logic, ensuring elements are ready before interaction.

### Browser and TaskSpace Management

The **browser facade** handles tab lifecycle through methods like `browser.listTabs()`, `browser.switchTab()`, and `browser.openOrReuseTab()`. The **taskSpaces facade** provides isolation primitives—`taskSpaces.new()`, `taskSpaces.claim()`, and `taskSpaces.handOff()`—that enforce ownership policies. As implemented in [`helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/helpers.ts), these checks ensure agents only modify DOM contexts they own, preventing accidental interference with user-controlled browsing sessions.

### Site Skills and Network Fetch

The **site facade** loads domain-specific automation logic from [[`src/learning/index.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/learning/index.ts)](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/learning/index.ts), allowing agents to execute pre-learned workflows via `site.runTool()`. The **fetch facade** offers dual-context network access: `fetch.server()` for Node.js-side requests and `fetch.browser()` for origin-mimicking fetch within the browser context, bypassing CORS restrictions when necessary.

## Practical Agent Implementation Examples

Agents write standard JavaScript that executes within the helper-injected scope. The following examples demonstrate common automation patterns using the ego-lite helper system.

### Basic Navigation and Element Interaction

```javascript
// Navigate and interact using the page facade
await page.goto('https://example.com');
const submitBtn = page.locator('button[type="submit"]');
await submitBtn.waitFor();
await submitBtn.click();

```

This code relies on [[`driver/nav.ts`](https://github.com/citrolabs/ego-lite/blob/main/driver/nav.ts)](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/driver/nav.ts) for navigation and [[`driver/pointer.ts`](https://github.com/citrolabs/ego-lite/blob/main/driver/pointer.ts)](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/driver/pointer.ts) for the click action, with implicit waiting handled by [[`driver/waits.ts`](https://github.com/citrolabs/ego-lite/blob/main/driver/waits.ts)](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/driver/waits.ts).

### Form Completion and Keyboard Input

```javascript
// Fill login credentials and submit
await page.goto('https://auth.example.com');
await page.locator('input#email').fill('agent@example.com');
await page.locator('input#password').fill('securePassword123');
await page.keyboard.press('Enter');

```

The `fill()` method coordinates with [[`driver/keyboard.ts`](https://github.com/citrolabs/ego-lite/blob/main/driver/keyboard.ts)](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/driver/keyboard.ts), while `page.keyboard` provides direct access to key press emulation.

### Task Space Isolation

```javascript
// Create isolated context for sensitive workflow
const checkoutSpace = await taskSpaces.new('secure-checkout');
await page.goto('https://checkout.example.com');

// Complete workflow and release control
await taskSpaces.handOff();

```

Task spaces enforce boundaries defined in [[`src/state.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/state.ts)](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/state.ts), with ownership validation occurring in the facade layer before any DOM mutation.

### Element Screenshots and Evaluation

```javascript
// Capture specific element screenshot
const chart = page.locator('.data-visualization');
await chart.screenshot({ path: 'chart.png' });

// Execute custom JavaScript in page context
const title = await cdp.evaluate(() => document.title);

```

The `screenshot()` method utilizes [[`driver/observe.ts`](https://github.com/citrolabs/ego-lite/blob/main/driver/observe.ts)](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/driver/observe.ts), while `cdp.evaluate()` provides direct access to the JavaScript execution environment via [[`src/cdp-eval.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/cdp-eval.ts)](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/cdp-eval.ts).

## Summary

- The **helper system** centralizes browser automation logic in [`package/ego-browser/src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/helpers.ts), exposing a unified API through `helperContext()`.
- **Facades** abstract CDP complexity, with the page facade offering Playwright-compatible locators and the browser facade managing tab lifecycles.
- **Task spaces** provide isolation boundaries, ensuring agents operate only within owned contexts through the `taskSpaces` facade.
- **Driver modules** ([`pointer.ts`](https://github.com/citrolabs/ego-lite/blob/main/pointer.ts), [`keyboard.ts`](https://github.com/citrolabs/ego-lite/blob/main/keyboard.ts), [`nav.ts`](https://github.com/citrolabs/ego-lite/blob/main/nav.ts), [`locator.ts`](https://github.com/citrolabs/ego-lite/blob/main/locator.ts), [`waits.ts`](https://github.com/citrolabs/ego-lite/blob/main/waits.ts), [`observe.ts`](https://github.com/citrolabs/ego-lite/blob/main/observe.ts)) implement concrete actions triggered by facade methods.
- Agents execute scripts without imports, receiving pre-injected helpers that handle snapshot consistency, event draining, and ownership validation automatically.

## Frequently Asked Questions

### What is the helperContext() function in ego-lite?

The `helperContext()` function is the factory method defined in [`helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/helpers.ts) that constructs and returns the complete set of browser automation helpers. It creates facades for page interaction, browser management, task spaces, site-specific skills, and network fetching, then injects these into the agent's execution scope so scripts can call methods like `page.goto()` without module imports.

### How do task spaces isolate agent sessions?

Task spaces create isolated browsing contexts using the `taskSpaces` facade methods like `new()`, `claim()`, and `handOff()`. As implemented in the helper system, each task space maintains ownership metadata in [`src/state.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/state.ts), and the facade layer validates that agents only manipulate DOM elements within spaces they explicitly own, preventing cross-contamination between agent workflows and user browsing sessions.

### Can agents execute custom JavaScript in the browser?

Yes, agents can execute arbitrary JavaScript using the `cdp.evaluate()` helper or the `evaluate` method on locator objects. These functions route through [`src/cdp-eval.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/cdp-eval.ts) to send direct Chrome DevTools Protocol commands, allowing agents to read page properties, modify the DOM, or invoke browser APIs that are not covered by the high-level facade methods.

### Where are mouse and keyboard actions implemented?

Mouse actions such as `click()` and `hover()` are implemented in [`driver/pointer.ts`](https://github.com/citrolabs/ego-lite/blob/main/driver/pointer.ts), while keyboard actions including `fill()` and `press()` reside in [`driver/keyboard.ts`](https://github.com/citrolabs/ego-lite/blob/main/driver/keyboard.ts). These driver modules receive calls from the page and locator facades, then translate them into CDP input dispatch commands with proper coordinate calculation and key event simulation.