Como resolver reCAPTCHA no Kit de Desenvolvimento de Software (KDS) de Agentes da OpenAI

O SDK de Agentes da OpenAI fornece um framework pronto para produção para criar agentes de IA com capacidades de chamada de ferramentas. Quando esses agentes interagem com sites protegidos pelo reCAPTCHA, eles precisam de uma maneira de limpar os desafios de verificação de forma programática. O pacote capsolver-agent da CapSolver integra-se ao SDK de Agentes da OpenAI por meio do decorador @function_tool, permitindo que seu agente resolva desafios reCAPTCHA v2 e v3 como parte de seu fluxo de trabalho autônomo.

TL;DR

• O SDK de Agentes da OpenAI usa @function_tool para registrar ferramentas chamáveis — a CapSolver se encaixa nesse padrão de forma nativa
• A função execute_tool() do capsolver-agent encapsula a resolução em uma única chamada assíncrona compatível com o SDK
• Suporta reCAPTCHA v2 (caixa de seleção e invisível), reCAPTCHA v3 (baseado em pontuação) e variantes Enterprise
• O modo de token não requer navegador — apenas a chave do site e a URL
• O agente decide de forma autônoma quando invocar a resolução de CAPTCHA com base no contexto da tarefa

Por que os Agentes da OpenAI Precisam de Resolução de reCAPTCHA

O SDK de Agentes da OpenAI permite que os desenvolvedores criem agentes que executem tarefas de múltiplos passos usando ferramentas. Quando uma tarefa do agente envolve interação com a web — acesso a dados atrás de um login, submissão de formulários ou coleta de informações de páginas protegidas — os desafios reCAPTCHA bloqueiam o progresso. O agente pode raciocinar sobre o que fazer em seguida, mas, sem uma ferramenta de resolução, não pode gerar o token de verificação necessário para prosseguir.

O reCAPTCHA é particularmente comum nos sites que os agentes precisam acessar: portais de login, APIs de dados com limitação de taxa, bancos de dados governamentais e plataformas SaaS. A documentação do reCAPTCHA da Google indica que mais de 5 milhões de sites usam reCAPTCHA globalmente, tornando-o o desafio de verificação mais provável que seu agente encontrará.

A arquitetura da CapSolver se alinha perfeitamente ao design do SDK de Agentes da OpenAI: o agente decide o que fazer (incluindo quando resolver um CAPTCHA), e a CapSolver lida com a resolução por meio de seu serviço de IA. Essa separação de responsabilidades mantém a lógica do agente limpa enquanto adiciona a capacidade de limpar a verificação.

O que Você Precisa Antes de Começar

Instale os pacotes necessários:

# Motor principal da CapSolver
pip install git+https://github.com/capsolver-ai/capsolver-core.git

# Ferramentas do agente da CapSolver
pip install git+https://github.com/capsolver-ai/capsolver-agent.git

# SDK de Agentes da OpenAI
pip install openai-agents

Defina variáveis de ambiente:

export CAPSOLVER_API_KEY="sua-chave-da-capsolver"
export OPENAI_API_KEY="sua-chave-da-openai"

Você precisa de uma conta na CapSolver com créditos. O SDK atualmente suporta reCAPTCHA v2, reCAPTCHA v3 (incluindo Enterprise) e Cloudflare Turnstile — cobrindo os tipos de verificação que os agentes encontram com mais frequência.

Etapa 1 — Registrar a Resolução de CAPTCHA como uma Ferramenta de Função

O que Fazer

O SDK de Agentes da OpenAI usa @function_tool para definir ferramentas que o agente pode chamar. Envolva o executor da CapSolver nesse padrão:

from agents import Agent, Runner, function_tool
from capsolver_agent.schema import execute_tool

