O Navegador Incorporado

Cada máquina (um espaço de trabalho, no editor de definições) vem com o seu próprio navegador web: um Chromium completo que se abre como um painel ao lado do chat ou do terminal. Existe para que um agente possa ver a web — abrir a aplicação que acabou de construir, ler uma página de documentação, reproduzir um erro, percorrer um fluxo — e para que você possa observar (e conduzir) o mesmo navegador que ele usa. O navegador é executado na sua própria VM sidecar descartável, separada da VM da máquina, de modo que uma página hostil nunca possa tocar nos ficheiros do agente ou no seu Mac.

Este capítulo é o guia completo para o utilizar: abri-lo, conduzi-lo à mão, deixar o agente conduzi-lo através do servidor MCP do navegador integrado, manter as sessões iniciadas e o modelo de privacidade. Tudo o que aqui consta aplica-se também quando um agente remoto o conduz através de uma ligação de cliente nativo.

Para os controlos gráficos da aplicação web Bromure autónoma, consulte Aceleração Metal no Bromure Web. Esses controlos são distintos das definições do navegador incorporado aqui descritas.

Abrir o navegador

Mostre ou oculte o painel do navegador com ⌃⌘B, ou clique no botão do globo na barra de ferramentas, ao lado do menu da máquina. Abre-se como uma divisão na extremidade direita do palco, ao lado do chat da sessão ou do terminal da máquina. Cada máquina tem o seu próprio navegador: o painel mostra o navegador da máquina que está por trás do que estiver no palco. Numa sala, o globo e o painel acompanham a sessão da célula em foco.

Na primeira vez que o abrir — por Mac, não por máquina — um cartão de consentimento pergunta Instalar o navegador? com Transferir e instalar e Agora não. A imagem do navegador é uma transferência única (o cartão indica o tamanho, cerca de 500 MB), partilhada por todas as máquinas. Durante a transferência, o painel mostra A preparar o navegador com uma barra de progresso. Também a pode pré-obter a partir das definições do Navegador da máquina com Transferir agora.

Uma vez instalado, a VM do navegador arranca de forma preguiçosa na primeira vez que qualquer máquina abre o painel (ou na primeira vez que um agente chama uma ferramenta do navegador), o que demora um segundo ou dois. Não gere esta VM diretamente — é criada, suspensa e desmontada por si (consulte Ciclo de vida e utilização de recursos).

Nota: O navegador é executado numa VM diferente daquela onde a shell do seu agente é executada. As duas partilham uma rede privada (consulte Carregar um servidor de desenvolvimento), mas não são a mesma máquina — um ficheiro que o agente escreve no seu diretório pessoal não está no disco do navegador, e localhost no navegador não é o localhost do agente.

Conduzi-lo você mesmo

O painel é uma vista de navegador sem interface do próprio navegador, sob uma barra de separadores compacta ao estilo do Safari:

Arraste a extremidade esquerda do painel para o redimensionar (predefinição de 640 pontos, ajustável entre 380 e 1400). Arraste-o para baixo da largura mínima para fechar o painel.

Nota: Enquanto a vista do navegador tem o foco do teclado, ⌘Q e ⌘Tab são capturados pelo convidado para que os atalhos internos das páginas funcionem — não fecham a aplicação nem alternam entre aplicações do macOS. Clique no terminal ou na barra lateral para devolver esses atalhos ao macOS.

Carregar um servidor de desenvolvimento iniciado pelo agente

O motivo mais comum para abrir o navegador é olhar para algo que o agente está a construir. Como a VM do navegador partilha a mesma rede privada que a VM da máquina, pode alcançar diretamente um servidor de desenvolvimento que o agente iniciou — mas não em localhost, porque o navegador é uma máquina separada.

Alcance o servidor de desenvolvimento pelo endereço IP da máquina:

1. Inicie o servidor no terminal do agente como habitualmente (por exemplo, um servidor de desenvolvimento na porta 3000).
2. Copie o endereço IP da máquina: abra o menu da máquina na barra de ferramentas (a cápsula com o nome da máquina) e escolha Copiar endereço IP (…). Também o pode ler no painel da máquina, ou executar hostname -I no terminal da máquina.
3. No navegador, navegue para http://<machine-ip>:3000.

O agente, quando conduz ele próprio o navegador, é instruído a fazer exatamente isto — alcançar os servidores de desenvolvimento pelo IP da LAN, nunca localhost — para que as suas capturas de ecrã e verificações atinjam o servidor correto.

Deixar o agente conduzi-lo

O navegador é agêntico: a cada agente da máquina é automaticamente entregue um servidor MCP browser integrado, sem qualquer configuração. As suas ferramentas permitem que o agente abra páginas, clique, escreva, leia o DOM, tire capturas de ecrã e inspecione a consola e a rede — conduzindo o próprio painel que você vê. Você e o agente partilham um único navegador: uma página que o agente abre aparece no seu painel, e um separador que você abre é visível para o browser_list_tabs do agente.

