[ AGENTS ]

Résolution de captcha pour
agents LangChain

Un agent qui rencontre un défi n'a rien dans sa boîte à outils pour y répondre : il se bloque ou hallucine un contournement. Donnez-lui un solveur sous forme d'outil et le blocage devient un appel de plus.

python · langchain

import time
import requests

CAPTCHANO_KEY = "cn-YOUR_API_KEY"
HEADERS = {"Authorization": f"Bearer {CAPTCHANO_KEY}"}

def solve(task: dict) -> dict:
    """Block until solved; returns e.g. {"token": "...", "userAgent": "..."}."""
    r = requests.post(
        "https://api.captchano.com/v1/solve",
        params={"wait": 60},
        json=task,
        headers=HEADERS,
        timeout=75,
    )
    data = r.json()
    # A solve can outlast the 60 s wait: poll the task until it finishes.
    while data.get("status") in ("queued", "solving"):
        time.sleep(5)
        data = requests.get(
            f"https://api.captchano.com/v1/task/{data['id']}",
            headers=HEADERS,
            timeout=30,
        ).json()
    if data.get("status") != "ready":
        raise RuntimeError(data.get("error") or data)
    return data["solution"]

from langchain_core.tools import tool

@tool
def solve_captcha(kind: str, sitekey: str, url: str) -> str:
    """Call when a captcha blocks the task. kind is recaptcha_v2, recaptcha_v3
    or turnstile. Returns the token to submit with the form."""
    return solve({"type": kind, "sitekey": sitekey, "url": url})["token"]

# add solve_captcha to your agent's tools list

Pourquoi les agents en ont particulièrement besoin

Un scraper qui tombe sur un défi échoue bruyamment, et vous le corrigez. Un agent échoue en silence : il raisonne sur la page bloquée, invente une étape suivante plausible et signale des progrès qu'il n'a jamais faits. L'échec est pire parce qu'il est silencieux. Un outil de résolution typé transforme une impasse ambiguë en un résultat déterministe sur lequel l'agent peut s'appuyer.

Ce que renvoie l'outil

Un token ou un cookie, selon le type de défi. Les systèmes évalués sur la session renvoient un cookie ainsi que l'ensemble des en-têtes utilisés pour l'obtenir.
Le user agent utilisé, pour que l'agent puisse le réutiliser lors de la soumission.
Le coût de la résolution, pour qu'un agent soumis à un budget puisse le comptabiliser au lieu de dépenser à l'aveugle.

Garder la boucle bornée

Donnez à l'agent un budget de résolutions par exécution. Chaque réponse indique son coût : un superviseur peut donc couper la boucle quand les dépenses dépassent un seuil, plutôt que de le découvrir sur la facture. À $0.00598 par résolution, une exécution d'agent typique coûte quelques centimes ou moins, mais une boucle de nouvelles tentatives sans limite reste une boucle sans limite.

Gardez l'appel d'outil bloquant

Les exemples appellent ?wait=60, pour que l'outil renvoie un token finalisé en une seule étape. C'est plus important pour les agents que pour les scripts : un outil qui renvoie "résolution en cours" oblige le modèle à raisonner sur le polling, ce qu'il fait mal. Si vous avez besoin d'un délai plus long, augmentez wait jusqu'à 120 secondes. Les formats de requête de chaque type de défi figurent dans la référence de l'API.

[ INTÉGRATION ]

Comment la résolution s'intègre à LangChain

Dans LangChain, le solveur est un outil doté d'un schéma typé. L'agent l'appelle lorsque son outil navigateur signale un défi.

01
Définir l'outil
Encapsulez l'appel à l'API avec le décorateur @tool et une docstring claire.
02
Le lier à l'agent
Ajoutez-le à la liste des outils, à côté de vos outils navigateur.
03
Décrire quand l'utiliser
La docstring indique au modèle de ne l'appeler que lorsqu'un captcha est présent.
04
Renvoyer un résultat clair
Renvoyez le token ou une courte erreur exploitable par le modèle.

Injecter le token dans la page

L'outil renvoie le token sous forme de chaîne que l'agent transmet à son outil navigateur ou HTTP.

[ PIÈGES ]

Là où les intégrations échouent le plus souvent

Docstrings vagues

Le modèle décide quand appeler un outil d'après sa description. Indiquez précisément les entrées nécessaires et ce qu'il renvoie.

Nouvelles tentatives illimitées

Limitez le nombre de résolutions par exécution pour qu'un agent désorienté ne boucle pas sur une page qui lui présente sans cesse un défi.

[ FAQ ]

FAQ captcha LangChain

Cela fonctionne-t-il avec LangGraph ?

Oui. Un outil LangChain est aussi une fonction appelable par un nœud dans LangGraph : la même définition fonctionne donc dans les deux.

Quel modèle fonctionne le mieux avec l'outil ?

Tout modèle qui prend en charge l'appel d'outils. Les entrées de l'outil sont de simples chaînes, donc les modèles plus petits s'en sortent très bien.

Comment l'agent sait-il qu'un captcha est présent ?

Son outil navigateur ou de scraping doit le signaler, par exemple en renvoyant la sitekey lorsqu'il en trouve une. Intégrez cela à la sortie de l'outil.

Puis-je l'utiliser dans un agent asynchrone ?

Oui. Utilisez un client HTTP asynchrone dans l'outil et définissez-le avec async def.

[ À LIRE ENSUITE ]