Como resolver o AWS WAF em LangChain com CapSolver

TL;DR

• O AWS WAF pode retornar uma resposta 202 de desafio ou uma resposta 405 de CAPTCHA quando uma solicitação não carrega um token válido; inspecione tanto o status quanto o cabeçalho x-amzn-waf-action antes de rotear um agente.
• Um fluxo confiável do LangChain separa o raciocínio da modelagem da autorização determinística, tratamento de desafios, armazenamento de sessão e verificação final da página.
• CapSolver documenta um adaptador de agente sobre capsolver-core, com ferramentas prontas do LangChain e métodos de detecção orientados ao navegador e preenchimento de resposta.
• Mantenha cookies, credenciais, tokens de solução e objetos do navegador fora dos prompts e estado do agente. Dê ao modelo apenas um resultado pequeno e tipado, como resolved, not_needed, review ou denied.
• Trate a conclusão do desafio como um resultado intermediário. O fluxo de trabalho deve repetir a solicitação desejada e verificar uma condição de sucesso específica da aplicação antes de continuar.
• Os exemplos abaixo são para sistemas próprios ou explicitamente autorizados. Eles são verificados sintaticamente, mas uma execução completa ainda requer uma página aprovada e credenciais reais.

Como o AWS WAF afeta um agente do LangChain

As ações de desafio e CAPTCHA do AWS WAF alteram o caminho normal da solicitação. De acordo com a documentação das ações do AWS WAF, uma solicitação com um token válido continua para a próxima regra. Uma solicitação sem um token válido pode receber uma resposta de desafio.

Para o desafio, o AWS documenta um cabeçalho de resposta x-amzn-waf-action: challenge e o status HTTP 202. Para a CAPTCHA, ele documenta x-amzn-waf-action: captcha e status 405. Quando o cliente espera HTML, o AWS WAF pode retornar uma página intersticial JavaScript. Uma interação bem-sucedida atualiza o token e reenvia a solicitação original.

Essa comportamento importa para os agentes porque um cliente HTTP genérico pode interpretar a resposta como uma página normal, um erro temporário do servidor ou um resultado vazio. Um modelo de linguagem não deve adivinhar qual caso ocorreu. O aplicativo hospedeiro deve classificar a resposta, verificar a autorização e rotear o fluxo de trabalho por um passo de recuperação controlado.

O objetivo não é tornar o tratamento de desafios invisível. O objetivo é torná-lo explícito, limitado, observável e limitado à automação legal em sistemas que o operador possui ou tem permissão para testar.

Arquitetura para LangChain, AWS WAF e CapSolver

Um design de produção tem cinco responsabilidades separadas:

1. Agente do LangChain: escolhe a próxima ação comercial de um conjunto limitado de ferramentas.
2. Cliente HTTP ou navegador: possui a sessão atual, cookies, cabeçalhos e estado da página.
3. Portão de política: verifica o domínio, propósito, ação e orçamento de tentativas.
4. Adaptador CapSolver: expõe capacidades documentadas de reconhecimento e preenchimento de navegador.
5. Verificador: repete a operação desejada e verifica uma condição de sucesso específica da aplicação.

A guia oficial de ferramentas do agente do CapSolver descreve capsolver-agent como um adaptador leve sobre capsolver-core. O pacote principal realiza operações como solve, detect e solve_on_page; o pacote do agente fornece esquemas de ferramentas amigáveis ao framework. Seu caminho documentado do LangChain fornece ferramentas prontas por meio de get_langchain_tools().

Essa fronteira é útil. O modelo não precisa de credencial bruta, token, objeto do navegador ou função de rede sem restrição. Ele recebe um contrato de ferramenta estreito enquanto o código de aplicação determinística controla quando a ferramenta pode ser executada.

Pré-requisitos para uma integração autorizada

Antes de escrever o código do agente, defina o limite de operação:

