agent-browser

Visão geral

O que é agent-browser?

agent-browser é uma skill de automação de navegador projetada para agentes de IA rodando sobre a plataforma inference.sh. Ela usa Playwright por baixo dos panos e expõe uma interface simples baseada em JSON, permitindo que agentes:

• Abram e naveguem em páginas web em um navegador real
• Interajam com elementos usando referências estáveis @e
• Cliquem, digitem, façam drag-and-drop e façam upload de arquivos
• Extraiam dados estruturados para scraping e pesquisa
• Capturem screenshots e gravem vídeos das sessões

Em vez de escrever código Playwright manualmente, você chama agent-browser pelo CLI infsh (ou a partir de um agente que consiga executar comandos Bash). A skill coordena a sessão do navegador, retorna descrições legíveis por máquina da página e permite que seu agente controle a interação passo a passo.

Para quem é o agent-browser?

agent-browser é voltado para:

• Desenvolvedores conectando agentes de IA a sites reais
• Engenheiros de automação que precisam de fluxos de navegador repetíveis
• Times de dados e pesquisa que fazem scraping direcionado ou pesquisa guiada por UI
• Construtores de workflows que usam inference.sh como camada de orquestração

Ele funciona melhor quando você já usa, ou está disposto a usar, inference.sh e quer que o navegador seja uma ferramenta controlada e acessível ao agente.

Que problemas ele resolve?

agent-browser ajuda a resolver tarefas comuns de automação de navegador:

• Automatizar fluxos de login, navegação e formulários
• Fazer scraping de conteúdo estruturado que exige interação (campos de busca, filtros, paginação)
• Executar fluxos "parecidos com testes" em sites ao vivo, dirigidos por agentes
• Gravar vídeos de uma sessão de navegação automatizada para revisão

Ele abstrai a escrita direta de scripts Playwright e oferece ao agente um conjunto de ações de mais alto nível usando referências de elementos @e, o que ajuda a manter as interações estáveis ao longo de múltiplos passos.

Quando o agent-browser é uma boa escolha?

Use agent-browser quando:

• Você roda agentes via inference.sh e precisa que eles naveguem na web
• Você quer a confiabilidade do Playwright sem escrever código Playwright
• Seus fluxos consistem em abrir páginas, interagir com elementos e ler resultados

Ele pode não ser uma boa opção quando:

• Você não pode usar o CLI infsh ou ferramentas do tipo Bash
• Você precisa de recursos Playwright extremamente personalizados além do que a skill expõe
• Seu caso de uso é puramente baseado em API e não exige um navegador real

Se você precisa de controle bem fino sobre internals do navegador ou frameworks além do que a skill oferece, talvez prefira scripts Playwright diretos. Para automação típica dirigida por agentes, agent-browser fornece uma interface mais simples e de mais alto nível.

Como usar

Pré-requisitos

Antes de usar agent-browser, verifique se você tem:

• Um ambiente em que possa executar comandos Bash
• O CLI do inference.sh (infsh) instalado
• Uma conta inference.sh na qual você consiga fazer login via CLI

O Quick Start da skill exige explicitamente o CLI infsh. Você pode seguir as instruções oficiais de instalação do CLI diretamente do repositório:

• Documentação de instalação do CLI: https://raw.githubusercontent.com/inference-sh/skills/refs/heads/main/cli-install.md

Depois que infsh estiver instalado e configurado, você pode invocar a skill agent-browser a partir do seu terminal ou de qualquer ferramenta de agente que consiga rodar comandos infsh.

Instalação e ativação da skill

agent-browser é distribuída como parte do repositório inferen-sh/skills. Na maioria dos ambientes baseados em inference.sh você não precisa instalar um pacote npm separado; em vez disso, basta garantir que a skill está disponível e chamá-la via infsh.

Passos de configuração típicos:

1. Instale o CLI do inference.sh
   • Siga o cli-install.md do repositório.
2. Autentique-se
   • Execute:

     infsh login
     

   • Siga as instruções para se autenticar no inference.sh.
