Cómo resolver AWS WAF en LangChain con CapSolver

TL;DR

• AWS WAF puede devolver una 202 respuesta de desafío o una 405 respuesta CAPTCHA cuando una solicitud no lleva un token válido; inspeccione tanto el estado como la cabecera x-amzn-waf-action antes de enrutar un agente.
• Un flujo de trabajo de LangChain confiable separa el razonamiento del modelo de la autorización determinista, el manejo de desafíos, el almacenamiento de sesiones y la verificación final de la página.
• CapSolver documenta un adaptador de agente sobre capsolver-core, con herramientas listas para usar de LangChain y métodos de detección orientados al navegador y relleno.
• Mantenga las cookies, credenciales, tokens de solución y objetos de navegador fuera de los mensajes y el estado del agente. Proporcione al modelo solo un resultado pequeño y tipado, como resuelto, no necesario, revisión o denegado.
• Trate la resolución de desafíos como un resultado intermedio. El flujo de trabajo debe repetir la solicitud original y verificar una condición de éxito específica de la aplicación antes de continuar.
• Los ejemplos a continuación son para sistemas propios o explícitamente autorizados. Son verificados sintácticamente, pero una ejecución en vivo aún requiere una página de prueba aprobada y credenciales reales.

Cómo afecta AWS WAF a un agente de LangChain

Las acciones de desafío y CAPTCHA de AWS WAF cambian la ruta de solicitud normal. Según la documentación de acciones de AWS WAF, una solicitud con un token válido continúa a la siguiente regla. Una solicitud sin un token válido puede recibir en cambio una respuesta de desafío.

Para el desafío, AWS documenta una cabecera de respuesta x-amzn-waf-action: challenge y el estado HTTP 202. Para CAPTCHA, documenta x-amzn-waf-action: captcha y el estado 405. Cuando el cliente espera HTML, AWS WAF puede devolver un intersticio de JavaScript. Una interacción exitosa actualiza el token y reenvía la solicitud original.

Este comportamiento importa para los agentes porque un cliente HTTP genérico puede interpretar la respuesta como una página normal, un error temporal del servidor o un resultado vacío. Un modelo de lenguaje no debe adivinar qué caso ocurrió. La aplicación anfitriona debe clasificar la respuesta, verificar la autorización y enrutar el flujo de trabajo a través de un paso de recuperación controlado.

El objetivo no es hacer invisible el manejo de desafíos. El objetivo es hacerlo explícito, acotado, observable y limitado a la automatización legal en sistemas que el operador posee o tiene permiso para probar.

Arquitectura para LangChain, AWS WAF y CapSolver

Un diseño de producción tiene cinco responsabilidades separadas:

1. Agente de LangChain: elige la siguiente acción comercial desde un conjunto limitado de herramientas.
2. Cliente HTTP o navegador: posee la sesión actual, cookies, encabezados y estado de la página.
3. Puerta de política: verifica el dominio, propósito, acción y presupuesto de reintentos.
4. Adaptador CapSolver: expone capacidades documentadas de reconocimiento y relleno de navegador.
5. Verificador: repite la operación deseada y comprueba una condición de éxito específica de la aplicación.

La guía oficial de herramientas de agente de CapSolver describe capsolver-agent como un adaptador delgado sobre capsolver-core. El paquete principal realiza operaciones como solve, detect y solve_on_page; el paquete de agente suministra esquemas de herramientas amigables para el framework. Su ruta documentada de LangChain proporciona herramientas listas para usar a través de get_langchain_tools().

Esta frontera es útil. El modelo no necesita una credencial, token, objeto de navegador o función de red sin restricciones. Recibe un contrato de herramienta estrecho mientras el código de aplicación determinista controla cuándo puede ejecutar la herramienta.

Requisitos previos para una integración autorizada

Antes de escribir código de agente, defina el límite de operación:

