Браузер: веб-автоматизация (browser_interact)

Навык — источник истины для browser_interact и request_credentials.

Действия

Список действий и их параметры — в JSON-схеме инструмента, она источник истины. Здесь только поведенческие нюансы, которых в схеме нет:

• После каждого действия возвращается page_structure (см. ниже); navigate открывает страницу, snapshot обновляет дерево без навигации.
• timeout — 1-120 сек (по умолчанию 30). Применяется к navigate, wait, select, hover, upload_file, screenshot.
• click/fill/check/type выполняются мгновенно через DOM — параметр timeout у них игнорируется.
• Для тяжёлых страниц (дашборды, отчёты) увеличь timeout у navigate до 60-90.
• select принимает value или видимый label опции.

page_structure

После каждого действия возвращается дерево accessibility-элементов:

[12] heading "Отслеживание посылок"
[13] textbox "Номера через запятую" value="768008218261"
[14] button "ПОИСК"
- group
  [15] StaticText "2026-06-05"
  [16] StaticText "14:54 +03:00"
  [17] StaticText "Прибыло на таможню."

Правила:

• [ref] — номер элемента для действий. Обновляется после КАЖДОГО действия — используй только свежие
• Роли: link, button, textbox, combobox, checkbox, radio, heading, img, dialog, alert, status
• value="..." — текущее значение поля
• checked=true/false — состояние чекбокса
• disabled — неактивен
• options=[...] — варианты combobox
• Отступы = вложенность
• - group — граница визуального блока (строка таблицы, карточка, событие): даты, суммы и статусы внутри одного group относятся друг к другу
• Максимум 200 элементов. Если element_count = 200 — список обрезан, нужный элемент может быть за пределами. Используй scroll + snapshot или wait(selector) для точного поиска

Обязательный рабочий процесс

1. navigate(url) → получить page_structure
2. Прочитай page_structure ПОЛНОСТЬЮ, найди нужные элементы
3. Одно действие за раз → проверь обновлённый page_structure
4. Все ref обновились — используй ТОЛЬКО свежие номера
5. После submit → проверь URL и page_structure (подтверждение? ошибка?)

Проверка результата click/fill/check

click/fill/check выполняются на DOM-уровне напрямую и НЕ проверяют actionability. Это значит:

• click по disabled-кнопке вернёт success=true, но ничего не произойдёт
• fill в readonly-поле пройдёт молча, value не изменится
• check на disabled-чекбоксе тоже silent no-op

После каждого click/fill/check сравни новый page_structure с ожиданием:

• click на «Войти» → URL должен смениться или появиться dashboard/ошибка валидации
• fill в поле → value="..." в page_structure должен содержать введённое
• check на чекбокс → checked=true в новом snapshot

Если ничего не изменилось — элемент был disabled, перекрыт или ref устарел:

1. Перечитай свежий page_structure — может элемент помечен disabled (видно в роли)
2. scroll(up) → snapshot — может над полем появилась ошибка валидации
3. Если нужна реальная mouse-симуляция (drag, custom slider на mousedown) — сообщи пользователю что не поддерживается

Элемент не найден в page_structure

Если нужный элемент (кнопка, ссылка, поле) не виден:

1. scroll(down) → snapshot — элемент ниже viewport
2. hover на иконки/кнопки без текста рядом с ожидаемой областью → snapshot (выпадающее меню, скрытая панель)
3. Для авторизации — navigate на прямой URL: /login, /signin, /auth, /account/login, /enter
4. wait(selector="нужный_CSS_селектор", timeout=10) → snapshot
5. Если ничего не помогло → screenshot + спроси пользователя: "Не нахожу [элемент]. Что вы видите на экране?"

НИКОГДА не кликай наугад. Лучше спросить пользователя, чем кликнуть не то.

SPA и динамические сайты

Признаки SPA: element_count < 5 после navigate, элементы появляются/исчезают после клика.

• element_count < 5 → wait(selector="body", timeout=10), затем snapshot
• Модальное окно не видно → wait(selector="input, form, [role=dialog]", timeout=10)
• Autocomplete → fill → snapshot (подожди варианты) → click по нужному
• SPA-навигация через back может не работать → используй navigate на нужный URL

fill vs type — когда что

fill — быстрый, очищает поле, вставляет целиком:

