OS Level Actions в Amazon Bedrock AgentCore Browser: прямое управление ОС через InvokeBrowser API

AI-агенты, автоматизирующие веб-сценарии, работают в веб-слое браузера — в DOM, который открывают Playwright и Chrome DevTools Protocol (CDP). Amazon Bedrock AgentCore Browser предоставляет для этого безопасную изолированную среду и хорошо подходит для большинства задач автоматизации: переходов по страницам, заполнения форм, кликов по элементам и извлечения контента. Но у веб-слоя есть жесткая граница. Все, что отображает операционная система — нативные диалоги, запросы безопасности, выбор сертификата, контекстные меню и даже настройки Chrome, — находится за пределами DOM. CDP этого не видит, а Playwright не может с этим работать.

Когда веб-приложение вызывает window.print() и появляется системный диалог печати, у Playwright нет DOM, с которым можно взаимодействовать. Когда в сценарии нужен клавиатурный шорткат или контекстное меню по правому клику, CDP не умеет отправлять такие команды на уровне ОС. Когда браузерная сессия сталкивается с диалогом конфиденциальности macOS, запросом Windows Security или выбором сертификата, веб-слой автоматизации их не видит. Как правило, такие сценарии проявляются в продакшене: они зависят от состояния приложения, конфигурации ОС или прав пользователя, а не от тестовой среды, где поведение веб-контента достаточно предсказуемо.

Для агентов с поддержкой зрения проблема становится еще острее. Распространенная архитектура — сделать снимок экрана, отправить его в модель, получить координаты или инструкцию и выполнить действие. Для веб-контента такой цикл работает хорошо, но ломается в момент, когда появляется нативный интерфейс. Снимок экрана его показывает, модель понимает, что нужно сделать, но действовать уже нечем. CDP не может дотянуться до того, что отрисовала ОС. Агент видит, что нужно делать, и не имеет способа это выполнить.

Мы объявляем OS Level Actions для AgentCore Browser. Эта новая возможность снимает ограничения в таких сценариях, открывая прямое управление ОС через API InvokeBrowser, чтобы агенты могли взаимодействовать с контентом, видимым на экране, а не только с тем, что доступно в веб-слое браузера. В сочетании с полноэкранными снимками и управлением мышью и клавиатурой на уровне ОС агенты могут наблюдать нативный интерфейс, рассуждать о нем и действовать в той же сессии. В этой статье показано, как работают OS Level Actions, какие действия поддерживаются и как начать работу.

Как работают OS Level Actions

OS Level Actions доступны для новых и существующих конфигураций браузера без дополнительной настройки. После запуска сессии вы отправляете действия через API InvokeBrowser. Каждый вызов содержит ровно одно действие, определяемое его типом и аргументами, и возвращает статус SUCCESS или FAILED. Активная сессия идентифицируется заголовком x-amzn-browser-session-id, который связывает каждое OS-действие с нужной браузерной сессией.

Ожидаемый паттерн взаимодействия — цикл действие-скриншот-реакция. Агент выполняет действие (клик, ввод, шорткат), делает снимок экрана, чтобы увидеть текущее состояние, а затем выбирает следующее действие на основе того, что видит. Такой цикл позволяет агенту реагировать на динамический интерфейс, включая нативные диалоги и системные запросы, которые могут появиться в середине процесса.

1. Агент отправляет действие. Это может быть клик мышью, нажатие клавиши или шорткат через InvokeBrowser.
2. AgentCore выполняет действие на полном рабочем столе ОС и возвращает SUCCESS или FAILED.
3. Агент запрашивает снимок экрана, чтобы увидеть текущее состояние дисплея.
4. AgentCore делает снимок всего рабочего стола, включая нативные диалоги, модальные окна ОС и интерфейс за пределами окна браузера, и возвращает PNG в base64.
5. Агент анализирует снимок экрана, отправляя его в vision-модель, чтобы понять, что произошло и что делать дальше.
6. Агент отправляет следующее действие на основе увиденного, продолжая цикл.

Поддерживаемые действия

OS Level Actions разделены на три категории: управление мышью, ввод с клавиатуры и визуальный захват. В таблице ниже приведены восемь действий, их поля и ограничения.

Действия мышью

Действия мышью покрывают весь диапазон взаимодействий с указателем: клики, перемещение, перетаскивание и прокрутку. Поля координат для mouseClick необязательны. Если их не указать, клик будет выполнен в текущей позиции курсора левой кнопкой и одиночным нажатием. Это удобно, когда предыдущий mouseMove уже поставил курсор в нужную точку. mouseDrag требует четыре координаты — начальные и конечные позиции. mouseScroll принимает позицию и значения delta для обеих осей; отрицательный deltaY прокручивает вниз, положительный — вверх. Например, контекстное меню по правому клику — это один mouseClick с кнопкой RIGHT в нужных координатах. Учтите, что некоторые пункты контекстного меню могут работать не так, как ожидается, из-за виртуализированной среды, в которой работает браузерная сессия.

