Intégrer un nœud CaptchaAI dans un workflow LangGraph

Périmètre sûr : ce guide s'applique uniquement à vos propres applications, à vos environnements de QA, de préproduction ou de production, ou à des systèmes pour lesquels vous détenez une autorisation écrite. Il ne couvre ni l'automatisation de sites tiers, ni l'évasion d'anti-bot.

Un nœud CaptchaAI dans un graphe LangGraph tient en trois responsabilités : soumettre la tâche au solveur, interroger le résultat, puis réinjecter le token dans la même session que le reste du graphe. La vraie difficulté n'est pas de faire fonctionner le flux une fois dans un notebook, mais de le garder stable quand l'agent tourne seul en CI, dans un cron ou derrière une file d'attente interne.

Ce guide montre où placer le nœud, quel contrat il doit respecter et quoi surveiller avant la production. Il vise un agent qui traverse une étape protégée par un CAPTCHA dans une application que vous contrôlez.

Ce que fait le nœud dans le graphe

Le nœud CaptchaAI reçoit un état (URL de page, sitekey, proxy éventuel), appelle CaptchaAI via HTTPS pour obtenir un token, puis enrichit l'état pour le nœud suivant, qui réinjecte le token dans le formulaire ou la route ayant déclenché le défi.

Isolez cette logique dans un seul nœud : un point d'entrée unique se teste, se trace et se remplace sans toucher au reste du graphe. Si le type de CAPTCHA change sur la page, vous n'ajustez que ce nœud.

Le contrat en trois temps : soumettre, interroger, réinjecter

Quel que soit le langage, le nœud suit toujours la même séquence.

1. Capturez uniquement ce dont le solveur a besoin (sitekey, URL de page, action, proxy facultatif) ; stocker davantage crée de fausses pistes de débogage.
2. Soumettez la tâche avec json=1 et traitez tout statut différent de 1 comme une erreur : journalisez la réponse et alertez la supervision.
3. Interrogez le résultat régulièrement. Attendez quelques secondes avant la première interrogation, espacez les suivantes et fixez un plafond de temps par tâche.
4. Réinjectez le token dans la même session que celle qui a déclenché le défi (même contexte de navigateur, même client HTTP, même jar de cookies). Une session dépareillée est la première cause de rejet après résolution.

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 CI, jamais dans le code source ni dans l'état du graphe. Le déploiement la monte en variable d'environnement au runtime.

Côté données, appliquez le réflexe RGPD : le nœud n'a besoin que du sitekey et de l'URL de page, jamais des identifiants de l'utilisateur final. Minimisez ce que le graphe conserve dans son état persistant, surtout si vous tracez chaque exécution.

Exemple : appeler CaptchaAI depuis le nœud

Voici un appel HTTP côté serveur, tel qu'il vivrait à l'intérieur d'un nœud de 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;
}

La même logique se transpose vers Python, Go, Ruby ou Java. L'API étant identique pour toutes les familles de CAPTCHA, vous changez le type de tâche sans réécrire le nœud.

Observabilité et journalisation

Instrumentez les appels CAPTCHA pour obtenir des métriques exploitables : durée 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 vos alertes.

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 alors un scénario complet à partir d'un identifiant unique — de quoi diviser par deux le temps de diagnostic.

Suivre la réussite du nœud

Une tâche résolue n'est pas un workflow réussi : distinguez toujours les deux. Câblez ces indicateurs dans votre tableau de bord habituel pour repérer les régressions avant vos utilisateurs.

• Latence de première résolution : la médiane et la queue (p95) disent si vos timeouts sont bien dimensionnés.
• Taux de réussite du solveur par famille de CAPTCHA : révèle si vos paramètres correspondent au défi réel.
• Taux d'acceptation en aval : le token est-il accepté par la vérification finale, dans la même session ?
• Coût par résolution acceptée : stable sur la semaine, il confirme que les retry n'érodent pas le volume.

Dépannage

Liste de contrôle avant la mise en production

• Le périmètre est 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.
• Les durées d'appel et les codes retour sont tracés pour chaque exécution du nœud.
• Un retry idempotent avec backoff exponentiel borné couvre les erreurs transitoires.
• Les tests du nœud sont rejouables en intégration continue.

FAQ

Où placer le nœud CaptchaAI dans le graphe LangGraph ?

Juste avant le nœud qui soumet le formulaire ou appelle la route protégée. Gardez la résolution et la soumission voisines pour ne pas perdre le contexte de session.

Le nœud bloque-t-il l'exécution du graphe pendant la résolution ?

Le temps de la boucle d'interrogation, oui. Fixez un plafond par tâche pour qu'un nœud lent ne fige jamais tout le graphe, exécutez les nœuds indépendants en parallèle et prévoyez une branche de repli au-delà du plafond.

Comment gérer une erreur transitoire de l'API pendant la résolution ?

Appliquez un backoff exponentiel borné : trois tentatives, doublement du délai à chaque essai, plafond à 30 secondes. Tracez chaque échec avec son identifiant de tâche. Si l'erreur persiste, vérifiez le réseau (DNS, certificats) et les quotas de votre clé.

Quel plan CaptchaAI convient à un agent LangGraph qui tourne en continu ?

CaptchaAI facture au thread concurrent, pas à la résolution : chaque thread traite un CAPTCHA à la fois puis enchaîne, avec un nombre illimité de résolutions dans le mois. Un agent qui résout quelques CAPTCHA en série tient dans le plan BASIC ($15/mois, 5 threads). Dimensionnez les threads sur votre pic de tâches simultanées, pas sur le volume total.

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 de CAPTCHA en CI
• Résoudre reCAPTCHA v2 via l'API

Un nœud CAPTCHA fiable se construit avec une méthode reproductible et des métriques claires. – Créez votre clé CaptchaAI.