@function_tool
async def solve_recaptcha(
    website_url: str, 
    website_key: str, 
    captcha_type: str = "reCaptchaV2"
) -> str:
    """Resolva um desafio de reCAPTCHA em um site e retorne o token de verificação.
    
    Use esta ferramenta quando precisar passar por uma verificação de reCAPTCHA em uma página da web.
    
    Args:
        website_url: A URL completa da página que contém o reCAPTCHA
        website_key: A chave do site do reCAPTCHA (encontrada no atributo data-sitekey)
        captcha_type: Either 'reCaptchaV2' ou 'reCaptchaV3' (padrão: reCaptchaV2)
    
    Returns:
        O token do reCAPTCHA resolvido para enviar como g-recaptcha-response
    """
    result = await execute_tool("solve_captcha", {
        "captcha_type": captcha_type,
        "website_url": website_url,
        "website_key": website_key
    }, api_key="SUA_CHAVE_DA_CAPSOLVER")
    
    if result["success"]:
        return f"reCAPTCHA resolvido. Token: {result['solution']['token']}"
    return f"Resolução falhou: {result['error']}"

A função execute_tool() do capsolver-agent é uma chamada assíncrona única que lida com o ciclo completo de resolução — criando a tarefa, verificando os resultados e retornando uma saída estruturada. Foi especificamente projetada para cenários em que você quer uma única resolução sem construir o loop completo do executor.

Por Que Isso Importa

O decorador @function_tool do SDK de Agentes da OpenAI gera automaticamente o esquema JSON que o modelo precisa para entender os parâmetros da ferramenta. O agente vê a descrição da ferramenta, entende quando usá-la e a chama com os argumentos corretos — tudo por meio do mecanismo interno de chamada de funções do SDK.

Erros Comuns a Evitar

• Execução síncrona: O SDK de Agentes da OpenAI é assíncrono. Sempre use async def para funções de ferramentas e await para chamadas da CapSolver.
• Dicas de tipo ausentes: O SDK gera esquemas a partir das dicas de tipo. Inclua anotações de tipo apropriadas para todos os parâmetros.

Etapa 2 — Criar um Agente com Capacidade de Resolução de reCAPTCHA

O que Fazer

Crie um agente da OpenAI que inclua a ferramenta de resolução de reCAPTCHA:

from agents import Agent, Runner

# Crie um agente com capacidade de resolução de CAPTCHA
captcha_agent = Agent(
    name="Agente de Acesso Web",
    instructions="""Você é um agente de acesso web que ajuda os usuários a interagirem com 
    sites. Quando uma tarefa requer acesso a uma página protegida pelo reCAPTCHA, use a 
    ferramenta solve_recaptcha para obter um token de verificação. 
    
    Para reCAPTCHA v2: use captcha_type='reCaptchaV2'
    Para reCAPTCHA v3: use captcha_type='reCaptchaV3'
    
    Sempre forneça a website_url e website_key exatas da solicitação do usuário.""",
    tools=[solve_recaptcha]
)

# Execute o agente
async def main():
    result = await Runner.run(
        captcha_agent,
        "Preciso acessar https://example.com/login que tem um reCAPTCHA v2. "
        "A chave do site é 6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI. "
        "Por favor, resolva e me dê o token."
    )
    print(result.final_output)

import asyncio
asyncio.run(main())

O agente processa a solicitação, reconhece que a resolução de reCAPTCHA é necessária, chama a ferramenta com os parâmetros fornecidos e retorna o token para o usuário.

Por Que Isso Importa

O SDK de Agentes da OpenAI lida automaticamente com o loop de conversa, o despacho de ferramentas e a integração de resultados. Você define a ferramenta uma vez, e o runtime do SDK gerencia quando e como ela é chamada. Isso é mais simples do que construir manualmente um loop de chamada de função.

Etapa 3 — Tratar o reCAPTCHA v3 com Requisitos de Pontuação

O que Fazer

O reCAPTCHA v3 é baseado em pontuação e invisível — ele requer um parâmetro page_action e retorna um token com uma pontuação associada. Crie uma ferramenta especializada:

