Cómo resolver reCAPTCHA v3 en OpenAI Agents SDK

reCAPTCHA v3 funciona de forma invisible: no hay casilla de verificación, ni cuadrícula de imágenes, sino que puntúa las interacciones del usuario en segundo plano. Cuando los agentes de OpenAI Agents SDK acceden a APIs y páginas protegidas por v3, reciben puntuaciones bajas que desencadenan bloques o desafíos secundarios. CapSolver genera tokens de reCAPTCHA v3 con altas puntuaciones (0.7-0.9) mediante su servicio de inteligencia artificial, integrándose con el OpenAI Agents SDK a través de @function_tool para que su agente supere la verificación invisible sin ninguna interacción visible.

TL;DR

• reCAPTCHA v3 es invisible y basado en puntuación: los agentes fallan silenciosamente cuando su puntuación es demasiado baja
• CapSolver genera tokens con altas puntuaciones (0.7-0.9) en 3-8 segundos mediante el tipo de tarea reCaptchaV3
• Requiere los parámetros website_url, website_key y page_action (nombre de acción como "inicio de sesión" o "enviar")
• La integración utiliza @function_tool de OpenAI Agents SDK con execute_tool asíncrono de CapSolver
• No se necesita navegador: el modo token funciona para todas las implementaciones de reCAPTCHA v3

¿Por qué reCAPTCHA v3 es diferente de v2?

reCAPTCHA v3 nunca muestra un desafío visible. En su lugar, ejecuta JavaScript en segundo plano que puntúa la sesión del usuario de 0.0 (probablemente un robot) a 1.0 (probablemente humano). El propietario del sitio establece un umbral, generalmente entre 0.5 y 0.7, y bloquea o desafía las solicitudes por debajo de ese umbral.

Para los agentes de OpenAI, esto crea un modo de fallo silencioso. El agente no ve un widget CAPTCHA para resolver. En su lugar, las llamadas a la API devuelven errores 403, los envíos de formularios fallan silenciosamente o el sitio redirige a una página de error. Sin entender que reCAPTCHA v3 los está bloqueando, los agentes no pueden recuperarse.

Documentación de reCAPTCHA v3 de Google explica que la puntuación se basa en "interacciones con su sitio": navegadores automatizados sin movimiento del mouse, sin comportamiento de desplazamiento y con navegación rápida puntúan por debajo de 0.3, desencadenando bloques.

CapSolver resuelve esto generando tokens con puntuaciones de 0.7 a 0.9, que pasan virtualmente todos los umbrales de los sitios. El agente envía este token con su solicitud, y el sitio lo acepta como una interacción de humano de alta confianza.

Lo que necesitas antes de comenzar

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="tu-clave-de-api-de-capsolver"
export OPENAI_API_KEY="tu-clave-de-api-de-openai"

Debes identificar la page_action de reCAPTCHA v3 para tu sitio objetivo. Acciones comunes: inicio de sesión, enviar, página de inicio, registro, pago. Búscalo en el código fuente de la página buscando grecaptcha.execute(sitekey, {action: '...'}).