• una lista de permitidos de nombres de host propios o explícitamente autorizados;
• propósitos aprobados como validación de QA o investigación de datos públicos permitidos;
• un almacén de secretos para CAPSOLVER_API_KEY y credenciales del modelo;
• un propietario de sesión para el ciclo de vida completo de la solicitud y desafío;
• un número máximo de reintentos y un presupuesto de tiempo total;
• una afirmación de éxito que demuestre que la operación original se completó;
• un camino de revisión humana para dominios desconocidos, fallas repetidas o acciones que cambien el estado;
• reglas de redacción para cookies, tokens, credenciales y contenido de página.

Use un entorno Python aislado. Los comandos de instalación a continuación siguen la guía actual de agente de CapSolver:

python -m venv .venv
source .venv/bin/activate

pip install git+https://github.com/capsolver-ai/capsolver-core.git
pip install "capsolver-agent[langchain] @ git+https://github.com/capsolver-ai/capsolver-agent.git"
pip install langchain-openai langgraph playwright

playwright install chromium

Almacene credenciales fuera del control de código fuente:

export CAPSOLVER_API_KEY="set-this-in-your-secret-manager"
export OPENAI_API_KEY="set-this-in-your-secret-manager"

No pase secretos reales en un prompt, traza, cuaderno, problema o punto de verificación. Las variables de entorno son convenientes para ejemplos locales; un almacén de secretos gestionado es preferible en sistemas implementados.

Detectar una respuesta de AWS WAF antes de invocar una herramienta

El primer componente determinista debe clasificar la respuesta. Este ejemplo usa la combinación de estado y cabecera documentada por AWS:

from dataclasses import dataclass
from typing import Mapping, Literal

WafAction = Literal["challenge", "captcha", "none", "unknown"]


@dataclass(frozen=True)
class WafSignal:
    action: WafAction
    status_code: int
    needs_review: bool = False


def classify_aws_waf_response(
    status_code: int,
    headers: Mapping[str, str],
) -> WafSignal:
    normalized = {key.lower(): value.lower() for key, value in headers.items()}
    action = normalized.get("x-amzn-waf-action", "")

    if action == "challenge" and status_code == 202:
        return WafSignal(action="challenge", status_code=status_code)
    if action == "captcha" and status_code == 405:
        return WafSignal(action="captcha", status_code=status_code)
    if action in {"challenge", "captcha"}:
        return WafSignal(
            action="unknown",
            status_code=status_code,
            needs_review=True,
        )
    return WafSignal(action="none", status_code=status_code)

Requiera ambos señales. Una 202 sola puede ser una respuesta de aplicación válida, y una 405 sola puede significar que el endpoint no permite el método HTTP. Una combinación inesperada debe ir a revisión en lugar de activar un bucle de recuperación automática.

AWS también señala que el JavaScript del navegador que se ejecuta entre orígenes no puede leer x-amzn-waf-action porque esa cabecera no está disponible a través de CORS. En ese caso, clasifique la respuesta de red en la capa de automatización del navegador o use una integración de mismo origen propiedad. No infiera un desafío solo a partir del texto de la página.

Canjear su código de bonificación de CapSolver

Aumente su presupuesto de automatización instantáneamente!
Use el código de bonificación CAP26 al recargar su cuenta de CapSolver para obtener un 5% adicional en cada recarga — sin límites.
Canjéalo ahora en tu Panel de CapSolver

Agregar una puerta de política determinista

El manejo de desafíos no debe estar disponible para cada URL que el modelo pueda mencionar. Verifique el objetivo antes de que se ejecute cualquier herramienta de agente:

from dataclasses import dataclass
from urllib.parse import urlparse


@dataclass(frozen=True)
class PolicyDecision:
    allowed: bool
    reason: str


ALLOWED_HOSTS = {"staging.example.com", "research.example.org"}
ALLOWED_PURPOSES = {"qa-validation", "authorized-research"}


