O problema: a fronteira invisível da automação web
Agentes de IA que automatizam fluxos de trabalho em navegadores operam dentro da camada web — o Modelo de Objeto de Documento (DOM) exposto pelo Playwright e pelo Protocolo Chrome DevTools (CDP). O AgentCore Browser já fornecia um ambiente de navegador seguro e isolado para isso, funcionando bem na grande maioria dos cenários: navegar páginas, preencher formulários, clicar em elementos e extrair conteúdo.
Mas essa camada web tem um limite rígido. Qualquer coisa que o sistema operacional renderiza — caixas de diálogo nativas, prompts de segurança, seletores de certificado, menus de contexto, até as configurações do próprio Chrome — fica completamente fora do DOM. O CDP não consegue enxergar esses elementos, e o Playwright não consegue interagir com eles.
Os exemplos práticos deixam o problema bem claro:
- Quando uma aplicação web chama
window.print() e um diálogo de impressão do sistema aparece, o Playwright não tem DOM para interagir.
- Quando um fluxo de trabalho exige um atalho de teclado ou um menu de contexto acionado com o botão direito, o CDP não tem mecanismo para emitir esses comandos no nível do SO.
- Quando uma sessão encontra um diálogo de privacidade do macOS, um prompt do Windows Security ou um seletor de certificado, esses elementos são invisíveis para a camada de automação web.
Esses cenários costumam aparecer em produção — acionados por estados específicos da aplicação, configurações do SO ou permissões de usuário — e não em ambientes de teste, onde o conteúdo web é previsível o suficiente para ser validado. O problema se agrava ainda mais para agentes com visão computacional: a arquitetura captura um screenshot, envia para um modelo, recebe coordenadas ou instruções de volta e executa. Esse ciclo funciona bem para conteúdo web, mas quebra no momento em que uma interface nativa aparece. O agente consegue ver o que precisa fazer, mas não tem como agir.
A solução: OS Level Actions para o AgentCore Browser
A AWS anunciou as OS Level Actions para o AgentCore Browser. Essa nova capacidade desbloqueia esses cenários ao expor controle direto do SO por meio da API InvokeBrowser, permitindo que agentes interajam com qualquer conteúdo visível na tela — não apenas o que está acessível pela camada web do navegador.
Ao combinar screenshots do desktop completo com controle de mouse e teclado no nível do SO, os agentes passam a conseguir observar interfaces nativas, raciocinar sobre elas e agir dentro da mesma sessão.
Como as OS Level Actions funcionam
As OS Level Actions estão disponíveis para configurações de navegador novas e existentes, sem necessidade de configuração adicional. Após uma sessão estar ativa, as ações são disparadas pela API InvokeBrowser. Cada chamada carrega exatamente uma ação, identificada pelo seu tipo e argumentos, e retorna um status SUCCESS ou FAILED. A sessão ativa é identificada pelo cabeçalho x-amzn-browser-session-id, que vincula cada ação em nível de SO à sessão de navegador correta.
O padrão de interação esperado é um ciclo de ação → screenshot → reação:
- O agente envia uma ação — clique de mouse, tecla pressionada ou atalho — usando o
InvokeBrowser.
- O AgentCore executa a ação no desktop completo do SO e retorna
SUCCESS ou FAILED.
- O agente solicita um screenshot para observar o estado atual da tela.
- O AgentCore captura o desktop completo — incluindo caixas de diálogo nativas, modais do SO e elementos fora da janela do navegador — e retorna uma imagem PNG codificada em base64.
- O agente raciocina sobre o screenshot, enviando-o a um modelo de visão para determinar o que aconteceu e o que fazer a seguir.
- O agente envia a próxima ação com base no que observou, continuando o ciclo.
Ações suportadas
As OS Level Actions são organizadas em três categorias: controle de mouse, entrada de teclado e captura visual. Ao todo, são oito ações com seus respectivos campos e restrições.
Ações de mouse
As ações de mouse cobrem toda a gama de interações com o ponteiro: clicar, mover, arrastar e rolar.
- mouseClick: os campos de coordenadas são opcionais. Se omitidos, o clique ocorre na posição atual do cursor, com botão esquerdo e clique único. O parâmetro
clickCount aceita valores de 1 a 10.
- mouseMove: move o cursor para as coordenadas especificadas.
- mouseDrag: exige as quatro coordenadas (início e fim). O botão padrão é o esquerdo.
- mouseScroll: aceita posição e valores delta para ambos os eixos.
deltaY negativo rola para baixo; o intervalo aceito vai de -1000 a 1000.
Um menu de contexto acionado com o botão direito, por exemplo, é um único mouseClick com o botão definido como RIGHT nas coordenadas alvo. Vale observar que alguns itens de menu de contexto podem não funcionar como esperado por conta do ambiente virtualizado em que a sessão de navegador roda.
Ações de teclado
As três ações de teclado cobrem diferentes níveis de entrada:
- keyType: para digitar texto. Envia caracteres diretamente e aceita strings de até 10.000 caracteres.
- keyPress: para teclas individuais que precisam ser pressionadas repetidamente — como
tab para avançar por campos de formulário ou escape para fechar um modal. O parâmetro presses aceita de 1 a 100, com padrão 1.
- keyShortcut: para combinações de teclas — passe um array com os nomes das teclas e o AgentCore as pressiona simultaneamente. Aceita até cinco teclas. Os nomes das teclas devem ser em minúsculas.
As teclas suportadas incluem caracteres únicos (a–z, 0–9) e teclas nomeadas como enter, tab, space, backspace, delete, escape, ctrl, alt e shift. Para selecionar todo o texto, por exemplo, usa-se keyShortcut com ["ctrl", "a"]:
{
"action": {
"keyShortcut": {
"keys": ["ctrl", "a"]
}
}
}
Screenshot
A ação de screenshot captura o desktop completo do SO e retorna uma imagem PNG codificada em base64 na resposta. É a única ação que retorna dados — as demais retornam apenas um status (SUCCESS ou FAILED) e um campo de erro em caso de falha.
{
"action": {
"screenshot": {
"format": "PNG"
}
}
}
Como começar: passo a passo prático
Os exemplos a seguir percorrem o ciclo ação → screenshot → reação, acompanhando o notebook de referência. Para o notebook completo com as oito ações demonstradas de ponta a ponta, vale começar por lá.
Configurar clientes e criar um navegador
São necessários dois clientes: um de plano de controle (bedrock-agentcore-control) para gerenciar recursos de navegador, e um de plano de dados (bedrock-agentcore) para disparar ações durante uma sessão.
import boto3
import time
browser_boto3 = boto3.client('bedrock-agentcore-control', region_name='us-west-2')
BROWSER_NAME = "browser_with_os_actions"
Antes de iniciar uma sessão, é necessário um perfil de execução do Gerenciamento de Identidade e Acesso da AWS (IAM) e um recurso de navegador. O perfil de execução requer as permissões bedrock-agentcore:InvokeBrowser, bedrock-agentcore:StartBrowserSession e bedrock-agentcore:StopBrowserSession. O notebook de referência inclui um helper que cria esse perfil automaticamente:
from helpers.utils import create_agentcore_execution_role, SAMPLE_ROLE_NAME
execution_role_arn = create_agentcore_execution_role(SAMPLE_ROLE_NAME)
Com o perfil criado, cria-se um navegador personalizado:
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}")
Iniciar uma sessão de navegador
Com o recurso de navegador criado, inicia-se uma sessão. O viewPort define a resolução da tela — isso determina o espaço de coordenadas para ações de mouse e as dimensões dos screenshots capturados. O sessionTimeoutSeconds controla por quanto tempo a sessão permanece ativa antes de ser encerrada automaticamente.
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)
# Aguarda a inicialização da sessão — ajuste conforme necessário para seu ambiente
time.sleep(3)
Invocar uma ação em nível de SO
Com a sessão em execução, as ações em nível de SO são disparadas pelo helper invoke. Cada chamada recebe uma única ação — neste caso, um clique esquerdo nas coordenadas (600, 370) da tela:
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']}")
A resposta indica se a ação foi bem-sucedida ou falhou. As coordenadas mapeiam para pixels da tela — se o viewport da sessão for 1920×1080, os valores válidos de x vão de 0 a 1919 e de y de 0 a 1079. Coordenadas fora das dimensões da tela retornam uma ValidationException.
Capturar um screenshot
Após cada ação, o agente precisa observar o que aconteceu. A ação de screenshot captura o desktop completo e retorna a imagem como PNG codificado em 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))
Essa é a etapa de observação no ciclo. O agente envia o screenshot para um modelo de visão, que raciocina sobre o que está na tela e retorna a próxima ação a ser tomada. O ciclo se repete até o fluxo de trabalho ser concluído.
Juntando tudo: descartando um diálogo de impressão
Aqui está o ciclo ação → screenshot → reação na prática. Suponha que o agente navegue até uma página que aciona window.print() e um diálogo de impressão nativo apareça. O agente não consegue interagir com ele via CDP, mas consegue com as OS Level Actions.
Primeiro, o agente captura um screenshot para ver o estado atual da tela:
r = invoke(
BEDROCK_AGENTCORE_DP_ENDPOINT,
sid,
{"screenshot": {"format": "PNG"}},
region=default_region,
credentials=creds,
browser_id=browser_id
)
# Envia o screenshot para um modelo de visão para identificar o diálogo e localizar o botão Cancelar.
# A integração com o modelo de visão depende da arquitetura do seu agente — veja a API
# InvokeModel do Bedrock para enviar imagens ao Claude ou outros modelos.
# O modelo retorna coordenadas, ex.: {"x": 410, "y": 535}
O modelo de visão identifica o diálogo de impressão e retorna as coordenadas do botão Cancelar. O agente o seleciona:
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']}")
O agente captura outro screenshot para confirmar que o diálogo foi fechado, e o fluxo de trabalho continua.
Encerrar a sessão e limpar recursos
Quando o fluxo de trabalho termina, encerra-se a sessão e limpam-se os recursos:
stop_session(BEDROCK_AGENTCORE_DP_ENDPOINT, sid, browser_id, region=default_region, credentials=creds)
Para deletar o recurso de navegador e o perfil 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)
O notebook de referência percorre as oito ações suportadas com uma sessão de navegador ao vivo, incluindo arrastar com o mouse, rolar, entrada de teclado e combinações de atalhos.
Conclusão
Quando a AWS lançou o Amazon Bedrock AgentCore Browser, ele ofereceu aos agentes de IA um ambiente de navegador totalmente gerenciado e baseado em nuvem para interagir com sites — navegando páginas, extraindo conteúdo e automatizando fluxos de trabalho em escala por meio do Playwright e do CDP.
As OS Level Actions estendem essa capacidade além da camada web para elementos de interface visíveis na tela. Caixas de diálogo nativas, prompts de segurança, atalhos de teclado e elementos do próprio navegador deixam de ser bloqueadores. Os agentes agora conseguem observar, raciocinar e agir sobre o desktop completo do SO dentro da mesma sessão.
Combinadas com as capacidades existentes do AgentCore Browser — como entendimento visual e integração com frameworks como Playwright e Amazon Nova Act — as OS Level Actions fecham a última lacuna na cobertura de automação de navegadores.
Para começar a construir:
Fonte
Introducing OS Level Actions in Amazon Bedrock AgentCore Browser (https://aws.amazon.com/blogs/machine-learning/introducing-os-level-actions-in-amazon-bedrock-agentcore-browser/)