AIKraft/AI/Поиск…⌘KВойти
Главная/Документация/Справочник агента/Инструменты браузера
Справочник агента

Инструменты браузера

Использование встроенного браузера Chromium в AIKraft Agents для управления окнами, навигации, взаимодействия с элементами и отладки веб-страниц.

Быстрый старт

Выполните browser_tool --help, чтобы увидеть все доступные команды и примеры их использования.

Пути использования браузера

  1. Основной и единственный интерфейс инструмента в рамках сессии: browser_tool
  2. Вспомогательный интерфейс командной строки: bun run browser-tool --help для поиска команд и шаблонов, а также bun run browser-tool parse-url <url> для безопасной диагностики URL вне хода выполнения задач агентом

Браузер как альтернатива настройке источника

Используйте рабочие процессы с браузером, когда создание источника добавило бы ненужные накладные расходы для текущей задачи.

Браузер подходит лучше всего для:

  • Разовых задач, не требующих повторно используемой интеграции
  • Рабочих процессов, работающих только с интерфейсом, где покрытие через API или MCP-серверы недостаточно
  • Сложных случаев настройки источника или аутентификации, когда пользователю нужны результаты прямо сейчас

Источники всё же предпочтительнее, когда:

  • Работа повторяема и требуется автоматизация или формирование отчётов
  • Важны повторное использование в рамках команды и стабильность инструментов

Основной рабочий процесс

Если вы не уверены, какое окно использовать, выполните:

terminalbash
browser_tool({ command: "windows" })

Рекомендуемый порядок действий:

  1. open — убедитесь, что окно браузера существует (по умолчанию открывается в фоновом режиме)
  2. navigate <url> — загрузите URL
  3. snapshot — изучите доступные элементы и получите ссылки на них (@e1, @e2 и т. д.)
  4. find <query> — быстро сузьте выбор до совпадающих ссылок по ключевым словам
  5. click / fill / select — взаимодействуйте, используя ссылки
  6. screenshot --annotated (или screenshot-region) — визуальная проверка при необходимости

Примеры команд browser_tool

terminalbash
browser_tool({ command: "--help" })
browser_tool({ command: "open" })
browser_tool({ command: "open --foreground" })
browser_tool({ command: "navigate https://example.com" })
browser_tool({ command: "snapshot" })
browser_tool({ command: "find login button" })
browser_tool({ command: "click @e12" })
browser_tool({ command: "click-at 350 200" })
browser_tool({ command: "drag 100 200 300 400" })
browser_tool({ command: "fill @e5 user@example.com" })
browser_tool({ command: "type Hello World" })
browser_tool({ command: "select @e3 optionValue" })
browser_tool({ command: "select @e75 CNAME --assert-text Target --timeout 3000" })
browser_tool({ command: "upload @e3 /absolute/path/to/file.pdf" })
browser_tool({ command: "set-clipboard Name\tAge\nAlice\t30" })
browser_tool({ command: "get-clipboard" })
browser_tool({ command: "paste Name\tAge\nAlice\t30" })
browser_tool({ command: "scroll down 800" })
browser_tool({ command: "evaluate document.title" })
browser_tool({ command: "console 50 warn" })
browser_tool({ command: "screenshot" })
browser_tool({ command: "screenshot --annotated" })
browser_tool({ command: "screenshot-region --ref @e12 --padding 8" })
browser_tool({ command: "window-resize 1280 720" })
browser_tool({ command: "network 50 failed" })
browser_tool({ command: "wait network-idle 8000" })
browser_tool({ command: "key Enter" })
browser_tool({ command: "downloads wait 15000" })
browser_tool({ command: "focus" })
browser_tool({ command: "windows" })
browser_tool({ command: "release" })
browser_tool({ command: "hide" })
browser_tool({ command: "close" })

Обёртка проверяет команды и возвращает понятные ошибки, если аргументы отсутствуют или некорректны.

Для большинства команд возвращается также расширенный вывод о выполнении, включая состояние до и после (где это доступно): позиции прокрутки, активный элемент, переходы URL/заголовка, ограничение размеров окна, сводки запросов/ошибок, а также детали владения окном и его видимости.

Вы можете объединять команды через точку с запятой, например:

fill @e1 user@example.com; fill @e2 password123; click @e3

Пакеты выполняются слева направо и автоматически останавливаются после команд навигации (navigate, click, back, forward), чтобы ссылки на элементы не устаревали незаметно.

Кавычки и экранирование