3. Confirme a disponibilidade da skill
   • Certifique-se de que seu ambiente inference.sh tem acesso ao app/skill agent-browser em tools/utilities/agent-browser dentro do repositório inferen-sh/skills.

Se você está integrando com um ecossistema de “skills” mais amplo que suporte npx skills add, também pode conectar esse repositório como fonte, mas o fluxo canônico para usar agent-browser é via infsh app run.

Fluxo principal de automação de navegador

A documentação da skill descreve um padrão consistente em 4 etapas:

1. Open – Iniciar uma sessão de navegador e navegar para uma URL.
2. Interact – Usar as referências de elementos @e retornadas para clicar, digitar, arrastar ou fazer upload.
3. Re-snapshot – Solicitar um snapshot atualizado para obter novos refs @e após navegação ou mudanças no DOM.
4. Close – Encerrar a sessão; opcionalmente recuperar uma gravação em vídeo se estiver habilitada.

Esse padrão permite que seu agente mantenha um modelo mental do estado da página. Cada chamada recebe um JSON de entrada e retorna um JSON estruturado de saída, que você alimenta no loop de raciocínio do seu agente.

Exemplo de início rápido

Para ver o agent-browser em ação com uma abertura simples de página, siga o padrão de Quick Start do repositório:

infsh login

# Abrir uma página e obter elementos interativos
infsh app run agent-browser --function open --input '{"url": "https://example.com"}' --session new

O que isso faz:

• --function open diz ao agent-browser para abrir uma nova página de navegador na URL informada.
• --session new cria uma nova sessão para que ações futuras reutilizem o mesmo estado de navegador.
• A skill retorna JSON que normalmente inclui descrições de elementos e referências @e que seu agente pode usar em chamadas subsequentes de interact.

Trabalhando com referências de elementos @e

Um recurso central do agent-browser é o uso de refs @e. Em vez de exigir seletores CSS ou XPath, a skill retorna handles como @e:button-1 (o formato exato depende da implementação) junto com descrições legíveis.

Seu agente então:

1. Lê a lista de elementos disponíveis e suas descrições.
2. Escolhe a ref @e apropriada (por exemplo, o botão rotulado “Search”).
3. Chama uma função de interação (como click ou fill) usando essa ref @e.

Esse design é otimizado para agentes de IA porque eles podem raciocinar sobre descrições em vez de detalhes de baixo nível do DOM. Isso também ajuda a manter as interações robustas mesmo se os seletores mudarem, desde que as descrições continuem interpretáveis.

Exemplo: abrir, clicar e tirar novo snapshot

Um fluxo típico de múltiplos passos pode ser assim (apenas padrão; ajuste às funções específicas da sua versão):

# 1. Iniciar uma sessão e abrir uma página
OPEN_RESULT=$(infsh app run agent-browser \
  --function open \
  --session new \
  --input '{"url": "https://example.com"}')

# 2. Usar o OPEN_RESULT para escolher uma ref @e (por ex. @e:search-button) na lógica do seu agente
# 3. Interagir com esse elemento
INTERACT_RESULT=$(infsh app run agent-browser \
  --function interact \
  --session "$INF_SH_SESSION" \
  --input '{"action": "click", "element": "@e:search-button"}')

# 4. Tirar um novo snapshot após o clique para obter elementos atualizados
SNAPSHOT_RESULT=$(infsh app run agent-browser \
  --function snapshot \
  --session "$INF_SH_SESSION" \
  --input '{}')

Os nomes das funções além de open podem variar, então sempre consulte o SKILL.md mais recente e qualquer documentação associada em tools/utilities/agent-browser para ver as assinaturas exatas de funções e o schema de entrada.

Screenshots e gravação de vídeo

agent-browser pode capturar artefatos visuais da sessão de navegação:

• Screenshots – Úteis para depurar o comportamento do agente ou guardar confirmações visuais.
• Vídeo – Quando você fecha a sessão com gravação habilitada, a skill pode retornar ou fornecer um link para um arquivo de vídeo de todo o fluxo automatizado.

