Cómo resolver reCAPTCHA v3 en Agentes de LlamaIndex

TL;DR

• Envuelva una función async de CapSolver con LlamaIndex FunctionTool; no exponga claves de API, credenciales de proxy, cookies o objetos de navegador sin procesar al modelo.
• Lea websiteURL, websiteKey y pageAction desde el flujo de trabajo autorizado en tiempo real. Nunca permita que el agente los invente.
• Use ReCaptchaV3TaskProxyLess para el modo de token con servidor proxy o ReCaptchaV3Task cuando se deba proporcionar un proxy aprobado.
• Trate un token devuelto como datos de ejecución de corta duración, súmelo inmediatamente a través de código confiable y verifique el estado de la aplicación antes de continuar.
• Limite los intentos de resolución, redirija los fracasos repetidos a la revisión del operador y registre solo metadatos con redacción.

Introducción

Un solucionador de reCAPTCHA v3 confiable de LlamaIndex es una herramienta de recuperación tipada, no una capacidad de navegación sin límites. El agente de LlamaIndex debe decidir cuándo una tarea aprobada está bloqueada, mientras que el código confiable valida el objetivo, lee la clave del sitio y la acción exactas de la página actual, llama a CapSolver, envía el token y verifica el estado esperado. Esta separación es importante porque reCAPTCHA v3 se ejecuta sin un casilla de verificación interactiva y evalúa una solicitud específica de acción. Un token creado para una URL incorrecta o pageAction puede ser rechazado incluso cuando la llamada a la API tiene éxito. Esta guía muestra los campos de tarea oficiales de CapSolver, una FunctionTool async de LlamaIndex, controles de política del lado del servidor, manejo de modo de sesión, resultados estructurados, reintentos limitados, verificación del navegador y observabilidad en producción.

Comprender los límites de la herramienta de LlamaIndex

La documentación oficial de herramientas de LlamaIndex explica que FunctionTool envuelve funciones Python sincrónicas o asincrónicas y puede inferir un esquema de función. También menciona que los nombres de herramientas, descripciones y descripciones de argumentos influyen fuertemente en cómo un modelo selecciona y llama a una herramienta.

Para un solucionador de reCAPTCHA v3 de LlamaIndex, mantenga la herramienta estrecha:

Agente de LlamaIndex
    ↓ elige una herramienta tipada
Wrapper de FunctionTool
    ↓ valida referencias confiables
Ejecutor de CapSolver
    ↓ devuelve una solución de corta duración
Servicio de navegador
    ↓ envía y verifica
El flujo de LlamaIndex continúa

La documentación de CapSolver AI Agents describe la misma división del trabajo: el modelo decide, el adaptador expone esquemas y el núcleo ejecuta el trabajo de desafíos admitidos.

Conozca los parámetros requeridos de reCAPTCHA v3

La documentación de CapSolver define cuatro tipos de tareas:

Los campos base son:

La guía de reCAPTCHA v3 de Google describe los nombres de acción como parte de la integración. La acción observada en la página debe preservarse exactamente.

El blog de reCAPTCHA de CapSolver contiene guías adicionales de solución de problemas e implementación.

No permita que el modelo invente parámetros de destino

Pase referencias al estado del lado del servidor, no valores arbitrarios.

from dataclasses import dataclass
from urllib.parse import urlparse

@dataclass(frozen=True)
class CaptchaContext:
    context_id: str
    website_url: str
    website_key: str
    page_action: str
    enterprise: bool = False
    proxy_profile: str | None = None
    session_mode: bool = False

TRUSTED_CONTEXTS: dict[str, CaptchaContext] = {}
ALLOWED_HOSTS = {"staging.example.com", "portal.example.org"}


def get_trusted_context(context_id: str) -> CaptchaContext:
    context = TRUSTED_CONTEXTS.get(context_id)
    if context is None:
        raise ValueError("Contexto de CAPTCHA desconocido")

    host = urlparse(context.website_url).hostname
    if host not in ALLOWED_HOSTS:
        raise PermissionError("El objetivo está fuera de la política de host aprobada")

    if not context.website_key or not context.page_action:
        raise ValueError("El contexto confiable carece de parámetros v3 requeridos")

    return context

El modelo recibe solo context_id. El servicio de navegador posee la página actual, la clave del sitio, la acción y el enlace de proxy.

Instale los paquetes compatibles

La documentación del agente CapSolver proporcionada por el usuario especifica instalar el paquete principal antes del paquete del agente:

