Autonomous Browser Agent — sin capturas de pantalla

El agente controla un Chromium real a través de Playwright, y las decisiones las toma la LLM basándose en una instantánea estructural de texto de la página (ref | role | name | estados), no en imágenes. No se necesita un modelo de visión, no se hacen capturas de pantalla en ningún paso.

Tres modos de funcionamiento desde una misma base de código:

Arquitectura

Related MCP server: project-tendril

1. Instalación en el equipo local

git clone https://github.com/maxmkab/autonomous-browser-agent.git
cd autonomous-browser-agent

python -m venv .venv
source .venv/bin/activate        # Windows: .venv\\Scripts\\activate
pip install -r requirements.txt
playwright install chromium

cp .env.example .env             # вписать ANTHROPIC_API_KEY

Comprobación sin gastar en LLM — ver exactamente lo que ve el modelo:

python main.py snapshot --url https://example.com

Ejecución de una tarea con navegador visible:

HEADLESS=false python main.py run \
  --task "Найди раздел с ценами и извлеки все тарифы через extract" \
  --url https://example.com \
  --json state/report.json

2. Integración en tu navegador real (CDP)

El agente puede trabajar no en su Chromium limpio, sino en tu Chrome — con sesiones en vivo, extensiones y una huella real. No hace falta instalar ninguna extensión: el control se realiza mediante el Chrome DevTools Protocol.

# 1) запустить Chrome с открытым портом (отдельный профиль для агента)
chmod +x scripts/chrome-cdp.sh
./scripts/chrome-cdp.sh 9222          # Windows: scripts\\chrome-cdp.bat 9222

# 2) в другом терминале отдать задачу агенту в этом же браузере
CDP_URL=http://127.0.0.1:9222 python main.py run --task "..."

En este modo el agente no toca storage_state.json: las sesiones se toman del perfil de Chrome. En el primer arranque, inicia sesión manualmente en los servicios que necesites; a partir de ahí el perfil los recuerda.

3. Integración en Claude Code / Cursor mediante MCP

mcp_server.py levanta un servidor MCP con transporte stdio. Herramientas: browser_open, browser_snapshot, browser_click, browser_type, browser_select, browser_check, browser_scroll, browser_press, browser_back, browser_tabs, browser_save_session, browser_run_task, browser_close.

Config para Claude Code (~/.claude.json o .mcp.json en la raíz del proyecto):

{
  "mcpServers": {
    "browser-agent": {
      "command": "/absolute/path/autonomous-browser-agent/.venv/bin/python",
      "args": ["/absolute/path/autonomous-browser-agent/mcp_server.py"],
      "env": {
        "HEADLESS": "false",
        "CDP_URL": "http://127.0.0.1:9222",
        "ANTHROPIC_API_KEY": "sk-ant-...",
        "REQUIRE_APPROVAL": "true"
      }
    }
  }
}

O con un solo comando:

claude mcp add browser-agent -- /absolute/path/.venv/bin/python /absolute/path/mcp_server.py

Después de esto, el modelo en Claude Code dirige el navegador con el ciclo browser_snapshot → browser_click → browser_snapshot, recibiendo solo instantáneas de texto. La sesión del navegador vive entre llamadas, por lo que el escenario se puede llevar paso a paso. Para autonomía total existe browser_run_task: el agente ejecuta el ciclo por sí mismo y devuelve un informe JSON.

4. Transferencia de la autorización al servidor

# локально, в видимом окне: залогинился → Enter в консоли
HEADLESS=false python main.py login --url https://site.ru/login

# переносим cookies + localStorage на сервер
scp state/storage_state.json root@YOUR_VPS_IP:/opt/browser-agent/state/

5. Despliegue en VPS (Ubuntu 24.04 + Docker)

mkdir -p /opt/browser-agent/state && cd /opt/browser-agent
git clone https://github.com/maxmkab/autonomous-browser-agent.git .
cp .env.example .env && nano .env

docker build -t browser-agent .
docker run -d --name browser-agent --restart unless-stopped \
  --shm-size=1g \
  --env-file .env \
  -v /opt/browser-agent/state:/app/state \
  browser-agent

--shm-size=1g es obligatorio: Chromium en un contenedor con los 64 MB por defecto de /dev/shm falla en páginas pesadas.

Tarea puntual en el servidor:

docker exec -it browser-agent python main.py run --task "..." --url https://...

Sin Docker (systemd)

apt update && apt install -y python3-venv
cd /opt/browser-agent && python3 -m venv .venv && . .venv/bin/activate
pip install -r requirements.txt
playwright install --with-deps chromium

/etc/systemd/system/browser-agent.service:

[Unit]
Description=Autonomous browser agent
After=network-online.target

[Service]
Type=simple
WorkingDirectory=/opt/browser-agent
EnvironmentFile=/opt/browser-agent/.env
ExecStart=/opt/browser-agent/.venv/bin/python main.py daemon --interval 300
Restart=always
RestartSec=10
StandardOutput=append:/var/log/browser-agent.log
StandardError=append:/var/log/browser-agent.log

[Install]
WantedBy=multi-user.target

systemctl daemon-reload && systemctl enable --now browser-agent
journalctl -u browser-agent -f

6. Planteamiento de tareas y n8n

El demonio lee state/tasks.jsonl — una línea = una tarea:

{"id":"price-check-1","task":"Открой карточку товара, извлеки цену и наличие через extract","url":"https://site.ru/item/123"}
{"id":"lead-form","task":"Заполни форму заявки: имя Иван, телефон +79990000000. Отправку подтвердит человек."}

Los resultados se escriben en state/results.jsonl con los campos success, result, extracted, steps, tokens_in/out y la traza completa history. n8n puede escribir tareas en este archivo (nodo Execute Command / SSH) y leer los resultados.

7. Ahorro de tokens

• Nada de capturas de pantalla: solo texto, sin modelo de visión.

• Filtrado del DOM: al contexto solo llegan los elementos interactivos visibles con nombre no vacío, máximo 250 por frame.

• Bloqueo de imágenes/fuentes/medios a nivel de red (BLOCK_MEDIA=true).

• Compresión del historial (HISTORY_WINDOW): instantáneas completas solo para los últimos pasos, los antiguos se resumen en action → result.

• Detección de bucles: si la huella de la instantánea no cambia, se le indica al modelo que cambie de estrategia.

8. Seguridad

Las acciones que coinciden con RISKY_PATTERNS (pago, comprar, pedir, eliminar, enviar, checkout, pay, delete) requieren confirmación: en la consola localmente o respondiendo «sí» en Telegram en el servidor (APPROVAL_MODE=telegram). ALLOW_EVAL=false por defecto prohíbe la ejecución de JS arbitrario. Todos los errores de acciones se devuelven al modelo como observation y no tumban el proceso. Los secretos se guardan solo en .env, que está excluido de git.

9. Verificación antes de producción

1. python main.py snapshot --url <sitio objetivo> — ¿los elementos necesarios aparecen en la instantánea?

2. Ejecución de la tarea localmente en headful con REQUIRE_APPROVAL=true.

3. La misma tarea localmente en headless — detecta diferencias de renderizado antes del despliegue.

4. Solo después, despliegue en VPS y arranque del demonio.

Licencia

MIT