Esses recursos são configurados pelas opções de entrada da skill. Para detalhes sobre como habilitar gravação e acessar os outputs, consulte a definição SKILL.md e quaisquer docs adicionais em tools/utilities/agent-browser no repositório.

Dicas de integração para agentes e workflows

Para tirar o máximo proveito do agent-browser em seus fluxos de automação ou pesquisa:

• Persista os IDs de --session: Garanta que seu agente armazene o identificador da sessão entre chamadas para que várias ações ocorram no mesmo navegador.
• Faça o parse do JSON com cuidado: Use parsing de JSON robusto no runtime do seu agente; listas de elementos e metadados podem ser ricas.
• Controle o ritmo das interações quando necessário: Se uma página for lenta ou muito dinâmica, faça com que seu agente considere timing e espere elementos aparecerem entre os passos, quando a skill suportar essa configuração.
• Logue ações-chave: Mantenha um log das chamadas open, interact e close se precisar auditar ou depurar o comportamento de navegação do seu agente.

FAQ

Qual é a relação entre agent-browser, inference.sh e Playwright?

agent-browser é uma skill que roda dentro do ecossistema inference.sh. Quando você a invoca via infsh app run, ela usa o Playwright como engine de automação de navegador. Você não chama o Playwright diretamente; em vez disso, trabalha com as funções de mais alto nível da skill e as referências de elementos @e.

Como instalo o agent-browser?

Você não instala o agent-browser como um binário standalone ou pacote npm. Em vez disso:

1. Instale o CLI do inference.sh (infsh) usando as instruções oficiais em cli-install.md.
2. Faça login com infsh login.
3. Certifique-se de que seu ambiente tem acesso à skill agent-browser no repositório inferen-sh/skills (em tools/utilities/agent-browser).

A partir daí, você já pode invocar a skill via infsh app run agent-browser.

Preciso ter experiência em programação para usar o agent-browser?

É altamente recomendável ter noções básicas de linha de comando e JSON. Você não precisa escrever scripts Playwright, mas deve estar confortável em:

• Rodar comandos infsh
• Passar JSON como --input
• Fazer o parse da saída JSON no seu agente ou scripts

Para fluxos mais avançados (lógica condicional, loops, tratamento de erros), conhecimento geral de scripting ou programação é bastante útil.

Posso usar o agent-browser fora do inference.sh?

A skill foi criada especificamente para uso com inference.sh e é descrita como “Browser automation for AI agents via inference.sh.” A forma suportada e documentada de rodá-la é pelo CLI infsh. Se você precisa de uma biblioteca standalone, talvez seja melhor usar Playwright diretamente na linguagem de sua preferência.

O agent-browser é adequado para web scraping em grande escala?

agent-browser pode ser usado para scraping direcionado, especialmente quando as páginas exigem interação ou renderização em JavaScript. Porém, para scraping em volume muito alto, você deve considerar:

• Limites e precificação da sua conta inference.sh
• Respeito aos termos de uso e ao robots.txt do site alvo
• Performance, concorrência e rate limiting

Para scraping de menor escala ou específico de um workflow, embutido em um agente, agent-browser é uma opção forte. Para crawling massivo em muitos sites, talvez um stack de scraping dedicado seja mais apropriado.

Como funciona o gerenciamento de sessão?

O gerenciamento de sessão é controlado via flag --session ao chamar infsh app run. Um padrão comum é:

• Usar --session new quando você chama open pela primeira vez
• Reutilizar esse ID de sessão nas chamadas subsequentes de interact e snapshot
• Chamar a função de close adequada para encerrar a sessão e, opcionalmente, recuperar o vídeo

Sempre consulte o SKILL.md atual para ver as opções e outputs exatos relacionados a gerenciamento de sessão.

Onde encontro a especificação completa de funções e entradas?

A referência oficial do agent-browser está no repositório:

• SKILL.md na raiz do repositório inferen-sh/skills
• O diretório tools/utilities/agent-browser com detalhes de implementação, exemplos e documentação adicional

Abra esses arquivos para ver a lista atual de funções, os JSONs de entrada esperados e os formatos de saída, e então modele seu agente ou scripts com base nessas definições.