agent-browser

Un navegador local endurecido para agentes de IA. Cero dependencias. Utiliza el Chrome que ya tienes a través del Protocolo DevTools, extrae Markdown eficiente en tokens y no se marca trivialmente como automatización.

npx -y @truenix/agent-browser markdown https://news.ycombinator.com

Todo se ejecuta localmente. Sin cuenta, sin clave de API, sin servicio remoto, sin cuota.

Por qué

Alimentar a un agente con HTML crudo desperdicia la mayor parte de su contexto. Medido en páginas reales:

Y un navegador que se anuncia como automatización es bloqueado, degradado o recibe contenido diferente — lo que corrompe silenciosamente lo que el agente haya concluido.

Related MCP server: Browser-MCP Navigator

Instalación

Como servidor MCP

claude mcp add browser -- npx -y @truenix/agent-browser mcp

{
  "mcpServers": {
    "browser": {
      "command": "npx",
      "args": ["-y", "@truenix/agent-browser", "mcp"]
    }
  }
}

Herramientas: browser_markdown, browser_text, browser_html, browser_links, browser_screenshot, browser_evaluate, browser_accessibility_tree, browser_pdf, browser_probe.

Como biblioteca

npm install @truenix/agent-browser

import { withBrowser } from '@truenix/agent-browser';

const md = await withBrowser({}, async (session) => {
  await session.navigate('https://example.com');
  return session.markdown();
});

Como plugin de DSH / Cordis

En una línea (recomendado: se conecta automáticamente cuando usas DSH):

npx -y @truenix/agent-browser install          # edits ~/.dsh/profiles/web/cordis.patch.yml + package.json, then pnpm install
# npx -y @truenix/agent-browser install --profile web --dry-run  # preview
# npx -y @truenix/agent-browser uninstall      # remove again

Reinicia dsh — browser_markdown, browser_text, browser_links, browser_evaluate, browser_screenshot, browser_probe aparecen como herramientas nativas. Ningún handler se ejecuta con un npm install simple; se requiere un install intencional.

Manual (si prefieres editar la composición tú mismo):

npm i -g @truenix/agent-browser
# or inside the harness checkout: pnpm add @truenix/agent-browser

Requiere Node ≥ 18 y una instalación de Chrome/Chromium. Luego añádelo a la composición del host (el registro de herramientas vive en el host, no por agente):

# ~/.dsh/profiles/web/cordis.patch.yml  — persists for every web session
- insert:
  - id: agent-browser
    name: '@truenix/agent-browser/cordis'
    config:
      timeoutMs: 180000   # per-tool call budget; default respects AGENT_BROWSER_BIN / ENDPOINT
      # cli: 'npx -y @truenix/agent-browser'  # override only if needed

Forma abreviada (cuando la composición ya envuelve insert):

- '@truenix/agent-browser/cordis':
    timeoutMs: 180000

Anulaciones de entorno: AGENT_BROWSER_BIN (binario de Chrome), AGENT_BROWSER_ENDPOINT (conectarse a un navegador de larga duración vía --endpoint), o config.cli.

CLI

agent-browser <command> [options]

  markdown <url>     Extract the page as Markdown (main content by default)
  text <url>         Visible text only
  html <url>         Full serialized DOM after JavaScript runs
  links <url>        Every anchor as JSON
  screenshot <url>   PNG/JPEG   (-o file, --full)
  pdf <url>          PDF        (-o file)
  a11y <url>         Filtered accessibility tree
  eval <url> <expr>  Evaluate JS in the page
  probe              Browser, GPU and capability report
  mcp                Run as an MCP server on stdio

Opciones: --headful, --no-stealth, --block-images, --gpu/--no-gpu, --width, --height, --viewport WxH, --main, --raw, --full, --endpoint <ws>, --timeout, --json, -o.

--endpoint se conecta a un navegador ya en ejecución en lugar de lanzar uno — útil para reutilizar un único navegador de larga duración en muchas llamadas.

Detección de bots

Pruébalo tú mismo: npm run test:bot. Último resultado:

El Chrome headless normal falla en cuatro filas de sannysoft (HEADCHR_UA, CHR_MEMORY, WebGL SwiftShader, UA antiguo) y es reportado como bot.

Un detector inalcanzable cuenta como SKIP, nunca como aprobado, y la verificación requiere tres aprobados alcanzables — así que un día en que los sitios de prueba estén caídos no puede confundirse con un éxito.

El entorno importa más que el parcheo

El mismo código, medido en dos lugares:

Toda señal a nivel CDP se mantiene limpia en ambos — esa parte es código, y el código es correcto. Lo que cambia el veredicto es el entorno: un ASN de datacenter más renderizado por software activa un compuesto de señales débiles que ningún parche de huellas resuelve.

Esta es la forma honesta del problema. Endurecer el navegador elimina las señales triviales. Dónde lo ejecutes decide el resto.

Qué hace el endurecimiento y por qué