Действия клавиатуры

Три клавиатурных действия покрывают разные уровни ввода. keyType предназначен для ввода текста. Он отправляет символы напрямую и поддерживает строки длиной до 10 000 символов. keyPress нужен для отдельных клавиш, которые требуется нажимать многократно, например tab для перехода между полями формы или escape для закрытия модального окна. keyShortcut используется для комбинаций — передайте массив имен клавиш, и AgentCore нажмет их одновременно.

Имена клавиш для keyPress и keyShortcut должны быть в нижнем регистре. Поддерживаются одиночные символы (a–z, 0–9) и именованные клавиши, такие как enter, tab, space, backspace, delete, escape, ctrl, alt и shift.

Чтобы выделить весь текст, например, нужно использовать keyShortcut с ["ctrl", "a"].

{
 "action": {
 "keyShortcut": {
 "keys": ["ctrl", "a"]
 }
 }
}

Снимок экрана

Действие screenshot делает снимок всего рабочего стола ОС и возвращает PNG в base64 в ответе. Это единственное действие, которое возвращает данные. Остальные действия возвращают только статус (SUCCESS или FAILED) и поле ошибки в случае сбоя.

{
 "action":{
 "screenshot":{
 "format":"PNG"
 }
 }
}

Как начать

Примеры ниже показывают цикл действие-скриншот-реакция и соответствуют сопроводительному ноутбуку. Для полноценного рабочего ноутбука, где восьми действий показаны end to end, начните с него.

Настройка клиентов и создание браузера

Нужны два клиента: client уровня control plane (bedrock-agentcore-control) для управления ресурсами браузера и client уровня data plane (bedrock-agentcore) для отправки действий во время сессии.

import boto3
import time

browser_boto3 = boto3.client('bedrock-agentcore-control', region_name='us-west-2')

BROWSER_NAME = "browser_with_os_actions"

Перед началом сессии нужен IAM execution role и ресурс браузера. Для execution role требуются разрешения bedrock-agentcore:InvokeBrowser, bedrock-agentcore:StartBrowserSession и bedrock-agentcore:StopBrowserSession. В сопроводительном ноутбуке есть helper, который создаст эту роль за вас:

from helpers.utils import create_agentcore_execution_role, SAMPLE_ROLE_NAME

execution_role_arn = create_agentcore_execution_role(SAMPLE_ROLE_NAME)

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

created_browser = browser_boto3.create_browser(
    name=BROWSER_NAME,
    executionRoleArn=execution_role_arn,
    networkConfiguration={
        'networkMode': 'PUBLIC'
    }
)

browser_id = created_browser['browserId']
print(f"Browser ID: {browser_id}")

Запуск браузерной сессии

Когда ресурс браузера создан, запустите сессию. Параметр viewPort задает разрешение экрана. Оно определяет пространство координат для действий мышью и размеры снимаемых экранов. Параметр sessionTimeoutSeconds управляет тем, как долго сессия будет активна до автоматического завершения.

# Эти helper-функции включены в репозиторий сопроводительного ноутбука
from helpers.browser import get_credentials, invoke, start_session, stop_session

creds, default_region = get_credentials()
BEDROCK_AGENTCORE_DP_ENDPOINT = f"https://bedrock-agentcore.{default_region}.amazonaws.com/"

sid = start_session(BEDROCK_AGENTCORE_DP_ENDPOINT, browser_id, region=default_region, credentials=creds)

# Подождите инициализации сессии — при необходимости скорректируйте задержку под свою среду
time.sleep(3)

Helper start_session отправляет SigV4-подписанный PUT-запрос для создания сессии и возвращает sessionId. Helper invoke выполняет подписание и отправку отдельных действий.

Вызов OS-уровневого действия

После запуска сессии можно отправлять OS-уровневые действия через helper invoke. Каждый вызов принимает одно действие — в этом примере это левый клик по координатам (600, 370) на экране:

r = invoke(
    BEDROCK_AGENTCORE_DP_ENDPOINT, sid,
    {"mouseClick": {"x": 600, "y": 370, "button": "LEFT"}},
    region=default_region, credentials=creds, browser_id=browser_id
)

print(f"Mouse click status: {r.status_code}, action: {r.json()['result']}")