• uma lista de permissões de nomes de host próprios ou explicitamente autorizados;
• propósitos aprovados como validação de QA ou pesquisa de dados públicos permitidos;
• um armazenamento secreto para CAPSOLVER_API_KEY e credenciais do modelo;
• um proprietário de sessão para o ciclo de vida completo da solicitação e desafio;
• um número máximo de tentativas e orçamento de tempo total;
• uma afirmação de sucesso que prove que a operação original foi concluída;
• um caminho de revisão humana para domínios desconhecidos, falhas repetidas ou ações que mudam o estado;
• regras de redação para cookies, tokens, credenciais e conteúdo da página.

Use um ambiente Python isolado. Os comandos de instalação abaixo seguem o guia atual do agente do 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

Armazene credenciais fora do controle de versão:

export CAPSOLVER_API_KEY="defina isso no seu gerenciador de segredos"
export OPENAI_API_KEY="defina isso no seu gerenciador de segredos"

Não cole segredos reais em um prompt, rastreamento, notebook, problema ou ponto de verificação. Variáveis de ambiente são convenientes para exemplos locais; um armazenamento de segredos gerenciado é preferível em sistemas implantados.

Detectar uma resposta do AWS WAF antes de invocar uma ferramenta

O primeiro componente determinístico deve classificar a resposta. Este exemplo usa a combinação de status e cabeçalho documentada pelo 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)

Exija ambos os sinais. Um 202 sozinho pode ser uma resposta de aplicação válida, e um 405 sozinho pode significar que o endpoint não permite o método HTTP. Uma combinação inesperada deve ir para revisão em vez de disparar um loop de recuperação automatizado.

O AWS também observa que o JavaScript do navegador executado entre origens não pode ler x-amzn-waf-action, pois esse cabeçalho não está disponível através do CORS. Nesse caso, classifique a resposta de rede na camada de automação do navegador ou use uma integração de mesma origem própria. Não infira um desafio apenas a partir do texto da página.

Resgate seu código promocional do CapSolver

Aumente seu orçamento de automação instantaneamente!
Use o código promocional CAP26 ao recarregar sua conta do CapSolver para obter um bônus adicional de 5% em cada recarga — sem limites.
Resgate-o agora em seu Painel do CapSolver

Adicione uma porta de política determinística

O tratamento de desafios não deve estar disponível para cada URL que o modelo pode mencionar. Verifique o alvo antes que qualquer ferramenta do agente seja executada:

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")

Mantenha essa função fora do modelo de linguagem. Em produção, carregue os hosts e propósitos aprovados de configuração versionada, rejeite redirecionamentos para um host diferente e registre apenas metadados de decisão não sensíveis.

Registre ferramentas do CapSolver para o LangChain

O pacote documentado pode expor ferramentas compatíveis com o LangChain. Uma configuração mínima parece assim:

import os
from capsolver_agent.langchain import get_langchain_tools


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

A API exata de construção do agente pode mudar entre versões do LangChain e LangGraph. Mantenha a aquisição de ferramentas do CapSolver em um pequeno módulo de adaptador, pinifique versões de dependência testadas e conecte capsolver_tools através do construtor de agente suportado por essas versões.

Não dê todas as ferramentas para cada agente. Um padrão mais seguro é expor ferramentas de desafio apenas dentro de um subgrafo de recuperação ou um executor dedicado que execute após authorize_recovery() retornar allowed=True.

O CapSolver documenta o mapeamento de ferramentas do agente em um nível alto:

• solve_captcha chama a capacidade solve do núcleo;
• detect_captchas chama a capacidade detect do núcleo;
• solve_on_page chama a capacidade solve_on_page do núcleo;
• ferramentas de saldo e tipos suportados fornecem informações sobre conta ou capacidade.

Use apenas a menor ferramenta necessária para a integração. Para uma sessão de navegador ativa, um fluxo de detecção e preenchimento orientado ao navegador geralmente preserva mais contexto do que pedir ao modelo para manipular uma solução bruta.

Mantenha a sessão do navegador fora do estado do agente

