Pular para o conteúdo principal

browser_action

A ferramenta browser_action permite a automação e interação na web através de um navegador controlado pelo Puppeteer. Ela permite que o AI Cockpit Reasoning inicie navegadores, navegue para sites, clique em elementos, digite texto e role páginas com feedback visual através de capturas de tela.

Parâmetros​

A ferramenta aceita estes parâmetros:

  • action (obrigatório): A ação a ser executada:
    • launch: Inicia uma nova sessão do navegador em uma URL
    • click: Clica em coordenadas x,y específicas
    • type: Digita texto através do teclado
    • scroll_down: Rola para baixo na altura de uma página
    • scroll_up: Rola para cima na altura de uma página
    • close: Encerra a sessão do navegador
  • url (opcional): A URL para navegar ao usar a ação launch
  • coordinate (opcional): As coordenadas x,y para a ação click (por exemplo, "450,300")
  • text (opcional): O texto a ser digitado ao usar a ação type

O Que Faz​

Esta ferramenta cria uma sessão de navegador automatizada que o AI Cockpit Reasoning pode controlar para navegar em sites, interagir com elementos e executar tarefas que exigem automação do navegador. Cada ação fornece uma captura de tela do estado atual, permitindo a verificação visual do processo.

Quando é usada?​

  • Quando o AI Cockpit Reasoning precisa interagir com aplicações web ou sites
  • Ao testar interfaces de usuário ou funcionalidades da web
  • Ao capturar telas de páginas da web
  • Ao demonstrar fluxos de trabalho da web visualmente

Principais Características​

  • Fornece feedback visual com capturas de tela após cada ação e captura logs do console
  • Suporta fluxos de trabalho completos, desde o lançamento até a interação com a página e o fechamento
  • Permite interações precisas através de coordenadas, entrada de teclado e rolagem
  • Mantém sessões de navegador consistentes com detecção inteligente de carregamento de página
  • Opera em dois modos: local (instância isolada do Puppeteer) ou remoto (conecta-se ao Chrome existente)
  • Lida com erros de forma elegante com limpeza automática da sessão e mensagens detalhadas
  • Otimiza a saída visual com suporte para vários formatos e configurações de qualidade
  • Rastreia o estado da interação com indicadores de posição e histórico de ações

Modos do Navegador​

A ferramenta opera em dois modos distintos:

Modo de Navegador Local (Padrão)​

  • Baixa e gerencia uma instância local do Chromium através do Puppeteer
  • Cria um ambiente de navegador novo a cada lançamento
  • Sem acesso a perfis de usuário, cookies ou extensões existentes
  • Comportamento consistente e previsível em um ambiente de sandbox
  • Fecha completamente o navegador quando a sessão termina

Modo de Navegador Remoto​

  • Conecta-se a uma instância existente do Chrome/Chromium em execução com a depuração remota ativada
  • Pode acessar o estado do navegador existente, cookies e, potencialmente, extensões
  • Inicialização mais rápida, pois reutiliza um processo de navegador existente
  • Suporta a conexão com navegadores em contêineres Docker ou em máquinas remotas
  • Apenas se desconecta (não fecha) do navegador quando a sessão termina
  • Requer que o Chrome esteja em execução com a porta de depuração remota aberta (normalmente a porta 9222)

Limitações​

  • Enquanto o navegador estiver ativo, apenas a ferramenta browser_action pode ser usada
  • As coordenadas do navegador são relativas à viewport, não à página
  • As ações de clique devem visar elementos visíveis dentro da viewport
  • As sessões do navegador devem ser fechadas explicitamente antes de usar outras ferramentas
  • A janela do navegador tem dimensões configuráveis (padrão 900x600)
  • Não pode interagir diretamente com as Ferramentas do Desenvolvedor do navegador
  • As sessões do navegador são temporárias e não persistentes entre as reinicializações do AI Cockpit Reasoning
  • Funciona apenas com navegadores Chrome/Chromium, não com Firefox ou Safari
  • O modo local não tem acesso aos cookies existentes; o modo remoto requer o Chrome com a depuração ativada

Como Funciona​

Quando a ferramenta browser_action é invocada, ela segue este processo:

  1. Validação da Ação e Gerenciamento do Navegador:

    • Valida os parâmetros necessários para a ação solicitada
    • Para launch: Inicializa uma sessão do navegador (instância local do Puppeteer ou Chrome remoto)
    • Para ações de interação: Usa a sessão do navegador existente
    • Para close: Encerra ou desconecta do navegador apropriadamente

  2. Interação com a Página e Estabilidade:

    • Garante que as páginas estejam totalmente carregadas usando a detecção de estabilidade do DOM através do algoritmo waitTillHTMLStable
    • Executa as ações solicitadas (navegação, clique, digitação, rolagem) com o tempo adequado
    • Monitora a atividade da rede após os cliques e aguarda a navegação quando necessário

  3. Feedback Visual:

    • Captura capturas de tela otimizadas usando o formato WebP (com fallback para PNG)
    • Grava os logs do console do navegador para fins de depuração
    • Rastreia a posição do mouse e mantém um histórico paginado de ações

  4. Gerenciamento da Sessão:

    • Mantém o estado do navegador em várias ações
    • Lida com erros e limpa os recursos automaticamente
    • Impõe a sequência de fluxo de trabalho adequada (lançamento → interações → fechamento)

Sequência do Fluxo de Trabalho​

As interações do navegador devem seguir esta sequência específica:

  1. Inicialização da Sessão: Todos os fluxos de trabalho do navegador devem começar com uma ação launch
  2. Fase de Interação: Várias ações de click, type e rolagem podem ser executadas
  3. Encerramento da Sessão: Todos os fluxos de trabalho do navegador devem terminar com uma ação close
  4. Troca de Ferramentas: Após fechar o navegador, outras ferramentas podem ser usadas

Exemplos de Quando Usado​

  • Ao criar um processo de envio de formulário da web, o AI Cockpit Reasoning inicia um navegador, navega até o formulário, preenche os campos com a ação type e clica em enviar.
  • Ao testar um site responsivo, o AI Cockpit Reasoning navega até o site e usa ações de rolagem para examinar diferentes seções.
  • Ao capturar telas de uma aplicação web, o AI Cockpit Reasoning navega por diferentes páginas e tira capturas de tela a cada passo.
  • Ao demonstrar um fluxo de checkout de comércio eletrônico, o AI Cockpit Reasoning simula todo o processo, desde a seleção do produto até a confirmação do pagamento.

Exemplos de Uso​

Lançando um navegador e navegando para um site:

<browser_action>
<action>launch</action>
<url>https://example.com</url>
</browser_action>

Clicando em coordenadas específicas (por exemplo, um botão):

<browser_action>
<action>click</action>
<coordinate>450,300</coordinate>
</browser_action>

Digitando texto em um campo de entrada focado:

<browser_action>
<action>type</action>
<text>Olá, Mundo!</text>
</browser_action>

Rolando para baixo para ver mais conteúdo:

<browser_action>
<action>scroll_down</action>
</browser_action>

Fechando a sessão do navegador:

<browser_action>
<action>close</action>
</browser_action>