browser_tool поддерживает аргументы в кавычках:

  • Двойные кавычки: fill @e5 "Hello world"
  • Одинарные кавычки: wait text 'welcome back' 5000

Точки с запятой внутри кавычек воспринимаются как буквальный текст (а не как разделители пакетов):

  • fill @e1 "a;b;c"; click @e2
  • screenshot-region --selector "div[data-x='a;b']" --padding 8

При необходимости используйте экранирование обратной косой чертой:

  • \; для буквальной точки с запятой вне кавычек
  • \" для буквальной двойной кавычки внутри текста в двойных кавычках

Ключевые команды

open [--foreground|-f]

Создаёт или повторно использует окно браузера сессии.

  • По умолчанию: открывается в фоновом режиме
  • --foreground / -f: фокусируется в переднем плане

snapshot

Возвращает дерево доступности со ссылками и метаданными элементов.

find <query>

Выполняет поиск по ключевым словам в узлах доступности снимка (role, name, value, description) и возвращает совпадающие ссылки.

click <ref> [waitFor] [timeoutMs]

Нажимает на элемент по ссылке из snapshot. Доступны опциональные режимы ожидания: none, navigation, network-idle.

click-at <x> <y>

Нажимает по координатам пикселей. Используйте это для интерфейсов на основе canvas (например, ячейки Google Sheets, элементы карты, точки данных графиков), где snapshot не может сгенерировать ссылки на элементы. Координаты можно получить из screenshot или screenshot-region.

drag <x1> <y1> <x2> <y2>

Перетаскивает от координат пикселей (x1, y1) к (x2, y2). Выполняет события mousedown, интерполированные mousemove и mouseup. Используйте это для:

  • Перемещения графиков или объектов в интерфейсах на основе canvas (например, графики в Google Sheets)
  • Изменения порядка элементов перетаскиванием
  • Изменения размеров элементов перетаскиванием маркеров
  • Рисования или выделения областей

Координаты можно получить из screenshot или screenshot --annotated.

fill <ref> <value> / select <ref> <value> [--assert-text <text>] [--assert-value <value>] [--timeout <ms>]

Заполняет текстовые поля или выбирает значения в выпадающих списках. Требует ссылку на элемент из snapshot.

Для современных интерфейсов комбинированных полей на React/portal команда select теперь выполняет дополнительную проверку и может вернуть предупреждение, если взаимодействие успешно, но состояние формы, похоже, не изменилось.

Полезные флаги:

  • --assert-text <text>: проверка изменения downstream-интерфейса (например, метка поля меняется на Target)
  • --assert-value <value>: проверка, что выбранное управление отражает ожидаемое значение
  • --timeout <ms>: таймаут проверки (по умолчанию 2000 мс)

upload <ref> <path> [path2...]

Прикрепляет локальные файл(ы) к полю ввода файла (<input type="file">), используя ссылку из snapshot.

Примечания:

  • Используйте абсолютные пути к файлам.
  • Поддерживается несколько файлов: upload @e3 /path/a.pdf /path/b.jpg
  • Файлы должны существовать и проходить проверку безопасности (чувствительные пути заблокированы).

type <text>

Вводит текст посимвольно в текущий активный элемент без необходимости использовать ссылку. Используйте это, когда:

  • Цель — поле ввода на основе canvas (ссылка DOM недоступна)
  • Элемент уже активирован через click или click-at
  • Приложение использует собственный механизм ввода

Отличие от fill: fill активирует ссылку и заменяет её значение. type отправляет нажатия клавиш тому элементу, который в данный момент активен.

set-clipboard <text> / get-clipboard

Чтение или запись буфера обмена страницы программно.

  • set-clipboard записывает текст и интерпретирует распространённые управляющие последовательности:
    • \t → табуляция
    • \n → новая строка
    • \r → возврат каретки
    • \\ → буквальная обратная косая черта
  • Неизвестные управляющие последовательности сохраняются буквально (пример: \\x остаётся \\x)
  • get-clipboard читает текущее содержимое буфера обмена как сырой текст (табуляции и новые строки возвращаются как реальные символы)

paste <text>

Удобная команда: записывает текст в буфер обмена, затем вызывает Ctrl+V (или Cmd+V на Mac). Эквивалентно set-clipboard <text>, за которым следует key v meta / key v control. Обработка экранирования идентична set-clipboard, что обеспечивает надёжность массового ввода данных в формате TSV.

screenshot / screenshot --annotated / screenshot-region ...

Создание снимков всего окна или его частей. Флаг --annotated накладывает метки @eN на интерактивные элементы для упрощения отладки ссылок.