pip install git+https://github.com/capsolver-ai/capsolver-core.git
pip install git+https://github.com/capsolver-ai/capsolver-agent.git
pip install llama-index-core

Establezca la clave de API en el entorno de ejecución:

export CAPSOLVER_API_KEY="su-clave-de-capsolver"

No pegue la clave en prompts, notebooks, conjuntos de datos de escenarios o trazas. La FAQ de CapSolver sobre IA y automatización explica el modelo de integración.

Cree el ejecutor de CapSolver del lado del servidor

capsolver-agent proporciona create_executor() para el límite modelo-adapter-núcleo.

import os
from capsolver_agent.schema import create_executor

executor = create_executor(
    api_key=os.environ["CAPSOLVER_API_KEY"],
    default_timeout=120,
)

El ejecutor envía solve_captcha al núcleo de CapSolver y devuelve un resultado estructurado. Manténgalo en código de aplicación confiable.

Escriba una función async estrecha para resolver

La función resuelve el contexto confiable, selecciona el tipo de tarea oficial y llama al ejecutor.

from typing import Annotated

async def solve_recaptcha_v3(
    context_id: Annotated[
        str,
        "ID opaco para un contexto de CAPTCHA de navegador actual y confiable"
    ],
) -> dict:
    """Resolver reCAPTCHA v3 para un contexto de navegador aprobado.

    Úselo solo cuando el flujo de trabajo actual informe un punto de control de reCAPTCHA v3 soportado.
    Nunca adivine o modifique la URL de destino, la clave del sitio o la acción.
    """
    context = get_trusted_context(context_id)

    captcha_type = (
        "reCaptchaV3Enterprise"
        if context.enterprise
        else "reCaptchaV3"
    )

    args = {
        "captcha_type": captcha_type,
        "website_url": context.website_url,
        "website_key": context.website_key,
        "page_action": context.page_action,
    }

    if context.proxy_profile:
        args["proxy"] = resolve_proxy(context.proxy_profile)

    result = await executor.execute("solve_captcha", args)
    if not result.get("success"):
        return {
            "success": False,
            "context_id": context_id,
            "error": normalize_error(result.get("error")),
        }

    solution = result.get("solution") or {}
    token = solution.get("token")
    if not token:
        return {
            "success": False,
            "context_id": context_id,
            "error": "la solución no contenía un token",
        }

    receipt = await submit_solution_and_verify(
        context_id=context_id,
        token=token,
        session_cookie=extract_session_cookie(solution),
    )

    return {
        "success": receipt["verified"],
        "context_id": context_id,
        "verified": receipt["verified"],
        "next_state": receipt["next_state"],
    }

resolve_proxy, normalize_error y submit_solution_and_verify son adaptadores de política propiedad de la aplicación. No deben ser visibles para el modelo.

Envuelva la función con LlamaIndex FunctionTool

from llama_index.core.tools import FunctionTool

tool = FunctionTool.from_defaults(
    async_fn=solve_recaptcha_v3,
    name="solve_recaptcha_v3",
    description=(
        "Resolver reCAPTCHA v3 para un contexto de navegador actual aprobado. "
        "La entrada debe ser un context_id opaco proporcionado por el servicio de navegador. "
        "No lo llame para páginas no soportadas o hosts no aprobados."
    ),
)

Inspeccione el esquema durante el desarrollo:

schema = tool.metadata.get_parameters_dict()
print(schema)

Esto sigue el patrón documentado de FunctionTool de LlamaIndex mientras reduce la superficie de argumentos del modelo a un identificador opaco.

Asocie la herramienta a un agente de LlamaIndex

from llama_index.core.agent.workflow import FunctionAgent

agent = FunctionAgent(
    llm=llm,
    tools=[tool],
    system_prompt=(
        "Opere solo en flujos de trabajo de navegador aprobados. Cuando el servicio de navegador "
        "informe un punto de control de reCAPTCHA v3 soportado, llame "
        "solve_recaptcha_v3 con el context_id proporcionado. Llame una vez. "
        "Continúe solo cuando verified=true; de lo contrario, solicite revisión."
    ),
)

Ejecute el flujo con una observación de navegador confiable:

response = await agent.run(
    "El flujo de staging aprobado está esperando en un punto de control de reCAPTCHA v3. "
    "Use el context_id ctx_7f19 y continúe solo si verified."
)

El agente nunca ve la clave de API, el proxy sin procesar, el token o la cookie.

Lea pageAction desde la página en vivo

Un solucionador de reCAPTCHA v3 confiable de LlamaIndex no debe reutilizar una acción genérica como login en cada objetivo. El servicio de navegador debe leer la integración actual del objetivo.

