Périmètre sûr : Ce guide s'applique exclusivement à vos propres applications, environnements de QA, de préproduction ou de production, ou à des systèmes pour lesquels vous disposez d'une autorisation écrite. Il ne décrit ni l'automatisation de sites tiers, ni le contournement de protections, ni l'évasion d'anti-bot.
Déléguez. Un agent computer-use OpenAI n'apporte ni la fiabilité ni la traçabilité qu'exige la résolution d'un défi CAPTCHA : son rôle s'arrête à la reconnaissance de l'étape protégée. Le token provient d'un service interne qui appelle l'API CaptchaAI, et il est réinjecté dans la session qui a déclenché le défi. Cette délégation tient en une fonction HTTP et rend le parcours mesurable : durée d'obtention du token, code retour, taux d'acceptation en aval.
Où l'agent se bloque réellement
Le blocage n'apparaît pas au premier essai, mais quand la boucle tourne sans surveillance. Deux symptômes dominent les traces : des actions répétées sur le même écran jusqu'au timeout, et un token appliqué dans un autre contexte, donc refusé.
Architecture : l'agent délègue, votre service résout
Votre composant interne appelle CaptchaAI via HTTPS pour récupérer un token, puis l'injecte dans votre formulaire ou votre route d'API. L'agent reconnaît l'étape protégée et passe la main. Trois séparations à poser :
- La détection du défi appartient à l'agent, la résolution à un service HTTP isolé.
- Le token revient dans la même session et le même contexte de navigateur que l'étape d'origine.
- Chaque étape porte un identifiant unique, ce qui expose les régressions après une montée de version du modèle ou du navigateur.
Exemple d'appel côté serveur
Votre service interne crée la tâche et renvoie son identifiant ; l'interrogation du résultat vient ensuite, dans la même fonction ou dans un worker séparé :
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;
}
Vous changez le type de tâche, pas la boucle. Cloudflare Turnstile se résout typiquement en moins de 10 s, reCAPTCHA v2 en moins de 60 s : dimensionnez vos timeouts sur ces ordres de grandeur.
Gestion de la clé API
La clé CaptchaAI vit dans un coffre (HashiCorp Vault, AWS Secrets Manager, Azure Key Vault) ou un secret CI, monté en variable d'environnement au runtime — jamais dans le prompt de l'agent, qui recopie tôt ou tard dans une trace ce qu'il voit.
Scénario : une équipe QA francophone
Une équipe QA à Nantes rejoue chaque nuit son parcours d'inscription, protégé par Turnstile, sur une application hébergée chez OVHcloud. Le worker de résolution tourne dans la même région pour limiter la latence, et les journaux ne gardent que l'identifiant de tâche, l'horodatage et le code retour — jamais le contenu des formulaires, conformément à la minimisation exigée par le RGPD.
Les métriques qui révèlent une régression
Instrumentez les appels : durée d'obtention du token, code retour HTTP, identifiant de tâche, taille de la file d'attente. Séparez les journaux par environnement et corrélez-les à votre traçage distribué (OpenTelemetry).
Suivez séparément le taux de réussite du solveur et le taux d'acceptation en aval : l'écart entre les deux courbes révèle un problème de session ou de paramètres.
Dimensionner les threads
La facturation se fait par thread simultané, résolutions illimitées sur chaque thread. Un agent qui rejoue des scénarios en série sature rarement plus de deux threads : BASIC ($15/mois, 5 threads) suffit pour démarrer, STANDARD ($30/mois, 15 threads) couvre une flotte d'agents en intégration continue.
Avant de brancher l'agent en production
- Périmètre limité à vos applications ou à des sources autorisées.
- Clé CaptchaAI en coffre ou secret CI, jamais dans le code source.
- Token appliqué dans la session qui a déclenché le défi.
- Durées d'appel et codes retour tracés à chaque exécution.
- Retry idempotent borné sur les erreurs transitoires.
FAQ
L'agent doit-il piloter le navigateur pendant la résolution ?
Non. Il met l'étape en pause et attend le token. Un rechargement ou un nouvel onglet pendant l'attente invalide la session.
CaptchaAI prend-il en charge hCaptcha dans ce type d'intégration ?
Non — hCaptcha n'est pas pris en charge, FunCaptcha non plus, et GeeTest v4 est à venir. Comptez sur reCAPTCHA v2 et v3, Cloudflare Turnstile, Cloudflare Challenge, GeeTest v3, les CAPTCHA image et texte et les grilles d'images ; CaptchaFox (bêta), Friendly Captcha (bêta) et Lemin (bêta) restent en bêta.
Un agent computer-use mobilise-t-il un thread en permanence ?
Non : un thread n'est occupé que pendant la résolution, pas pendant que l'agent clique ou lit l'écran. Dimensionnez donc sur les défis simultanés observés sur une semaine, pas sur le nombre d'agents, puis ajoutez une marge pour les nouvelles tentatives.
Que journaliser sans alourdir vos obligations RGPD ?
L'identifiant de tâche, l'horodatage, la durée et le code retour suffisent. Évitez les captures d'écran de formulaires renseignés et les payloads complets : ils contiennent des données personnelles inutiles au diagnostic.
Guides connexes
- Démarrage rapide CaptchaAI
- QA CAPTCHA en environnements autorisés
- Tester l'endpoint API sur vos formulaires
- Intégration CAPTCHA en CI
- Résoudre reCAPTCHA v2 via API
Donnez à vos agents une étape de résolution mesurable et reproductible. – Obtenez votre clé CaptchaAI.
