Como resolver reCAPTCHA v3 em Agentes LlamaIndex

TL;DR

• Envolver uma função assíncrona do CapSolver com o LlamaIndex FunctionTool; não expor chaves de API, credenciais de proxy, cookies ou objetos de navegador brutos ao modelo.
• Ler websiteURL, websiteKey e pageAction do fluxo autorizado em tempo real. Nunca deixe o agente inventá-los.
• Usar ReCaptchaV3TaskProxyLess para o modo de token com proxy do servidor ou ReCaptchaV3Task quando um proxy aprovado deve ser fornecido.
• Tratar um token retornado como dados de tempo de execução de curta duração, enviá-lo imediatamente por meio de código confiável e verificar o estado da aplicação antes de continuar.
• Limitar as tentativas de resolução, redirecionar falhas repetidas para revisão do operador e registrar apenas metadados redacionados.

Introdução

Um solucionador confiável de reCAPTCHA v3 do LlamaIndex é uma ferramenta de recuperação tipada, não uma capacidade de navegação sem limites. O agente do LlamaIndex deve decidir quando uma tarefa aprovada está bloqueada, enquanto o código confiável valida o alvo, lê a chave do site e a ação exatas da página atual, chama o CapSolver, envia o token e verifica o estado esperado. Essa separação importa porque o reCAPTCHA v3 é executado sem um checkbox interativo e avalia uma solicitação específica da ação. Um token criado para a URL errada ou pageAction pode ser rejeitado mesmo quando a chamada da API em si for bem-sucedida. Este guia mostra os campos oficiais de tarefa do CapSolver, um FunctionTool assíncrono do LlamaIndex, controles de política do lado do servidor, tratamento de modo de sessão, resultados estruturados, tentativas limitadas, verificação do navegador e observabilidade em produção.

Entenda o Limite da Ferramenta do LlamaIndex

A documentação oficial de ferramentas do LlamaIndex explica que o FunctionTool envolve funções Python síncronas ou assíncronas e pode inferir um esquema de função. Também observa que nomes de ferramentas, descrições e descrições de argumentos influenciam fortemente como um modelo seleciona e chama uma ferramenta.

Para um solucionador de reCAPTCHA v3 do LlamaIndex, mantenha a ferramenta estreita:

Agente LlamaIndex
    ↓ escolhe uma ferramenta tipada
Wrapper FunctionTool
    ↓ valida referências confiáveis
Executor CapSolver
    ↓ retorna uma solução de curta duração
Serviço de navegador
    ↓ envia e verifica
O fluxo LlamaIndex retoma

A documentação do CapSolver AI Agents descreve a mesma divisão de trabalho: o modelo decide, o adaptador expõe esquemas e o núcleo executa o trabalho de desafio suportado.

Conheça os Parâmetros Necessários do reCAPTCHA v3

A documentação do reCAPTCHA v3 do CapSolver define quatro tipos de tarefa:

Os campos básicos são:

O guia do reCAPTCHA v3 do Google descreve nomes de ações como parte da integração. A ação observada na página deve ser preservada exatamente.

O blog do reCAPTCHA do CapSolver contém guias adicionais de solução de problemas e implementação.

Não Deixe o Modelo Inventar Parâmetros de Alvo

Passe referências a estados do lado do servidor, não valores arbitrários.

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

    host = urlparse(context.website_url).hostname
    if host not in ALLOWED_HOSTS:
        raise PermissionError("Alvo fora da política de host aprovada")

    if not context.website_key or not context.page_action:
        raise ValueError("Contexto confiável está faltando parâmetros v3 necessários")

    return context

O modelo recebe apenas context_id. O serviço de navegador é responsável pela página atual, chave do site, ação e vinculação de proxy.

Instale os Pacotes Suportados

A documentação do Agente CapSolver fornecida pelo usuário especifica a instalação do pacote principal antes do pacote do 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

Defina a chave de API no ambiente de execução:

export CAPSOLVER_API_KEY="sua-chave-de-api-do-capsolver"