Paso 1 — Registrar la resolución de reCAPTCHA v3 como una herramienta de función

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 = "verificar",
    min_score: float = 0.7
) -> str:
    """Resolver un desafío reCAPTCHA v3 invisible y devolver un token con alta puntuación.
    
    Úselo cuando un sitio utilice reCAPTCHA v3 (invisible, basado en puntuación).
    El token debe enviarse como 'g-recaptcha-response' con su solicitud.
    
    Args:
        website_url: La URL completa de la página
        website_key: La clave de sitio de reCAPTCHA v3
        page_action: El nombre de la acción (ej.: 'inicio de sesión', 'enviar', 'verificar')
        min_score: Puntuación aceptable mínima (por defecto 0.7, rango 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="TU_CLAVE_DE_API_DE_CAPSOLVER")
    
    if result["success"]:
        return f"reCAPTCHA v3 resuelto (puntuación ≥{min_score}). Token: {result['solution']['token']}"
    return f"Fallo: {result['error']}"

Paso 2 — Crear al agente

v3_agent = Agent(
    name="Agente de Acceso a API",
    instructions="""Usted accede a APIs y páginas protegidas por reCAPTCHA v3 (invisible).
    
    Cómo identificar una página que usa v3:
    - Etiqueta de script: <script src="...recaptcha/api.js?render=SITE_KEY">
    - No hay widget CAPTCHA visible en la página
    - La API devuelve 403 o falla silenciosamente
    
    Cuando necesite un token v3:
    1. Identifique la clave del sitio desde el parámetro render del script
    2. Identifique la page_action desde las llamadas a grecaptcha.execute
    3. Llame a solve_recaptcha_v3 con estos parámetros
    4. Envíe el token como g-recaptcha-response con su solicitud""",
    tools=[solve_recaptcha_v3]
)

async def main():
    result = await Runner.run(
        v3_agent,
        "Acceda a la API en https://example.com/api/data. Utiliza reCAPTCHA v3 "
        "con clave de sitio 6LdKlZEpAAAAAN... y acción 'getData'. Obtenga un token válido."
    )
    print(result.final_output)

import asyncio
asyncio.run(main())

Paso 3 — Identificar los parámetros de reCAPTCHA v3

Los parámetros de reCAPTCHA v3 se encuentran en el JavaScript de la página:

// Clave del sitio en la etiqueta de script
<script src="https://www.google.com/recaptcha/api.js?render=6LdKlZEpAAAAAN..."></script>

// Acción en la llamada execute
grecaptcha.execute('6LdKlZEpAAAAAN...', {action: 'enviar'}).then(function(token) {
    document.getElementById('g-recaptcha-response').value = token;
});

La guía de identificación de reCAPTCHA v3 explica cómo extraer estos valores. La extensión de CapSolver detecta automáticamente los parámetros v3 en cualquier página.

¡Obtén tu código de bonificación: Utilice el código WEBS en Dashboard de CapSolver para obtener un 5% adicional de bonificación en cada recarga.

Conclusión

Resolver reCAPTCHA v3 en OpenAI Agents SDK requiere identificar la clave del sitio y la acción, y luego llamar al tipo de tarea reCaptchaV3 de CapSolver a través de @function_tool. A diferencia de v2, no hay widget visible: el agente debe reconocer fallos silenciosos y generar proactivamente tokens con altas puntuaciones. CapSolver genera tokens con puntuaciones de 0.7-0.9 en 3-8 segundos, superando la verificación invisible sin ninguna interacción del navegador.

Preguntas frecuentes

¿Qué puntuación genera CapSolver para reCAPTCHA v3?

CapSolver genera tokens con puntuaciones de 0.7 a 0.9, que pasan virtualmente todos los umbrales de los sitios. La mayoría de los sitios establecen su umbral en 0.5-0.7, por lo que los tokens de CapSolver superan consistentemente la verificación.

¿Necesito un navegador para resolver reCAPTCHA v3?

No. El modo token funciona sin ningún navegador. Proporcione la clave del sitio, la URL y la acción: reciba un token de vuelta. Esto hace que resolver v3 sea más rápido y sencillo que v2 en la mayoría de los casos.

¿Qué pasa si no conozco la page_action?

Pruebe acciones comunes: verificar, enviar, inicio de sesión, página de inicio. Si ninguna funciona, inspeccione el código fuente de la página para encontrar llamadas a grecaptcha.execute. El parámetro de acción siempre es visible en JavaScript del lado del cliente.

¿Es diferente reCAPTCHA v3 Enterprise?

Sí. v3 Enterprise puede requerir la bandera enterprise: true y potencialmente un token s. CapSolver maneja variantes Enterprise: agregue enterprise: true a sus parámetros si el enfoque estándar falla.