Ответ сообщает, успешно ли выполнено действие или оно завершилось ошибкой. Координаты соответствуют пикселям экрана: если viewport сессии равен 1920×1080, допустимые значения x находятся в диапазоне от 0 до 1919, а y — от 0 до 1079. Координаты за пределами экрана возвращают ValidationException.

Сделать снимок экрана

После каждого действия агент должен наблюдать, что произошло. Действие screenshot делает снимок всего рабочего стола и возвращает изображение в формате PNG, закодированное в base64:

import base64
from IPython.display import Image, display

r = invoke(
    BEDROCK_AGENTCORE_DP_ENDPOINT, sid,
    {"screenshot": {"format": "PNG"}},
    region=default_region, credentials=creds, browser_id=browser_id
)

img_bytes = base64.b64decode(r.json()['result']['screenshot']['data'])
display(Image(img_bytes))

Это шаг наблюдения в цикле. Агент отправляет снимок экрана в vision-модель, которая анализирует то, что на экране, и возвращает следующее действие. Цикл повторяется, пока workflow не будет завершен.

Практический пример: закрытие диалога печати

Ниже показан цикл действие-скриншот-реакция в реальном сценарии. Допустим, агент переходит на страницу, которая вызывает window.print(), и появляется нативный диалог печати. Через CDP агент не может взаимодействовать с ним, но с помощью OS Level Actions — может. Сначала агент делает снимок экрана, чтобы увидеть текущее состояние дисплея:

r = invoke(
    BEDROCK_AGENTCORE_DP_ENDPOINT, sid,
    {"screenshot": {"format": "PNG"}},
    region=default_region, credentials=creds, browser_id=browser_id
)

# Отправьте снимок экрана в vision-модель, чтобы определить диалог и найти кнопку Cancel.
# Интеграция с vision-моделью зависит от архитектуры вашего агента — см. Bedrock
# InvokeModel API, чтобы узнать, как отправлять изображения в Claude или другие модели.
# Модель возвращает координаты, например: {"x": 410, "y": 535}

Vision-модель определяет диалог печати и возвращает координаты кнопки Cancel. Агент нажимает ее:

r = invoke(
    BEDROCK_AGENTCORE_DP_ENDPOINT, sid,
    {"mouseClick": {"x": 410, "y": 535, "button": "LEFT"}},
    region=default_region, credentials=creds, browser_id=browser_id
)

print(f"Click status: {r.status_code}, action: {r.json()['result']}")

После этого агент делает еще один снимок экрана, чтобы подтвердить, что диалог закрыт, и workflow продолжается.

Остановка сессии и очистка ресурсов

Когда задача завершена, остановите сессию и очистите ресурсы:

stop_session(BEDROCK_AGENTCORE_DP_ENDPOINT, sid, browser_id, region=default_region, credentials=creds)

Чтобы удалить ресурс браузера и IAM-роль:

browser_boto3.delete_browser(browserId=browser_id)
print(f"Browser {browser_id} deleted")

from helpers.utils import delete_agentcore_execution_role, SAMPLE_ROLE_NAME
delete_agentcore_execution_role(SAMPLE_ROLE_NAME)

Эти шаги — действие, наблюдение, решение — составляют основу паттерна action-screenshot-reaction. Сопроводительный ноутбук проводит через восемь поддерживаемых действий в живой браузерной сессии, включая drag мышью, прокрутку, ввод с клавиатуры и комбинации клавиш.

Заключение

Когда мы запускали Amazon Bedrock AgentCore Browser, он дал AI-агентам полностью управляемую облачную браузерную среду для работы с веб-сайтами. Он переходил по страницам, извлекал контент и автоматизировал workflow в масштабе через Playwright и CDP. OS Level Actions расширяют эту возможность за пределы веб-слоя — к UI-элементам, видимым на экране. Нативные диалоги, запросы безопасности, сочетания клавиш и chrome browser уже не являются блокерами. Теперь агенты могут наблюдать, рассуждать и действовать на всем рабочем столе ОС в рамках той же сессии.

В сочетании с уже существующими возможностями AgentCore Browser, такими как визуальное понимание и интеграция с Playwright и Amazon Nova Act, OS Level Actions закрывают последний пробел в покрытии браузерной автоматизации.

Чтобы начать разработку:

• Следуйте руководству Amazon Bedrock AgentCore Developer Guide
• Попробуйте сопроводительный ноутбук для практического пошагового разбора
• Для более широкого контекста браузерной автоматизации см. документацию Amazon Bedrock AgentCore Browser

Материал — перевод статьи с английского.

Оригинал: Introducing OS Level Actions in Amazon Bedrock AgentCore Browser