Como resolver reCAPTCHA v3 no OpenAI Agents SDK

O reCAPTCHA v3 opera de forma invisível — sem caixa de seleção, sem grade de imagens — classificando as interações do usuário em segundo plano. Quando os agentes do OpenAI Agents SDK acessam APIs e páginas protegidas pelo reCAPTCHA v3, recebem pontuações baixas que acionam bloqueios ou desafios secundários. O CapSolver gera tokens de reCAPTCHA v3 com alta pontuação (0,7-0,9) por meio de seu serviço de inteligência artificial, integrando-se ao OpenAI Agents SDK via @function_tool, permitindo que seu agente supere a verificação invisível sem interação visível.

TL;DR

• O reCAPTCHA v3 é invisível e baseado em pontuação — os agentes falham silenciosamente quando sua pontuação é muito baixa
• O CapSolver gera tokens com alta pontuação (0,7-0,9) em 3-8 segundos via o tipo de tarefa reCaptchaV3
• Requer os parâmetros website_url, website_key e page_action (nome da ação como "login" ou "submit")
• A integração usa o @function_tool do OpenAI Agents SDK com o execute_tool() assíncrono do CapSolver
• Nenhum navegador é necessário — o modo de token funciona para todas as implementações do reCAPTCHA v3

Por que o reCAPTCHA v3 é diferente do v2

O reCAPTCHA v3 nunca exibe um desafio visível. Em vez disso, executa JavaScript em segundo plano que classifica a sessão do usuário de 0,0 (provavelmente robô) a 1,0 (provavelmente humano). O proprietário do site define um limiar — geralmente 0,5-0,7 — e bloqueia ou desafia solicitações abaixo desse limiar.

Para os agentes do OpenAI, isso cria um modo de falha silenciosa. O agente não vê um widget de CAPTCHA para resolver. Em vez disso, as chamadas à API retornam erros 403, submissões de formulário falham silenciosamente ou o site redireciona para uma página de erro. Sem entender que o reCAPTCHA v3 está bloqueando-os, os agentes não conseguem se recuperar.

Documentação do reCAPTCHA v3 da Google explica que a pontuação é baseada em "interações com seu site" — navegadores automatizados sem movimento do mouse, sem comportamento de rolagem e navegação rápida pontuam consistentemente abaixo de 0,3, acionando bloqueios.

O CapSolver resolve isso gerando tokens com pontuações de 0,7-0,9, que passam virtualmente todos os limiares de site. O agente envia esse token com sua solicitação e o site o aceita como uma interação humana de alta confiança.

O que você precisa antes de começar

pip install git+https://github.com/capsolver-ai/capsolver-core.git
pip install git+https://github.com/capsolver-ai/capsolver-agent.git
pip install openai-agents

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

Você precisa identificar a page_action do reCAPTCHA v3 para o site alvo. Ações comuns: login, submit, homepage, register, checkout. Encontre-a pesquisando o código-fonte da página por grecaptcha.execute(sitekey, {action: '...'}).

Etapa 1 — Registrar a resolução do reCAPTCHA v3 como uma ferramenta de função

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

@function_tool
async def solve_recaptcha_v3(
    website_url: str,
    website_key: str,
    page_action: str = "verify",
    min_score: float = 0.7
) -> str:
    """Resolver um desafio de reCAPTCHA v3 invisível e retornar um token com alta pontuação.
    
    Use isso quando um site usar reCAPTCHA v3 (invisível, baseado em pontuação).
    O token deve ser enviado como 'g-recaptcha-response' com sua solicitação.
    
    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 (ex: 'login', 'submit', 'verify')
        min_score: Pontuação mínima aceitável (padrão 0,7, intervalo 0,1-0,9)
    """
    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_API_DO_CAPSOLVER")
    
    if result["success"]:
        return f"reCAPTCHA v3 resolvido (pontuação ≥{min_score}). Token: {result['solution']['token']}"
    return f"Falha: {result['error']}"

Etapa 2 — Construir o agente

v3_agent = Agent(
    name="Agente de Acesso a API",
    instructions="""Você acessa APIs e páginas protegidas pelo reCAPTCHA v3 (invisível).
    
    Sinais de que uma página usa v3:
    - Tag script: <script src="...recaptcha/api.js?render=SITE_KEY">
    - Nenhum widget de CAPTCHA visível na página
    - API retorna 403 ou falha silenciosamente
    
    Quando você precisar de um token v3:
    1. Identifique a chave do site a partir do parâmetro render do script
    2. Identifique a page_action a partir das chamadas grecaptcha.execute
    3. Chame solve_recaptcha_v3 com esses parâmetros
    4. Envie o token como g-recaptcha-response com sua solicitação""",
    tools=[solve_recaptcha_v3]
)

async def main():
    result = await Runner.run(
        v3_agent,
        "Acesse a API em https://example.com/api/data. Ela usa reCAPTCHA v3 "
        "com chave do site 6LdKlZEpAAAAAN... e ação 'getData'. Me forneça um token válido."
    )
    print(result.final_output)

import asyncio
asyncio.run(main())

Etapa 3 — Identificar os parâmetros do reCAPTCHA v3

Os parâmetros do reCAPTCHA v3 são encontrados no JavaScript da página:

// Chave do site na tag script
<script src="https://www.google.com/recaptcha/api.js?render=6LdKlZEpAAAAAN..."></script>

// Ação na chamada execute
grecaptcha.execute('6LdKlZEpAAAAAN...', {action: 'submit'}).then(function(token) {
    document.getElementById('g-recaptcha-response').value = token;
});

O guia de identificação do reCAPTCHA v3 explica como extrair esses valores. A extensão do CapSolver detecta automaticamente os parâmetros v3 em qualquer página.

Claim Your Bonus Code: Use o código WEBS no Painel do CapSolver para obter um bônus adicional de 5% em cada recarga.

Conclusão

Resolver o reCAPTCHA v3 no OpenAI Agents SDK requer identificar a chave do site e a ação, depois chamar o tipo de tarefa reCaptchaV3 do CapSolver através do @function_tool. Ao contrário do v2, não há widget visível — o agente deve reconhecer falhas silenciosas e gerar ativamente tokens com alta pontuação. CapSolver gera tokens com pontuação de 0,7-0,9 em 3-8 segundos, eliminando a verificação invisível sem nenhuma interação com o navegador.

Perguntas Frequentes

Qual pontuação o CapSolver gera para o reCAPTCHA v3?

O CapSolver gera tokens com pontuações de 0,7-0,9, que passam virtualmente todos os limiares de site. A maioria dos sites define seu limiar em 0,5-0,7, então os tokens do CapSolver passam consistentemente na verificação.

Preciso de um navegador para resolver o reCAPTCHA v3?

Não. O modo de token funciona sem nenhum navegador. Forneça a chave do site, a URL e a ação — receba um token de volta. Isso torna a resolução do v3 mais rápida e simples do que a do v2 na maioria dos casos.

O que fazer se eu não souber a page_action?

Tente ações comuns: verify, submit, login, homepage. Se nenhuma funcionar, inspecione o código-fonte da página para encontrar chamadas a grecaptcha.execute. O parâmetro de ação sempre está visível no JavaScript do lado do cliente.

O reCAPTCHA v3 Enterprise é diferente?

Sim. O v3 Enterprise pode exigir a bandeira enterprise: true e potencialmente um token s. O CapSolver lida com variantes Enterprise — adicione enterprise: true aos seus parâmetros se o método padrão falhar.