Ferramentas de CAPTCHA de IA: Entradas Digitadas e Resultados do Solucionador

Resumo

• O Pydantic AI pode expor a resolução de CAPTCHA como uma ferramenta de função Python tipada, apoiada pelo adaptador oficial CapSolver.
• Mantenha o wrapper pequeno: receba os parâmetros documentados, chame o executor e retorne seu resultado estruturado sem inventar uma resposta bem-sucedida.
• O exemplo abaixo executa um loop real de agente Pydantic AI com TestModel e chama o catálogo de tipos suportados do adaptador instalado.
• A função de resolução é registrada, mas deliberadamente excluída dessa execução de teste; nenhuma solicitação de modelo-provedor ou resolução paga ocorre.
• A validação de tipo ajuda a descrever as entradas da ferramenta. Sua aplicação ainda decide qual página e operação são aprovadas e se a tarefa final do navegador foi bem-sucedida.

Uma ferramenta CAPTCHA do Pydantic AI fornece uma operação definida a um agente quando uma tarefa de navegador aprovada atinge um desafio suportado. O modelo não precisa inventar um algoritmo de resolução, e a aplicação não precisa de um cliente CAPTCHA novo para cada framework de agente.

O adaptador de agente CapSolver fornece a camada de execução. O Pydantic AI fornece a interface de ferramenta de função. Este guia mostra como essas peças se conectam, usando um exemplo derivado do repositório Pydantic AI mantido pelo CapSolver e um teste local que executa a operação do catálogo do adaptador real.

O que o integrador Pydantic AI adiciona?

A integração Pydantic AI transforma uma função Python tipada comum em uma ferramenta disponível para um agente. A função recebe argumentos nomeados, delega a operação CAPTCHA e retorna um resultado que o agente pode inspecionar.

Para um formulário de QA proprietário, a sequência útil é concreta: o navegador identifica um desafio suportado, a aplicação fornece os parâmetros da página, a ferramenta de solução retorna seu resultado e o navegador continua a mesma tentativa de formulário. A afirmação final pertence ao fluxo de trabalho do formulário.

Uma biblioteca de API embalagem as chamadas de serviço subjacente. Nesse caso, a documentação do CapSolver agent-tools descreve um executor que despacha operações nomeadas para a implementação central.

A documentação de ferramentas do Pydantic AI explica como as assinaturas de função e anotações contribuem para as definições de ferramentas. Três strings anotadas podem descrever a forma de entrada necessária, mas elas não estabelecem que uma URL seja aprovada ou que uma chave de site pertença à página atual.

Por que usar o adaptador oficial em vez de outro cliente HTTP?

Use o adaptador oficial quando quiser um pequeno wrapper de framework em torno da implementação de resolução documentada. Isso mantém o wrapper focado na interface do agente em vez de duplicar a criação de tarefas, recuperação e conversão de resultados.

O CapSolver mantém um repositório de exemplo Pydantic AI usando create_executor, Agent e @agent.tool_plain. É um aplicativo de exemplo, não um pacote adicional nomeado após o repositório.

O exemplo neste artigo retém a função de resolução de três argumentos e a chamada do executor do repositório. Ele muda o ambiente de demonstração para usar o TestModel do Pydantic AI e uma chamada de catálogo de tipo suportado. Isso permite que a conexão da ferramenta seja testada sem fornecer uma chave de modelo ou criar uma tarefa de resolução paga.

Essa abordagem difere de anexar um servidor MCP. As funções chamam o adaptador instalado na mesma aplicação Python; não há um processo separado de servidor MCP neste exemplo. Escolha a interface que se encaixa no seu agente existente em vez de adicionar ambas as interfaces a mesma tarefa pequena sem motivo.

Etapa 1: Instalar os pacotes testados

Instale o framework e o adaptador em um ambiente Python isolado. A execução registrada usou Python 3.12.14, pydantic-ai-slim 2.44.0, capsolver-agent 0.1.1 e capsolver-core 0.1.1.

O pacote slim fornece a funcionalidade central do Pydantic AI usada pelo TestModel sem instalar todas as integrações de modelo-provedor. As seguintes versões correspondem à execução local:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install pydantic-ai-slim==2.44.0 capsolver-agent==0.1.1 capsolver-core==0.1.1

A guia de ambiente virtual do Python descreve a criação do ambiente e a ativação específica da shell. Mantenha as versões dos pacotes com seu projeto para que a demonstração possa ser reproduzida antes de atualizar.