Não precisa de ativar isto. Basta pedir ao agente para fazer algo que necessite de um navegador — por exemplo:

Open http://<machine-ip>:3000, click "Sign up", fill the form with a test
account, and tell me if the confirmation page renders. Screenshot it.

As chamadas de ferramenta do agente podem arrancar e revelar o navegador automaticamente para a sua máquina; se o painel estava fechado, uma chamada de ferramenta abre-o e aguarda o arranque a frio. (O painel nunca se reabre a si próprio depois de o ter fechado manualmente dentro de uma sessão, pelo que você mantém sempre o controlo sobre se está visível.)

Prompts que acionam o navegador

Não existe um comando "usar o navegador" — o agente recorre às ferramentas browser_* sempre que o seu pedido só possa ser respondido carregando, vendo ou atuando sobre uma página real. Na prática, qualquer coisa que nomeie um URL, peça ao agente para olhar ou clicar em algo renderizado, ou peça uma captura de ecrã, um registo da consola ou atividade de rede vai trazer o navegador para a ação. Algumas formas que o fazem de forma fiável:

• Ver algo que construiu — "Abre o meu servidor de desenvolvimento em http://<machine-ip>:3000 e diz-me se o painel de controlo é renderizado." / "Tira uma captura de ecrã em largura total da página inicial." / "Mudei o cabeçalho para azul — recarrega a página e confirma que está com bom aspeto."
• Reproduzir ou testar um fluxo — "Vai à página de registo, preenche-a com uma conta de teste, submete-a e diz-me se o ecrã de confirmação aparece." / "Percorre a finalização da compra e para no primeiro passo que der erro."
• Ler ou extrair de uma página — "Abre <docs URL> e resume a secção de autenticação." / "Lista todas as ligações de saída desta página." / "Obtém a tabela de preços em Markdown."
• Depurar um problema do lado do cliente — "O botão Comprar não faz nada — abre a página, clica nele e verifica a consola e o registo de rede à procura do pedido que está a falhar." (O agente usa browser_console e browser_network para ler exatamente o que você veria nas DevTools, sem que precise de copiar nada.)

Quanto mais concretamente apontar para uma página ou uma ação no ecrã, mais diretamente o agente vai ao navegador. Se apenas descrever um resultado ("o registo funciona?"), o agente normalmente ainda abrirá o navegador para verificar — mas nomear o URL ou o botão elimina uma viagem de ida e volta. Lembre-se de lhe dar o endereço IP da máquina, e não localhost, para os servidores de desenvolvimento (consulte Carregar um servidor de desenvolvimento).

As ferramentas do navegador

O servidor expõe 23 ferramentas, agrupadas pelo que fazem:

O browser_evaluate executa JavaScript arbitrário na página e devolve o resultado, e o browser_network / browser_console dão ao agente o mesmo registo de pedidos e saída da consola que você leria nas DevTools — que é como um agente depura um fetch que falha ou um erro do lado do cliente sem que você copie nada à mão. O browser_pick_element é o que o envolve diretamente, e tem a sua própria secção abaixo.

Apontar para um elemento

As palavras são uma forma desajeitada de identificar um elemento numa página cheia — "o segundo cartão", "aquele botão avariado", "a etiqueta desalinhada". Quando o agente não consegue perceber a que elemento se refere, peça-lhe que o deixe apontar, e ele passar-lhe-á o controlo em vez de adivinhar:

One card in this grid is misaligned — let me point at it. Then read that
element's classes and tell me why it's off.

Por trás disso, o agente chama browser_pick_element, que arma um seletor interativo diretamente no painel do navegador: os elementos ficam destacados à medida que move o rato sobre eles, e um banner "clique num elemento" aparece no topo. Clique no elemento que pretende, e o agente recebe imediatamente o seu seletor CSS exato — nada para descrever, copiar ou colar. Tem cerca de 60 segundos para clicar antes de o seletor expirar e o agente não receber nada de volta.

Nunca precisa de premir um botão "ativar seletor" nem de abrir qualquer menu — armar o seletor é a chamada de ferramenta do agente, por isso acontece no instante em que o pede. Formulações que o acionam de forma fiável: "deixa-me apontar para ele", "eu clico no que quero dizer", "que elemento? eu mostro-te", ou simplesmente "apontar e selecionar". Assim que o agente tem o seletor, pode fazer qualquer coisa com esse elemento — clicar nele, ler o seu texto ou classes, observá-lo, ou usá-lo como âncora para explicar um erro de disposição — pelo que um bom seguimento é dizer o que quer que seja feito com o elemento no mesmo fôlego em que se oferece para apontar para ele.

Dica: O seletor é a forma mais rápida de fazer a ponte entre "eu consigo ver o problema, tu não". Em vez de descrever uma falha visual, aponte para o elemento em questão e deixe o agente inspecionar o nó DOM real.