@function_tool
async def solve_recaptcha_v3(
    website_url: str,
    website_key: str,
    page_action: str = "verify",
    min_score: float = 0.7
) -> str:
    """Resolva um desafio de reCAPTCHA v3 (invisível, baseado em pontuação).
    
    Use isso quando o site usar reCAPTCHA v3 — não há caixa de seleção visível,
    mas o site valida um token com pontuação no fundo.
    
    Args:
        website_url: A URL completa da página
        website_key: A chave do site do reCAPTCHA v3
        page_action: O nome da ação para pontuação (ex.: 'login', 'submit', 'verify')
        min_score: Pontuação mínima aceitável (0,0-1,0, padrão 0,7)
    """
    result = await execute_tool("solve_captcha", {
        "captcha_type": "reCaptchaV3",
        "website_url": website_url,
        "website_key": website_key,
        "page_action": page_action,
        "min_score": min_score
    }, api_key="SUA_CHAVE_DA_CAPSOLVER")
    
    if result["success"]:
        return f"reCAPTCHA v3 resolvido com alta pontuação. Token: {result['solution']['token']}"
    return f"Resolução falhou: {result['error']}"

O guia de resolução do reCAPTCHA v3 explica como identificar o parâmetro page_action correto para diferentes sites. Ações comuns incluem login, submit, homepage e verify.

Etapa 4 — Construir um Agente Multiferramenta para Fluxos de Trabalho Web Completos

O que Fazer

Combine a resolução de reCAPTCHA com outras ferramentas para agentes que realizem tarefas completas na web:

from agents import Agent, Runner, function_tool

@function_tool
async def solve_recaptcha(website_url: str, website_key: str, captcha_type: str = "reCaptchaV2") -> str:
    """Resolva o reCAPTCHA e retorne o token."""
    result = await execute_tool("solve_captcha", {
        "captcha_type": captcha_type,
        "website_url": website_url,
        "website_key": website_key
    }, api_key="SUA_CHAVE_DA_CAPSOLVER")
    if result["success"]:
        return f"Token: {result['solution']['token']}"
    return f"Falha: {result['error']}"

@function_tool
async def check_solver_balance() -> str:
    """Verifique os créditos restantes para resolução de CAPTCHA."""
    result = await execute_tool("get_balance", {}, api_key="SUA_CHAVE_DA_CAPSOLVER")
    if result["success"]:
        return f"Saldo: ${result['balance']:.2f}"
    return "Não foi possível verificar o saldo"

# Agente com múltiplas capacidades
web_agent = Agent(
    name="Agente Web Autônomo",
    instructions="""Você ajuda os usuários a acessar recursos da web que podem estar protegidos por 
    reCAPTCHA. Você pode resolver tanto o reCAPTCHA v2 (caixa de seleção visível) quanto o v3 (invisível 
    baseado em pontuação). Sempre verifique o saldo antes de resolver se o usuário perguntar sobre custos.
    
    Ao resolver o reCAPTCHA:
    - v2: Use captcha_type='reCaptchaV2' 
    - v3: Use captcha_type='reCaptchaV3' e inclua page_action se conhecido
    
    Retorne o token claramente para que o usuário possa enviá-lo com seu formulário.""",
    tools=[solve_recaptcha, check_solver_balance]
)

async def run_web_agent(task: str):
    result = await Runner.run(web_agent, task)
    return result.final_output

Esse padrão funciona para agentes que precisam lidar com várias versões do reCAPTCHA em diferentes sites dentro de uma única sessão.

Claim Your Bonus Code: Use o código WEBS no Painel da CapSolver para obter um bônus adicional de 5% em cada recarga. Ideal para desenvolvedores que constroem Agentes da OpenAI com capacidades de acesso à web.

Etapa 5 — Considerações para Implantação em Produção

Para agentes da OpenAI em produção com resolução de reCAPTCHA:

import os
from agents import Agent, Runner, function_tool
from capsolver_agent.schema import create_executor

# Executor de produção com configurações personalizadas
executor = create_executor(
    api_key=os.environ["CAPSOLVER_API_KEY"],
    default_timeout=90,      # 90 segundos de timeout
    polling_interval=3       # Verifique a cada 3 segundos
)

