Périmètre sûr : ce guide couvre uniquement vos propres applications, vos environnements de QA, de préproduction ou de production, et les systèmes pour lesquels vous détenez une autorisation écrite. Il ne traite ni de l'automatisation de sites tiers, ni de l'évasion d'anti-bot.
Un agent Anthropic Computer Use enchaîne capture d'écran, clic et saisie jusqu'au moment où un défi CAPTCHA apparaît : la boucle recommence alors indéfiniment sur le même écran. Le bon réflexe n'est pas d'apprendre à l'agent à mieux cliquer : sortez cette étape de la boucle visuelle. Votre backend appelle l'API CaptchaAI, récupère un token et l'injecte dans la session en cours.
Le modèle garde alors son rôle — décider quoi faire ensuite — pendant que la résolution devient un appel HTTP mesurable et rejouable.
Pourquoi la boucle de l'agent s'arrête sur le défi
Un agent Computer Use raisonne sur des pixels. Un widget reCAPTCHA v2 ou Cloudflare Turnstile, lui, attend une valeur signée côté serveur, pas un clic bien placé. Même quand la case se coche visuellement, le formulaire refuse l'envoi tant que le champ g-recaptcha-response ou cf-turnstile-response reste vide. Les tentatives visuelles répétées consomment des tokens du modèle et brouillent vos métriques sans faire avancer le parcours.
Architecture : l'agent observe, votre service résout
Exposez à l'agent un outil unique, par exemple solve_challenge, qui prend le sitekey et l'URL de la page. Derrière cet outil, votre propre service appelle CaptchaAI en HTTPS, attend le token, puis le rend à l'agent qui reprend son parcours. Trois avantages : la clé API ne quitte jamais votre backend, la latence de résolution est isolée de la latence du modèle, et vous pouvez rejouer un incident sans relancer l'agent complet.
Le déroulé en cinq étapes
- Détecter le défi. L'agent signale la présence d'un widget ; votre outil récupère le sitekey et l'URL exacte de la page depuis le DOM, jamais depuis une lecture approximative de la capture d'écran.
- Envoyer la tâche. Votre service soumet la tâche à CaptchaAI avec le type correspondant (
userrecaptcha,turnstile,geetest,postpour l'image). - Interroger le résultat. Attendez 15 s avant la première interrogation, puis toutes les 5 s, avec un plafond de 120 s par tâche.
- Injecter le token dans la même session. Même contexte de navigateur, mêmes cookies : un token appliqué dans une autre session est la première cause de rejet après une résolution pourtant réussie.
- Rendre la main à l'agent. L'outil retourne un résultat structuré (succès, durée, identifiant de tâche) pour que le modèle sache s'il doit continuer ou abandonner proprement.
Exemple : créer une tâche Turnstile depuis votre backend
L'appel ci-dessous vit dans votre service, jamais dans le prompt ni dans le contexte de l'agent :
import fetch from 'node-fetch';
const API_KEY = process.env.CAPTCHAAI_KEY;
export async function createTurnstileTask(siteKey, pageUrl) {
const res = await fetch('https://api.captchaai.com/createTask', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
clientKey: API_KEY,
task: {
type: 'TurnstileTaskProxyless',
websiteURL: pageUrl,
websiteKey: siteKey,
},
}),
});
const data = await res.json();
return data.taskId;
}
Où vit la clé API
La clé CaptchaAI reste dans un coffre (HashiCorp Vault, AWS Secrets Manager, Azure Key Vault) ou dans un secret d'intégration continue, montée en variable d'environnement au démarrage. Ne la placez jamais dans un message système, un descriptif d'outil ou une trace d'agent : tout ce que le modèle lit finit tôt ou tard dans vos journaux de débogage.
Ce qu'il faut journaliser
Instrumentez chaque appel avec la durée totale d'obtention du token, le code retour HTTP, l'identifiant de tâche et le nombre de threads occupés. Corrélez ces champs à votre traçage distribué (OpenTelemetry, par exemple) et à l'identifiant de session de l'agent : vous rejouez ensuite un incident complet à partir d'une seule ligne de log.
Séparez les journaux par environnement et surveillez l'écart entre le taux de réussite de la résolution et le taux d'acceptation du formulaire en aval.
Dépannage : trois symptômes fréquents
| Symptôme | Cause probable | Correctif |
|---|---|---|
| L'agent reboucle sur le même écran | Le widget attend une valeur signée, pas un clic | Déclenchez l'outil solve_challenge dès la détection du widget |
| Résolution réussie, formulaire refusé | Contexte de navigateur ou cookies différents | Rejouez l'injection dans la session qui a déclenché le défi |
| Tâches en attente pendant les campagnes nocturnes | Threads saturés par les agents lancés en parallèle | Calez le palier sur le pic de tâches simultanées mesuré |
Scénario : recette e-commerce hébergée en Europe
Une équipe QA lyonnaise fait tourner ses agents sur une machine OVHcloud pendant que la préproduction vit sur eu-west-3 (Paris). Chaque nuit, l'agent rejoue le parcours de paiement et franchit le Turnstile de la page de connexion via l'outil solve_challenge. Deux réflexes locaux : pas de données personnelles réelles dans les jeux de test — minimisation RGPD oblige — et des threads dimensionnés sur le nombre d'agents en parallèle. Le plan BASIC ($15/mois, 5 threads) suffit à cinq résolutions simultanées ; au-delà, STANDARD ($30/mois, 15 threads) absorbe une flotte nocturne. La facturation reste en dollars US, par thread, avec des résolutions illimitées.
Liste de contrôle avant la mise en production
- Le périmètre couvre vos applications ou des sources explicitement autorisées.
- La clé CaptchaAI vit dans un coffre, jamais dans le contexte du modèle.
- Le sitekey et l'URL proviennent du DOM, pas d'une lecture de capture d'écran.
- Le token est injecté dans la session qui a déclenché le défi.
- Le retry est borné : trois tentatives, backoff exponentiel, plafond explicite.
- Les durées, codes retour et identifiants de tâche partent vers vos tableaux de bord.
FAQ
L'agent Claude peut-il résoudre le défi directement depuis la capture d'écran ?
Non. Le widget attend une valeur signée côté serveur : cliquer sur l'image ne produit aucun token exploitable. Faites de la résolution un outil que le modèle appelle, exactement comme un accès à une base de données.
CaptchaAI prend-il en charge hCaptcha dans ce type d'intégration ?
Non — hCaptcha n'est pas pris en charge, tout comme FunCaptcha (Arkose Labs) ; GeeTest v4 est annoncé comme à venir. Les types disponibles ici sont reCAPTCHA v2 et v3, Cloudflare Turnstile, Cloudflare Challenge, GeeTest v3, l'image/OCR et les grilles d'images ; CaptchaFox (bêta), Friendly Captcha (bêta) et Lemin (bêta) complètent la liste.
Combien de threads prévoir pour plusieurs agents en parallèle ?
Comptez un thread par résolution en cours, pas par agent : un agent qui passe l'essentiel de son temps à raisonner n'occupe un thread que par intermittence. Mesurez le pic de tâches simultanées sur une semaine avant de choisir le palier.
Que faire si le token est refusé après une résolution réussie ?
Vérifiez d'abord la session : contexte de navigateur, cookies et adresse de sortie doivent rester identiques de bout en bout. Contrôlez ensuite l'âge du token — au-delà de quelques minutes, la plupart des formulaires le rejettent — puis l'exactitude du sitekey.
Guides connexes
- Démarrage rapide : votre première résolution
- Tester les CAPTCHA en environnement autorisé
- Valider l'endpoint API sur vos formulaires
- Intégrer la résolution dans votre chaîne CI
- Résoudre reCAPTCHA v2 via l'API
Donnez à vos agents une étape de résolution mesurable plutôt qu'une boucle qui tourne à vide. – Obtenez votre clé CaptchaAI.
