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.
Le Vercel AI SDK laisse votre agent déclarer des outils (tools) qu'il déclenche au bon moment. Exposer CaptchaAI comme l'un de ces outils permet à l'agent de franchir une étape protégée par un CAPTCHA — dans votre propre application ou un environnement autorisé — sans sortir du flux de génération. L'enjeu n'est pas de faire tourner l'appel une fois dans un notebook, mais de tenir en production : latence prévisible, échecs propres et un code qu'un collègue relit en cinq minutes.
Pourquoi exposer CaptchaAI comme un outil du Vercel AI SDK
Déclarer la résolution comme un outil isole l'effet de bord : l'agent décide quand résoudre, tandis que la logique d'appel reste côté serveur, testable et journalisée. Vous gardez la main sur les paramètres, les délais et les nouvelles tentatives, sans laisser fuiter la clé API dans le contexte du modèle.
CaptchaAI expose une seule API pour les principales familles — reCAPTCHA v2 et v3, Cloudflare Turnstile, Cloudflare Challenge, GeeTest v3, ainsi que les CAPTCHA image/OCR et en grille. Vous changez de type sans réécrire l'intégration : seul le corps de la tâche évolue. La facturation se fait par thread simultané, pas à la résolution — le plan BASIC ($15/mois, 5 threads) suffit à démarrer, et le coût reste lisible quand le volume monte parce qu'il ne dépend pas du nombre de résolutions.
Architecture de l'intégration
Le principe tient en une phrase : un composant interne appelle CaptchaAI via HTTPS pour récupérer un token, puis l'injecte dans votre formulaire ou votre route d'API. La définition de l'outil s'exécute côté serveur (route Node.js, fonction serverless), jamais dans le navigateur : la clé API reste hors de portée du client.
Tracez chaque étape : soumission de la tâche, interrogation du résultat, injection du token. Ce fil continu détecte les régressions et évite de confondre un échec de résolution avec un rejet en aval.
Déclarer l'outil et gérer les secrets
La clé CaptchaAI vit dans un coffre (HashiCorp Vault, AWS Secrets Manager, Azure Key Vault) ou dans un secret d'intégration continue. Le déploiement la monte en variable d'environnement au runtime ; elle n'apparaît ni dans le code source, ni dans la définition d'outil exposée au modèle. Côté SDK, vous enveloppez l'appel dans un tool() doté d'un schéma d'entrée minimal — sitekey et URL de la page suffisent dans la plupart des cas.
Si vos workers tournent sur OVHcloud, Scaleway ou une région AWS eu-west-3 (Paris), gardez la même discipline : un secret par environnement, jamais partagé. Et comme ces journaux peuvent contenir des données de session, minimisez les données personnelles conservées et vérifiez vos obligations RGPD avant de tout tracer.
Exemple de code
Exemple d'appel HTTP côté serveur, à envelopper ensuite dans la définition d'outil du SDK :
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;
}
Observabilité et journalisation
Quel que soit le langage, instrumentez les appels CAPTCHA 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 de QA et distinguent « l'outil est lent » de « l'outil échoue ».
Séparez les journaux par environnement (développement, préproduction, production) et corrélez les identifiants à votre traçage distribué, par exemple via OpenTelemetry. Vous rejouez ainsi un scénario complet à partir d'un identifiant unique, et divisez d'autant le temps de diagnostic en cas d'incident.
Tests et intégration continue
Ajoutez des tests d'intégration sur vos endpoints critiques et rendez-les rejouables depuis votre intégration continue : un scénario reproductible vaut mieux qu'un run manuel réussi une fois.
Dépannage
Voici les incidents les plus fréquents sur une intégration outil, avec le correctif à appliquer sans quitter votre éditeur.
| Symptôme | Cause probable | Correctif |
|---|---|---|
| Clé API rejetée au runtime | Espace parasite dans la clé, ou secret non monté | Recopiez la clé et vérifiez que le secret est exposé au runtime |
| Solde insuffisant | Solde sous le minimum par tâche | Rechargez le compte et ajoutez une alerte de solde |
| Token refusé après résolution | Token injecté dans une autre session que celle du défi | Appliquez le token dans la session HTTP qui continue le flux |
| L'interrogation du résultat expire | Plafond de polling atteint, ou paramètres erronés | Revalidez le sitekey et l'URL, puis bornez le polling |
Liste de contrôle avant mise en production
- Le périmètre est strictement limité à vos propres applications ou à des sources autorisées.
- La clé CaptchaAI est stockée dans un secret CI ou un coffre, jamais dans le code source ni dans la définition d'outil.
- L'appel s'exécute côté serveur ; le navigateur ne voit jamais la clé API.
- Les durées d'appel et les codes retour sont tracés pour chaque exécution.
- Une stratégie de retry idempotent avec backoff exponentiel borné est en place pour les erreurs transitoires.
- Les tests sont rejouables et reproductibles depuis votre intégration continue.
FAQ
Comment déclarer CaptchaAI comme outil dans le Vercel AI SDK ?
Enveloppez l'appel HTTP dans un tool() avec un schéma d'entrée simple (sitekey, URL) et une fonction d'exécution qui soumet la tâche à CaptchaAI, interroge le résultat puis renvoie le token. L'agent invoque l'outil au moment voulu ; toute la logique réseau, y compris la clé API, reste dans votre code serveur.
Faut-il appeler CaptchaAI côté serveur plutôt que dans le navigateur ?
Côté serveur, toujours. La définition d'outil et l'appel doivent s'exécuter dans votre backend pour ne jamais exposer la clé API au client ni au contexte du modèle. Le navigateur ne reçoit que le résultat utile — le token à injecter dans la même session que celle qui a déclenché le défi.
Quels types de CAPTCHA cet outil peut-il résoudre ?
Les familles prises en charge par CaptchaAI : reCAPTCHA v2 et v3, Cloudflare Turnstile, Cloudflare Challenge, GeeTest v3, et les CAPTCHA image/OCR et en grille. hCaptcha et FunCaptcha (Arkose Labs) ne sont pas pris en charge, et GeeTest v4 est annoncé « à venir ». Pour changer de type, vous adaptez le corps de la tâche sans toucher au reste de l'intégration.
Comment maîtriser le coût quand le volume augmente ?
Le tarif dépend du nombre de threads simultanés, pas du nombre de résolutions : le coût par résolution acceptée reste stable tant que vos paramètres sont corrects. Les vrais gouffres sont les boucles de mauvais paramètres et les tempêtes de retry, que la liste de contrôle ci-dessus élimine. Suivez ce coût sur la semaine pour repérer toute dérive.
Guides connexes
- Le démarrage rapide CaptchaAI
- La QA CAPTCHA en environnements autorisés
- Tester l'endpoint API sur vos formulaires
- Intégrer la résolution CAPTCHA en CI
- Résoudre reCAPTCHA v2 via l'API
Structurez vos workflows CAPTCHA avec une approche méthodique et reproductible. – Obtenez votre clé CaptchaAI.