def authorize_recovery(
    url: str,
    purpose: str,
    attempts: int,
) -> PolicyDecision:
    host = (urlparse(url).hostname or "").lower()

    if host not in ALLOWED_HOSTS:
        return PolicyDecision(False, "host-not-allowed")
    if purpose not in ALLOWED_PURPOSES:
        return PolicyDecision(False, "purpose-not-allowed")
    if attempts >= 2:
        return PolicyDecision(False, "retry-budget-exhausted")
    return PolicyDecision(True, "authorized")

Mantenga esta función fuera del modelo de lenguaje. En producción, cargue hosts y propósitos aprobados desde configuración versionada, rechace redirecciones a un host diferente y registre solo metadatos de decisión no sensibles.

Registrar herramientas de CapSolver para LangChain

El paquete documentado puede exponer herramientas compatibles con LangChain. Una configuración mínima se ve así:

import os
from capsolver_agent.langchain import get_langchain_tools


capsolver_tools = get_langchain_tools(
    api_key=os.environ["CAPSOLVER_API_KEY"],
)

La API exacta de construcción de agente puede cambiar entre versiones de LangChain y LangGraph. Mantenga la adquisición de herramientas de CapSolver en un pequeño módulo de adaptador, fije versiones de dependencias probadas y conecte capsolver_tools a través del constructor de agente respaldado por esas versiones.

No dé a cada agente cada herramienta. Un patrón más seguro es exponer herramientas de desafío solo dentro de un subgrafo de recuperación o un ejecutor dedicado que se ejecute después de que authorize_recovery() devuelva allowed=True.

CapSolver documenta el mapeo de herramientas de agente a nivel alto:

• solve_captcha llama a la capacidad solve del núcleo;
• detect_captchas llama a la capacidad detect del núcleo;
• solve_on_page llama a la capacidad solve_on_page del núcleo;
• herramientas de balance y tipos admitidos proporcionan información sobre la cuenta o capacidad.

Use solo la herramienta más pequeña requerida para la integración. Para una sesión de navegador en vivo, un flujo de detección y relleno orientado al navegador generalmente preserva más contexto que pedirle al modelo que manipule una solución cruda.

Mantener la sesión del navegador fuera del estado del agente

Los tokens de AWS WAF forman parte de la sesión del cliente. La documentación de tokens de AWS WAF explica que las acciones de desafío y CAPTCHA usan tokens para rastrear interacciones exitosas. Reemplazar el navegador o perder sus cookies entre la detección y el reintentar puede descartar ese estado.

No serialice un Page de Playwright en un mensaje de LangChain o punto de verificación de gráfico. Almacénelo en un registro propiedad de la aplicación:

class BrowserRegistry:
    def __init__(self) -> None:
        self._pages: dict[str, object] = {}

    def register(self, page_id: str, page: object) -> None:
        self._pages[page_id] = page

    def get(self, page_id: str) -> object:
        if page_id not in self._pages:
            raise KeyError("browser page is not registered")
        return self._pages[page_id]

    async def close(self, page_id: str) -> None:
        page = self._pages.pop(page_id, None)
        if page is not None:
            await page.close()

El estado del agente debe contener solo page_id opaco, URL actual, propósito, contador de intentos y estado. Excluya cookies, almacenamiento local, tokens de solución, claves API y HTML crudo.

Enrutar el flujo de trabajo de LangChain con resultados tipados

Use un tipo de resultado pequeño para que el modelo no reinterpretar una respuesta de nivel inferior:

from typing import Literal, TypedDict

RecoveryStatus = Literal[
    "not_needed",
    "authorized",
    "resolved",
    "retry",
    "review",
    "denied",
]


class RecoveryState(TypedDict, total=False):
    request_id: str
    purpose: str
    current_url: str
    page_id: str
    attempts: int
    waf_action: str
    recovery_status: RecoveryStatus
    error_code: str | None
    final_assertion_passed: bool


def route_after_detection(state: RecoveryState) -> str:
    if state.get("waf_action") not in {"challenge", "captcha"}:
        return "continue"
    if state.get("recovery_status") == "authorized":
        return "recover"
    if state.get("recovery_status") in {"denied", "review"}:
        return "human_review"
    return "authorize"


