Périmètre sûr : ce guide couvre vos propres applications, vos environnements de QA ou de préproduction, et les systèmes pour lesquels vous détenez une autorisation écrite. Il ne décrit ni l'automatisation de sites tiers, ni la neutralisation de protections anti-abus.
Un agent browser-use sait lire une page, décider et cliquer ; il ne sait pas résoudre un défi CAPTCHA. Dès qu'une case « Je ne suis pas un robot » s'intercale dans le parcours, la boucle de raisonnement tourne à vide et finit en timeout. La règle tient en une phrase : sortez la résolution du raisonnement de l'agent, confiez-la à un outil qui appelle l'API CaptchaAI, puis réinjectez le token dans la session qui a déclenché le défi.
Pourquoi un agent qui « voit » la page bloque quand même
Un agent piloté par LLM raisonne sur une représentation textuelle du DOM. Le défi CAPTCHA, lui, vit dans une iframe cloisonnée, et le token attendu par le formulaire n'existe nulle part dans l'arbre que l'agent peut lire. L'agent clique, relit, réessaie : le parcours n'avance pas et la facture d'inférence grimpe. Un appel HTTP unique remplace ces dizaines d'allers-retours, avec un coût et une durée bornés.
Le schéma d'intégration : un outil de résolution branché sur l'agent
Déclarez la résolution comme un outil de l'agent, au même titre qu'un clic. L'agent détecte le défi et appelle l'outil ; l'outil transmet le sitekey, l'URL et l'identifiant de session à votre service interne ; le service seul parle à CaptchaAI et détient la clé API. Chaque couche garde ainsi une responsabilité unique, ce qui rend les régressions faciles à localiser.
Du défi détecté au token injecté
- Relevez les paramètres du défi : sitekey, URL exacte de la page et, le cas échéant, action attendue. Rien de plus : un paramètre superflu crée une fausse piste de diagnostic.
- Envoyez la tâche depuis votre service, jamais depuis le navigateur piloté. Toute réponse non conforme est une erreur : journalisez le payload.
- Interrogez le résultat avec un polling discipliné : 15 secondes d'attente, puis une interrogation toutes les 5 secondes, plafond dur à 120 secondes.
- Réinjectez le token dans la même session : même contexte navigateur, même cookie jar. Le changement de session est la première cause de token refusé.
- Rendez la main à l'agent avec un signal explicite de succès ou d'échec, pour qu'il n'improvise pas de rattrapage.
L'appel côté service, en Node.js
L'exemple ci-dessous crée une tâche Cloudflare Turnstile depuis votre propre service et renvoie l'identifiant que la boucle d'interrogation réutilisera :
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;
}
Cet identifiant de tâche est votre clé de corrélation : propagez-le dans vos logs, votre trace distribuée et le contexte de l'agent. Une seule valeur suffit alors à rejouer un parcours complet.
Cloisonner la clé API et les environnements
La clé CaptchaAI vit dans un coffre (HashiCorp Vault, AWS Secrets Manager, Azure Key Vault) ou dans un secret d'intégration continue — jamais dans le dépôt, et surtout jamais dans le prompt de l'agent, souvent journalisé en entier.
Exemple concret : une équipe QA lyonnaise exécute ses agents sur des workers Scaleway à Paris, avec une clé distincte par environnement. Les traces d'agent embarquent des captures d'écran et des extraits de DOM : minimisez les données personnelles conservées et fixez une durée de rétention au titre de vos obligations RGPD.
Ce qu'il faut mesurer
Les chiffres ci-dessous reposent sur des mesures observées et des retours d'utilisateurs. Les résultats varient selon l'environnement, le volume et le moment de la journée.
| Indicateur | Repère | Signal |
|---|---|---|
| Résolution Cloudflare Turnstile | moins de 10 s | Aucune nouvelle tentative en attente |
| Résolution reCAPTCHA v2 | moins de 60 s | Timeouts bien dimensionnés |
| Écart résolution / acceptation | proche de zéro | Un écart croissant trahit une injection hors session |
| Retries par parcours | 3 au maximum | Au-delà, un défaut de paramétrage est masqué |
Alertez en priorité sur l'écart entre résolution et acceptation : c'est le signal qui se dégrade en premier quand une page change.
Erreurs fréquentes et correctifs
| Symptôme | Cause probable | Correctif |
|---|---|---|
ERROR_WRONG_USER_KEY |
Espace parasite ou clé d'un autre compte | Recopiez la clé, stockez-la en secret CI |
ERROR_ZERO_BALANCE |
Solde insuffisant | Rechargez et posez une alerte de solde |
ERROR_PAGEURL |
sitekey ou URL erronés | Comparez-les au HTML réellement servi |
CAPCHA_NOT_READY en boucle |
Interrogation trop rapprochée | 15 s, puis toutes les 5 s, plafond à 120 s |
| Token refusé après résolution | Injection hors session | Restez dans le même contexte navigateur |
Ce que coûte un agent qui tourne en continu
La facturation CaptchaAI porte sur les threads simultanés, pas sur le nombre de résolutions : chaque plan inclut des résolutions illimitées par thread, en dollars US. Un agent unique en préproduction tient dans BASIC ($15/mois, 5 threads). Quelques agents en parallèle relèvent de STANDARD ($30/mois, 15 threads), un parc de tests nocturnes d'ADVANCE ($90/mois, 50 threads). Dimensionnez sur les défis simultanés en pointe, pas sur le cumul mensuel.
Liste de contrôle avant la mise en production
- Périmètre limité à vos applications ou à des sources autorisées.
- Clé API en coffre ou en secret CI, absente du dépôt comme des prompts.
- Polling conforme : attente initiale, cadence, plafond par tâche.
- Token injecté dans le contexte navigateur d'origine.
- Retries plafonnés à trois, backoff exponentiel, échecs journalisés.
FAQ
browser-use résout-il les CAPTCHA nativement ?
Non. Le framework pilote un navigateur et raisonne sur la page ; il n'embarque aucun solveur et n'accède pas à l'iframe du défi. La résolution vient d'un service externe, appelé comme un outil de l'agent.
Pourquoi le token est-il refusé alors que la résolution a réussi ?
Le plus souvent, le token a été appliqué hors de la session qui a reçu le défi : nouveau contexte navigateur, cookies réinitialisés, ou expiration pendant un polling trop long. Vérifiez le partage de contexte, puis réduisez le délai entre obtention et usage.
CaptchaAI prend-il en charge hCaptcha dans ce type d'agent ?
Non — hCaptcha n'est pas pris en charge, FunCaptcha (Arkose Labs) non plus. Les types couverts sont reCAPTCHA v2 et v3, Cloudflare Turnstile et Challenge, GeeTest v3, les CAPTCHA image/OCR, les grilles d'images et BLS CAPTCHA. GeeTest v4 est à venir ; CaptchaFox, Friendly Captcha et Lemin sont en bêta.
Combien de threads prévoir pour un agent qui tourne en continu ?
Comptez un thread par défi résolu au même instant : un agent séquentiel n'en occupe qu'un, dix agents lancés en parallèle la nuit en occupent dix. Mesurez la simultanéité réelle sur une semaine avant de changer de plan.
Guides connexes
- Le démarrage rapide CaptchaAI
- La QA CAPTCHA en environnement autorisé
- Tester vos formulaires contre l'endpoint API
- La résolution CAPTCHA en intégration continue
- Résoudre reCAPTCHA v2 via l'API
Passez de l'agent qui bloque à l'agent qui termine. – Obtenez votre clé CaptchaAI.