Tokens do AWS WAF fazem parte da sessão do cliente. A documentação dos tokens do AWS WAF explica que as ações de desafio e CAPTCHA usam tokens para rastrear interações bem-sucedidas. Substituir o navegador ou perder seus cookies entre detecção e tentativa pode descartar esse estado.

Não serializar um Page do Playwright em uma mensagem do LangChain ou checkpoint do gráfico. Armazene-o em um registro proprietário da aplicação:

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()

O estado do agente deve conter apenas o page_id opaco, URL atual, propósito, contagem de tentativas e status. Exclua cookies, armazenamento local, tokens de solução, chaves de API e HTML bruto.

Roteie o fluxo do LangChain com resultados tipados

Use um tipo de resultado pequeno para que o modelo não reinterprete uma resposta de baixo nível:

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"

O nó de recuperação pode chamar a ferramenta do CapSolver aprovada, mas deve retornar apenas um status e um código de erro estável. Nunca coloque a resposta bruta da ferramenta no próximo prompt do modelo.

Verifique o sucesso após a etapa do desafio

A conclusão do desafio não prova que a operação comercial original foi bem-sucedida. Repita a navegação ou solicitação desejada na mesma sessão e verifique um sinal da aplicação própria:

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

Escolha um marcador estável controlado pela sua aplicação: um ID de teste, uma resposta de API específica ou uma transição de estado conhecida. Evite afirmações amplas como "a página contém texto" porque uma página de erro pode conter palavras semelhantes.

Se a verificação falhar, não chame o solucionador novamente imediatamente. Reclassifique a resposta atual, verifique se a sessão mudou, enforce o orçamento de tentativas e envie casos ambíguos para uma pessoa.

Trate tentativas e falhas sem loops

Um fluxo limitado deve distinguir ao menos esses casos:

Use backoff exponencial para erros de transporte transitórios, mas não use um loop sem limite. O contador de tentativas pertence ao estado determinístico, não à memória do modelo.

Registre eventos como waf_signal_detected, policy_allowed, recovery_started, recovery_finished e page_verified. Inclua um ID de solicitação, host, duração, número de tentativas e código de erro. Exclua credenciais, cookies, tokens, payloads de desafio brutos e conteúdo de página sensível.

Monitore o comportamento do AWS WAF e do agente

Rastreamentos do agente mostram o que o fluxo de trabalho decidiu; as métricas da AWS mostram o que a camada de proteção observou. A AWS lista métricas da CloudWatch para atividade de Challenge e CAPTCHA, incluindo contagens de solicitação, tentativa, resolvida e token válido em sua referência de métricas WAF.

Perguntas operacionais úteis incluem:

• A volume de desafios mudou após um lançamento de aplicativo?
• As repetições do agente estão concentradas em uma rota específica?
• O verificador de aplicativo falha após a etapa de recuperação?
• As negações de política são causadas por redirecionamentos inesperados?
• Os tempos limite ocorrem no navegador, no adaptador de ferramenta ou na solicitação final?

Correlacione sistemas com um ID de solicitação interno, não com credencial ou token. Um aumento repentino no tráfego de desafios deve disparar uma investigação, não um orçamento maior de repetição por padrão.

Erros comuns na implementação

Deixar o modelo inferir um desafio a partir do texto da página

O texto é ambíguo e fácil de mudar. Prefira o status de resposta documentado e cabeçalhos, eventos de rede do navegador ou um sinal de propriedade da aplicação.

Iniciar um novo navegador após a detecção

Um novo navegador pode perder cookies e estado de token. Mantenha a mesma sessão aprovada durante a detecção, recuperação, repetição e verificação.

Retornar tokens brutos ao agente

O modelo não precisa deles. Mantenha valores sensíveis dentro do adaptador determinístico e retorne um status tipado.

Tratar o sucesso da ferramenta como sucesso do fluxo de trabalho

Sempre repita a operação desejada e verifique uma afirmação específica do domínio.

Dar à ferramenta acesso sem restrições aos alvos

Impõe uma lista de hosts permitidos, verificação de propósito, verificação de redirecionamento, orçamento de repetição e revise a rota fora do modelo.

