Cómo resolver reCAPTCHA en el SDK de Agentes de OpenAI

El SDK de Agentes de OpenAI proporciona un marco listo para producción para construir agentes de IA con capacidades de llamada a herramientas. Cuando estos agentes interactúan con sitios web protegidos por reCAPTCHA, necesitan una forma de resolver desafíos de verificación de manera programática. El paquete capsolver-agent de CapSolver se integra con el SDK de Agentes de OpenAI a través del decorador @function_tool, permitiendo que su agente resuelva desafíos de reCAPTCHA v2 y v3 como parte de su flujo de trabajo autónomo.

TL;DR

• El SDK de Agentes de OpenAI utiliza @function_tool para registrar herramientas llamables: CapSolver se adapta a este patrón de forma nativa
• La función execute_tool() de capsolver-agent encapsula la resolución en una sola llamada asíncrona compatible con el SDK
• Soporta reCAPTCHA v2 (casilla de verificación e invisible), reCAPTCHA v3 (basado en puntuación) y variantes de Enterprise
• El modo de token no requiere navegador: solo la clave del sitio y la URL
• El agente decide de forma autónoma cuándo invocar la resolución de CAPTCHA según el contexto de la tarea

¿Por qué los Agentes de OpenAI necesitan resolver reCAPTCHA?

El SDK de Agentes de OpenAI permite a los desarrolladores construir agentes que ejecutan tareas de múltiples pasos utilizando herramientas. Cuando una tarea del agente implica interacción con la web - acceder a datos detrás de un inicio de sesión, enviar formularios o recopilar información de páginas protegidas - los desafíos de reCAPTCHA bloquean el progreso. El agente puede razonar sobre qué hacer a continuación, pero sin una herramienta de resolución, no puede generar el token de verificación necesario para continuar.

reCAPTCHA es particularmente común en los sitios que los agentes necesitan acceder: portales de inicio de sesión, APIs de datos con límites de velocidad, bases de datos gubernamentales y plataformas SaaS. La documentación de reCAPTCHA de Google indica que más de 5 millones de sitios utilizan reCAPTCHA a nivel mundial, lo que lo hace el desafío de verificación más probable que encuentre su agente.

La arquitectura de CapSolver se alinea perfectamente con el diseño del SDK de Agentes de OpenAI: el agente decide qué hacer (incluyendo cuándo resolver un CAPTCHA), y CapSolver se encarga de resolverlo a través de su servicio de IA. Esta separación de responsabilidades mantiene la lógica de su agente limpia mientras agrega la capacidad de eliminar la verificación.

Lo que necesita antes de comenzar

Instalar paquetes requeridos:

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

# Herramientas de agente de CapSolver
pip install git+https://github.com/capsolver-ai/capsolver-agent.git

# SDK de Agentes de OpenAI
pip install openai-agents

Establecer variables de entorno:

export CAPSOLVER_API_KEY="su-clave-de-api-de-capsolver"
export OPENAI_API_KEY="su-clave-de-api-de-openai"

Necesita una cuenta de CapSolver con créditos. El SDK actualmente soporta reCAPTCHA v2, reCAPTCHA v3 (incluyendo Enterprise) y Cloudflare Turnstile - cubriendo los tipos de verificación que los agentes encuentran con más frecuencia.

Paso 1 - Registrar la resolución de CAPTCHA como una herramienta de función

Qué hacer

