Périmètre sûr : ce guide couvre uniquement vos propres applications, vos environnements de QA, de préproduction ou de production, ainsi que les systèmes pour lesquels vous disposez d'une autorisation écrite. Il ne traite ni de l'automatisation de sites tiers que vous ne contrôlez pas, ni de la neutralisation des protections anti-bot d'autrui.
Un « outil » (tool) LlamaIndex n'est rien d'autre qu'une fonction que votre agent peut appeler à la demande. Enregistrer CaptchaAI comme outil LlamaIndex revient donc à exposer la résolution de CAPTCHA sous la forme d'une fonction que l'agent déclenche dès qu'un formulaire ou une route protégée bloque son parcours. L'objectif n'est pas de faire tourner l'appel une fois dans un notebook, mais de le rendre assez stable pour s'exécuter sans surveillance en CI, dans un cron ou derrière une file d'attente interne.
Ce qu'un outil LlamaIndex attend de CaptchaAI
Côté agent, un outil se résume à un contrat clair : des entrées typées, une sortie prévisible, des erreurs explicites. CaptchaAI se prête bien à ce modèle, car la même API couvre toutes les familles de CAPTCHA qui vous concernent — reCAPTCHA v2 et v3, Cloudflare Turnstile, GeeTest v3, image/OCR et grilles d'images. Votre fonction outil envoie une tâche, interroge le résultat, puis renvoie le token à l'agent, qui l'injecte dans la session à l'origine du défi.
Le contrat tient en deux temps :
- Soumettez la tâche avec les seuls paramètres attendus par la famille de CAPTCHA (sitekey, URL de la page, action éventuelle, proxy facultatif). En capturer davantage crée de fausses pistes de débogage.
- Interrogez le résultat jusqu'à obtenir le token : attendez environ 15 secondes avant la première interrogation, puis espacez les suivantes de 5 secondes, avec un plafond strict par tâche.
Toute réponse dont le statut n'est pas positif est une erreur : journalisez-la intégralement plutôt que de la relancer à l'aveugle.
Exemple de code
L'outil que l'agent enregistre est une simple fonction côté serveur. Voici un exemple de création de tâche Turnstile 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;
}
L'agent appelle cette fonction, récupère l'identifiant de tâche, puis interroge le résultat selon la cadence décrite plus haut. Le même schéma se transpose à n'importe quel langage compatible HTTP : seule change la déclaration de l'outil auprès de LlamaIndex.
Configuration des secrets
La clé API CaptchaAI ne doit jamais vivre dans le code source ni dans le prompt de l'agent. Stockez-la dans un coffre (HashiCorp Vault, AWS Secrets Manager, Azure Key Vault) ou dans un secret d'intégration continue, et montez-la en variable d'environnement au moment de l'exécution — exactement ce que fait process.env.CAPTCHAAI_KEY dans l'exemple. Pour les lecteurs soumis au RGPD, limitez aussi les données personnelles qui transitent par l'outil : une fonction de résolution de CAPTCHA n'a besoin ni d'identifiants utilisateur, ni du contenu des formulaires.
Observabilité et journalisation
Quel que soit le langage, instrumentez chaque appel pour obtenir des métriques exploitables : durée totale d'obtention du token, code retour HTTP, identifiant de tâche et taille de la file d'attente interne. Ces signaux alimentent vos tableaux de bord et vos alertes.
Séparez les journaux par environnement (développement, préproduction, production) et corrélez chaque identifiant à votre traçage distribué, par exemple via OpenTelemetry. Vous pourrez ainsi rejouer un scénario complet à partir d'un identifiant unique ; en cas d'incident, ces journaux réduisent nettement le temps de diagnostic.
Mesurer la réussite
Une tâche résolue et un parcours réussi sont deux mesures distinctes : suivez les deux. Côté résolution, surveillez le temps d'obtention du token et le taux de réussite par famille de CAPTCHA. Côté agent, mesurez l'acceptation en aval — le token est-il validé dans la même session que celle qui a déclenché le défi ? Ajoutez enfin le coût par résolution acceptée, qui doit rester stable d'une semaine à l'autre : une dérive trahit presque toujours des paramètres erronés ou des tentatives en boucle.
Dépannage
Ces erreurs couvrent l'essentiel des incidents rencontrés sur ce type d'intégration. Chaque ligne se corrige sans quitter votre éditeur.
| Symptôme | Cause probable | Correctif |
|---|---|---|
ERROR_WRONG_USER_KEY |
Clé copiée avec un espace parasite ou mauvais compte. | Recopiez la clé depuis le tableau de bord et stockez-la en secret CI. |
ERROR_ZERO_BALANCE |
Solde inférieur au minimum par tâche. | Rechargez le solde et ajoutez une alerte de solde bas. |
ERROR_BAD_PARAMETERS |
Paramètre requis manquant ou mal formé. | Revalidez l'URL de la page et le sitekey face au HTML réel. |
| Token refusé après résolution | Token appliqué dans une session différente de celle du défi. | Conservez la résolution et l'envoi du formulaire dans le même contexte. |
Liste de contrôle
- Le périmètre reste limité à vos propres applications ou à des sources autorisées.
- La clé API CaptchaAI est stockée dans un coffre ou un secret CI, jamais dans le code.
- Les durées d'appel et les codes retour sont tracés à chaque exécution.
- Une stratégie de retry idempotent, avec backoff exponentiel borné, gère les erreurs transitoires.
- Les tests sont rejouables depuis votre intégration continue.
FAQ
Qu'est-ce qu'un outil LlamaIndex, concrètement ?
C'est une fonction que l'agent peut invoquer pendant son raisonnement. En l'enregistrant, vous donnez à l'agent la capacité de résoudre un CAPTCHA au moment précis où il en rencontre un, sans intervention humaine. La fonction reçoit les paramètres du défi et renvoie un token.
Où stocker la clé API dans un agent LlamaIndex ?
Dans un coffre ou un secret d'intégration continue, jamais dans le code ni dans le prompt système. Montez-la en variable d'environnement au démarrage du service. Vous évitez ainsi qu'une clé se retrouve dans les journaux de l'agent ou dans un dépôt public.
Comment éviter que l'agent reste bloqué sur le polling ?
Fixez un plafond par tâche et un nombre maximal d'interrogations. Attendez 15 secondes avant la première, puis interrogez toutes les 5 secondes ; au-delà du plafond, renvoyez une erreur claire que l'agent sait gérer, plutôt que de le laisser attendre indéfiniment.
Combien coûte la résolution de CAPTCHA à grande échelle ?
La facturation CaptchaAI repose sur les threads simultanés, pas sur le nombre de résolutions. Le plan BASIC ($15/mois, 5 threads) suffit à un agent unique ; montez en gamme — STANDARD ($30/mois, 15 threads), ADVANCE ($90/mois, 50 threads) — quand plusieurs agents résolvent en parallèle. Chaque plan inclut des résolutions illimitées par thread.
Guides connexes
- le démarrage rapide CaptchaAI
- la résolution de CAPTCHA en environnement de test autorisé
- tester l'endpoint API sur vos formulaires
- intégrer la résolution de CAPTCHA à votre CI
- résoudre reCAPTCHA v2 via l'API
Donnez à vos agents une résolution de CAPTCHA fiable et reproductible. – Obtenez votre clé CaptchaAI.