Cada elemento provino de un detector que nos decía que estábamos equivocados:

• Sin --enable-automation. Esa bandera — que Puppeteer y Playwright añaden — es la que establece navigator.webdriver = true. El CDP crudo no la establece, así que se mantiene false sin nada parcheado.

• Sin Runtime.enable. Es la señal CDP más ruidosa y alimenta el detector clásico de consola/Error.stack. Runtime.evaluate funciona bien sin ella.

• Ventana y pantalla se mueven juntas. --window-size sin --ozone-override-screen-size da outerWidth > screen.width, lo que es físicamente imposible — una señal más fuerte que el headless simple.

• Sin anulación de métricas de dispositivo por defecto. El 1280×720 habitual es el viewport por defecto de Playwright y los detectores lo marcan por nombre. Establece --viewport solo si lo necesitas.

• GPU real cuando esté disponible, dando un renderizador ANGLE (NVIDIA …) genuino en lugar de SwiftShader.

• UA establecido en el lanzamiento, no solo vía CDP. Emulation.setUserAgentOverride no llega a los Web Workers, así que un worker sigue reportando el UA headless mientras la página reporta el limpio (hasInconsistentWorkerValues).

• Sin anulación de acceptLanguage. CDP deriva navigator.languages dividiendo esa cabecera, así que "en-US,en;q=0.9" se convierte en ["en-US","en;q=0.9"] — un valor q donde ninguno puede existir legalmente — y otro desajuste página/worker. --lang lo hace correctamente.

• Client Hints derivados de la propia versión del binario, así que Sec-CH-UA no puede discrepar de navigator.userAgent.

• Contexto de navegador aislado por sesión, eliminado al cerrar — estado limpio por tarea sin un segundo proceso de navegador.

La lección recurrente: la consistencia vence a la cobertura. Cuatro de esos son casos donde el suplantamiento parcial hizo la detección más fácil, capturados solo al ejecutar detectores reales.

Por qué el suplantamiento de WebGL está desactivado por defecto

spoofWebgl existe y está implementado con cuidado — un Proxy alrededor de getParameter nativo, así que Function.prototype.toString sigue reportando [native code]. Está desactivado, porque la medición dice que revienta. De test/webgl-spoof-experiment.mjs:

Reclamar hardware que no tienes arregla una fila cosmética y hace fallar el detector compuesto: el script inyectado no llega a los Web Workers, así que el worker sigue reportando SwiftShader, y MAX_TEXTURE_SIZE se mantiene en el valor de software mientras la cadena del renderizador afirma una GPU discreta.

El SwiftShader honesto aprueba. Una mentira convincente no. Dale al navegador una GPU real en su lugar — es gratis.

Lo que esto NO hace

La detección a nivel de huella es todo el alcance. No vence, y no intenta vencer:

• Huellas TLS/JA3-JA4 y HTTP/2 — decididas antes de que se ejecute cualquier JavaScript

• Reputación de IP — ASN de datacenter vs residencial, a menudo el verdadero bloqueo

• Análisis de comportamiento — trayectorias del ratón, tiempos, permanencia

Los productos comerciales de desafío se apoyan en esos, así que "pasar la puerta" significa no ser trivialmente marcado como automatización, nunca indetectable. Pensado para tus propios sitios, pruebas, trabajo de accesibilidad y navegación ordinaria de agentes.

Memoria

Una pila de Chrome cuesta aproximadamente 450 MB. La palanca es la arquitectura, no las banderas: ejecuta un navegador y muchos contextos aislados en lugar de un navegador por tarea. Inicia un navegador una vez y luego apunta cada llamada con --endpoint / AGENT_BROWSER_ENDPOINT. --block-images ayuda para trabajo de texto.

Cero dependencias

dependencies está vacío, incluido el transporte WebSocket.

El WebSocket global de Node (WHATWG) no puede enviar cabeceras de solicitud, que cualquier endpoint CDP autenticado o con proxy necesita, y undici no es importable de forma independiente. Así que src/ws.mjs implementa RFC 6455 directamente sobre node:http(s) — handshake, enmascarado, fragmentos de continuación, longitudes de 64 bits, ping/pong — que es todo lo que CDP requiere.

El conversor de Markdown recorre el DOM con una pila explícita, manteniendo la profundidad de llamadas JS en O(1) independientemente del anidamiento, y usa innerText nativo para nodos en línea a nivel de hoja. Esto lo hace tanto seguro contra recursión en documentos profundamente anidados como notablemente más rápido en páginas grandes.

Entorno

Requisitos

Node ≥ 18 y una instalación de Chrome/Chromium. Sin paso de compilación.

Créditos

El endurecimiento de este proyecto se deriva casi por completo de la investigación de detección publicada por otros — ver CREDITS.md. Agradecimientos especiales a rebrowser-bot-detector, bot.sannysoft.com, deviceandbrowserinfo.com y Camoufox por mostrar cómo se hace esto correctamente.

Licencia

MIT