Autonomous Browser Agent — ohne Screenshots

Der Agent steuert ein echtes Chromium über Playwright, die Entscheidungen trifft eine LLM auf Basis einer strukturellen textuellen Momentaufnahme der Seite (ref | role | name | Zustände), nicht von Bildern. Ein Vision-Modell wird nicht benötigt, Screenshots werden in keinem Schritt erstellt.

Drei Betriebsmodi aus einer einzigen Codebasis:

Architektur

Related MCP server: project-tendril

1. Installation auf dem lokalen Rechner

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

Überprüfung ohne LLM-Kosten — sehen, was das Modell genau sieht:

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

Aufgabenstart mit sichtbarem Browser:

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

2. Einbindung in deinen echten Browser (CDP)

Der Agent kann nicht in seinem eigenen sauberen Chromium arbeiten, sondern in deinem Chrome — mit Live-Sitzungen, Erweiterungen und echtem Fingerprint. Es müssen keine Erweiterungen installiert werden — die Steuerung erfolgt über das 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 "..."

In diesem Modus berührt der Agent storage_state.json nicht: Sitzungen werden aus dem Chrome-Profil übernommen. Beim ersten Start loggst du dich manuell in den benötigten Diensten ein, danach merkt sich das Profil diese.

3. Einbindung in Claude Code / Cursor über MCP

mcp_server.py startet einen MCP-Server mit stdio-Transport. Tools: 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.

Konfiguration für Claude Code (~/.claude.json oder .mcp.json im Projektstamm):

{
  "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"
      }
    }
  }
}

Oder mit einem einzigen Befehl:

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

Danach führt das Modell in Claude Code den Browser im Zyklus browser_snapshot → browser_click → browser_snapshot und erhält dabei nur textuelle Momentaufnahmen. Die Browser-Sitzung lebt zwischen den Aufrufen weiter, sodass das Szenario Schritt für Schritt geführt werden kann. Für volle Autonomie gibt es browser_run_task — der Agent dreht selbst den Zyklus und liefert einen JSON-Bericht zurück.

4. Übertragung der Autorisierung auf den Server

# локально, в видимом окне: залогинился → 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. Deployment auf 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 ist Pflicht: Chromium im Container mit den Standard-64 MB /dev/shm stürzt bei schweren Seiten ab.

Einmalige Aufgabe auf dem Server:

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

Ohne 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. Aufgabenstellung und n8n

Der Daemon liest state/tasks.jsonl — eine Zeile = eine Aufgabe:

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

Ergebnisse werden in state/results.jsonl geschrieben mit den Feldern success, result, extracted, steps, tokens_in/out und der vollständigen Spur history. n8n kann Aufgaben in diese Datei schreiben (Execute Command / SSH-Knoten) und Ergebnisse lesen.

7. Token-Ersparnis

• Keine Screenshots: nur Text, ohne Vision-Modell.

• DOM-Filterung: In den Kontext gelangen nur sichtbare interaktive Elemente mit nicht-leerem Namen, maximal 250 pro Frame.

• Blockierung von Bildern/Schriften/Medien auf Netzwerkebene (BLOCK_MEDIA=true).

• Verlaufskomprimierung (HISTORY_WINDOW): vollständige Momentaufnahmen nur für die letzten Schritte, ältere werden zu action → result zusammengefaltet.

• Schleifenerkennung: Wenn sich der Fingerprint der Momentaufnahme nicht ändert, erhält das Modell die Anweisung, die Strategie zu wechseln.

8. Sicherheit

Aktionen, die unter RISKY_PATTERNS fallen (Zahlung, kaufen, bestellen, löschen, senden, checkout, pay, delete), erfordern eine Bestätigung: in der Konsole lokal oder per „Ja“-Antwort in Telegram auf dem Server (APPROVAL_MODE=telegram). ALLOW_EVAL=false verbietet standardmäßig die Ausführung beliebigen JS. Alle Aktionsfehler werden dem Modell als Observation zurückgegeben und lassen den Prozess nicht abstürzen. Geheimnisse werden nur in .env gespeichert, das von git ausgeschlossen ist.

9. Prüfung vor dem Produktionsbetrieb

1. python main.py snapshot --url <Zielseite> — landen die benötigten Elemente in der Momentaufnahme?

2. Aufgabenlauf lokal im Headful-Modus mit REQUIRE_APPROVAL=true.

3. Dieselbe Aufgabe lokal im Headless-Modus — fängt Rendering-Unterschiede vor dem Deployment ab.

4. Erst danach Deployment auf VPS und Start des Daemons.

Lizenz

MIT