Браузерный агент

Браузерный агент выполняет веб-задачи, которые ваш код не может решить обычным HTTP-запросом: ищет на сайте, переходит по страницам, заполняет и отправляет формы, входит в аккаунты и читает то, что показывает страница. Вы описываете задачу простыми словами. Агент работает в настоящем браузере Chromium, по одному действию за раз, и возвращает текстовый ответ answer, а если вы попросите, ещё и JSON в data.

Он использует тот же API-ключ и предоплаченный баланс, что и остальной Lovely Router. Вы платите за шаг, от $0.006, и модели уже включены. Платы за запуск нет.

Запуск первой задачи#

1. 1

   Получите API-ключ

   Создайте ключ на странице API-ключи и экспортируйте его. За пост о Lovely Router в X вы получите $2 бесплатного кредита — этого хватит на десятки коротких запусков (как).

   Shell

   export LOVELY_API_KEY="lr-..."

2. 2

   Запустите задачу

   Отправьте goal и start_url на POST /v1/browser/runs. Ответ приходит сразу со статусом 202 и id запуска. Агент продолжает работать в фоне.

   cURLPythonNode.js

   Shell

   curl https://lovelyrouter.com/v1/browser/runs \
     -H "Authorization: Bearer $LOVELY_API_KEY" \
     -H "content-type: application/json" \
     -d '{
       "goal": "Find the price of the book \"A Light in the Attic\" and whether it is in stock.",
       "start_url": "https://books.toscrape.com/"
     }'

3. 3

   Дождитесь результата

   Запросите запуск с ?wait=30. Запрос удерживается до 30 секунд (максимум 50) и возвращается, как только меняется статус, поэтому цикл из таких вызовов следит за запуском без активного опроса.

   Чтобы вместо этого наблюдать за запуском — видеть каждый шаг и экран браузера в момент, когда они происходят, — добавьте "stream": true при старте. См. События и экран в реальном времени.

   cURLPythonNode.js

   Shell

   curl "https://lovelyrouter.com/v1/browser/runs/brun_3f9a1c7e0b2d4e6f8a9b0c1d?wait=30" \
     -H "Authorization: Bearer $LOVELY_API_KEY"

4. 4

   Прочитайте результат

   У завершённого запуска есть status, ответ агента answer и его стоимость в charge_usd (в сокращении):

   JSON

   {
     "id": "brun_3f9a1c7e0b2d4e6f8a9b0c1d",
     "object": "browser_run",
     "status": "succeeded",
     "mode": "fast",
     "steps": 2,
     "max_steps": 50,
     "current_url": "https://books.toscrape.com/catalogue/a-light-in-the-attic_1000/index.html",
     "answer": "\"A Light in the Attic\" costs £51.77 and is in stock (22 available).",
     "data": null,
     "error": null,
     "charge_usd": 0.012,
     "reserved_usd": 0
   }

   Полный список полей — в разделе Объект запуска. Добавьте к запросу &trace=1, чтобы получить все шаги, которые сделал агент.

Запускать задачи можно и из консоли: выберите пример или напишите задачу, наблюдайте за экраном браузера и каждым шагом в реальном времени, отвечайте агенту, когда он спрашивает, и копируйте соответствующий код на cURL, Python или JavaScript.

Как работает запуск#

Запуск начинается в статусе running и заканчивается одним из четырёх финальных статусов. В промежутке он может приостановиться в статусе waiting_for_human и продолжиться после вашего ответа.

На каждом шаге агент читает текущую страницу, выбирает одно действие и выполняет его. Он останавливается, когда цель достигнута, когда нужен человек или когда исчерпан max_steps. Прежде чем нажать кнопку, отправляющую форму, он сверяет каждое поле с вашей целью и исправляет значения, которые ей не соответствуют.

succeeded означает, что агент закончил работу, а не что сайт принял сделанное. Для задач, которые что-то отправляют, читайте answer: если страница показала ошибку валидации или не показала подтверждения, ответ об этом скажет.

Когда запуск завершается, неиспользованная часть суммы, зарезервированной в начале, возвращается на баланс, а charge_usd показывает итоговое списание. До этого момента charge_usd равен null.

Что считается шагом#

Шаг — это одно действие в браузере:

• клик по ссылке, кнопке, флажку или пункту списка
• ввод текста в поле или ввод с нажатием Enter
• выбор варианта в выпадающем списке
• подстановка сохранённого секрета или загрузка файла
• возврат на предыдущую страницу
• ожидание страницы, которая ещё не загрузилась, или её повторная загрузка
• выполнение кода только для чтения, чтобы извлечь данные со страницы (только в точном режиме)
• запись итогового ответа

Паузы ради человека (вопрос, подтверждение, передача управления) видны в трассировке, но не оплачиваются. Неудачный шаг, например из-за того, что элемент сместился, всё равно считается. Поле steps запуска учитывает каждый записанный шаг, включая паузы.

Простой поиск занимает от 1 до 3 шагов. Вход в аккаунт — от 4 до 8. Длинная многостраничная форма — от 15 до 25. Примеры стоимости приведены в разделе Режимы, модели и цены.

Как писать работающие цели#

Цель — единственная инструкция для агента. Пишите её так, как ставили бы задачу внимательному ассистенту, который ни разу не видел этот сайт.

• Указывайте все значения, нужные для задачи. Имена, email, даты, количества, точный товар. Не заставляйте агента угадывать: если значения не хватает, он остановится и спросит вас (если вы не отключили вопросы).
• Говорите, что нужно сообщить. «Скажи цену и есть ли книга в наличии» даёт лучший ответ, чем «проверь книгу».
• Для действий указывайте, что подтверждает успех. «Отправь форму и сообщи номер подтверждения».
• Начинайте поближе к задаче. Если знаете, используйте как start_url страницу поиска или саму форму, а не главную.
• Называйте, где искать, если на сайте таких мест несколько: «во вкладке Reviews», «через собственный поиск сайта».
• Одна задача на запуск. Разносите несвязанные задачи по отдельным запускам.
• Не пишите секреты в цели. Передавайте пароли как секреты из хранилища, никогда в тексте цели.

Ограничения#

Если достигнут лимит одновременных запусков, POST /v1/browser/runs возвращает 429. Если баланс меньше суммы, которую резервирует запуск, возвращается 402. Все ошибки перечислены в разделе Ошибки.

Использование из ИИ-агента#

MCP-сервер по адресу https://lovelyrouter.com/mcp предоставляет браузерного агента в виде четырёх инструментов: browser_run, browser_status, browser_reply и browser_takeover. Они используют тот же ключ, лимиты и цены, что и REST API. MCP-инструменты принимают имена секретов из хранилища, а не их значения: сначала сохраните секреты в хранилище.

Что дальше#