Résoudre les CAPTCHA dans les pipelines d'agents LangChain

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 décrit ni l'automatisation de sites tiers, ni la neutralisation de protections anti-bot.

Un agent LangChain s'arrête net dès qu'un de ses outils tombe sur un défi CAPTCHA : la chaîne récupère une page de vérification au lieu du contenu attendu, et le modèle improvise une réponse à partir de rien. La bonne réponse tient en une décision d'architecture : sortez la résolution du raisonnement du modèle et confiez-la à un outil déterministe qui appelle l'API CaptchaAI, renvoie un token, puis rend la main à la chaîne. Ce guide décrit où placer cet outil, quels signaux journaliser et comment dimensionner vos threads.

Pourquoi un agent LLM trébuche là où un script tient

Un script connaît son parcours à l'avance : il sait qu'un formulaire protégé arrive à l'étape trois et prévoit l'appel correspondant. Un agent, lui, découvre la page à l'exécution. S'il reçoit un HTML de challenge, rien ne l'empêche de le résumer, de le prendre pour un résultat valide et de poursuivre son plan sur une base fausse : l'erreur se propage alors à toutes les étapes suivantes.

Deuxième piège : la latence. Une résolution prend plusieurs secondes, bien au-delà du timeout par défaut de la plupart des outils LangChain. Si vous ne relevez pas ce plafond, l'agent enregistre un échec alors que le token est bien arrivé.

Architecture : la résolution comme outil déterministe

N'exposez qu'un seul outil, invoqué uniquement lorsque la page renvoie un défi. Sa logique ne dépend jamais du modèle et suit toujours la même séquence :

1. Extraire les paramètres du défi : le sitekey, l'URL de la page et le type de CAPTCHA. Rien de plus — chaque champ superflu crée une fausse piste de débogage.
2. Envoyer la tâche à l'API CaptchaAI depuis votre propre service, jamais depuis un appel construit par le modèle.
3. Interroger le résultat à intervalle fixe, avec un plafond dur par tâche pour éviter qu'un agent reste bloqué.
4. Injecter le token dans la même session — même contexte de navigateur, même client HTTP, mêmes cookies. Une session dépareillée reste la première cause de rejet après résolution.

La même API couvre reCAPTCHA v2 et v3, Cloudflare Turnstile, Cloudflare Challenge, GeeTest v3, ainsi que les CAPTCHA image/OCR et les grilles d'images ; s'y ajoutent CaptchaFox (bêta), Friendly Captcha (bêta) et Lemin (bêta). hCaptcha et FunCaptcha (Arkose Labs) ne sont pas pris en charge, et GeeTest v4 est annoncé « à venir » : si un de vos parcours en dépend, prévoyez une branche de repli explicite dans l'agent plutôt qu'une tentative silencieuse.

Gérer la clé API et 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, jamais dans un prompt ni dans une variable exposée au modèle ; le déploiement la monte en variable d'environnement au runtime. La règle est simple : tout ce que le modèle peut lire, il peut aussi le restituer dans une trace.

Exemple : créer une tâche depuis votre service

Appel HTTP côté serveur, encapsulé dans l'outil invoqué par la chaîne :

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'outil retourne ensuite au modèle une valeur courte et typée — « token obtenu » ou « échec : cause » — jamais la réponse brute de l'API, qu'un agent tenterait de reformuler.

Observabilité : ce que chaque appel doit produire

Instrumentez quatre signaux par tâche : durée d'obtention du token, code retour HTTP, identifiant de tâche et profondeur de la file d'attente. Séparez les journaux par environnement et corrélez-les à votre traçage distribué, OpenTelemetry par exemple, pour rejouer un incident à partir d'un identifiant unique.

Attention au volume de données côté agent : les traces LangChain capturent par défaut le contenu des pages visitées, qui peut contenir des données personnelles. Minimisez ce qui est conservé et vérifiez vos obligations RGPD avant d'archiver des traces complètes — l'identifiant de tâche et la latence suffisent au diagnostic.

Dimensionner les threads pour un parc d'agents LangChain

La facturation CaptchaAI se fait au thread simultané, avec un nombre de résolutions illimité par thread : un thread correspond à un CAPTCHA en vol, libéré dès la résolution terminée. Pour une équipe qui exécute cinq agents en parallèle sur des workers Scaleway ou OVHcloud, le plan BASIC ($15/mois, 5 threads) couvre le développement et la QA ; un parc nocturne qui déclenche des dizaines de parcours simultanés passe naturellement sur STANDARD ($30/mois, 15 threads) ou ADVANCE ($90/mois, 50 threads). Dimensionnez sur la concurrence réellement mesurée, pas sur le volume mensuel : c'est le pic de tâches simultanées qui détermine le palier.

Liste de contrôle avant la mise en production

• Le périmètre reste limité à vos applications ou sources autorisées.
• La clé CaptchaAI vient d'un coffre ou d'un secret CI, jamais du contexte du modèle.
• Le timeout de l'outil LangChain dépasse le plafond de résolution que vous avez fixé.
• Les tentatives de retry sont bornées (trois essais, backoff exponentiel) et tout échec terminal est tracé.
• La réussite de la résolution et la réussite du parcours sont mesurées séparément.

FAQ

Faut-il placer la résolution dans un outil LangChain ou en amont de la chaîne ?

Dans un outil dédié, appelé explicitement. Résoudre en amont oblige à traiter un défi qui n'apparaîtra peut-être pas, et laisser le modèle composer la requête rend la séquence imprévisible. L'outil garde la logique ; le modèle décide seulement du moment de l'invoquer.

CaptchaAI prend-il en charge hCaptcha dans ce type de pipeline ?

Non — hCaptcha n'est pas pris en charge, pas plus que FunCaptcha (Arkose Labs). Si un parcours en dépend, l'agent doit s'arrêter proprement avec une erreur explicite plutôt que de boucler sur des tentatives inutiles.

Combien de threads prévoir pour dix agents simultanés ?

Comptez les CAPTCHA réellement en vol au même instant, pas les agents : dix agents qui rencontrent un défi une fois par parcours consomment rarement dix threads simultanés. Mesurez la concurrence sur une semaine, puis prenez le palier au-dessus du pic observé.

Pourquoi un token est-il refusé après une résolution réussie ?

Dans la grande majorité des cas, il a été injecté dans une session différente de celle qui a déclenché le défi. Vérifiez que le contexte de navigateur, le client HTTP et le cookie jar sont identiques entre l'appel de l'outil et la soumission du formulaire.

Que journaliser sans alourdir la charge RGPD ?

L'identifiant de tâche, l'horodatage, la latence et le code retour. Évitez d'archiver le HTML complet des pages traversées par l'agent : il contient souvent des données personnelles sans valeur pour le diagnostic.

Guides connexes

• Le démarrage rapide CaptchaAI
• La QA CAPTCHA en environnements autorisés
• Tester vos formulaires via l'endpoint API
• Intégrer la résolution CAPTCHA à votre CI
• Résoudre reCAPTCHA v2 via l'API

Branchez un outil de résolution déterministe sur votre chaîne et gardez votre architecture intacte. – Obtenez votre clé CaptchaAI.