async def collect_v3_context(page, context_id: str) -> CaptchaContext:
    website_url = page.url
    host = urlparse(website_url).hostname
    if host not in ALLOWED_HOSTS:
        raise PermissionError("Objetivo no aprobado")

    values = await page.evaluate("""
    () => {
      const scripts = Array.from(document.scripts)
        .map(s => s.textContent || '')
        .join('\n');

      const siteKey =
        document.querySelector('[data-sitekey]')?.getAttribute('data-sitekey')
        || null;

      const actionMatch = scripts.match(
        /grecaptcha(?:\.enterprise)?\.execute\([^,]+,\s*\{\s*action:\s*['\"]([^'\"]+)/
      );

      return {
        siteKey,
        pageAction: actionMatch ? actionMatch[1] : null,
        enterprise: scripts.includes('grecaptcha.enterprise')
      };
    }
    """)

    if not values["siteKey"] or not values["pageAction"]:
        raise RuntimeError("No se pudieron leer los parámetros v3 requeridos")

    return CaptchaContext(
        context_id=context_id,
        website_url=website_url,
        website_key=values["siteKey"],
        page_action=values["pageAction"],
        enterprise=values["enterprise"],
    )

Para integraciones complejas, use la guía de extensión de CapSolver para inspeccionar parámetros de página durante el desarrollo y pruebas aprobados.

Maneje el modo de sesión con cuidado

La documentación oficial de v3 de CapSolver menciona que algunos objetivos pueden devolver recaptcha-ca-t cuando isSession está habilitado. Trátelo como material de sesión sensible y de corta duración.

SESSION_KEYS = {
    "recaptcha-ca-t",
    "recaptcha_ca_t",
}


def extract_session_cookie(solution: dict) -> str | None:
    raw = solution.get("raw") or {}
    for key in SESSION_KEYS:
        value = solution.get(key) or raw.get(key)
        if value:
            return value
    return None

Habilite el modo de sesión solo cuando la integración del objetivo lo requiera y el flujo esté autorizado. Almacene el valor en memoria del proceso o en almacenamiento cifrado de corta duración; nunca lo coloque en el contexto de LlamaIndex.

Envíe y verifique en código de navegador confiable

La documentación de verificación del lado del servidor de Google explica que un sitio valida el token en su backend. Su automatización debe enviar el token a través del mismo flujo de aplicación aprobado, luego verificar el estado de la página resultante.

async def submit_solution_and_verify(
    context_id: str,
    token: str,
    session_cookie: str | None,
) -> dict:
    browser_state = BROWSER_CONTEXTS[context_id]
    page = browser_state.page

    if session_cookie:
        await browser_state.context.add_cookies([{
            "name": "recaptcha-ca-t",
            "value": session_cookie,
            "domain": urlparse(page.url).hostname,
            "path": "/",
            "secure": True,
        }])

    await page.evaluate(
        """({ token }) => {
          let input = document.querySelector(
            'textarea[name="g-recaptcha-response"]'
          );
          if (!input) {
            input = document.createElement('textarea');
            input.name = 'g-recaptcha-response';
            input.style.display = 'none';
            document.body.appendChild(input);
          }
          input.value = token;
          input.dispatchEvent(new Event('change', { bubbles: true }));
        }""",
        {"token": token},
    )

    await trigger_trusted_callback(page, browser_state.callback_name)

    try:
        await page.locator(browser_state.success_selector).wait_for(
            state="visible",
            timeout=15000,
        )
        return {"verified": True, "next_state": "continue"}
    except Exception:
        return {"verified": False, "next_state": "operator_review"}

El descubrimiento de la llamada de devolución es específico del objetivo. Cópielo en el contexto de navegador confiable en lugar de pedirle al modelo que genere JavaScript.

La guía de API de respuesta de reCAPTCHA de CapSolver explica patrones comunes de manejo de respuestas.

Imponga un solo intento y estados explícitos

from enum import Enum

class RecoveryState(str, Enum):
    DETECTED = "detected"
    SOLVING = "solving"
    VERIFIED = "verified"
    REVIEW_REQUIRED = "review_required"

ATTEMPTS: dict[str, int] = {}

async def guarded_solve(context_id: str) -> dict:
    attempts = ATTEMPTS.get(context_id, 0)
    if attempts >= 1:
        return {
            "success": False,
            "context_id": context_id,
            "next_state": RecoveryState.REVIEW_REQUIRED,
            "error": "se agotó el presupuesto de recuperación",
        }

    ATTEMPTS[context_id] = attempts + 1
    return await solve_recaptcha_v3(context_id)

