Outils navigateur pour Claude Agent SDK avec Playwright

Claude Agent SDK exécute la boucle de l’agent et appelle des outils via MCP. Le gestionnaire lance le navigateur et vérifie le résultat. Ici, la tâche se termine lorsque le code d’état apparaît sur une page locale.

Choisir une intégration navigateur

Pour une tâche répétée dont les entrées et le résultat sont connus, créez un outil ciblé. Un serveur Playwright MCP général convient à l’exploration d’une interface. Les outils navigateur des SDK d’API d’Anthropic utilisent leur propre interface de pilote.

Guide des outils du SDK d’API · Guide Playwright

Agents de navigateur · Automatisation du navigateur · Agents d’automatisation

Séparer l’enregistrement, l’exécution et le résultat

Lorsque le client MCP liste les trois noms courts, l’enregistrement fonctionne. Vérifiez ensuite quelle page le gestionnaire a utilisée, avec l’URL et l’état observé. Enfin, l’hôte doit vérifier le résultat de la tâche par une lecture indépendante. Procédez dans cet ordre en cas de panne.

Implémenter trois outils

Déclarez la validation et le gestionnaire avec tool(), puis enregistrez les outils avec createSdkMcpServer(). Le point d’entrée facultatif place le serveur dans query().options.mcpServers.fixture. Le nom de l’action devient mcp__fixture__reveal_status. Autorisez les noms exacts et limitez les opérations de chaque gestionnaire. Guide des outils personnalisés

Le contexte Playwright neuf démarre sans session. L’entrée sélectionne l’une des deux variantes et la navigation reste sur l’origine locale. Recherchez le bouton par son nom accessible exact. Cliquez uniquement si le bouton est unique, puis lisez la zone d’état.

Sécurité des agents · Navigateurs virtuels

Lire les fichiers dans leur ordre d’exécution

Ouvrez fixture.mjs pour repérer les deux variantes. Dans browser-tools.mjs, repérez le sélecteur par rôle, la lecture de l’état et le budget. Passez ensuite à smoke.mjs. Le client MCP en mémoire appelle les mêmes gestionnaires que le point d’entrée facultatif. Ce test distingue les erreurs du navigateur des problèmes de modèle.

Exécuter l’exemple en local

Le test utilise un client MCP déterministe, un transport en mémoire, le véritable serveur créé par le SDK et Chromium local. Nous l’avons exécuté sans identifiants de modèle. Le point d’entrée facultatif nécessite votre clé autorisée et reste à exécuter.

Télécharger le projet

npm ci
npx playwright install chromium
npm test

Suivre les deux scénarios

Le premier appel ouvre la page normale, le deuxième affiche le code et le troisième le relit. Le test ouvre ensuite la page sans bouton. Il vérifie que l’action échoue et qu’une lecture distincte voit le code toujours masqué. Les appels restants atteignent la limite en lecture seule.

Lire les retours des outils

La variante d’erreur retire le bouton. L’outil signale zéro correspondance et un code toujours masqué. Une lecture indépendante confirme cet état. Au neuvième appel, le budget est épuisé. La capture montre la page et le JSON conserve le retour de l’outil.

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

Limiter l’outil là où il agit

L’exemple utilise une origine locale, deux variantes et un bouton. Gardez des limites comparables avec une autre page. Son contenu est une donnée et ne peut accorder de droits. Évitez d’accepter un sélecteur, un script ou une destination fournie par une page. Pour les écritures, précisez les champs, l’environnement et le traitement d’un résultat incertain.

Définir le point d’arrêt

Si la cible manque ou présente plusieurs correspondances, conservez l’état de la page et vérifiez le sélecteur. Si le clic passe sans mettre à jour l’état, relisez la page avant de réessayer. Une fois le budget atteint, arrêtez la tâche et conservez le dernier résultat vérifié. Relisez toute valeur écrite avant de réessayer une écriture.

Un utilisateur de Claude Code a signalé qu’un test de formulaire annoncé comme réussi ne correspondait à aucune activité visible. Dans une autre discussion, un commentaire suggérait de vérifier l’apparition de l’erreur et l’arrêt de l’action suivante. Ces observations motivent la vérification indépendante. r/ClaudeCode · r/AI_Agents

Liste de contrôle de la première tâche · Débogage avec DevTools

Diagnostiquer avant de modifier le sélecteur

La lecture peut échouer si la page manque, si la cible est absente ou si le clic passe sans mise à jour. Conservez le code d’erreur et l’état observé. Si le client déterministe reproduit l’échec, corrigez le gestionnaire ou la page de test avant de modifier les instructions du modèle.

Vérifier hors du modèle

Le point d’entrée facultatif désactive les outils intégrés, autorise trois noms exacts et limite le temps et les tours. Le programme hôte vérifie la page même si le modèle signale un succès. Pour adapter le projet, ajoutez une vérification autonome, par exemple une lecture après rechargement.

npm run agent

Raisonnement agentique

Adapter une tâche limitée

Remplacez la page par une origine de test, le code par une condition métier et l’entrée par un schéma ciblé. Journalisez le nom de l’action, un code stable et un résumé de la vérification. Retirez les identifiants, les données d’utilisateur et les valeurs de formulaire des traces partagées. Élargissez les actions après validation du flux réduit.

Secholar.L

Croissance et contenu chez Tabbit

Secholar.L rédige des guides pratiques sur les navigateurs IA et les workflows agentiques, en comparant les outils sur la base de recherches réelles et de sources vérifiables.