CogniWeb Agent

Автономный агент для управления браузером, построенный на Playwright и языковых моделях через OpenRouter. Агент навигирует по любому сайту и выполняет задачи, описанные на естественном языке — без захардкоженных селекторов, готовых сценариев и сайт-специфичной логики.

---

Демонстрация

Демонстрация WebAgent

Полное видео демонстрации

---

Архитектура

Реестр подагентов (Sub-agent Registry)

Каждый специализированный агент наследует от SubAgentBase и декларирует роль через свойство role. AgentOrchestrator строит SubAgentRegistry при инициализации и получает агентов по роли — это делает состав пайплайна явным и позволяет подменять агентов в тестах без изменения оркестратора.

SubAgentBase (ABC)
├── PlannerAgent   role=AgentRole.PLANNER   — 1 вызов LLM, декомпозиция задачи
├── ExecutorAgent  role=AgentRole.EXECUTOR  — ReAct-цикл, 11 инструментов
└── VerifierAgent  role=AgentRole.VERIFIER  — независимая проверка успеха шага

SubAgentRegistry
├── register(agent)          — регистрация по agent.role
├── get(AgentRole.PLANNER)   — получение по роли
└── registered_roles()       — список активных ролей

Трёхзвенный конвейер

Задача пользователя
        │
        ▼
┌─────────────────────────────────────────────────┐
│           SubAgentRegistry                       │
│  ┌─────────────┐  ┌──────────────┐  ┌─────────┐ │
│  │PlannerAgent │  │ExecutorAgent │  │Verifier │ │
│  │  PLANNER    │  │  EXECUTOR    │  │VERIFIER │ │
│  └──────┬──────┘  └──────┬───────┘  └────┬────┘ │
└─────────┼────────────────┼───────────────┼──────┘
          │ Plan            │ ActionResult  │ Verification
          ▼                 ▼               ▼
┌─────────────────────────────────────────────────┐
│              AgentOrchestrator                   │
│         Plan → Execute → Verify → Retry?         │
└─────────────────────────────────────────────────┘
          │
          ▼
┌──────────────────┐
│ SecurityGateway  │  — terminal confirmation / dry-run / disabled
└──────────────────┘
          │
          ▼
┌──────────────────┐
│   AuditLogger    │  — audit/session_*.jsonl
└──────────────────┘

Структура исходников

src/
├── config/          — Pydantic v2 BaseSettings
├── core/            — Доменные модели и иерархия исключений
├── infrastructure/  — BrowserService (Playwright), LLMService (OpenRouter)
├── agent/
│   ├── base.py      — SubAgentBase (ABC) + AgentRole (enum)
│   ├── registry.py  — SubAgentRegistry
│   ├── orchestrator.py — тонкий координатор
│   ├── planner.py   — PlannerAgent
│   ├── executor.py  — ExecutorAgent (ReAct-цикл)
│   └── verifier.py  — VerifierAgent
├── security/        — SecurityGateway (normal / dry-run / disabled)
└── utils/
    ├── dom.py        — DOMProcessor (JavaScript-инъекция в живой DOM)
    └── audit.py      — AuditLogger (JSONL-транскрипт действий)

---

Установка

Требования: Python 3.10+, Google Chrome (установленный в системе)

Виртуальное окружение

Перед установкой зависимостей создайте и активируйте виртуальное окружение:

Windows (cmd):

python -m venv .venv
.venv\Scripts\activate

Windows (Git Bash / MSYS2):

python -m venv .venv
source .venv/Scripts/activate

Linux / macOS:

python -m venv .venv
source .venv/bin/activate

Проверить активацию:

python --version   # должен показать Python 3.10+
pip --version

Деактивировать окружение после работы: deactivate

---

Зависимости и конфигурация

pip install -r requirements.txt
playwright install chrome
cp .env.example .env
# Открыть .env и указать OPENAI_API_KEY

API-ключ — на openrouter.ai/keys.

Запуск

Windows:

run.bat

MSYS2 / Git Bash:

./run.sh

Агент спросит задачу и опциональный стартовый URL.

---

Демо-фикстуры

