Como resolver reCAPTCHA v3 em Agentes CrewAI com CapSolver

TL;DR

• Um solucionador de reCAPTCHA v3 para CrewAI deve ser uma ferramenta com tipo estreito, não uma ferramenta de navegador genérica ou função de URL arbitrária.
• Resolva a URL de destino, chave do site, ação esperada pageAction e política de pontuação a partir de um registro do lado do servidor, em vez de texto gerado pelo modelo.
• Use os parâmetros de tarefa de reCAPTCHA v3 documentados do CapSolver e mantenha as configurações de Enterprise, proxy e sessão explícitas.
• Submeta o token retornado dentro do código de aplicação confiável; retorne apenas um objeto de status redacionado para o agente CrewAI.
• Trate o resultado do solucionador como um passo intermediário e verifique se o estado da página desejada mudou antes que a equipe continue.

Introdução

A maneira mais segura de resolver o reCAPTCHA v3 no CrewAI é expor o CapSolver por meio de uma ferramenta com tipo controlado por política. O CrewAI deve decidir quando a tarefa precisa de verificação, mas o código de aplicação confiável deve resolver o destino aprovado, chave do site, ação da página, modo de proxy e política de pontuação. A documentação do reCAPTCHA v3 do CapSolver define os tipos e parâmetros de tarefa suportados, enquanto o SDK do Agente fornecido pelo usuário mapeia chamadas de ferramenta estruturadas para capsolver-core. A ferramenta deve submeter o token do lado do servidor, verificar o estado da página resultante e dar à equipe um pequeno resultado, como verificado, revisão necessária ou parado. Este design evita desvio de URL, adivinhação de ação, vazamento de segredos, soluções duplicadas e sinais falsos de sucesso.

Por que o reCAPTCHA v3 Precisa de uma Ferramenta Diferente para o CrewAI

O reCAPTCHA v3 é baseado em pontuação e geralmente é executado sem um checkbox visível. O aplicativo de destino invoca uma ação, recebe um token e avalia esse token no servidor. Portanto, um fluxo de trabalho do CrewAI pode falhar mesmo quando nunca vê um desafio visual.

As causas comuns são operacionais, não conversacionais:

• a ferramenta usou a chave do site errada;
• a pageAction não corresponde à ação em tempo real da página;
• o token foi submetido a uma rota ou estado de navegador diferente;
• o tipo de tarefa não corresponde a Standard ou Enterprise;
• a equipe tratou a conclusão da tarefa como verificação da aplicação;
• o mesmo passo criou vários tokens sem alteração de estado.

O blog do reCAPTCHA do CapSolver contém guias de implementação complementares, enquanto a FAQ de IA e automação ajuda a definir limites seguros para o agente.

Separe os Papéis da Equipe da Autoridade do Solucionador

Uma equipe de múltiplos agentes funciona melhor quando a responsabilidade é explícita.

O modelo pode escolher um ID de destino registrado. Ele não deve construir a URL de destino ou os parâmetros do desafio.

Use o Padrão Oficial de Ferramenta do CrewAI

A documentação de ferramenta personalizada do CrewAI suporta BaseTool com args_schema Pydantic, o decorador @tool, resultados tipados e ferramentas assíncronas para operações I/O-bound.

A documentação do Agente CapSolver fornecida pelo usuário explica que capsolver-agent encapsula capsolver-core: create_executor() cria o executor, e executor.execute("solve_captcha", args) envia a solicitação tipada para o motor principal.

Instale os pacotes documentados:

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

export CAPSOLVER_API_KEY="CAP-..."

Mantenha as chaves no armazenamento de segredos em tempo de execução. Não as coloque em prompts de equipe, descrições de tarefa ou resultados de ferramenta.

Defina um Registro de Destino Confiável

from dataclasses import dataclass

@dataclass(frozen=True)
class RecaptchaV3Policy:
    target_id: str
    website_url: str
    website_key: str
    page_action: str
    minimum_score: float
    enterprise: bool
    proxy_profile: str | None
    allowed_crew_role: str
    max_attempts: int = 1

TARGETS = {
    "approved_login_test": RecaptchaV3Policy(
        target_id="approved_login_test",
        website_url="https://approved.example.com/login",
        website_key="PUBLIC_SITE_KEY",
        page_action="login",
        minimum_score=0.7,
        enterprise=False,
        proxy_profile=None,
        allowed_crew_role="verification_specialist",
    )
}

A chave do site pública não é um segredo de conta, mas ainda deve vir de uma configuração confiável para que o modelo não redirecione a ferramenta.

Observe pageAction Em vez de Adivinhar

O documento do reCAPTCHA v3 do CapSolver lista pageAction como um campo opcional de tarefa e explica que o valor pode ser encontrado na chamada grecaptcha.execute da página.