@function_tool
async def solve_recaptcha_production(
    website_url: str,
    website_key: str,
    captcha_type: str = "reCaptchaV2"
) -> str:
    """Resolvedor de reCAPTCHA de produção com lógica de tentativas."""
    for attempt in range(3):
        result = await executor.execute("solve_captcha", {
            "captcha_type": captcha_type,
            "website_url": website_url,
            "website_key": website_key
        })
        if result["success"]:
            return f"Resolvido (tentativa {attempt+1}). Token: {result['solution']['token']}"
        if attempt < 2:
            await asyncio.sleep(2)
    return f"Falha após 3 tentativas: {result.get('error')}"

Principais considerações para produção:

• Configuração de timeout: Defina default_timeout com base nas exigências de tempo de resposta do seu agente
• Lógica de tentativas: Problemas de rede e falhas temporárias devem acionar tentativas, não falhas imediatas
• Monitoramento de saldo: Verifique o saldo periodicamente para evitar falhas durante a tarefa devido a créditos insuficientes
• Relatório de erros: Retorne mensagens de erro claras para que o agente possa raciocinar sobre alternativas

A documentação da API da CapSolver aborda opções adicionais de configuração para otimizar os tempos de resolução em ambientes de produção. Para identificar os parâmetros do reCAPTCHA nos sites alvo, a extensão do navegador da CapSolver fornece detecção automática.

Conclusão

Integrar a resolução de reCAPTCHA ao SDK de Agentes da OpenAI requer definir um @function_tool que envolva a função execute_tool() da CapSolver, depois atribuí-lo ao seu agente. O runtime do SDK lida automaticamente com o despacho de ferramentas — o agente decide quando a resolução de reCAPTCHA é necessária e chama a ferramenta com parâmetros apropriados. CapSolver fornece a infraestrutura de resolução baseada em IA que gera tokens válidos para reCAPTCHA v2, v3 e variantes Enterprise.

Comece com uma única ferramenta solve_recaptcha, teste-a com seu agente em um alvo conhecido e depois adicione suporte para v3 e lógica de tentativas em produção. A arquitetura assíncrona do SDK de Agentes da OpenAI se alinha naturalmente com a API assíncrona da CapSolver, tornando a integração limpa e eficiente.

Perguntas Frequentes

O SDK de Agentes da OpenAI suporta resolução de CAPTCHA assíncrona?

Sim. O SDK é totalmente assíncrono e a função execute_tool() da CapSolver é assíncrona. O decorador @function_tool suporta funções async def de forma nativa, então a resolução de CAPTCHA roda sem bloquear o loop de eventos do agente.

O agente pode resolver o reCAPTCHA Enterprise com esta integração?

Sim. Passe enterprise: true nos parâmetros. O reCAPTCHA Enterprise usa os mesmos tipos de tarefa v2/v3, mas pode exigir o parâmetro s token. A CapSolver lida com variantes Enterprise de forma transparente por meio da mesma API.

Como o agente sabe qual versão do reCAPTCHA um site usa?

Inclua orientações nas instruções do agente sobre como identificar v2 vs v3. Alternativamente, forneça o tipo de CAPTCHA na solicitação da tarefa. O guia de identificação do reCAPTCHA explica as diferenças: o v2 mostra um widget visível, enquanto o v3 carrega invisivelmente via tag de script.

Qual é o custo por resolução de reCAPTCHA?

O reCAPTCHA v2 custa aproximadamente $2-3 por 1.000 resoluções, e o reCAPTCHA v3 custa $1-2 por 1.000. Para um agente que resolve 10 CAPTCHAs por sessão, o custo é aproximadamente $0,02-0,03 por sessão — insignificante em comparação ao valor da conclusão de tarefas autônomas.

Posso usar isso com a funcionalidade de handoff do SDK de Agentes da OpenAI?

Sim. Você pode criar um "agente solucionador de CAPTCHA" especializado e transferi-lo quando o agente principal encontrar um desafio de verificação. O agente solucionador resolve o CAPTCHA e devolve ao agente principal com o token. Isso mantém as responsabilidades dos agentes separadas de forma limpa.