# Запустить сервер фикстур
python demo/serve.py   # → http://localhost:8765

# Примеры задач для демо
# Task: Read the last 10 emails and delete spam
# Starting URL: http://localhost:8765/mail.html

# Task: Find a BBQ burger and add it to the cart
# Starting URL: http://localhost:8765/food.html

# Task: Find 3 relevant job listings and check application requirements
# Starting URL: http://localhost:8765/jobs.html

Фикстура	URL	Описание
mail.html	/mail.html	Входящие с 10 письмами
food.html	/food.html	Меню ресторана, корзина, Pay Now / Checkout
jobs.html	/jobs.html	5 вакансий с Apply Now

---

Тесты

pip install -r requirements-dev.txt
pytest tests/ -v

Файл	Тесты	Описание
test_agent_core.py	26	Модели, история, LLM-парсинг, детектирование петель
test_security.py	11	SecurityGateway (normal / dry-run / disabled)
test_sub_agent_registry.py	24	SubAgentBase, SubAgentRegistry, AuditLogger
test_demo_fixtures.py	5	Интеграционные тесты с живым браузером

Интеграционные тесты:

python demo/serve.py &
pytest tests/test_demo_fixtures.py -v -m integration

---

Шлюз безопасности

Режим	Настройка	Поведение
Нормальный	SECURITY_CONFIRMATION_ENABLED=true	Блокирует и ждёт yes в терминале
Dry-run	SECURITY_DRY_RUN=true	Логирует предупреждение, пропускает без prompt'а
Отключён	SECURITY_CONFIRMATION_ENABLED=false	Всё проходит без проверки

Критичные паттерны: URL /checkout, /payment, /delete; кнопки pay, submit, delete, buy; поля card, cvv, billing.

---

Аудит-лог

После каждого запуска в audit/ появляется файл session_YYYYMMDD_HHMMSS.jsonl. Каждая строка — JSON-запись одного события (план, действие, результат шага, итог задачи).

---

Конфигурация

Переменная	По умолчанию	Описание
OPENAI_API_KEY	—	API-ключ OpenRouter (обязательно)
MODEL_NAME	upstage/solar-pro	Модель в формате OpenRouter
HEADLESS	false	Запуск без видимого окна
MAX_STEPS	50	Бюджет действий на все шаги
RATE_LIMIT_SECONDS	15.0	Интервал между вызовами LLM
DOM_ELEMENT_LIMIT	50	Максимум элементов в наблюдении
USE_FUNCTION_CALLING	true	OpenAI tool calling
SECURITY_CONFIRMATION_ENABLED	true	Подтверждение критичных действий
SECURITY_DRY_RUN	false	Dry-run режим безопасности
ENABLE_STEALTH	true	playwright-stealth
PLANNER_TEMPERATURE	0.2	Температура планировщика
VERIFY_MAX_TOKENS	500	Лимит токенов верификатора
MAX_RETRY_ATTEMPTS	3	Попытки при ошибках LLM
RETRY_WAIT_MIN / MAX	2.0 / 10.0	Диапазон backoff (сек)
EXECUTOR_HISTORY_WINDOW	10	Сообщений в истории Executor
EXECUTOR_RETRY_BUDGET	5	Бюджет при повторном шаге
CAPTCHA_WAIT_SECONDS	3.0	Пауза между проверками CAPTCHA

Полный список — в .env.example.

---

Стек технологий

Категория	Технология	Версия	Назначение
Язык	Python	3.10+	Весь проект
Браузер	Playwright	≥1.40	Управление Chromium
Stealth	playwright-stealth	≥1.0.6	Маскировка WebDriver
LLM-клиент	openai (AsyncOpenAI)	≥1.0	Асинхронные вызовы LLM
Валидация	Pydantic v2	≥2.0	Типобезопасные модели
Конфигурация	pydantic-settings	≥2.0	BaseSettings → .env
HTTP	httpx	≥0.25	Async HTTP, proxy
Retry	tenacity	≥8.2	Экспоненциальный откат
Тесты	pytest + pytest-asyncio	≥7.4	Юнит-тесты async