console, network, wait, downloads

Отладка проблем во время выполнения, запросов, точек синхронизации и прогресса загрузок.

Вывод downloads включает разрешённый локальный savePath (если доступен), чтобы вы могли напрямую ссылаться на загруженный файл.

focus [windowId] / windows

Управление и проверка владения окном браузера и его видимости.

Команды жизненного цикла

  • release — снимает оверлей агента, оставляя окно видимым для пользователя
  • hide — скрывает окно, но сохраняет состояние сессии
  • close — закрывает и уничтожает окно

Распространённые ошибки валидации

  • Missing command... → передайте строку команды (попробуйте --help)
  • Unknown browser_tool command ... → опечатка или неподдерживаемое действие; проверьте справку
  • ...requires ... → отсутствует обязательный аргумент для этой команды
  • ...must be numbers → не удалось распознать числовой аргумент

Вспомогательный инструмент: browser-tool parse-url

Используйте его для безопасной отладки URL в режиме Изучение без запуска фрагментов общего интерпретатора:

terminalbash
bun run browser-tool parse-url https://example.com/path?q=1#hash
bun run browser-tool parse-url file:///Users/me/Desktop/report.html

Вывод — детерминированный JSON (href, protocol, host, hostname, pathname, search, hash, origin, а также basename для URL вида file://).

Примечания по поведению

  • Инструменты браузера по умолчанию разрешены в режиме Изучение/Безопасный режим.
  • Перед первым использованием инструментов браузера агент должен прочитать это руководство (~/.craft-agent/docs/browser-tools.md).
  • Закрытие интерфейса браузера через системные элементы управления может скрыть окно; используйте browser_tool close для явного завершения работы.

Рецепт: Интерфейсы на основе canvas (Google Sheets и др.)

Веб-приложения на основе canvas (Google Sheets, Google Docs, некоторые интерфейсы карт/графиков) рендерят содержимое как пиксели на <canvas> — отдельные ячейки или элементы не являются узлами DOM и не появятся в snapshot. Используйте следующие шаблоны:

Рабочий процесс Google Sheets

terminalbash
# 1. Переход и ожидание загрузки
navigate https://docs.google.com/spreadsheets/d/{id}/edit
wait selector [aria-label="Name Box"] 10000

# 2. Переход к ячейке через поле имени (DOM-элемент — snapshot находит его)
snapshot
click @nameBoxRef
type A1
key Enter

# 3. Редактирование ячейки
key F2
type Hello World
key Enter

# 4. Массовая запись через вставку TSV из буфера обмена
snapshot
click @nameBoxRef
type A1
key Enter
paste Name\tAge\tCity\nAlice\t30\tNYC\nBob\t25\tLA

# 5. Чтение данных через буфер обмена
key a meta           # Выделить всё (Cmd+A)
key c meta           # Копировать (Cmd+C)
get-clipboard        # Возвращает строку TSV

# 6. Нажатие на ячейку canvas по координатам (из снимка)
click-at 350 200

# 7. Перемещение графика перетаскиванием (координаты из снимка)
drag 400 300 100 50

# 8. Чтение данных через URL экспорта (редактирование не требуется)
navigate https://docs.google.com/spreadsheets/d/{id}/export?format=csv&gid=0

Ключевые принципы для интерфейсов на основе canvas

  • Поле имени и строка формул — это DOM-элементы — snapshot может их найти
  • Ячейки — это пиксели canvas — используйте click-at или навигацию клавиатурой, а не click
  • Графики и объекты можно перемещать — используйте drag для изменения положения элементов на canvas
  • Горячие клавиши надёжнее кликов — используйте key для навигации
  • Буфер обмена TSV — самый быстрый путь для массовых данных — paste с значениями, разделёнными табуляцией
  • URLы экспорта работают с cookie сессии — ключи API для чтения не требуются

Устранение неполадок

«Элементы управления окном браузера недоступны»

Диспетчер десктопного браузера не подключён к этому времени выполнения/сессии. Убедитесь, что вы используете десктопное приложение Electron и сессия инициализирована.

«Элемент @eX не найден»

Ссылки устарели. Повторно выполните snapshot и используйте свежие ссылки.

Взаимодействие кажется нестабильным

Дождитесь готовности страницы и повторите попытку, используя:

open → snapshot → взаимодействие

Нужен такой агент в вашей компании?

Устанавливаем под ключ: настройка на компьютерах сотрудников, единый аккаунт, интеграция с 1С и внутренними системами, обучение команды. Подробнее о внедрении →