Copiar um exemplo sem fixar versões

As APIs de construção do LangChain e LangGraph evoluem. Fixe as versões que passam nos seus testes, isole o wiring da framework em um módulo e execute testes de integração novamente antes de atualizar.

Teste o fluxo antes da produção

Use uma página de staging própria e cubra esses casos:

1. resposta normal sem desafio;
2. sinal de desafio documentado;
3. sinal de CAPTCHA documentado;
4. status e cabeçalho desalinhados;
5. hostname não aprovado;
6. redirecionamento fora da lista permitida;
7. sessão do navegador ausente;
8. tempo limite da ferramenta;
9. afirmação final falha;
10. esgotamento do orçamento de repetição.

Simule o classificador, porta de política e verificador em testes unitários. Reserve testes end-to-end com credenciais para um ambiente aprovado. Teste também os logs: afirme que credenciais, cookies e tokens estejam ausentes.

O guia de início rápido da CapSolver documenta seu ciclo de vida de tarefa e categorias de CAPTCHA suportadas. Use a documentação oficial atual ao selecionar um caminho de tarefa; não adivinhe campos a partir de um snippet antigo ou um post de terceiros.

Conclusão

Uma integração confiável da AWS WAF com LangChain é uma máquina de estados controlada, não um único "resolva" prompt. Detecte o sinal documentado da WAF, verifique o alvo e o propósito, invoque uma ferramenta com escopo estreito, mantenha a mesma sessão do cliente e confirme a operação original antes que o agente prossiga.

Para automação autorizada, CapSolver fornece as camadas de agente e núcleo necessárias para conectar o tratamento de desafio ao LangChain, mantendo política, segredos e verificação final no código da aplicação.

Crie fluxos de automação confiáveis com o CapSolver

Use a documentação do CapSolver para validar o caminho de integração atual, depois experimente o CapSolver em um ambiente de teste próprio ou explicitamente autorizado. Use o código de bônus CAP26 ao recarregar para receber o bônus configurado de 5%.

Perguntas frequentes

Q: Como um agente LangChain detecta um desafio AWS WAF?

Verifique a combinação documentada de HTTP 202 e x-amzn-waf-action: challenge em uma camada HTTP ou navegador determinística. Não peça ao modelo de linguagem para inferir a condição a partir do texto da página.

Q: Qual resposta indica uma ação CAPTCHA da AWS WAF?

A AWS documenta HTTP 405 com x-amzn-waf-action: captcha para uma resposta CAPTCHA quando a solicitação não possui um token válido. Trate uma combinação de status/cabeçalho desalinhada como desconhecida e direcione-a para revisão.

Q: O chave da API do CapSolver deve ser passada para o modelo LangChain?

Não. Carregue-a dentro da aplicação ou adaptador de ferramenta de um repositório de segredos aprovado. O modelo nunca deve ver a chave, cookies, tokens WAF ou valores brutos de solução.

Q: O agente pode usar um novo navegador após um desafio ser concluído?

Ele deve manter o mesmo contexto de navegador quando possível, pois o estado dos tokens WAF da AWS está associado à sessão do cliente. Substituir a sessão pode descartar o estado necessário para a solicitação repetida.

Q: Um resultado bem-sucedido da ferramenta de desafio é suficiente para continuar?

Não. Repita a operação desejada e verifique uma afirmação de sucesso específica do aplicativo. Um resultado da ferramenta é apenas um estado intermediário.

Q: Quantas vezes o agente deve repetir?

Defina um pequeno orçamento de repetição explícito baseado no risco e limite de tempo do fluxo de trabalho. Os exemplos usam duas tentativas como política de aplicativo, não como garantia do CapSolver ou AWS.

Q: Essa workflow pode ser usada em qualquer site?

Não. Use-a apenas em sistemas que você possua ou que estejam explicitamente autorizados para automação. Impõe verificações de alvo e propósito fora do modelo e direcione casos incertos para revisão humana.