• Обычные текстовые поля, email, textarea
• Стандартные HTML-формы

type — посимвольный ввод (имитирует набор на клавиатуре):

• Поля с маской ввода (телефон +7(_), дата //__, ИНН)
• contenteditable-элементы (Google Docs, Notion, CMS)
• Rich-text редакторы (TinyMCE, CKEditor, Quill)
• Поля с автокомплитом, где нужно вызвать JS-обработчик keydown/keyup

Если fill не сработал (value осталось пустым или маска сломалась) → попробуй type.

Датапикеры и сложные виджеты

Кастомные JS-компоненты (календари, слайдеры, color picker) могут не иметь стандартных ролей в page_structure.

Стратегия:

1. Найди связанный textbox → fill/type с датой в нужном формате ("2024-03-15", "15.03.2024")
2. Если textbox нет → click на виджет, ищи появившиеся элементы через snapshot
3. Для слайдеров → click на элемент, затем press_key(ArrowRight/ArrowLeft) нужное число раз
4. Если ничего не работает → сообщи пользователю

Горизонтальный скроллинг

Таблицы с большим количеством колонок часто имеют горизонтальную прокрутку.

После горизонтального скролла → snapshot для обновления page_structure.

Спаривание дата↔значение в списках

Плоские списки StaticText (трекинг посылок, выписки, история заказов/событий) неоднозначны: подряд идущие даты и статусы легко спарить неправильно.

• Ориентируйся ТОЛЬКО на - group-границы и отступы — какой статус лежит в одном блоке с какой датой
• НИКОГДА не переставляй пары «как логичнее по хронологии» — бери буквально как сгруппировано на странице
• group-границ нет и спаривание неочевидно → сверь через web_fetch того же URL (HTML сохраняет разметку строк) или screenshot + analyze_image
• В ответе пользователю приводи пары дата+статус только если уверен в спаривании; иначе скажи, что порядок требует проверки

Работа с таблицами и пагинацией

Для извлечения данных из таблиц с пагинацией:

1. Прочитай page_structure — найди данные и кнопки пагинации ("Следующая", "Next", ">", "2", "3")
2. Собери данные с текущей страницы
3. click по кнопке следующей страницы
4. snapshot → собери данные → повтори
5. Остановись когда кнопка "Следующая" disabled или отсутствует

Для горизонтально широких таблиц — комбинируй scroll(right) + snapshot.

iframe

Контент внутри

Если ожидаемые элементы не найдены и на странице должен быть iframe:

1. Сообщи пользователю: "Форма находится внутри iframe, автоматическое взаимодействие ограничено"
2. Предложи альтернативу: прямой URL формы (если известен), API, ручной ввод

Несколько вкладок и popup-окна

Браузер всегда работает с первой вкладкой. Если клик открывает новую вкладку (target="_blank") или popup:

• Новая вкладка становится доступна, но автоматического переключения нет
• Предпочитай: перед кликом скопируй URL из href, открой через navigate
• Для OAuth popup — сообщи пользователю: "Авторизация открывается в отдельном окне. Войдите вручную и сообщите, когда будете готовы"

Скачивание файлов

Браузер НЕ поддерживает скачивание файлов напрямую. Для скачивания:

• Найди прямую ссылку (href) на файл в page_structure → используй web_fetch или sandbox_bash с wget/curl
• Если ссылка доступна только после авторизации → сообщи пользователю

alert / confirm / prompt

Нативные JS-диалоги автоматически принимаются (accept). ⚠ Включая confirm("Удалить?") — будет принят автоматически. Перед действиями удаления/отмены/отписки предупреди пользователя о том, что confirm-диалоги принимаются без подтверждения.

Drag-and-drop

Не поддерживается. Если интерфейс требует перетаскивание (канбан, конструктор):

• Проверь, есть ли альтернативные кнопки/меню для перемещения
• Если нет → сообщи пользователю

Правый клик / контекстное меню

Не поддерживается. Если нужно контекстное меню — ищи альтернативные элементы управления (кнопки "...", иконки шестерёнки, выпадающие меню).

Печать / экспорт в PDF

Прямой экспорт страницы в PDF не поддерживается. Альтернативы:

• screenshot для визуального снимка
• web_fetch для текстового контента
• Кнопка "Экспорт" / "Скачать PDF" на самом сайте

Авторизация (request_credentials)

НИКОГДА не вводи пароли через fill/type. Только request_credentials.

Поток:

1. navigate(url_логина)
2. Если SPA → wait(selector="input[type='password'], form", timeout=15), snapshot
3. Найди в page_structure: textbox для логина (Email/Логин/Телефон), textbox для пароля, button входа
4. request_credentials(service="Название", fields=[{name, label, type, ref}, ...])
5. click на кнопку входа
6. Проверь результат (URL сменился? dashboard?)

Если форма входа не найдена

1. navigate на прямой URL: /login, /signin, /auth, /account/login, /enter
2. hover на иконки в хедере (часто логин скрыт за иконкой пользователя)
3. Если после 3 попыток форма не найдена → screenshot + спроси пользователя

OAuth / SSO (Google, GitHub, VK)

Если кнопка "Войти через Google" → click. Если открывается:

• Редирект на том же домене → работай как обычно
• Popup/новая вкладка → ОСТАНОВИСЬ, сообщи: "OAuth открывается в отдельном окне. Войдите вручную"

Многостраничные формы (визарды)

1. Заполни все поля текущего шага
2. click на "Далее" / "Next"
3. wait(selector="input, select, textarea", timeout=10) или snapshot
4. ref обновились — работай с новой page_structure
5. Повтори до "Отправить" / "Submit"

Если "Далее" не работает:

• Ищи alert/status в page_structure — ошибка валидации?
• Все обязательные поля заполнены?
• Попробуй press_key(Enter)

Загрузка файлов

Файл должен быть в sandbox (/tmp/input/ или /tmp/work/). После загрузки проверь page_structure — имя файла или статус.

Попапы, cookie-баннеры, оверлеи

navigate автоматически закрывает распространённые cookie-баннеры.

Если попап блокирует:

1. Ищи button "Закрыть", "Close", "×", "Принять" → click
2. press_key(Escape)
3. snapshot — если попап исчез, продолжай

CAPTCHA / 2FA / SMS

ОСТАНОВИСЬ НЕМЕДЛЕННО. Сообщи пользователю:

• Что обнаружено (CAPTCHA / 2FA / SMS)
• "Автоматически пройти невозможно"
• Предложи: "Войдите вручную и скажите, когда будете на нужной странице"

НЕ пытайся обойти. НЕ делай retry.

Обработка ошибок

"Element [ref=N] not found"

ref устарел. НЕ повторяй. Прочитай page_structure из ответа, найди элемент заново.

element_count = 0

Страница не загрузилась → wait(selector="body", timeout=15). Если 0 — заблокирована (403, капча). Сообщи.

Правило трёх попыток

3 действия без прогресса → СТОП. Сообщи пользователю что пытался, какие ошибки, что делать.

Антипаттерны (ЗАПРЕЩЕНО)

1. click по элементу без текста наугад — если не знаешь что это, НЕ КЛИКАЙ. Используй hover или спроси пользователя
2. Повтор невалидного ref
3. screenshot для своей диагностики (ты НЕ видишь результат) — используй page_structure. screenshot полезен только чтобы показать пользователю
4. fill/type для паролей — только request_credentials
5. Бесконечные retry — максимум 3 попытки
6. navigate вместо snapshot для обновления page_structure
7. Взаимодействие при element_count < 5 — сначала wait

Когда НЕ использовать браузер

• Чтение текста → web_fetch
• API-запросы → connector() или sandbox_bash
• Скачивание файлов → web_fetch или wget/curl в sandbox_bash
• Парсинг → sandbox_bash + python + requests + BeautifulSoup

Браузер = интерактивное взаимодействие: клики, формы, авторизация, JS-рендеринг.

Live Preview

The user can see a live preview of the browser viewport in the artifacts panel. After every action, a JPEG frame is streamed to the UI automatically. You do NOT need to take explicit screenshots for the user to see what is happening — they already see it. Use the screenshot action only when you need a full PNG for file output or detailed analysis.

WebMCP (Forward-Looking)

If a website supports WebMCP (navigator.modelContext available), prefer calling structured tools exposed via WebMCP instead of DOM navigation. This provides more reliable, API-level interaction with the page.