O Navegador Incorporado

Cada espaço de trabalho vem com o seu próprio navegador web: um Chromium completo que se abre como um painel ao lado 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 do espaço de trabalho, 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. É o mesmo painel apresentado em Sessões; tudo o que aqui consta aplica-se também quando um agente remoto o conduz através de uma ligação de cliente nativo.

Abrir o navegador

Alterne o painel do navegador com ⌃⌘B, ou clique no botão do globo na barra de ferramentas da janela da sessão. Abre-se como uma divisão na extremidade direita do palco, partilhando a janela com o terminal.

Na primeira vez que o abrir — por Mac, não por espaço de trabalho — 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 de cerca de 500 MB, partilhada por todos os espaços de trabalho. Até estar instalado, o painel mostra o pedido de instalação em vez de uma página; também o pode pré-obter a partir das definições do Navegador do espaço de trabalho com Transferir agora.

Uma vez instalado, a VM do navegador arranca de forma preguiçosa na primeira vez que qualquer espaço de trabalho 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; o terminal mantém sempre pelo menos 240 pontos). 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 sub-rede NAT que a VM do espaço de trabalho, 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 VM do espaço de trabalho:

1. Inicie o servidor no terminal do agente como habitualmente (por exemplo, um servidor de desenvolvimento na porta 3000).
2. Copie o IP do espaço de trabalho a partir da pastilha de IP na barra de ferramentas (ou execute hostname -I no terminal do agente).
3. No navegador, navegue para http://<workspace-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 do espaço de trabalho é 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://<workspace-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 o espaço de trabalho selecionado; 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://<workspace-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 IP da LAN do espaço de trabalho, 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, Automatização e MCP.

Nota: Num cliente nativo, o fluxo de MCP do navegador de um agente remoto pode ser encaminhado através da ligação SSH, de modo que o agente remoto conduza o painel do navegador que você está a observar localmente. Um desses retransmissores está ativo de cada vez.

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 do espaço de trabalho. O perfil do Chromium passa então a residir num disco encriptado, por espaço de trabalho, em ~/Library/Application Support/BromureAC/browser-profiles/ e sobrevive às desmontagens. Alternar a definição reinicia o navegador do espaço de trabalho, 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 espaço de trabalho apontado 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 é lembrado por espaço de trabalho enquanto a aplicação está em execução, mas deliberadamente não entre reinícios da aplicação — um navegador descartável não sobreviveria de qualquer forma a um reinício.

Ao contrário das VMs de espaço de trabalho, 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 IP da LAN da VM do espaço de trabalho (hostname -I no terminal do agente, ou a pastilha de IP da barra de ferramentas), 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.
• Sessões — o painel do navegador no contexto de toda a janela da sessão.
• CLI, Automatização e MCP — a referência completa das ferramentas browser_* e o transporte vsock.