Una llamada repetida suele señalar parámetros caducados, acción incorrecta, estado de navegador expirado o un camino no soportado. Detenga el bucle y recolecte diagnósticos.

Registre observabilidad con metadatos redactados

Registre metadatos operativos, no secretos.

from datetime import datetime, timezone


def recovery_event(context: CaptchaContext, result: dict) -> dict:
    return {
        "event": "recaptcha_v3_recovery",
"context_id": context.context_id,
        "host": urlparse(context.website_url).hostname,
        "page_action": context.page_action,
        "enterprise": context.enterprise,
        "session_mode": context.session_mode,
        "success": result.get("success", False),
        "next_state": str(result.get("next_state")),
        "observed_at": datetime.now(timezone.utc).isoformat(),
    }

No registre websiteKey si su política lo trata como configuración, y nunca registre tokens de solución, cookies de sesión, claves de API, proxies sin procesar o HTML de página privada completo.

La FAQ de errores de CapSolver puede ayudar a normalizar las categorías de errores.

Código de bonificación: Use el código WEBS en CapSolver Dashboard para obtener un 5% adicional de bonificación en cada recarga.

Resumen de comparación

El patrón de contexto opaco da al agente de LlamaIndex suficiente control para solicitar recuperación sin permitir que reescriba parámetros sensibles o específicos del objetivo.

Lista de verificación para producción

• Mantenga la clave de API y los perfiles de proxy en un gestor de secretos.
• Permita solo hosts aprobados y propósitos de flujo de trabajo exactos.
• Lea websiteKey y pageAction desde la página en vivo actual.
• Ajuste Enterprise y configuraciones de sesión al integración objetivo.
• Envíe el token inmediatamente a través de código de navegador confiable.
• Verifique el estado de aplicación esperado antes de continuar.
• Permita un solo intento de resolución, luego redirija a revisión por operador.
• Elimine tokens, cookies, proxies y credenciales de los registros.
• Vuelva a probar el esquema de herramienta cada vez que cambie el SDK o el prompt.

La página de productos de CapSolver enumera las categorías de solución compatibles, mientras que la blog de IA de CapSolver cubre los patrones de integración de agentes relacionados.

Uso responsable

Use este flujo de trabajo solo en aplicaciones que posea, pruebe o tenga permiso explícito para automatizar. La capacidad técnica no otorga derechos de acceso. Respete los términos del objetivo, límites de frecuencia, requisitos de privacidad y límites de autenticación. No use una herramienta de agente para acceder a cuentas privadas, registros restringidos o flujos de trabajo de terceros sin autorización. Mantenga acciones de alto impacto como envío, pago, reserva y cambios de cuenta detrás de un paso adicional de política y confirmación.

Conclusión

Un solucionador de reCAPTCHA v3 para producción en LlamaIndex debe exponer una función de recuperación estrecha y tipificada. El servicio de navegador proporciona un ID de contexto confiable, el código del lado del servidor preserva la URL exacta, clave del sitio, acción, modo Enterprise y política de proxy, CapSolver devuelve una solución de corta duración y el navegador verifica el estado esperado antes de que el agente continúe.

Comience una integración de LlamaIndex aprobada con CapSolver, pruébelo en un flujo de trabajo controlado y agregue afirmaciones de fijación de parámetros y reintentos antes de producción.

Preguntas frecuentes

¿Requiere reCAPTCHA v3 un clic en la casilla de verificación?

No. reCAPTCHA v3 es basado en puntuación y generalmente funciona en segundo plano. El flujo de trabajo debe preservar la clave del sitio, la URL y la acción del objetivo.

¿Por qué es importante pageAction?

La acción identifica la operación que se está evaluando, como inicio de sesión o envío. Use la acción exacta leída desde la integración en vivo en lugar de un valor genérico.

¿Debe recibir el agente de LlamaIndex el token?

Prefiera el envío del lado del servidor y devuelva solo un estado verificado. Un token es datos de tiempo de ejecución de corta duración y no debe ingresar al contexto del modelo o registros.

¿Cuándo debe activarse el modo de sesión?

Actívelo solo cuando el objetivo autorizado lo requiera. Guarde ese valor en almacenamiento en tiempo de ejecución cifrado de corta duración.

¿Qué debe ocurrir después de un intento fallido?

Deténgase después del presupuesto de intentos configurado, registre un evento de diagnóstico redactado, refresque los parámetros de página confiables si es apropiado y redirija el flujo de trabajo a revisión por operador.