Nos bastidores, as ferramentas alcançam o navegador através de um shim stdio de Python gerado, bromure-browser-mcp.py, colocado apenas para leitura na VM do agente em /mnt/bromure-meta/. Contacta o anfitrião através da porta 5830 do vsock e reconecta-se indefinidamente, de modo que as ferramentas nunca desaparecem da lista de ferramentas do agente, mesmo entre desmontagens do navegador. A referência completa das ferramentas encontra-se em CLI, API e MCP.

Nota: Num cliente nativo, o tráfego de MCP do navegador de uma máquina remota pode ser retransmitido através da ligação SSH, de modo que os seus agentes conduzam o painel do navegador que você está a observar localmente. O retransmissor transporta todos os agentes dessa máquina ao mesmo tempo, pelo que várias sessões na mesma máquina podem todas usar o navegador através dele.

Manter a sessão iniciada vs. manter-se descartável

Por predefinição, o navegador é descartável: o seu disco é um clone efémero que é eliminado quando o navegador é desmontado, de modo que os cookies, os inícios de sessão e o histórico desaparecem com ele. Cada nova abertura começa limpa. Esta é a predefinição segura — nada do que um agente faz no navegador persiste ou vaza para trabalhos posteriores.

Quando precisar que os inícios de sessão sobrevivam — iniciar sessão num site de teste que o agente irá revisitar, manter uma sessão entre reinícios — ative Manter a sessão iniciada nos sites nas definições do Navegador da máquina. O perfil do Chromium passa então a residir num disco encriptado, por máquina, em ~/Library/Application Support/BromureAC/browser-profiles/ e sobrevive às desmontagens. Alternar a definição reinicia o navegador da máquina, pelo que é avisado antes de a alteração ser guardada.

Aviso: Ativar Manter a sessão iniciada troca a descartabilidade por conveniência. Os cookies e inícios de sessão guardados são exatamente o tipo de coisa que um agente sob injeção de prompt tentaria exfiltrar. Prefira a predefinição descartável para qualquer máquina apontada a código não fidedigno, e reserve a persistência para navegadores que apenas visitem sites em que confia.

Ciclo de vida e utilização de recursos

A VM do navegador é gerida por si e mantida barata quando está inativa:

• É criada de forma preguiçosa na primeira abertura (ou na primeira chamada de ferramenta do agente) e arranca a partir da imagem partilhada de 500 MB como um clone de cópia na escrita.
• Um navegador oculto suspende ao fim de cerca de 10 segundos e é desmontado por completo ao fim de 5 minutos recolhido, libertando a sua memória e disco.
• O estado aberto/fechado do painel pertence ao que está no palco: cada sessão memoriza o seu (abra o navegador numa sessão e ele não o segue para outra sessão na mesma máquina — a Central, por exemplo — mesmo que partilhem o navegador da máquina), e a vista de terminal própria de uma máquina memoriza o da máquina. Uma sessão adormecida, e o ecrã de nova sessão, nunca mostram o painel — não há lá nenhum globo para o fechar. O estado dura enquanto a aplicação está em execução, e deliberadamente não entre reinícios — um navegador descartável não sobreviveria a um reinício de qualquer forma.

Ao contrário das máquinas, a VM sidecar do navegador é servida a partir de um conjunto pré-aquecido, o que explica por que abrir o painel costuma parecer instantâneo depois da primeira vez.

Atalhos de teclado

Estes aplicam-se enquanto o painel do navegador tem o foco do teclado:

Resolução de problemas

O painel mostra um pedido de instalação em vez de uma página. A imagem do navegador ainda não foi transferida. Clique em Transferir e instalar, ou pré-obtenha-a a partir das definições do Navegador → Transferir agora (cerca de 500 MB).

A página do agente não carrega / mostra ligação recusada. O agente está quase de certeza a usar localhost. O navegador é uma VM separada — tem de alcançar o servidor de desenvolvimento pelo endereço IP da máquina (Copiar endereço IP (…) no menu da máquina da barra de ferramentas, ou hostname -I no terminal da máquina), como em Carregar um servidor de desenvolvimento.

⌘Q ou ⌘Tab não fazem nada. A vista do navegador tem o foco e está a capturá-los para uso interno da página. Clique no terminal ou na barra lateral para devolver esses atalhos ao macOS.

Os inícios de sessão desaparecem entre sessões. Essa é a predefinição descartável. Ative Manter a sessão iniciada nos sites nas definições do Navegador para manter um perfil persistente.

O painel do navegador não se reabre sozinho depois de o agente o ter usado. Por design: depois de fechar o painel manualmente, ele permanece fechado até que o reabra, mesmo que o agente continue a emitir chamadas de ferramenta do navegador (que continuam a ser executadas — você só não vê o painel). Prima ⌃⌘B para o trazer de volta.

Definições e ferramentas relacionadas

• Definições do Navegador — o botão Manter a sessão iniciada nos sites e a gestão da imagem do navegador.
• Máquinas — o menu da máquina, o painel e o painel Ficheiros que fica ao lado do navegador.
• CLI, API e MCP — a referência completa das ferramentas browser_* e o transporte vsock.