A demonstração do catálogo local não precisa de credencial de resolução. Uma chamada posterior solve_captcha real requer sua chave de API do CapSolver para resolução, e uma conversa de modelo real precisa do pacote e autenticação do provedor escolhido. Esses são pré-requisitos separados.

Não use uma credencial de blog-publishing como chave de resolução. A credencial do executor pertence fora do prompt do modelo e do código comprometido.

Etapa 2: Registrar as ferramentas tipadas

Salve o seguinte como quickstart.py. O wrapper de resolução segue o repositório oficial; o catálogo de ferramentas e a configuração do TestModel são a adaptação executada localmente. O código registra a ferramenta de resolução, mas não a chama.

import asyncio
import json

from capsolver_agent import create_executor
from pydantic_ai import Agent, models
from pydantic_ai.models.test import TestModel

models.ALLOW_MODEL_REQUESTS = False
capsolver = create_executor()
agent = Agent(TestModel(call_tools=["get_supported_captchas"]))


@agent.tool_plain
async def get_supported_captchas() -> str:
    """Retorne os tipos de CAPTCHA registrados sem resolver um desafio."""
    return json.dumps(await capsolver.execute("get_supported_captchas", {}))


@agent.tool_plain
async def solve_captcha(captcha_type: str, website_url: str, website_key: str) -> str:
    """Resolva um CAPTCHA suportado para um fluxo legal e autorizado pelo usuário."""
    result = await capsolver.execute(
        "solve_captcha",
        {
            "captcha_type": captcha_type,
            "website_url": website_url,
            "website_key": website_key,
        },
    )
    return json.dumps(result, ensure_ascii=False)


async def main() -> None:
    result = await agent.run("Liste os tipos de CAPTCHA suportados.")
    print(result.output)


if __name__ == "__main__":
    asyncio.run(main())

Execute o arquivo com o interpretador Python do ambiente:

python quickstart.py

O script define ALLOW_MODEL_REQUESTS como falso para evitar chamadas acidentais a um modelo não-teste. Também restringe o TestModel ao catálogo de ferramentas. Ambas as escolhas importam: evitar solicitações de modelo é diferente de evitar que uma ferramenta entre em contato com um serviço externo.

A documentação de teste do Pydantic AI explica que o TestModel pode chamar ferramentas registradas usando dados de entrada gerados. Deixar uma ferramenta de resolução paga em uma execução de teste sem restrições seria uma operação diferente da verificação de catálogo controlada mostrada aqui.

Etapa 3: Ler o resultado observado corretamente

A execução local retornou um resultado bem-sucedido de catálogo do adaptador CapSolver instalado. Ele relatou manipuladores nomeados recaptcha e cloudflare, com valores de tipo reCaptchaV2, reCaptchaV3 e cloudflare.

A saída impressa do TestModel continha a string JSON do catálogo dentro de um resumo de resultado da ferramenta. As aspas escapadas nesse resumo impresso são uma consequência de retornar JSON serializado da função; elas não são um token de CAPTCHA recém-gerado.

O wrapper oficial usa json.dumps para retornar o resultado do executor como uma string. Preserve a distinção entre essa string e o dicionário subjacente se outra componente a consumir. Analise o valor JSON relevante deliberadamente em vez de assumir que cada camada retorna a mesma forma.

O teste estabelece que o registro, a execução de ferramenta sem argumentos, o despacho do adaptador e o retorno do resultado funcionam juntos nas versões instaladas. Ele não estabelece que um LLM selecione a ferramenta de resolução correta ou que um formulário protegido específico aceite um token.

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

Como os inputs tipados se mapeiam para uma solicitação CAPTCHA?

Inputs tipados mapeiam a chamada da ferramenta do agente para o dicionário de argumentos aceito pelo adaptador. O wrapper mínimo de resolução aceita captcha_type, website_url e website_key.

Esses nomes pertencem à interface do adaptador. Eles não são uma solicitação REST literal contendo clientKey e um objeto task. Consulte o esquema da ferramenta instalada e a documentação da tarefa reCAPTCHA v2 ao conectar uma página real.

O wrapper de três campos é intencionalmente mínimo. Algumas variantes exigem contexto adicional. Não assuma que todo desafio listado pelo serviço mais amplo pode ser resolvido apenas com essas três strings, ou que os nomes de tipo do wrapper podem ser substituídos pelos nomes de tarefa REST.

