Web Agent

La capability de browser automation del lab. Maneja un browser Chromium-based a través del OpenClaw browser control server, expone el accessibility tree y soporta los web flows comunes.

Status

Implemented. El Web Agent es una thin layer sobre el OpenClaw browser control server. Expone un action vocabulary pequeño que el Coordinator y el usuario pueden invocar a través de lenguaje natural.

Role

El Web Agent es responsable de:

Abrir URLs en una controlled browser instance.
Navegar la página a través del accessibility tree.
Rellenar forms, clickear botones y leer contenido.
Tomar snapshots y screenshots (para el usuario).
Mantener el browser state entre requests.

El Web Agent no razona sobre la página. Es un action executor, no un planner. El Coordinator (o el usuario) decide qué hacer; el Web Agent lo hace.

Architecture

El Web Agent corre en el main gateway process. Controla un browser Chromium-based a través del OpenClaw browser control server.

Loading diagram…

Component	Purpose
Browser Control	La tool de browser de OpenClaw que expone el CDP.
CDP	El Chrome DevTools Protocol en el puerto 18800.
Chromium	La browser instance (headless=false por defecto).
Snapshot	El accessibility tree de la current page.

Browser control

El Web Agent usa la tool browser de OpenClaw. La tool está documentada en el bundled skill browser-automation. El resumen:

action="open" abre una URL en un nuevo tab.
action="snapshot" devuelve el accessibility tree del current tab.
action="act" ejecuta una UI action (click, type, hover, drag, etc.).
action="screenshot" devuelve un screenshot (para el usuario; el Web Agent en sí usa snapshots).
action="tabs" lista los tabs abiertos.
action="close" cierra un tab.

El Web Agent usa snapshot para casi todo. El accessibility tree es más fiable que los screenshots (el model puede leerlo directamente, no hace falta vision) y más estable que los CSS selectors (la page structure puede cambiar; el accessibility tree es más semántico).

Refs and snapshot mode

El snapshot tiene dos ref modes:

role: los refs son role + name based (p. ej., e12 es un link con name "Sign in").
aria: los refs son Playwright aria-ref ids (stable entre calls dentro del mismo tab).

El Web Agent prefiere aria para flows multi-step (porque los refs son stable) y role para acciones puntuales (porque es el default).

El snapshot se toma después de cada navigation y después de cada action que cambia la página. El Web Agent mantiene el snapshot más reciente en memoria.

Common flows

El Web Agent soporta una pequeña library de named flows. Cada flow es una secuencia de actions que el Web Agent puede ejecutar en una request.

Open and read

El flow más simple. Abrir una URL, devolver el text content de la página.

open(url) → snapshot → extract(text)

El text es lo que el Coordinator surface al usuario.

Search a site

Abrir la search page de un site, rellenar el search box, submit, devolver los results.

open(search_url) →
  act(fill, selector="input[name=q]", text=query) →
  act(press, key=Enter) →
  snapshot →
  extract(results)

El selector se toma del snapshot.

Fill a form

Abrir una página con un form, rellenar los fields, submit, devolver la confirmation.

open(form_url) →
  act(fill, field1, value1) →
  act(fill, field2, value2) →
  act(click, submit_button) →
  snapshot →
  extract(confirmation)

Cada act(fill, ...) usa un ref del snapshot.

Apply filters

Abrir una search results page, aplicar filters, devolver los filtered results.

open(search_url) →
  act(click, filter_button) →
  act(click, filter_option) →
  snapshot →
  extract(filtered_results)

Las filter interactions se toman del snapshot.

Capture content for archival

Abrir una serie de URLs, snapshot de cada una, save los snapshots a un fichero. Usado para capturar documentation (p. ej., la research page del public site del lab).

for url in urls:
  open(url) →
  snapshot →
  save_to({workspace-root}/captures/<name>.md)

Este es el flow que el lab usa para capturar las páginas del public site para análisis.

Real flows in the lab

El Web Agent se ha usado para:

Booking.com. Buscar casas en una ciudad para un date range específico, aplicar filters, devolver los results. El flow usa open + fill (destination, dates, guests) + click (search) + snapshot + extract.
Stremio catalog. Abrir el Stremio catalog, encontrar un title, devolver las streaming options.
Public site archival. Capturar el public site del lab para análisis offline. El flow abre cada URL, snapshot, y save a disco.
Form filling. Rellenar forms relacionados con research (subscriptions, alerts).

Las flow implementations no se guardan en el framework; se componen del action vocabulary en el momento de la request. Esto mantiene el Web Agent pequeño y flexible.

Limitations

El Web Agent no es una tool de browser automation de propósito general. Está limitado a:

Una browser instance a la vez por agent.
Un tab abierto a la vez por flow (varios tabs se soportan pero no son el default).
Páginas que el usuario puede alcanzar en un browser normal.
Páginas que no requieren login credentials (el Coordinator no pasa credentials al Web Agent).

Las páginas que requieren login credentials se alcanzan a través de un flow separado que usa las session cookies del usuario. El Coordinator es el dueño de las session cookies; el Web Agent las usa.

Configuration

La configuration del Web Agent:

Field	Type	Default	Purpose
`web_agent.browser_profile`	string	`openclaw`	El browser profile a usar.
`web_agent.headless`	boolean	`false`	Si el browser es headless.
`web_agent.cdp_port`	integer	`18800`	El CDP port.
`web_agent.snapshot_mode`	string	`aria`	El default ref mode.
`web_agent.screenshot_quality`	integer	`80`	El screenshot quality (0-100).

Failure modes

Failure	Web Agent response
El browser no está corriendo	Arrancar una nueva browser instance.
Browser CDP target is detached	Aplicar el procedure Runbook → Browser CDP target detached.
La página devuelve 4xx o 5xx	Surface el error al Coordinator.
La página requiere login	Pedirle al Coordinator que provea credentials.
Snapshot no devuelve actionable elements	Surface el snapshot para inspección.
Action times out	Reintentar una vez; surface el error.
Tab se cierra inesperadamente	Abrir un nuevo tab; continuar.

El failure catalog completo está en Failure Catalog.

Privacy and security

El Web Agent no loguea page content. Loguea:

La URL que abrió.
Las actions que tomó.
Los errors que encontró.

El page content se devuelve al Coordinator en la response. El Coordinator decide si loguear el content (normalmente no).

El Web Agent no almacena cookies entre invocations. Las cookies son session-scoped. El Coordinator maneja las persistent cookies por separado.

Future work

Multi-tab flows. Soportar flows que abarcan varios tabs.
Persistent sessions. Permitir al usuario hacer login una vez y reusar la session.
Vision fallback. Cuando el accessibility tree no es suficiente, caer a interaction vision-based.
Recorded flows. Permitir al usuario grabar un flow y reproducirlo.
Mobile emulation. Emular un mobile device para flows mobile-specific.