Não cole a chave em prompts, notebooks, conjuntos de dados de cenários ou rastros. A FAQ do CapSolver AI e automação explica o modelo de integração.

Crie o Executor do CapSolver do Lado do Servidor

capsolver-agent fornece create_executor() para a fronteira modelo–adaptador–núcleo.

import os
from capsolver_agent.schema import create_executor

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

O executor envia solve_captcha para o CapSolver Core e retorna um resultado estruturado. Mantenha-o no código de aplicação confiável.

Escreva uma Função de Resolução Estreita Assíncrona

A função resolve o contexto confiável, seleciona o tipo de tarefa oficial e invoca o executor.

from typing import Annotated

async def solve_recaptcha_v3(
    context_id: Annotated[
        str,
        "ID opaco para um contexto de CAPTCHA de navegador atual aprovado"
    ],
) -> dict:
    """Resolver reCAPTCHA v3 para um contexto de navegador aprovado.

    Use apenas quando o fluxo atual reportar um checkpoint de reCAPTCHA v3 suportado.
    Nunca adivinhe ou modifique a URL de destino, chave do site ou ação.
    """
    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": "a solução não contém um 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 e submit_solution_and_verify são adaptadores de política de propriedade da aplicação. Eles não devem ser visíveis para o modelo.

Envolva a Função com o 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 um contexto de navegador atual aprovado. "
        "A entrada deve ser um context_id opaco fornecido pelo serviço de navegador. "
        "Não chame para páginas não suportadas ou hosts não aprovados."
    ),
)

Inspeção do esquema durante o desenvolvimento:

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

Isso segue o padrão FunctionTool documentado do LlamaIndex enquanto reduz a superfície de argumentos do modelo para um identificador opaco.

Anexe a Ferramenta a um Agente do LlamaIndex

from llama_index.core.agent.workflow import FunctionAgent

agent = FunctionAgent(
    llm=llm,
    tools=[tool],
    system_prompt=(
        "Operar apenas fluxos de navegador aprovados. Quando o serviço de navegador "
        "relatar um checkpoint de reCAPTCHA v3 suportado, chame "
        "solve_recaptcha_v3 com o context_id fornecido. Chame apenas uma vez. "
        "Continue apenas quando verified=true; caso contrário, solicite revisão."
    ),
)

Execute o fluxo com uma observação de navegador confiável:

response = await agent.run(
    "O fluxo de staging aprovado está esperando em um checkpoint de reCAPTCHA v3. "
    "Use o context_id ctx_7f19 e continue apenas se verified."
)

O agente nunca vê a chave de API, proxy bruto, token ou cookie.

Leia pageAction da Página em Tempo Real

Um solucionador confiável de reCAPTCHA v3 do LlamaIndex não deve reutilizar uma ação genérica como login em todos os alvos. O serviço de navegador deve ler a integração atual do alvo.

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("Alvo não aprovado")

    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("Não foi possível ler os parâmetros v3 necessários")

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

Para integrações complexas, use o guia de extensão do CapSolver para inspecionar parâmetros de página durante o desenvolvimento e teste aprovados.

Trate o Modo de Sessão com Cuidado

A documentação oficial do v3 do CapSolver observa que alguns alvos podem retornar recaptcha-ca-t quando isSession está ativado. Trate-o como material de sessão sensível e de curta duração.

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

Ative o modo de sessão apenas quando a integração do alvo exigir e o fluxo for autorizado. Armazene o valor na memória do processo ou em armazenamento criptografado de curta duração; nunca o coloque no contexto do LlamaIndex.

Envie e Verifique no Código de Navegador Confiável

O documento de verificação do lado do servidor do Google explica que um site valida o token em seu backend. Sua automação deve enviar o token por meio do mesmo fluxo de aplicação aprovado, depois verificar o estado da 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"}

A descoberta de callback é específica do alvo. Capture-a no contexto de navegador confiável, em vez de pedir ao modelo para gerar JavaScript.

O guia da API de resposta do reCAPTCHA do CapSolver explica padrões comuns de tratamento de resposta.

