Herramientas de navegador para Claude Agent SDK con Playwright

Claude Agent SDK ejecuta el bucle del agente y llama a herramientas mediante MCP. El controlador inicia el navegador y comprueba el resultado. En este ejemplo, la tarea termina cuando el código aparece en una página local.

Elige cómo conectar el navegador

Para una tarea repetida con entradas y resultados conocidos, define una herramienta específica. Usa un servidor Playwright MCP general si aún estás explorando la interfaz. Las herramientas de navegador de los SDK de API de Anthropic usan su propia interfaz de controlador.

Guía de herramientas del SDK de API · Guía de Playwright

Agentes de navegador · Automatización del navegador · Agentes de automatización

Separa el registro, la ejecución y el resultado

Si el cliente MCP enumera los tres nombres cortos, el registro funciona. Para verificar la ejecución, comprueba la URL y el estado observado. La última comprobación es la tarea misma: el host tiene que leer el estado esperado por su cuenta. Revisa esos tres puntos en ese orden cuando falle una ejecución.

Implementa tres herramientas

Define la validación y el controlador con tool(), y registra los tres con createSdkMcpServer(). La entrada opcional coloca el servidor en query().options.mcpServers.fixture. Así, el nombre de la acción es mcp__fixture__reveal_status. Mantén una lista exacta y restringe lo que puede hacer cada controlador. Guía de herramientas personalizadas

El contexto nuevo de Playwright empieza sin sesión. La entrada elige entre dos modos y la navegación se limita al origen local. Busca el botón por su nombre accesible exacto. Solo se pulsa cuando hay una coincidencia y después se lee la región de estado.

Seguridad del agente · Navegadores virtuales

Lee los archivos en orden

Abre fixture.mjs para ver los dos modos. En browser-tools.mjs, identifica el selector por rol, la lectura del estado y el límite de llamadas. Luego sigue smoke.mjs. El cliente MCP en memoria llama a los mismos controladores que utilizaría la entrada opcional. Empieza por esta prueba para separar errores de herramientas y del modelo.

Ejecuta el proyecto en local

Un cliente MCP determinista llama al servidor real creado por el SDK mediante transporte en memoria. Chromium se ejecuta en local. La prueba se ejecutó sin credenciales. El punto de entrada opcional del agente necesita una clave autorizada y quedó pendiente de ejecución.

Descarga el proyecto de ejemplo

npm ci
npx playwright install chromium
npm test

Sigue el caso normal y el caso negativo

La primera llamada abre la página normal, la segunda revela el código y la tercera lo vuelve a leer. Luego la prueba abre la variante sin botón. Espera el fallo de la operación y una lectura que confirme que el código sigue oculto. Las llamadas restantes son de lectura para llegar al límite sin efectos adicionales.

Interpreta los resultados

La variante de error elimina el botón. La respuesta indica cero coincidencias y que el código sigue oculto. Una lectura independiente lo confirma. La novena llamada agota el presupuesto. La captura muestra el estado de la página y el JSON registra la respuesta de la herramienta.

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

Limita la herramienta donde se ejecuta

La herramienta de ejemplo tiene un origen local, dos modos y un botón. Conserva esas restricciones al sustituir la página. El contenido de una página es un dato y no amplía permisos. Evita aceptar de ella un selector, un script o un destino. Para una escritura, define los campos permitidos, el entorno y la respuesta a un resultado incierto.

Decide cuándo detener la ejecución

Si falta el botón o hay varias coincidencias, guarda el estado y revisa el selector. Si hubo un clic y no aparece el código, vuelve a leer la página antes de repetirlo. Cuando se agota el presupuesto, conserva el último resultado confirmado. Antes de reintentar una escritura, comprueba el valor guardado.

Un usuario de Claude Code describió una prueba supuestamente exitosa sin actividad visible del navegador. En otra conversación, un comentario propuso comprobar el error de validación y que la siguiente acción se detuviera. Ambas observaciones motivan las comprobaciones independientes. r/ClaudeCode · r/AI_Agents

Lista de primera tarea · Depuración con DevTools

Diagnostica antes de cambiar el selector

La lectura puede fallar si la página no se abrió, falta el control o la aplicación no actualizó el estado tras recibir el clic. Guarda el código de fallo y el estado visto. Si el cliente determinista lo reproduce, corrige el controlador o la página de prueba antes de modificar las instrucciones del agente.

Verifica el resultado fuera del modelo

La entrada opcional desactiva las herramientas integradas, permite los tres nombres explícitos y limita el tiempo y los turnos. El proceso anfitrión verifica la página aunque el modelo declare que terminó. Si adaptas el ejemplo, añade una comprobación separada que pueda ejecutarse después de recargar.

npm run agent

Razonamiento agéntico

Migra una tarea pequeña

Cambia la página sintética por un origen de prueba, el código por una condición de negocio y el modo por un esquema acotado. Registra el nombre de la acción, un código estable y un resumen de verificación. Excluye credenciales, datos de usuario y valores de formularios de las trazas compartidas. Amplía las acciones después de verificar el flujo reducido.

Secholar.L

Crecimiento y contenido en Tabbit

Secholar.L escribe guías prácticas sobre navegadores con IA y flujos de trabajo con agentes, comparando herramientas con investigación real y fuentes verificables.