[ AGENTES ]

Resolução de captcha para
agentes LangChain

Um agente que encontra um desafio não tem nada no seu conjunto de ferramentas que consiga respondê-lo, então ele trava ou alucina para contorná-lo. Dê a ele um solucionador como ferramenta e o bloqueio vira só mais uma chamada.

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

Por que agentes precisam especificamente disso

Um scraper que encontra um desafio falha de forma evidente e você corrige. Um agente falha em silêncio: ele raciocina sobre a página bloqueada, inventa um próximo passo plausível e relata um progresso que nunca fez. A falha é pior porque é silenciosa. Uma ferramenta de resolução tipada transforma um beco sem saída ambíguo em um resultado determinístico a partir do qual o agente pode decidir.

O que a ferramenta retorna

Um token ou cookie — dependendo do tipo de desafio. Sistemas avaliados por sessão retornam um cookie e o conjunto de headers usado para obtê-lo.
O user agent usado, para que o agente possa reutilizá-lo no envio.
O custo da resolução, para que um agente que opera com orçamento possa contabilizá-lo em vez de gastar às cegas.

Mantendo o loop sob controle

Dê ao agente um orçamento de resoluções por execução. Toda resposta informa o seu custo, então um supervisor pode cortar o loop quando o gasto passar de um limite, em vez de descobrir isso na fatura. A $0.00598 por resolução, uma execução típica de agente custa alguns centavos ou menos, mas um loop de novas tentativas sem limite continua sendo um loop sem limite.

Mantenha a chamada da ferramenta bloqueante

Os exemplos chamam ?wait=60, então a ferramenta retorna um token pronto em uma única etapa. Isso importa mais para agentes do que para scripts: uma ferramenta que retorna "ainda resolvendo" obriga o modelo a raciocinar sobre polling, algo que ele faz mal. Se você precisar de um teto maior, aumente wait para até 120 segundos. Os formatos de requisição de cada tipo de desafio estão na referência da API.

[ COMO SE ENCAIXA ]

Como a resolução se encaixa no LangChain

No LangChain, o solucionador é uma ferramenta com schema tipado. O agente a chama quando a ferramenta de navegador relata um desafio.

01
Defina a ferramenta
Envolva a chamada à API com o decorator @tool e uma docstring clara.
02
Vincule-a ao agente
Adicione-a à lista de ferramentas junto com suas ferramentas de navegador.
03
Descreva quando usá-la
A docstring orienta o modelo a chamá-la apenas quando houver um captcha.
04
Retorne um resultado claro
Retorne o token ou um erro curto com o qual o modelo possa agir.

Colocando o token na página

A ferramenta retorna o token como uma string que o agente passa para a ferramenta de navegador ou de HTTP.

[ ARMADILHAS ]

Onde as integrações costumam dar errado

Docstrings vagas

O modelo decide quando chamar uma ferramenta com base na descrição dela. Diga exatamente quais entradas ela precisa e o que ela retorna.

Retentativas sem limite

Limite as resoluções por execução para que um agente confuso não fique em loop numa página que continua apresentando desafios.

[ FAQ ]

Perguntas frequentes sobre captcha no LangChain

Funciona com o LangGraph?

Sim. Uma ferramenta do LangChain também é uma função que pode ser chamada por um nó no LangGraph, então a mesma definição funciona nos dois.

Qual modelo funciona melhor com a ferramenta?

Qualquer modelo com suporte a tool calling. As entradas da ferramenta são strings simples, então modelos menores lidam bem com ela.

Como o agente sabe que há um captcha?

A ferramenta de navegador ou de scraping deve informar isso, por exemplo retornando a sitekey quando encontrar uma. Inclua isso na saída da ferramenta.

Posso usar em um agente assíncrono?

Sim. Use um cliente HTTP assíncrono dentro da ferramenta e defina-a com async def.

[ LEIA A SEGUIR ]