Impõe uma Única Tentativa e 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": "orçamento de recuperação esgotado",
        }

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

Uma chamada repetida frequentemente sinaliza parâmetros obsoletos, ação errada, estado de navegador expirado ou caminho não suportado. Interrompa o loop e colete diagnósticos.

Registre Observabilidade com Metadados Redacionados

Registre metadados operacionais, não segredos.

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

Não registre o websiteKey se sua política o tratar como configuração, e nunca registre tokens de solução, cookies de sessão, chaves de API, proxies brutos ou HTML de página privada completo.

A FAQ de erros do CapSolver pode ajudar a normalizar as categorias de erros.

Código Bônus: Use o código WEBS no Painel do CapSolver para obter um bônus adicional de 5% em cada recarga.

Resumo da Comparação

O padrão de contexto opaco fornece ao agente LlamaIndex o controle necessário para solicitar recuperação sem permitir que ele reescreva parâmetros sensíveis ou específicos do alvo.

Checklist de Produção

• Mantenha a chave da API e os perfis de proxy em um gerenciador de segredos.
• Permita apenas hosts aprovados e propósitos de fluxo de trabalho exatos.
• Leia o websiteKey e o pageAction da página atual.
• Alinhe as configurações de Enterprise e sessão ao alvo da integração.
• Submeta o token imediatamente por meio de código de navegador confiável.
• Verifique o estado esperado da aplicação antes de continuar.
• Permita apenas uma tentativa de resolução, depois direcione para revisão por operador.
• Remova tokens, cookies, proxies e credenciais de rastreamentos.
• Re-teste o esquema da ferramenta sempre que o SDK ou prompt mudar.

A página de produtos do CapSolver lista as categorias de soluções suportadas, enquanto o blog de IA do CapSolver aborda padrões de integração relacionados a agentes.

Uso Responsável

Use este fluxo apenas em aplicações que você possua, teste ou tenha permissão explícita para automatizar. Capacidade técnica não concede direitos de acesso. Respeite os termos do alvo, limites de taxa, requisitos de privacidade e limites de autenticação. Não use uma ferramenta de agente para acessar contas privadas, registros restritos ou fluxos de trabalho de terceiros sem autorização. Mantenha ações de alto impacto, como submissão, pagamento, reserva e alterações de conta, atrás de uma etapa separada de política e confirmação.

Conclusão

Um solucionador de reCAPTCHA v3 para LlamaIndex em produção deve expor uma única função de recuperação estreita e tipada. O serviço de navegador fornece um ID de contexto confiável, o código do lado do servidor preserva a URL exata, chave do site, ação, modo Enterprise e política de proxy, o CapSolver retorna uma solução de curta duração e o navegador verifica o estado esperado antes que o agente continue.

Inicie uma integração aprovada com o CapSolver, teste-o em um fluxo de trabalho controlado e adicione fundamentação de parâmetros e afirmações de repetição antes da produção.

Perguntas Frequentes

O reCAPTCHA v3 requer um clique em caixa de seleção?

Não. O reCAPTCHA v3 é baseado em pontuação e geralmente executa em segundo plano. O fluxo de trabalho deve preservar a chave do site, URL e ação do alvo.

Por que o pageAction é importante?

A ação identifica a operação que está sendo avaliada, como login ou envio. Use a ação exata lida da integração em tempo real em vez de um valor genérico.

O agente LlamaIndex deve receber o token?

Prefira a submissão do lado do servidor e retorne apenas um status verificado. Um token é dados de tempo de execução de curta duração e não deve entrar no contexto do modelo ou logs.

Quando habilitar o modo de sessão?

Habilite-o apenas quando o alvo autorizado exigir o valor de sessão retornado. Mantenha esse valor em armazenamento criptografado de curta duração.

O que deve acontecer após uma tentativa falhada?

Pare após o orçamento de tentativas configurado, registre um evento de diagnóstico redigido, atualize os parâmetros da página confiáveis se apropriado e direcione o fluxo de trabalho para revisão por operador.