Ferramentas de navegador para Claude Agent SDK com Playwright

O Claude Agent SDK executa o ciclo do agente e chama ferramentas via MCP. O manipulador abre o navegador e verifica o resultado. Neste exemplo, a tarefa termina quando o código de status aparece na página local.

Escolha a integração do navegador

Use uma ferramenta específica para tarefas repetidas com entradas conhecidas e resultado verificável. Um servidor Playwright MCP geral serve para explorar uma interface. Os SDKs de API da Anthropic também oferecem ferramentas de navegador com uma interface de driver própria.

Guia das ferramentas dos SDKs de API · Guia do Playwright

Agentes de navegador · Automação de navegador · Agentes de automação

Separe registro, execução e resultado

Se o cliente MCP listar os três nomes curtos, o registro funcionou. Depois confirme qual página o manipulador usou, com a URL e o estado observado. Por fim, o hospedeiro precisa verificar a condição da tarefa por leitura independente. Siga essa ordem para investigar falhas.

Implemente três ferramentas

Use tool() para definir validação e manipulador, e createSdkMcpServer() para registrar as ferramentas. A entrada opcional coloca o servidor em query().options.mcpServers.fixture. Assim, o nome da ação é mcp__fixture__reveal_status. Use nomes exatos na lista de permissões e limite as ações de cada manipulador. Guia de ferramentas personalizadas

O Playwright cria um contexto sem sessão autenticada. A entrada seleciona um de dois modos e a navegação fica na origem local. Procure o botão pelo nome acessível exato. Clique somente quando houver uma correspondência e leia a área de status depois.

Segurança dos agentes · Navegadores virtuais

Leia os arquivos na ordem de execução

Veja os dois modos em fixture.mjs. Em browser-tools.mjs, localize o seletor por função, a leitura de estado e o limite de chamadas. Depois leia smoke.mjs. O cliente em memória chama os mesmos manipuladores da entrada opcional. Use essa prova para separar um erro de ferramenta de um problema com o modelo.

Execute o exemplo localmente

O teste usa um cliente MCP determinístico, transporte em memória, o servidor real criado pelo SDK e Chromium local. Executamos o teste sem credenciais de modelo. A entrada opcional do agente requer sua chave autorizada e não foi executada.

Baixe o projeto de exemplo

npm ci
npx playwright install chromium
npm test

Acompanhe o cenário normal e o negativo

A primeira chamada abre a página normal, a segunda revela o código e a terceira lê o resultado. Depois o teste abre a variante sem botão, espera que a ação falhe e confirma por outra leitura que o código continua oculto. As chamadas restantes são leituras para chegar ao limite sem mais efeitos.

Leia os retornos

A variante de erro remove o botão. A ferramenta informa zero correspondências e código oculto. Uma leitura independente confirma o estado. A nona chamada retorna erro de orçamento. A captura mostra a página e o JSON registra a resposta da ferramenta.

{
  "isError": true,
  "ok": false,
  "code": "TARGET_MISSING_OR_AMBIGUOUS",
  "expected": "Reveal status code",
  "matches": 0,
  "observed": "Status code hidden"
}

Limite a ferramenta onde a ação ocorre

O exemplo tem uma origem local, dois modos e um botão. Mantenha limites semelhantes ao trocar a página. O conteúdo é dado e não amplia permissões. Evite aceitar da página um seletor, script ou destino. Para gravações, defina os campos permitidos, o ambiente e como lidar com um resultado incerto.

Defina quando parar

Quando o alvo não aparece ou é ambíguo, preserve a página e revise o seletor. Se o clique ocorreu sem mudar o status, releia a página antes de repetir. Ao esgotar o orçamento, encerre e retenha o último resultado confirmado. Confira o valor salvo antes de repetir qualquer gravação.

Um usuário do Claude Code relatou um teste de formulário descrito como bem-sucedido sem atividade visível no navegador. Em outra conversa, um comentário sugeriu confirmar o erro de validação e que a ação seguinte foi interrompida. Essas observações motivaram a verificação independente. r/ClaudeCode · r/AI_Agents

Checklist da primeira tarefa · Depuração com DevTools

Investigue antes de mudar o seletor

A leitura pode falhar porque a página não abriu, o controle não existe ou o aplicativo aceitou o clique sem mudar o estado. Guarde o código de falha e o estado observado. Se o cliente determinístico reproduzir o erro, corrija o manipulador ou a página de teste antes de ajustar a instrução do agente.

Verifique o resultado fora do modelo

A entrada opcional desativa ferramentas internas, permite três nomes exatos e limita tempo e turnos. O processo hospedeiro verifica a página mesmo quando o modelo relata sucesso. Ao adaptar o exemplo, adicione uma verificação independente, como conferir o valor após recarregar.

npm run agent

Raciocínio agêntico

Migre uma tarefa pequena

Use uma origem de teste, uma condição de negócio e um esquema de entrada restrito. Registre a ação, um código de erro estável e um resumo da verificação. Mantenha credenciais, dados de usuário e valores de formulários fora dos registros compartilhados. Amplie as ações quando o fluxo menor estiver verificável.

Secholar.L

Crescimento e conteúdo na Tabbit

Secholar.L escreve guias práticos sobre navegadores com IA e fluxos de trabalho com agentes, comparando ferramentas com pesquisa real e fontes verificáveis.