Resolução de captcha para
agentes CrewAI
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.
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 crewai import Agent
from crewai.tools import tool
@tool("Solve captcha")
def solve_captcha(kind: str, sitekey: str, url: str) -> str:
"""Call when a captcha blocks the task. Returns the token to submit."""
return solve({"type": kind, "sitekey": sitekey, "url": url})["token"]
researcher = Agent(role="Researcher", goal="...", backstory="...", tools=[solve_captcha])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 a resolução se encaixa no CrewAI
No CrewAI, o solucionador é uma ferramenta personalizada atribuída ao agente que navega. Os outros agentes da crew nunca precisam saber de captchas.
- 01Crie uma subclasse de BaseTool
Defina name, description e um args schema, e chame a API em _run.
- 02Atribua a ferramenta
Dê a ferramenta apenas ao agente que faz a navegação.
- 03Descreva o gatilho
A descrição diz para usá-la quando uma página mostrar um captcha.
- 04Retorne o token
Retorne a string do token ou um erro curto.
Colocando o token na página
A ferramenta retorna o token ao agente navegador, que o envia com suas próprias ferramentas.
Onde as integrações costumam dar errado
Só o agente navegador precisa dela. Dá-la a todos convida chamadas desnecessárias.
Tokens são de uso único. Desative o cache de resultados de ferramentas do CrewAI para o solucionador.
Perguntas frequentes sobre captcha no CrewAI
O CrewAI tem uma ferramenta de captcha nativa?
Não para resolução. Uma ferramenta personalizada de poucas linhas resolve isso e mantém a chave sob o seu controle.
Vários agentes podem compartilhar uma chave?
Sim, ou crie uma chave por crew no painel para que o uso seja reportado separadamente.
Funciona com CrewAI Flows?
Sim. A ferramenta é chamada por um agente, onde quer que esse agente rode.
Por que desativar o cache?
Um resultado em cache retornaria um token antigo, que o site rejeita porque tokens são de uso único e expiram em cerca de dois minutos.
Guias que ajudam
Pronto para começar?
Comece com um teste grátis de 3 dias e depois pague por resolução bem-sucedida conforme seu tráfego cresce. Não é preciso cartão para o teste.