Uma anotação de string não restringe a URL a um hostname aprovado. Impõe o destino e a operação permitidos na aplicação que fornece os argumentos da ferramenta. O conteúdo da página não deve poder autorizar um novo destino simplesmente solicitando ao modelo que use um.

Como o agente deve lidar com os resultados do solucionador?

O agente deve inspecionar o resultado do executor e manter o resultado CAPTCHA separado do resultado da tarefa comercial. O adaptador de agente documentado retorna um envelope de sucesso contendo uma solução, ou um envelope de falha descrevendo o erro.

Em caso de falha, a aplicação deve manter as informações de erro relevantes e decidir se entradas corrigidas, uma nova tentativa ou revisão do operador são apropriadas. Não transforme um erro em um espaço reservado com aparência de token apenas para satisfazer um campo de string subsequente.

Em caso de sucesso, passe o resultado para a componente da aplicação responsável pela mesma tentativa de desafio. A função deste guia não controla um navegador, localiza um campo de resposta, submete um formulário ou afirma a aceitação da aplicação.

Para um teste de formulário proprietário, um critério de conclusão apropriado pode ser o registro de confirmação esperado. Uma falha do solucionador e uma rejeição da aplicação devem permanecer duas observações separadas. Essa separação torna distinguível uma chave de página errada de uma falha de validação de formulário não relacionada.

Evite colocar credenciais ou tokens completos em rastreamentos rotineiros. Se o agente precisar de um resumo legível, mantenha o status operacional e os campos diagnósticos seguros, enquanto mantém o valor do resultado na componente que realmente o consome.

Como passar do TestModel para um agente real?

Mova-se para um agente real configurando o provedor de modelo desejado, fornecendo sua autenticação e habilitando apenas as operações ao vivo que a aplicação precisa. Mantenha os wrappers de ferramentas testados e inspecione as chamadas reais da ferramenta do novo modelo.

O TestModel da demonstração é infraestrutura de teste procedural, não um modelo de linguagem. Sua escolha bem-sucedida de catálogo não mede o raciocínio do modelo. Uma conversa real pode produzir um parâmetro ausente, selecionar a ferramenta errada ou solicitar outra operação, então a aplicação ainda deve verificar seus inputs.

Comece com uma página QA proprietária e uma variante de desafio documentada. Forneça a URL real da página e a chave pública do site da aplicação, depois valide o resultado do solucionador e a resposta final do formulário. Registre falhas por etapa em vez de reduzir todo o experimento a se o texto apareceu em uma resposta do agente.

O guia mais amplo de resolução de CAPTCHA para empresas discute a adoção da equipe. Este exemplo de framework estabelece uma base mais estreita: registro de função tipada e execução real do adaptador com uma operação controlada, não de resolução.

Tente o CapSolver para o desafio suportado em sua tarefa aprovada uma vez que essa conexão local seja compreendida. Mantenha o escopo de cada teste explícito: registro de ferramenta, seleção de modelo, resolução paga e aceitação do navegador são verificações diferentes.

Perguntas frequentes

Q: Há um pacote separado pydantic-ai-capsolver?

O repositório referenciado contém exemplos usando o Pydantic AI e a biblioteca oficial de agente do CapSolver. Este tutorial instala essas bibliotecas diretamente em vez de assumir que o nome do repositório é um pacote.

Q: O TestModel chama o serviço real de CAPTCHA?

O TestModel pode executar ferramentas registradas, então a ferramenta selecionada determina o que acontece. Este exemplo chama explicitamente apenas o catálogo de tipos suportados e não invoca uma solicitação de resolução.

Q: Os inputs de string tipados são suficientes para aprovar uma página de destino?

Não. As anotações de tipo descrevem a forma de entrada. A aplicação deve impor a URL, tarefa e contexto permitidos separadamente.

Q: Por que o resultado impresso contém JSON escapado?

O wrapper retorna JSON serializado, e o TestModel inclui essa string em seu resumo de saída. Trate cada camada de serialização deliberadamente em vez de assumir que o resumo é um objeto de solução simples.

Q: Este wrapper exato pode lidar com toda variante de CAPTCHA?

Nenhuma cobertura é estabelecida aqui. A função mínima aceita três parâmetros; variantes que exigem contexto adicional exigem os campos e validação documentados correspondentes.

Q: Um CAPTCHA real foi resolvido durante o teste?

Não. O framework e adaptador instalados executaram uma operação real de catálogo usando o TestModel. Uma resolução real e aceitação por uma aplicação proprietária permanecem testes separados que exigem as credenciais apropriadas e página.