@dataclass(frozen=True)
class PageObservation:
    target_id: str
    current_url: str
    observed_action: str
    observed_site_key: str
    form_state: str
    observed_at: str


def validate_observation(
    observation: PageObservation,
    policy: RecaptchaV3Policy,
) -> None:
    if observation.current_url != policy.website_url:
        raise PermissionError("URL observada não corresponde à política")
    if observation.observed_site_key != policy.website_key:
        raise ValueError("Chave do site observada não corresponde à política")
    if observation.observed_action != policy.page_action:
        raise ValueError("Ação da página observada não corresponde à política")
    if observation.form_state != "READY_FOR_VERIFICATION":
        raise ValueError("Estado da aplicação não está pronto")

A ferramenta deve rejeitar as discrepâncias em vez de criar um token para parâmetros incertos.

Entenda os Parâmetros do CapSolver v3

O CapSolver documenta variantes de tarefa padrão, Enterprise, proxy e sem proxy. Seu resultado pode conter gRecaptchaResponse, dados de user-agent e valores de sessão quando o modo relevante estiver ativado.

A página de produtos do CapSolver ajuda a confirmar a família de tarefas suportada antes da implementação.

Crie uma Ferramenta Tipada do CrewAI

import os
from typing import Literal

from crewai.tools import tool
from pydantic import BaseModel, Field
from capsolver_agent.schema import create_executor

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

class SolveRequest(BaseModel):
    target_id: str = Field(description="Identificador de destino registrado")
    crew_role: str = Field(description="Papel solicitando a verificação")
    observed_action: str = Field(description="Ação observada na página ativa")
    observed_site_key: str = Field(description="Chave do site observada na página ativa")
    state_id: str = Field(description="Identificador de estado do servidor da aplicação")

class SolveResult(BaseModel):
    status: Literal["verificado", "revisão_necessária", "parado"]
    target_id: str
    state_id: str
    reason: str
    task_attempted: bool

O modelo de resultado exclui deliberadamente o token, chave da API, proxy, cookies e resposta bruta do provedor.

Resolva Segredos e Submeta o Token do Lado do Servidor

PROXY_VAULT = {
    "approved_proxy": os.environ.get("APPROVED_PROXY")
}

async def submit_token_and_verify(
    *,
    state_id: str,
    token: str,
    policy: RecaptchaV3Policy,
) -> bool:
    """Função de submissão e verificação própria da aplicação."""
    response = await application_sessions.submit_recaptcha_v3(
        state_id=state_id,
        token=token,
        expected_action=policy.page_action,
    )
    return (
        response.current_url.startswith("https://approved.example.com/account")
        and response.semantic_marker == "AUTHENTICATED_ACCOUNT_PAGE"
        and response.challenge_present is False
    )

application_sessions representa seu serviço de sessão de navegador ou HTTP autorizado. A ferramenta do solucionador o usa, mas o modelo não recebe suas credenciais.

Implemente a Ferramenta Assíncrona

@tool("Resolver reCAPTCHA v3 aprovado", result_schema=SolveResult)
async def solve_approved_recaptcha_v3(
    target_id: str,
    crew_role: str,
    observed_action: str,
    observed_site_key: str,
    state_id: str,
) -> dict:
    """Resolver uma etapa registrada de reCAPTCHA v3 e verificar o estado da aplicação."""
    policy = TARGETS.get(target_id)
    if policy is None:
        return SolveResult(
            status="parado",
            target_id=target_id,
            state_id=state_id,
            reason="Destino desconhecido",
            task_attempted=False,
        ).model_dump()

    if crew_role != policy.allowed_crew_role:
        return SolveResult(
            status="parado",
            target_id=target_id,
            state_id=state_id,
            reason="Papel não é permitido para chamar esta ferramenta",
            task_attempted=False,
        ).model_dump()

    if observed_action != policy.page_action:
        return SolveResult(
            status="revisão_necessária",
            target_id=target_id,
            state_id=state_id,
            reason="Ação observada não corresponde à política de destino",
            task_attempted=False,
        ).model_dump()

    if observed_site_key != policy.website_key:
        return SolveResult(
            status="revisão_necessária",
            target_id=target_id,
            state_id=state_id,
            reason="Chave do site observada não corresponde à política de destino",
            task_attempted=False,
        ).model_dump()

    args = {
        "captcha_type": "reCaptchaV3",
        "website_url": policy.website_url,
        "website_key": policy.website_key,
        "page_action": policy.page_action,
        "min_score": policy.minimum_score,
        "enterprise": policy.enterprise,
    }
    if policy.proxy_profile:
        args["proxy"] = PROXY_VAULT[policy.proxy_profile]

    result = await executor.execute("solve_captcha", args)
    if not result.get("success"):
        return SolveResult(
            status="revisão_necessária",
            target_id=target_id,
            state_id=state_id,
            reason="Tarefa do CapSolver não foi concluída",
            task_attempted=True,
        ).model_dump()

    solution = result.get("solution") or {}
    token = solution.get("token")
    if not token:
        return SolveResult(
            status="revisão_necessária",
            target_id=target_id,
            state_id=state_id,
            reason="Resultado da tarefa não contém um token",
            task_attempted=True,
        ).model_dump()

    verified = await submit_token_and_verify(
        state_id=state_id,
        token=token,
        policy=policy,
    )
    return SolveResult(
        status="verificado" if verified else "revisão_necessária",
        target_id=target_id,
        state_id=state_id,
        reason="Estado da aplicação verificado" if verified else "Estado da aplicação não verificado",
        task_attempted=True,
    ).model_dump()