def route_after_recovery(state: RecoveryState) -> str:
    status = state.get("recovery_status")
    if status == "resolved":
        return "verify"
    if status == "retry":
        return "authorize"
    return "human_review"

El nodo de recuperación puede llamar a la herramienta de navegador de CapSolver aprobada, pero debe devolver solo un estado y un código de error estable. Nunca coloque la respuesta cruda de la herramienta en el siguiente prompt del modelo.

Verificar el éxito después del paso de desafío

La resolución del desafío no demuestra que la operación comercial original tuvo éxito. Repita la navegación o solicitud deseada en la misma sesión y verifique una señal de aplicación propiedad:

async def verify_expected_page(page, expected_url_prefix: str) -> bool:
    await page.wait_for_load_state("domcontentloaded")

    if not page.url.startswith(expected_url_prefix):
        return False

    marker = page.get_by_test_id("authorized-content")
    try:
        await marker.wait_for(state="visible", timeout=15_000)
        return True
    except Exception:
        return False

Elija un marcador estable controlado por su aplicación: un ID de prueba, una respuesta de API específica o una transición de estado conocida. Evite afirmaciones amplias como "la página contiene texto" porque una página de error puede contener palabras similares.

Si la verificación falla, no vuelva a llamar al solucionador inmediatamente. Reclasifique la respuesta actual, verifique si la sesión cambió, haga cumplir el presupuesto de reintentos y envíe casos ambiguos a un humano.

Manejar reintentos y fallas sin bucles

Un flujo acotado debe distinguir al menos estos casos:

Use backoff exponencial para errores de transporte transitorios, pero no use un bucle sin límite. El contador de reintentos pertenece al estado determinista, no a la memoria del modelo.

Registre eventos como waf_signal_detected, policy_allowed, recovery_started, recovery_finished y page_verified. Incluya un ID de solicitud, host, duración, número de intento y código de error. Excluya credenciales, cookies, tokens, cargas de desafío crudas y contenido de página sensible.

Monitorear el comportamiento de AWS WAF y el agente

Los registros de agentes muestran lo que decidió el flujo de trabajo; las métricas de AWS muestran lo que observó la capa de protección. AWS enumera métricas de CloudWatch para actividad de desafío y CAPTCHA, incluyendo conteos de solicitudes, intentos, resueltos y tokens válidos en su referencia de métricas WAF.

Preguntas operativas útiles incluyen:

• ¿Cambió el volumen de desafíos después de una liberación de la aplicación?
• ¿Están concentrados los reintentos del agente en una sola ruta?
• ¿Falla el verificador de la aplicación después del paso de recuperación?
• ¿Las denegaciones de política se deben a redirecciones inesperadas?
• ¿Ocurren tiempos de espera en el navegador, el adaptador de herramientas o la solicitud final?

Correlacione sistemas con un ID de solicitud interno, no con credenciales o tokens. Un aumento repentino en el tráfico de desafíos debe desencadenar una diagnóstico, no un mayor presupuesto de reintentos por defecto.

Errores comunes en la implementación

Dejar que el modelo infiera un desafío a partir del texto de la página

El texto es ambiguo y fácil de cambiar. Prefiera el estado de respuesta y encabezados documentados, eventos de red del navegador o una señal propia de la aplicación.

Iniciar un nuevo navegador después de la detección

Un nuevo navegador puede perder cookies y estado de token. Mantenga la misma sesión aprobada a través de detección, recuperación, reintentos y verificación.

Devolver tokens sin procesar al agente

El modelo no los necesita. Mantenga valores sensibles dentro del adaptador determinista y devuelva un estado tipado.

Tratar el éxito de la herramienta como éxito del flujo de trabajo

Siempre repita la operación deseada y verifique una afirmación específica del dominio.

Dar a la herramienta accesos sin restricciones

Imponga una lista de host permitidos, verificación de propósito, verificación de redirección, presupuesto de reintentos y revisión de ruta fuera del modelo.

Copiar un ejemplo sin fijar versiones

