Liga o teu agente de código ao teu Chrome

O tracker nunca toca num browser. Preencher formulários de diretórios é trabalho do teu agente de código, e para isso precisa de uma integração que controle um Chrome que consegues ver e supervisionar. O BROWSER-SETUP.md do kit descreve duas formas de estabelecer essa ligação; este guia resume ambas, as permissões do macOS que podem surgir e a verificação rápida que te diz que a ligação é real. O princípio, sempre: um agente, um produto, um separador atribuído, uma ligação duradoura por lote.

Modo A: ligar o Chrome que já usas

Este modo exige Chrome 144 ou mais recente.

1. Verifica chrome://version, depois abre chrome://inspect/#remote-debugging na instância do Chrome que queres que o agente use e ativa aí a depuração remota. Se esse controlo não existir, não procures uma flag escondida — usa o modo B.
2. Configura a integração MCP do teu agente para correr o Chrome DevTools MCP com --autoConnect. Como definição genérica de servidor MCP tem este aspeto; o ficheiro e o formato de configuração do teu agente podem diferir, por isso segue a sua própria interface:

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": ["-y", "chrome-devtools-mcp@latest", "--autoConnect", "--no-usage-statistics", "--no-performance-crux"]
    }
  }
}

3. Desencadeia uma ação inofensiva no browser a partir do agente e aprova o pedido de ligação do Chrome na janela pretendida. Um processo MCP a correr não prova nada por si só; um separador visível que se mexe, sim.

Se o npx não existir, instala o Node.js. A primeira chamada descarrega o pacote; quando tudo funcionar, fixa a versão que testaste. Como esta integração controla um browser autenticado, fecha primeiro os separadores sensíveis não relacionados, nunca copies o perfil para outra máquina e nunca faças commit de cookies. Se o teu agente já tem uma integração de browser a funcionar, mantém-na.

Modo B: um perfil CDP local dedicado

Algumas integrações querem um endpoint HTTP que fale o Chrome DevTools Protocol em vez de auto-connect. Para essas, lança um Chrome separado com diretório de dados de utilizador próprio dentro do teu espaço de trabalho privado. No macOS:

mkdir -p .browser/chrome
"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" \
  --remote-debugging-address=127.0.0.1 \
  --remote-debugging-port=9222 \
  --user-data-dir="$PWD/.browser/chrome" about:blank

Windows (PowerShell), no teu workspace:

$chrome = Join-Path $env:ProgramFiles "Google/Chrome/Application/chrome.exe"
if (!(Test-Path $chrome)) { $chrome = Join-Path ${env:ProgramFiles(x86)} "Google/Chrome/Application/chrome.exe" }
if (!(Test-Path $chrome)) { $chrome = Join-Path $env:LOCALAPPDATA "Google/Chrome/Application/chrome.exe" }
$profile = Join-Path (Get-Location) ".browser/chrome"
& $chrome --remote-debugging-address=127.0.0.1 --remote-debugging-port=9222 "--user-data-dir=$profile" about:blank

No Linux, substitui pelo binário do Chrome instalado. Inicia tu sessão nessa janela nas contas de diretórios, Google e caixa de correio de que precisas. O diretório separado não é opcional: desde o Chrome 136, as flags de depuração antigas são ignoradas para o perfil por defeito. Na configuração MCP, substitui --autoConnect por --browserUrl=http://127.0.0.1:9222; nunca combines os dois modos.

Mantém a porta local: nunca a exponhas, encaminhes por túnel ou reutilizes o endpoint de outra pessoa, e confirma que o listener está ligado a 127.0.0.1. Fecha este Chrome quando a sessão terminar; o perfil guarda as tuas sessões iniciadas para a próxima vez. Se a 9222 estiver ocupada, descobre que programa a tem — não mates browsers não relacionados nem apagues locks de perfil para forçar uma ligação.

Permissões do macOS, só onde forem precisas

Uma ligação só por CDP normalmente não precisa de permissões extra. Se o teu agente clica nativamente ou usa AppleScript, o macOS vai pedir em Definições do Sistema → Privacidade e Segurança: Automatização para a app anfitriã controlar o Chrome, Acessibilidade para entrada nativa de teclado e rato, Gravação do ecrã só se a integração capturar o ecrã. Aprova a aplicação anfitriã real (terminal, editor ou app do agente) e conta que a aprovação de depuração remota do próprio Chrome volte a aparecer depois de reconexões — é um controlo à parte, e nenhuma configuração pode prometer «permitir uma vez para sempre».

A verificação rápida antes de qualquer submissão

Antes de o agente tocar num formulário real, pede-lhe que abra um separador em branco novo, navegue até à página inicial de um diretório público, leia o título principal e te diga que separador usou. Observa a mesma janela. Depois inicia sessão num diretório-alvo e pede ao agente que inspecione o menu da conta em busca da identidade correta: concluir o OAuth não é prova de estar autenticado no destino. Regista apenas passou/falhou e uma nota não sensível no onboarding.json ou no SESSION.md, nunca uma transcrição do browser.

Para formulários, as regras são as que um humano cuidadoso usaria: ler as etiquetas atuais antes de localizar campos, preencher valores aprovados, sair do campo e reler, verificar os contadores de caracteres e nunca tratar uma chamada de ferramenta bem-sucedida como prova de que a página guardou.

Quando algo corre mal

O kit inclui uma tabela de resolução de problemas; os casos mais frequentes são:

• Mexe-se a janela errada do Chrome — para, verifica a instância selecionada e o modo de ligação.
• Aparece um pedido a cada ação — a ferramenta provavelmente está a reiniciar a cada chamada; reutiliza uma única ligação.
• O OAuth tem sucesso mas o site está anónimo — inspeciona a conta no destino antes de submeter o que quer que seja.
• CAPTCHA ou 2FA — resolves tu; o agente regista prepared_needs_human e não tenta contornar.
• Timeout depois de Submeter — procura primeiro no painel do diretório e pelo nome do teu produto; um timeout descreve o browser, não o servidor.

A comparação com um agente de browser autónomo está no artigo sobre as três vias; a configuração por agente vive nas páginas do Claude Code, Codex e Cursor.