Esta implementação mantém as credenciais dentro do código confiável e fornece à equipe apenas um status seguro de política.

Anexe a Ferramenta a Um Agente

from crewai import Agent, Crew, Process, Task

verification_agent = Agent(
    role="verification_specialist",
    goal="Completar apenas etapas de verificação registradas e relatar o estado verificado",
    backstory=(
        "Você opera ferramentas de verificação aprovadas. Você nunca inventa IDs de destino, "
        "chaves do site, ações, credenciais ou estados de sucesso."
    ),
    tools=[solve_approved_recaptcha_v3],
    allow_delegation=False,
    verbose=True,
)

verification_task = Task(
    description=(
        "Para o destino registrado na observação fornecida, chame a ferramenta apenas se a URL, "
        "chave do site, ação e estado forem confirmados. Retorne o resultado estruturado sem segredos."
    ),
    expected_output="Um resultado estruturado de verificado, revisão_necessária ou parado.",
    agent=verification_agent,
)

crew = Crew(
    agents=[verification_agent],
    tasks=[verification_task],
    process=Process.sequential,
    verbose=True,
)

Não anexe a ferramenta do solucionador a todos os agentes. Limitá-la a um único papel torna a autorização e auditoria mais claras.

Evite Chamadas Repetidas à Ferramenta

from datetime import datetime, timedelta, timezone

ATTEMPTS: dict[tuple[str, str], datetime] = {}


def claim_attempt(target_id: str, state_id: str) -> bool:
    key = (target_id, state_id)
    now = datetime.now(timezone.utc)
    prior = ATTEMPTS.get(key)
    if prior and now - prior < timedelta(minutes=2):
        return False
    ATTEMPTS[key] = now
    return True

Chame claim_attempt() antes de executor.execute(). Uma mensagem repetida da equipe não deve criar um segundo token para o mesmo estado da aplicação.

Mantenha o Token Fora da Memória do Crew

Os logs de memória, rastreamento e verbose do CrewAI podem preservar a saída da ferramenta. Retorne apenas:

{
  "status": "verificado",
  "target_id": "approved_login_test",
  "state_id": "state_7c19",
  "reason": "Estado da aplicação verificado",
  "task_attempted": true
}

Nunca retorne o token, chave da API do CapSolver, valor de proxy, cookie do navegador, HTML bruto, senha ou dados de formulário pessoal.

A FAQ de erros e solução de problemas do CapSolver pode apoiar a classificação de erros do provedor sem expor a resposta bruta ao crew.

Valide a Página Após a Submissão

O validador deve exigir vários sinais independentes:

@dataclass(frozen=True)
class StateCheck:
    expected_path_prefix: str
    required_marker: str
    forbidden_markers: tuple[str, ...]


def is_verified(page, check: StateCheck) -> bool:
    return (
        page.url.path.startswith(check.expected_path_prefix)
        and page.has_semantic_marker(check.required_marker)
        and not any(page.contains(marker) for marker in check.forbidden_markers)
        and page.http_status == 200
    )

Uma URL alterada sozinha não é suficiente. Exija a rota esperada, marcador semântico, status e ausência de estados de desafio ou erro conhecidos.

Trate os Modos Enterprise e Sessão Explicitamente

CapSolver documenta variantes de Enterprise e modo de sessão opcional. Não deixe a equipe inferir essas opções.

@dataclass(frozen=True)
class RecaptchaV3Policy:
    target_id: str
    website_url: str
    website_key: str
    page_action: str
    minimum_score: float
    enterprise: bool
    is_session: bool
    proxy_profile: str | None
    allowed_crew_role: str
    max_attempts: int = 1

Se o alvo aprovado usar Enterprise, armazene esse fato na política. Se o modo de sessão for necessário, trate os valores de sessão retornados dentro do serviço de sessão da aplicação e mantenha-os fora da saída da equipe.

Resumo da Comparação

O design preferido dá autoridade de decisão ao modelo, mas mantém a autoridade de execução dentro do código confiável.