Las APIs de construcción de LangChain y LangGraph evolucionan. Fije versiones que pasen sus pruebas, aísle el cableado del framework en un módulo y ejecute pruebas de integración antes de actualizar.

Pruebe el flujo antes de producción

Use una página de prueba propia y cubra estos casos:

1. respuesta normal sin desafío;
2. señal de desafío documentada;
3. señal de CAPTCHA documentada;
4. estado y encabezado incompatibles;
5. host no aprobado;
6. redirección fuera de la lista permitida;
7. sesión de navegador faltante;
8. tiempo de espera de herramienta;
9. afirmación final fallida;
10. agotamiento del presupuesto de reintentos.

Simule el clasificador, la puerta de política y el verificador en pruebas unitarias. Reserve pruebas end-to-end con credenciales para un entorno aprobado. Pruebe también los registros: asegúrese de que credenciales, cookies y tokens estén ausentes.

La guía de inicio de CapSolver documenta su ciclo de vida de tareas y categorías de CAPTCHA soportadas. Use la documentación oficial actual al seleccionar un camino de tarea; no adivine campos a partir de un fragmento antiguo o una publicación de terceros.

Conclusión

Una integración confiable de AWS WAF con LangChain es una máquina de estados controlada, no un único "resolver" prompt. Detecte la señal documentada de WAF, verifique el objetivo y propósito, invoque una herramienta con alcance estrecho, mantenga la misma sesión del cliente y confirme la operación original antes de que el agente continúe.

Para automatización autorizada, CapSolver proporciona las capas de agente y núcleo necesarias para conectar el manejo de desafíos a LangChain, manteniendo la política, secretos y verificación final en el código de la aplicación.

Cree Flujos de Automatización Confiables con CapSolver

Use la documentación de CapSolver para validar la ruta de integración actual, luego pruebe CapSolver en un entorno de prueba propio o explícitamente autorizado. Aplica el código de bonificación CAP26 al recargar para recibir el bono configurado de 5%.

Preguntas frecuentes

P: ¿Cómo detecta un agente de LangChain un desafío de AWS WAF?

Verifique la combinación documentada de HTTP 202 y x-amzn-waf-action: challenge en una capa HTTP o de navegador determinista. No pida al modelo de lenguaje que infiera la condición a partir del texto de la página.

P: ¿Qué respuesta indica una acción de CAPTCHA de AWS WAF?

AWS documenta HTTP 405 con x-amzn-waf-action: captcha para una respuesta de CAPTCHA cuando la solicitud no tiene un token válido. Trate una combinación de estado y encabezado incompatibles como desconocida y enrútela a revisión.

P: ¿Debe pasarse la clave de API de CapSolver al modelo de LangChain?

No. Cárguela dentro de la aplicación o adaptador de herramientas desde un almacén de secretos aprobado. El modelo nunca debe ver la clave, cookies, tokens de WAF o valores de solución sin procesar.

P: ¿Puede el agente usar un navegador nuevo después de completar un desafío?

Debe mantener el mismo contexto de navegador cuando sea posible, ya que el estado de los tokens de AWS WAF está asociado con la sesión del cliente. Reemplazar la sesión puede descartar el estado necesario para la solicitud repetida.

P: ¿Es suficiente un resultado exitoso de herramienta de desafío para continuar?

No. Repita la operación deseada y verifique una afirmación de éxito específica del dominio. El resultado de la herramienta es solo un estado intermedio.

P: ¿Cuántas veces debe reintentar el agente?

Establezca un pequeño presupuesto explícito de reintentos basado en el riesgo y límite de tiempo del flujo de trabajo. Los ejemplos usan dos intentos como política de aplicación, no como garantía de CapSolver o AWS.

P: ¿Puede usarse este flujo en cualquier sitio web?

No. Úselo solo en sistemas que posea o que esté explícitamente autorizado a automatizar. Imponga verificaciones de objetivo y propósito fuera del modelo y enrute casos inciertos a revisión humana.