El SDK de Agentes de OpenAI utiliza @function_tool para definir herramientas que el agente puede llamar. Envuelva el ejecutor de CapSolver en este patrón:

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:
    """Resolver un desafío de reCAPTCHA en un sitio web y devolver el token de verificación.
    
    Use esta herramienta cuando necesite pasar un desafío de verificación de reCAPTCHA en una página web.
    
    Args:
        website_url: La URL completa de la página que contiene la reCAPTCHA
        website_key: La clave de sitio de reCAPTCHA (encontrada en el atributo data-sitekey)
        captcha_type: Ya sea 'reCaptchaV2' o 'reCaptchaV3' (por defecto: reCaptchaV2)
    
    Returns:
        El token de reCAPTCHA resuelto 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="SU_CLAVE_DE_API_DE_CAPSOLVER")
    
    if result["success"]:
        return f"reCAPTCHA resuelta. Token: {result['solution']['token']}"
    return f"Falló la resolución: {result['error']}"

La función execute_tool() de capsolver-agent es una llamada asíncrona única que maneja el ciclo completo de resolución - crear la tarea, sondear resultados y devolver una salida estructurada. Está específicamente diseñada para escenarios donde quiere una resolución única sin construir el bucle completo del ejecutor.

Por qué esto importa

El decorador @function_tool del SDK de Agentes de OpenAI genera automáticamente el esquema JSON que el modelo necesita para entender los parámetros de la herramienta. El agente ve la descripción de la herramienta, entiende cuándo usarla y la llama con los argumentos correctos - todo a través del mecanismo integrado de llamada a funciones del SDK.

Errores comunes a evitar

• Ejecución sincrónica: El SDK de Agentes de OpenAI es asíncrono. Siempre use async def para funciones de herramientas y await para llamadas a CapSolver.
• Falta de anotaciones de tipo: El SDK genera esquemas a partir de anotaciones de tipo. Incluya anotaciones de tipo adecuadas para todos los parámetros.

Paso 2 - Crear un Agente con capacidad de resolución de reCAPTCHA

Qué hacer

Construya un agente de OpenAI que incluya la herramienta de resolución de reCAPTCHA:

from agents import Agent, Runner

# Crear agente con capacidad de resolución de CAPTCHA
captcha_agent = Agent(
    name="Agente de Acceso Web",
    instructions="""Usted es un agente de acceso web que ayuda a los usuarios a interactuar con 
    sitios web. Cuando una tarea requiere acceder a una página protegida por reCAPTCHA, use la 
    herramienta solve_recaptcha para obtener un token de verificación. 
    
    Para reCAPTCHA v2: use captcha_type='reCaptchaV2'
    Para reCAPTCHA v3: use captcha_type='reCaptchaV3'
    
    Siempre proporcione la website_url y website_key exactas de la solicitud del usuario.""",
    tools=[solve_recaptcha]
)

# Ejecutar el agente
async def main():
    result = await Runner.run(
        captcha_agent,
        "Necesito acceder a https://example.com/login que tiene un reCAPTCHA v2. "
        "La clave del sitio es 6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI. "
        "Por favor resuélvalo y dígame el token."
    )
    print(result.final_output)

import asyncio
asyncio.run(main())

El agente procesa la solicitud, reconoce que se necesita resolver reCAPTCHA, llama a la herramienta con los parámetros proporcionados y devuelve el token al usuario.

Por qué esto importa

El SDK de Agentes de OpenAI maneja el bucle de conversación, la asignación de herramientas y la integración de resultados automáticamente. Define la herramienta una vez, y el entorno de ejecución del SDK maneja cuándo y cómo se llama. Esto es más sencillo que construir manualmente un bucle de llamada a funciones.

Paso 3 - Manejar reCAPTCHA v3 con requisitos de puntuación

Qué hacer

reCAPTCHA v3 es basado en puntuación e invisible - requiere un parámetro page_action y devuelve un token con una puntuación asociada. Cree una herramienta especializada:

@function_tool
async def solve_recaptcha_v3(
    website_url: str,
    website_key: str,
    page_action: str = "verify",
    min_score: float = 0.7
) -> str:
    """Resolver un desafío de reCAPTCHA v3 (invisible, basado en puntuación).
    
    Use esto cuando el sitio utilice reCAPTCHA v3 - no hay casilla de verificación visible,
    pero el sitio valida un token basado en puntuación en segundo plano.
    
    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 para la puntuación (ej.: 'login', 'submit', 'verify')
        min_score: Puntuación mínima aceptable (0.0-1.0, por defecto 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="SU_CLAVE_DE_API_DE_CAPSOLVER")
    
    if result["success"]:
        return f"reCAPTCHA v3 resuelta con alta puntuación. Token: {result['solution']['token']}"
    return f"Falló la resolución: {result['error']}"

La guía de resolución de reCAPTCHA v3 explica cómo identificar el parámetro page_action correcto para diferentes sitios. Acciones comunes incluyen login, submit, homepage y verify.

Paso 4 - Construir un agente de múltiples herramientas para flujos completos de web

Qué hacer

Combine la resolución de reCAPTCHA con otras herramientas para agentes que realicen tareas completas en la 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:
    """Resolver reCAPTCHA y devolver el token."""
    result = await execute_tool("solve_captcha", {
        "captcha_type": captcha_type,
        "website_url": website_url,
        "website_key": website_key
    }, api_key="SU_CLAVE_DE_API_DE_CAPSOLVER")
    if result["success"]:
        return f"Token: {result['solution']['token']}"
    return f"Falló: {result['error']}"

@function_tool
async def check_solver_balance() -> str:
    """Verificar los créditos restantes para resolver CAPTCHA."""
    result = await execute_tool("get_balance", {}, api_key="SU_CLAVE_DE_API_DE_CAPSOLVER")
    if result["success"]:
        return f"Saldo: ${result['balance']:.2f}"
    return "No se pudo verificar el saldo"

# Agente con múltiples capacidades
web_agent = Agent(
    name="Agente Web Autónomo",
    instructions="""Ayuda a los usuarios a acceder a recursos web que pueden estar protegidos por 
    reCAPTCHA. Puede resolver tanto reCAPTCHA v2 (casilla de verificación visible) como v3 (invisible 
    basado en puntuación). Siempre verifique el saldo antes de resolver si el usuario pregunta sobre costos.
    
    Al resolver reCAPTCHA:
    - v2: Use captcha_type='reCaptchaV2' 
    - v3: Use captcha_type='reCaptchaV3' e incluya page_action si se conoce
    
    Devuelva el token claramente para que el usuario pueda enviarlo con su formulario.""",
    tools=[solve_recaptcha, check_solver_balance]
)

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

