Périmètre sûr : ce guide s'applique uniquement à vos propres applications, à vos environnements de QA ou de préproduction, ou à des systèmes pour lesquels vous disposez d'une autorisation écrite. Il ne décrit aucune technique visant à échapper aux protections d'un site tiers.
Dans un run Skyvern, l'échec ne ressemble pas à une erreur : la tâche se termine, le rapport signale une étape « non complétée », et rien n'indique que le défi CAPTCHA du formulaire en est la cause. Le token attendu par le serveur ne figure nulle part dans la page que l'agent sait décrire : il se demande à une API dédiée. Le branchement à faire tient en quatre gestes : suspendre la tâche au moment du défi, obtenir le token auprès de CaptchaAI, l'injecter dans la session que Skyvern pilote déjà, puis laisser la tâche reprendre son cours.
La suite détaille ce branchement : architecture, séquence d'appels, code, mesures et contrôles avant déploiement.
Pourquoi un agent navigateur ne résout pas un CAPTCHA tout seul
Skyvern décompose un objectif en étapes et raisonne sur ce que la page expose. Or un défi CAPTCHA est précisément conçu pour que la réponse n'y figure pas : le sitekey est public, la validation se fait côté serveur. Laisser l'agent « essayer » quand même produit trois symptômes.
- Des boucles coûteuses : l'agent relance des actions inutiles, votre facture de tokens LLM grimpe, le parcours n'avance pas.
- Des exécutions non reproductibles : le même scénario réussit le lundi et échoue le mardi.
- Des échecs silencieux : le formulaire est soumis, la vérification serveur refuse la réponse, et l'agent enchaîne comme si tout allait bien.
La bonne frontière est nette. L'agent gère la navigation et le remplissage ; un composant déterministe gère le défi CAPTCHA.
Architecture cible : l'agent délègue, votre service résout
L'architecture tient en trois briques.
- L'agent Skyvern détecte l'élément de défi et met le parcours en pause au lieu d'improviser.
- Un service interne de résolution (une fonction, un worker, un endpoint privé) appelle CaptchaAI en HTTPS, attend la réponse et renvoie le token.
- L'agent reprend la main et injecte le token dans la même session : même contexte de navigateur, mêmes cookies, même client HTTP.
Ce dernier point, souvent négligé, est la première cause de rejet après résolution : un token obtenu dans une session A puis appliqué dans une session B est presque toujours refusé.
Séquence d'intégration, étape par étape
Étape 1 : identifiez le défi. Relevez le type (reCAPTCHA v2, reCAPTCHA v3, Cloudflare Turnstile, GeeTest v3, image ou OCR), le sitekey et l'URL de la page. Rien d'autre : chaque paramètre superflu crée une fausse piste de débogage.
Étape 2 : envoyez la tâche à l'API avec votre clé, puis récupérez l'identifiant de tâche.
Étape 3 : interrogez le résultat. Laissez passer un délai avant le premier appel, puis interrogez à intervalle fixe, avec un plafond dur par tâche. Un polling agressif ajoute du bruit sans rien accélérer.
Étape 4 : injectez le token dans le champ attendu par la page, puis laissez l'agent poursuivre.
Étape 5 : mesurez deux choses distinctes — la réussite de la résolution et celle du parcours complet. L'écart entre les deux est votre meilleur signal d'alerte.
Exemple de code
Exemple d'appel HTTP côté serveur dans votre propre service :
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;
}
Cas concret : recette nocturne chez un éditeur SaaS français
Prenons une équipe QA d'un éditeur SaaS français dont les agents Skyvern rejouent chaque nuit une trentaine de parcours d'inscription en préproduction, hébergée chez OVHcloud. Depuis l'activation de Turnstile, la moitié des scénarios s'arrêtait à la même étape.
Le correctif n'a pas touché à l'agent. Un worker interne a été ajouté : il reçoit le sitekey et l'URL, appelle CaptchaAI, renvoie le token, et l'agent le pose dans le champ cf-turnstile-response avant de valider le formulaire. Côté RGPD, les jeux de données de préproduction ont été purgés de toute donnée personnelle réelle : seuls le sitekey et l'URL de page transitent vers l'API.
Un plan BASIC ($15/mois, 5 threads) suffit pour une nuit de recette de ce volume : la facturation se fait par thread simultané, avec un nombre de résolutions illimité et en dollars US.
Secrets, solde et déploiement
La clé CaptchaAI vit dans un coffre (HashiCorp Vault, AWS Secrets Manager) ou dans un secret d'intégration continue, jamais dans le dépôt. Le déploiement la monte en variable d'environnement au runtime : une rotation ne coûte alors qu'un redéploiement.
Surveillez aussi le solde : un agent nocturne à court de crédit échoue de la façon la plus difficile à diagnostiquer.
Observabilité : ce qu'il faut journaliser
Instrumentez chaque appel avec quatre champs : durée d'obtention du token, code retour HTTP, identifiant de tâche et profondeur de la file interne. Séparez les journaux par environnement et corrélez-les à votre traçage distribué (OpenTelemetry) pour rejouer un scénario à partir d'un identifiant unique.
Liste de contrôle avant mise en production
- Le périmètre reste limité à vos applications ou à des sources autorisées.
- La clé API est stockée dans un coffre ou un secret CI, jamais en dur.
- Le token est injecté dans la session qui a déclenché le défi.
- Le retry est borné (trois tentatives, backoff exponentiel, plafond explicite).
- Une alerte se déclenche sur le solde et sur l'écart résolution/acceptation.
- Les scénarios sont rejouables depuis l'intégration continue, sans intervention manuelle.
FAQ
Skyvern peut-il résoudre un CAPTCHA sans service externe ?
Non. Aussi performant soit-il en vision, un agent navigateur ne dispose pas de la réponse : elle est vérifiée côté serveur à partir d'un token délivré par une API dédiée. Insister par le prompt engineering fait monter la facture LLM sans améliorer le taux de réussite.
Quels types de CAPTCHA sont pris en charge dans ce flux ?
reCAPTCHA v2, reCAPTCHA v3, Cloudflare Turnstile, Cloudflare Challenge, GeeTest v3, ainsi que les CAPTCHA image, texte et grilles d'images. CaptchaFox, Friendly Captcha et Lemin sont disponibles en bêta. hCaptcha et FunCaptcha (Arkose Labs) ne sont pas pris en charge ; GeeTest v4 est annoncé comme à venir.
Où exactement injecter le token dans le parcours de l'agent ?
Dans le champ caché attendu par la page — g-recaptcha-response pour reCAPTCHA, cf-turnstile-response pour Turnstile — puis déclenchez la soumission depuis le même contexte de navigateur. Si votre agent recrée un contexte entre la résolution et la soumission, le token sera refusé.
Quel plan choisir pour un parc d'agents nocturnes ?
Comptez en threads simultanés, pas en résolutions. Un lot séquentiel tient sur BASIC ($15/mois, 5 threads) ; une exécution parallélisée sur plusieurs environnements vise plutôt STANDARD ($30/mois, 15 threads) ou ADVANCE ($90/mois, 50 threads). Chaque plan inclut un nombre de résolutions illimité par thread.
Guides connexes
- Le démarrage rapide CaptchaAI
- Tests QA de CAPTCHA en environnements autorisés
- Tester l'endpoint API sur vos propres formulaires
- Intégrer la résolution CAPTCHA à votre CI
- Résoudre reCAPTCHA v2 via l'API
Vos agents avancent quand le défi CAPTCHA cesse d'être un point d'arrêt. – Obtenez votre clé CaptchaAI.
