Resolução de captcha para
agentes OpenAI Agents SDK
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 agents import Agent, function_tool
@function_tool
def solve_captcha(kind: str, sitekey: str, url: str) -> str:
"""Return a token for a captcha blocking the current page."""
return solve({"type": kind, "sitekey": sitekey, "url": url})["token"]
agent = Agent(name="browser", 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 OpenAI Agents SDK
O OpenAI Agents SDK transforma uma função Python tipada em ferramenta com function_tool. O solucionador vira uma das ferramentas do agente.
- 01Decore uma função
Envolva a chamada à API com @function_tool e argumentos tipados.
- 02Adicione-a ao agente
Passe-a na lista de ferramentas do agente.
- 03Instrua o agente
Diga a ele para chamar a ferramenta, com a sitekey e a URL, quando uma página mostrar um captcha.
- 04Rastreie
O tracing do SDK mostra cada chamada de ferramenta e seu resultado, incluindo o custo que retornamos.
Colocando o token na página
O agente recebe o token e o passa para a ferramenta de navegador ou de HTTP.
Onde as integrações costumam dar errado
Tipe todos os argumentos para que o schema gerado seja preciso e o modelo o preencha corretamente.
Defina o timeout HTTP acima do valor de wait para que a ferramenta não falhe enquanto a resolução ainda está em andamento.
Perguntas frequentes sobre captcha no OpenAI Agents SDK
Funciona com modelos que não sejam da OpenAI?
O SDK oferece suporte a outros provedores pela sua interface de modelos, e a ferramenta em si é HTTP simples, então sim.
Posso usar com handoffs?
Sim. Dê a ferramenta ao agente que controla o navegador; os outros podem fazer handoff para ele.
Onde a chave de API deve ficar?
Em uma variável de ambiente lida dentro da função da ferramenta, nunca nas instruções do agente.
Como limitar os gastos?
Acompanhe o campo cost de cada resultado no contexto da execução e recuse novas resoluções acima de um orçamento.
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.