Este patrón funciona para agentes que necesitan manejar múltiples versiones de reCAPTCHA en diferentes sitios dentro de una sola sesión.

Obtenga su código de bonificación: Use el código WEBS en Panel de CapSolver para obtener un 5% adicional en cada recarga. Ideal para desarrolladores que construyen Agentes de OpenAI con capacidades de acceso web.

Paso 5 - Consideraciones para implementación en producción

Para agentes de OpenAI en producción con resolución de reCAPTCHA:

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

# Ejecutor de producción con configuraciones personalizadas
executor = create_executor(
    api_key=os.environ["CAPSOLVER_API_KEY"],
    default_timeout=90,      # 90 segundos de tiempo de espera
    polling_interval=3       # Sondeo cada 3 segundos
)

@function_tool
async def solve_recaptcha_production(
    website_url: str,
    website_key: str,
    captcha_type: str = "reCaptchaV2"
) -> str:
    """Resolver reCAPTCHA de grado de producción con lógica de reintentos."""
    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"Resuelto (intentos {attempt+1}). Token: {result['solution']['token']}"
        if attempt < 2:
            await asyncio.sleep(2)
    return f"Falló después de 3 intentos: {result.get('error')}"

Consideraciones clave para producción:

• Configuración de tiempo de espera: Establezca default_timeout según los requisitos de tiempo de respuesta de su agente
• Lógica de reintentos: Los errores de red y fallos temporales deben activar reintentos, no fallos inmediatos
• Monitoreo de saldo: Verifique el saldo periódicamente para evitar fallos en medio de una tarea por falta de créditos
• Informes de errores: Devuelva mensajes de error claros para que el agente pueda razonar sobre enfoques alternativos

La documentación de la API de CapSolver cubre opciones adicionales de configuración para optimizar los tiempos de resolución en entornos de producción. Para identificar los parámetros de reCAPTCHA en sitios objetivo, la extensión del navegador de CapSolver proporciona detección automática.

Conclusión

Integrar la resolución de reCAPTCHA en el SDK de Agentes de OpenAI requiere definir un @function_tool que envuelva la función execute_tool() de CapSolver, y luego asignarla a su agente. El entorno de ejecución del SDK maneja automáticamente la asignación de herramientas - el agente decide cuándo se necesita resolver reCAPTCHA y llama a la herramienta con los parámetros adecuados. CapSolver proporciona la infraestructura de resolución impulsada por IA que genera tokens válidos para reCAPTCHA v2, v3 y variantes Enterprise.

Comience con una herramienta solve_recaptcha, pruébela con su agente en un objetivo conocido, luego agregue soporte para v3 y lógica de reintentos en producción. La arquitectura asíncrona del SDK de Agentes de OpenAI se alinea naturalmente con la API asíncrona de CapSolver, haciendo la integración limpia y eficiente.

Preguntas frecuentes

¿Soporta el SDK de Agentes de OpenAI la resolución de CAPTCHA asíncrona?

Sí. El SDK es completamente asíncrono, y execute_tool() de CapSolver es una función asíncrona. El decorador @function_tool admite funciones async def de forma nativa, por lo que la resolución de CAPTCHA se ejecuta sin bloquear el bucle de eventos del agente.

¿Puede el agente resolver reCAPTCHA Enterprise con esta integración?

Sí. Pase enterprise: true en los parámetros. reCAPTCHA Enterprise utiliza los mismos tipos de tarea v2/v3, pero puede requerir el parámetro s token. CapSolver maneja las variantes Enterprise de forma transparente a través de la misma API.

¿Cómo sabe el agente qué versión de reCAPTCHA utiliza un sitio?

Incluya guías en las instrucciones del agente sobre cómo identificar v2 vs v3. Alternativamente, proporcione el tipo de CAPTCHA en el prompt de la tarea. La guía de identificación de reCAPTCHA explica las diferencias: v2 muestra un widget visible, mientras que v3 se carga de forma invisible a través de una etiqueta de script.

¿Cuál es el costo por resolución de reCAPTCHA?

reCAPTCHA v2 cuesta aproximadamente $2-3 por 1,000 resoluciones, y reCAPTCHA v3 cuesta $1-2 por 1,000. Para un agente que resuelve 10 CAPTCHAs por sesión, el costo es aproximadamente $0.02-0.03 por sesión - despreciable en comparación con el valor de la finalización de tareas autónomas.

¿Puedo usar esto con la función de transferencia del SDK de Agentes de OpenAI?

Sí. Puede crear un "agente solucionador de CAPTCHA" especializado y transferirlo cuando el agente principal encuentre un desafío de verificación. El agente solucionador resuelve el CAPTCHA y devuelve al agente principal con el token. Esto mantiene las responsabilidades de los agentes claramente separadas.