Périmètre sûr : ce guide s'applique uniquement à vos propres applications, à vos environnements de QA ou de préproduction, et aux systèmes pour lesquels vous disposez d'une autorisation écrite. Il ne couvre ni l'automatisation de sites tiers, ni les techniques d'anti-détection.
Un agent web MultiOn sait décrire le défi CAPTCHA qu'il a sous les yeux ; il ne sait pas produire le token que le serveur attend. La réponse tient en une phrase : sortez la résolution de l'agent, confiez-la à l'API CaptchaAI depuis votre propre service, puis réinjectez le token dans la session qui a déclenché le défi. Le reste de cet article détaille ce découpage, le code minimal, les métriques à surveiller et le coût réel.
Où votre agent MultiOn se bloque face à un CAPTCHA
Trois points de rupture reviennent systématiquement. Le premier : l'agent atteint un formulaire protégé par reCAPTCHA v2 ou Cloudflare Turnstile et boucle sur la page sans jamais valider. Le deuxième : un token est bien obtenu, mais il est appliqué depuis un autre contexte navigateur que celui d'origine, et le serveur le refuse. Le troisième : l'appel de résolution n'a aucun timeout, et une tâche bloquée immobilise un worker pendant plusieurs minutes.
Un agent n'est pas un solveur. Traitez la résolution comme un service externe, avec son contrat, son délai d'expiration et ses journaux.
Résoudre le CAPTCHA hors de l'agent, en quatre étapes
- Détectez le défi côté orchestrateur, pas dans le prompt de l'agent. Repérez la présence du sitekey dans le DOM et suspendez l'étape en cours.
- Créez la tâche auprès de l'API CaptchaAI avec le sitekey, l'URL de la page et, le cas échéant, le proxy utilisé par l'agent.
- Interrogez le résultat à intervalle fixe, avec un plafond dur par tâche. Sans plafond, votre file d'attente se remplit silencieusement.
- Injectez le token dans la même session : même contexte navigateur, même client HTTP, mêmes cookies. C'est la cause numéro un des rejets après résolution.
Exemple de code : créer une tâche Turnstile
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;
}
Cette fonction ne renvoie qu'un identifiant de tâche. L'interrogation du résultat reste volontairement séparée : elle devient testable seule et rejouable en cas d'incident.
Gardez la clé API hors du code de l'agent
La clé CaptchaAI n'a rien à faire dans le prompt, dans un fichier de configuration versionné ni dans une constante en dur. Stockez-la dans un coffre (HashiCorp Vault, AWS Secrets Manager, Azure Key Vault) ou dans un secret d'intégration continue, puis montez-la en variable d'environnement au démarrage du conteneur. Prévoyez la rotation : un agent qui tourne en continu doit relire la clé au redémarrage, pas seulement au premier appel.
Les métriques qui comptent vraiment
Instrumentez chaque appel et exposez quatre signaux : durée totale d'obtention du token, code retour HTTP, identifiant de tâche et profondeur de la file d'attente interne. Séparez les journaux par environnement et corrélez-les à votre traçage distribué (OpenTelemetry, par exemple) : vous rejouez ainsi un scénario complet à partir d'un seul identifiant.
Distinguez surtout deux taux différents : le taux de réussite de la résolution et le taux d'acceptation en aval. Un token obtenu mais refusé par le formulaire ne se voit que si vous mesurez les deux séparément. Cloudflare Turnstile est généralement résolu en moins de 10 s et reCAPTCHA v2 en moins de 60 s ; calibrez vos timeouts sur ces ordres de grandeur, pas sur une moyenne relevée un jour de faible charge.
Scénario : un parc d'agents QA en Europe
Une équipe QA lyonnaise fait tourner six agents MultiOn sur des instances OVHcloud, contre son propre back-office de préproduction. Les agents ne parlent jamais directement à l'API de résolution : un service interne déployé dans la même région (Gravelines, par exemple) centralise les appels, applique le plafond de tentatives et journalise tout. Bénéfice concret côté conformité : les URL de pages et les identifiants de session ne sortent pas du périmètre maîtrisé, ce qui simplifie la revue RGPD des traitements. Vérifiez vos propres obligations avant de conserver des journaux contenant des données personnelles.
Le coût, sans mauvaise surprise
La facturation CaptchaAI se fait par thread simultané, avec un nombre de résolutions illimité par thread, et non à la résolution. Un thread correspond à un défi en cours de traitement. Pour un parc d'agents, la question n'est donc pas « combien de CAPTCHA par mois ? » mais « combien de défis simultanés au pic ? ». Le plan BASIC ($15/mois, 5 threads) suffit à quelques agents séquentiels ; STANDARD ($30/mois, 15 threads) couvre une petite flotte ; ADVANCE ($90/mois, 50 threads) vise les parcs qui lancent des campagnes de tests en parallèle. La facturation est en dollars US.
Liste de contrôle avant la mise en production
- Le périmètre reste limité à vos applications ou à des sources explicitement autorisées.
- La clé CaptchaAI provient d'un coffre ou d'un secret CI, jamais du dépôt.
- Chaque appel a un timeout et un plafond de tentatives (trois essais, backoff exponentiel borné).
- Le token est injecté dans la session d'origine, et un test d'intégration couvre ce point.
- Les tableaux de bord distinguent taux de résolution et taux d'acceptation en aval.
FAQ
MultiOn peut-il résoudre un CAPTCHA tout seul ?
Non. Un agent web pilote un navigateur et raisonne sur le contenu de la page ; il ne génère pas le token attendu par le vérificateur. La résolution doit être déléguée à une API dédiée, puis le token réinjecté dans le flux.
CaptchaAI prend-il en charge hCaptcha ou FunCaptcha pour ce type d'agent ?
Non — ces deux types ne sont pas pris en charge, et GeeTest v4 est annoncé comme à venir. Sont couverts : reCAPTCHA v2 et v3, Cloudflare Turnstile, Cloudflare Challenge, GeeTest v3, les CAPTCHA image et les grilles d'images. CaptchaFox (bêta), Friendly Captcha (bêta) et Lemin (bêta) restent en phase bêta.
Combien de threads prévoir pour dix agents en parallèle ?
Comptez les défis réellement simultanés, pas le nombre d'agents. Dix agents qui rencontrent un CAPTCHA toutes les quelques minutes tiennent largement dans STANDARD ($30/mois, 15 threads) ; passez à ADVANCE ($90/mois, 50 threads) si toutes vos campagnes démarrent en même temps.
Le token passe en test mais il est refusé en production : pourquoi ?
Dans la grande majorité des cas, la session diffère entre la résolution et la soumission : proxy différent, contexte navigateur recréé, cookies perdus au redémarrage du worker. Vérifiez aussi que l'URL de page envoyée à l'API correspond exactement à celle affichée par l'agent.
Guides connexes
- Démarrage rapide CaptchaAI
- Tests CAPTCHA en environnement autorisé
- Tester vos formulaires via l'endpoint API
- Intégrer la résolution CAPTCHA à votre CI
- Résoudre reCAPTCHA v2 via l'API
Passez de l'agent qui bloque à l'agent qui termine son parcours. – Obtenez votre clé CaptchaAI.