Adicione Métricas Operacionais

Rastreie campos redigidos, como:

• ID do alvo;
• papel da equipe;
• correspondência de ação observada;
• tarefa tentada;
• categoria de status do provedor;
• duração da submissão;
• página verificada;
• motivo de revisão manual.

SAFE_FIELDS = {
    "target_id",
    "crew_role",
    "action_match",
    "task_attempted",
    "provider_category",
    "duration_ms",
    "verified",
    "review_reason",
}


def safe_event(event: dict) -> dict:
    return {key: event[key] for key in SAFE_FIELDS if key in event}

A página de status do CapSolver pode ajudar a distinguir a disponibilidade do provedor de falhas específicas da aplicação.

Teste a Ferramenta Antes da Produção

import pytest

@pytest.mark.asyncio
async def test_unknown_target_stops_before_task():
    result = await solve_approved_recaptcha_v3.run(
        target_id="unknown",
        crew_role="verification_specialist",
        observed_action="login",
        observed_site_key="x",
        state_id="state-1",
    )
    assert result["status"] == "stopped"
    assert result["task_attempted"] is False

@pytest.mark.asyncio
async def test_action_mismatch_requests_review():
    result = await solve_approved_recaptcha_v3.run(
        target_id="approved_login_test",
        crew_role="verification_specialist",
        observed_action="checkout",
        observed_site_key="PUBLIC_SITE_KEY",
        state_id="state-2",
    )
    assert result["status"] == "review_required"
    assert result["task_attempted"] is False

Teste também bloqueio de tentativas duplicadas, redação de segredos, tratamento de token ausente, política Enterprise e falhas de verificação de página.

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

Checklist de Produção

• Registre cada URL de alvo, chave do site, ação, pontuação e configuração de Enterprise do lado do servidor.
• Permita que um único papel da CrewAI chame a ferramenta de solução.
• Valide a URL observada, chave do site, ação e estado antes da criação da tarefa.
• Use os parâmetros documentados do reCAPTCHA v3 do CapSolver.
• Submeta o token dentro do código da aplicação confiável.
• Retorne apenas um resultado estruturado redigido para a equipe.
• Permita uma tentativa por estado de aplicação observado.
• Verifique rota, marcador semântico, status e ausência de desafio.
• Mantenha chaves, tokens, dados de proxy, cookies e dados de formulário fora da memória e rastros.
• Direcione estados incertos ou sensíveis para um revisor humano.

A Perguntas Frequentes do CapSolver sobre resolução de CAPTCHA fornece orientação adicional sobre o ciclo de vida da tarefa.

Uso Responsável

Use um solucionador reCAPTCHA v3 da CrewAI apenas em sites que você possui, testa ou tem permissão explícita para automatizar. Respeite termos, limites de taxa, limites de autenticação, obrigações de privacidade e políticas de acesso interno. Uma chave de site pública não concede permissão para acessar um fluxo protegido. Mantenha submissões significativas, pagamentos, alterações de conta e decisões sobre dados sensíveis atrás de controles de aprovação separados.

Conclusão

Um solucionador reCAPTCHA v3 da CrewAI em produção deve ser estreito, tipado e controlado por políticas. A CrewAI pode identificar a necessidade de verificação, mas o código confiável deve resolver o alvo, chave do site, ação da página, pontuação, modo Enterprise e configurações de rede. O CapSolver deve ser executado uma vez para um estado validado, o token deve ser submetido do lado do servidor e a equipe deve receber apenas um resultado redigido após a página verificada.

Inicie uma implementação autorizada com CapSolver, teste-o em uma página controlada e adicione testes de parâmetros, chamadas duplicadas, redação e estado da página antes do uso em produção.

Perguntas Frequentes

A CrewAI pode chamar o CapSolver diretamente?

A CrewAI pode chamar uma ferramenta tipada que delega para o executor de agente documentado do CapSolver. Mantenha a resolução do alvo, segredos, submissão de token e verificação dentro do código da aplicação confiável.

Quais parâmetros do reCAPTCHA v3 são necessários?

A URL do alvo e a chave do site são necessárias. A ação da página, pontuação mínima, configuração de Enterprise, modo de sessão e proxy dependem da configuração do alvo aprovado.

O modelo deve escolher a ação da página?

Não. Observe a ação da página aprovada e compare-a com o valor da política do lado do servidor.

O token do CapSolver deve ser retornado para a equipe?

Não. Submeta-o dentro do código confiável e retorne apenas um status verificado, necessário para revisão ou interrompido.

Quantas tentativas uma tarefa da CrewAI deve fazer?

Use uma tentativa por estado de aplicação observado por padrão. Uma segunda tentativa deve exigir uma nova observação e uma decisão de política explícita.