Como Retornar Resultados de Ferramentas CAPTCHA que um Agente de IA Possa Usar

TL;DR

• Devolva um resultado de ferramenta de CAPTCHA que distinga erro de ferramenta, erro de serviço, tarefa pendente e solução pronta para o navegador.
• Uma resposta MCP chegando com sucesso não significa que a operação de CAPTCHA foi bem‑sucedida.
• Com a API direta, inspecione errorId antes de interpretar status ou solution.
• Mantenha o resultado do solver separado do estado de conclusão da tarefa do navegador.
• Dê ao agente um breve resumo operacional; mantenha credenciais e valores completos de solução fora de logs rotineiros visíveis ao modelo.

Um agente de navegador pode receber uma resposta de ferramenta válida e ainda assim não ter nada útil a fazer em seguida. A resposta pode conter um erro de validação, uma tarefa não concluída ou uma solução que a página não aceitou. Transformar os três na mesma mensagem de “concluído” faz o agente continuar cedo demais.

O CapSolver expõe operações de CAPTCHA por meio de APIs diretas e interfaces para agentes. A interface escolhida determina o formato do resultado. Este guia explica como interpretar esses formatos e projetar um pequeno resumo para a aplicação sem inventar novos campos do provedor.

O caso de uso concreto é um agente operando um formulário de teste próprio. O navegador chega a um CAPTCHA compatível, o solver selecionado é executado e a aplicação decide se deve esperar, corrigir entradas, aplicar um resultado ou parar. A pergunta aqui é: qual evidência deve controlar essa decisão.

Que resultado você está realmente lendo?

Identifique a camada da resposta antes de ler um campo chamado success ou status.

Há três camadas úteis: o transporte da ferramenta, a operação de CAPTCHA e a tarefa do navegador. Uma API define uma interface específica; sua resposta deve ser interpretada dentro desse contrato. Um wrapper de ferramenta pode adicionar outro envelope, e a aplicação pode adicionar seu próprio status de fluxo de trabalho.

Camada	Pergunta que responde	O que não pode estabelecer sozinha
Transporte MCP/ferramenta	A chamada da ferramenta retornou ou relatou um erro de ferramenta?	Se existe uma solução de CAPTCHA utilizável
Serviço de CAPTCHA	A operação de resolução falhou, segue pendente ou produziu o resultado documentado?	Se o formulário ou página pretendidos aceitaram esse resultado
Navegador/aplicação	A operação pretendida atingiu o estado esperado?	Se todo diagnóstico anterior foi corretamente registrado

Mantenha o resultado original disponível para depuração. Se sua aplicação normalizar resultados, rotule seus campos como pertencentes à aplicação. Não apresente um campo interno conveniente como workflow_state como se fosse um campo documentado da API do CapSolver.

Como ler uma resposta MCP de CAPTCHA?

Verifique o sinal de erro de ferramenta MCP e então inspecione o payload de acordo com o próprio contrato da ferramenta.

A especificação de ferramentas MCP descreve o conteúdo do resultado da ferramenta e o sinalizador isError. Bibliotecas cliente podem expor isso com um nome diferente na linguagem de programação. Por exemplo, os resultados de ferramentas do FastMCP expõem .is_error, .content e dados já parseados.

Não presuma que toda resposta de ferramenta é um dicionário JSON “cru”. Alguns servidores retornam conteúdo de texto contendo JSON serializado; alguns também fornecem conteúdo estruturado. Leia a propriedade documentada do cliente e só faça o parse da camada que realmente contém JSON. Procurar a palavra “success” em toda a string de resposta é pouco confiável.

Em um teste de conexão local com FastMCP 3.4.11 e capsolver-mcp 0.1.3, uma chamada propositalmente incompleta para solve_captcha retornou um erro de ferramenta identificando as entradas ausentes website_url e website_key. Uma chamada de registro separada retornou com sucesso. Essas observações confirmam o caminho de leitura de erro e a execução do registro, não a resolução paga.

Uma ferramenta também pode retornar um envelope MCP normal que contenha uma falha em nível de serviço. Portanto, “sem exceção de ferramenta” é apenas a primeira verificação. Em seguida, inspecione o resultado de negócio documentado para aquela ferramenta específica. Não traduza os campos da API direta para campos MCP por adivinhação.

Para um exemplo específico de registro em um framework, o guia de ferramentas do Pydantic AI cobre entradas tipadas e execução do adaptador. O foco aqui é a decisão após a chegada de uma resposta, independentemente de qual framework registrou a ferramenta.

Como ler o resultado da API direta de CAPTCHA?

Com a API direta, comece com errorId e então siga o estado de tarefa documentado.

As referências de createTask e getTaskResult definem esse fluxo. Uma criação de tarefa bem‑sucedida pode retornar um identificador de tarefa para recuperação posterior. Esse identificador é um handle da operação, não a resposta resolvida.

Para um resultado obtido por polling, uma resposta de erro deve ser tratada antes de ler uma solução. Os estados documentados idle e processing são estados não concluídos. Continue o fluxo existente de recuperação dentro do prazo configurado; a referência instrui os chamadores a esperar três segundos antes de tentar novamente após um resultado em processamento. Um resultado pronto ainda deve conter o formato de solução documentado para aquele tipo de tarefa.

Observação da resposta	Interpretação	Ação da aplicação
errorId diferente de zero	O serviço relata um erro	Preserve errorCode e errorDescription; escolha corrigir ou parar
Tarefa aceita, resultado ainda em processamento	Ainda não há solução final	Faça polling da mesma tarefa dentro dos limites documentados
Resultado pronto com campo de solução esperado	Uma solução candidata está disponível	Passe‑a para o componente responsável pelo mesmo desafio
Campos de resultado ausentes ou inesperados	Contrato não estabelecido	Pare a interpretação e inspecione a resposta; não fabrique um token
Navegador confirma a tarefa pretendida	Resultado da aplicação estabelecido	Registre a conclusão do fluxo de trabalho separadamente

Alguns tipos de tarefa podem ser concluídos de forma síncrona. Siga a resposta documentada para o tipo selecionado em vez de forçar toda tarefa a um loop de polling. Por outro lado, não chame createTask repetidamente só porque um resultado assíncrono ainda não está pronto.

A referência de reCAPTCHA v2 descreve seus campos de solução. Outras famílias de tarefas podem retornar dados diferentes. Um wrapper que presume que todo resultado contém o mesmo campo de token pode descartar silenciosamente uma resposta válida ou confundir um campo não relacionado com um token.

Resgate Seu Código de Bônus CapSolver

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

O que sua aplicação deve retornar ao agente?

Retorne informação suficiente para o próximo passo permitido do agente, enquanto mantém os detalhes do serviço no componente que os consome.

Um pequeno resumo da aplicação pode conter a etapa da operação, um resultado normalizado, uma explicação segura e a próxima ação permitida. Esses são campos da sua aplicação, não um substituto para a resposta do provedor.

Por exemplo, após uma resposta pendente da API direta, o resumo pode dizer: “A tarefa de CAPTCHA está em processamento; continue aguardando a tarefa existente.” Após um erro de entrada, pode dizer: “A requisição está incompleta; obtenha os parâmetros de página ausentes antes de outra tentativa.” Após um resultado do solver, pode dizer: “Uma solução está disponível; a verificação pelo navegador está pendente.”

Note o que essas mensagens evitam: nenhuma afirma que um formulário foi enviado ou que uma requisição de dados foi concluída. O navegador deve fornecer essa evidência mais tarde.

Uma implementação prática mantém dois registros. O registro operacional armazena a referência da tarefa, campos de diagnóstico seguros e transições de estágio. O componente de navegador mantém temporariamente o valor da solução de que precisa. O resumo voltado ao modelo aponta para a próxima ação permitida sem copiar o token completo para uma resposta conversacional.

Se a aplicação aceita saídas estruturadas do modelo, valide essas saídas contra o seu próprio schema. Um schema válido estabelece o formato, não a veracidade. O modelo não deve poder transformar uma observação de solver pendente em um resultado concluído no navegador apenas retornando uma string de status diferente.

Quais erros devem levar a uma nova tentativa?

Escolha a próxima ação a partir da descrição de erro e do estado atual da página, não a partir de uma regra universal de retry.

A referência oficial de erros distingue dados inválidos, tarefas não suportadas, credenciais, limites e falhas de resolução. Essas categorias exigem tratamentos diferentes. Repetir o envio do mesmo payload inválido não corrige seus campos. Iniciar outra tarefa paga não conserta uma credencial ausente.

Use uma sequência de decisão compacta:

1. Se a validação da ferramenta falhou, corrija os argumentos ausentes ou malformados antes de chamar novamente.
2. Se o serviço retornou um erro, preserve seu código e descrição e siga a ação documentada relevante.
3. Se a tarefa ainda está em processamento, continue o fluxo de recuperação existente dentro do prazo.
4. Se uma solução está disponível, passe‑a para a tentativa atual do navegador e verifique o estado esperado da página.
5. Se a página mudou ou a tarefa foi abandonada, não aplique o resultado antigo a uma nova tentativa.

Um encerramento com limite é um resultado útil. “Não foi possível concluir esta etapa” com um motivo preciso é mais acionável do que uma string vazia que faça o agente se comportar como se a resolução tivesse sido bem‑sucedida.

O que prova que a tarefa do navegador foi concluída?

A aplicação deve observar o resultado esperado da tarefa original após a etapa de CAPTCHA.

Para um formulário de teste próprio, defina essa condição antes de invocar o solver: talvez um elemento de confirmação conhecido e o registro de envio de teste correspondente. Um iframe desaparecendo, um campo de resposta sendo preenchido ou uma ferramenta retornando um token podem ser evidências intermediárias úteis, mas cada uma é mais fraca do que o resultado final pretendido da aplicação.

A documentação de verificação do Google reCAPTCHA explica a etapa de verificação no lado do servidor. É por isso que um token retornado ao navegador não deve ser confundido com aceitação pela aplicação receptora.

Quando um fluxo de trabalho falha, preserve o último estágio estabelecido. “Solver retornou; aplicação rejeitou” é diferente de “solver nunca retornou”. A distinção evita que uma sessão de depuração mude a requisição ao solver quando o problema real é um campo obrigatório não relacionado no formulário.

O que testar antes de habilitar o fluxo de trabalho?

Teste os ramos de resultado de forma independente e, depois, execute um teste ponta a ponta permitido com credenciais reais e uma página própria.

Inclua uma falha de validação de entrada, um fixture de erro de serviço, uma resposta de processamento, uma resposta pronta, um payload inesperado e uma rejeição do navegador após uma solução candidata. Fixtures testam as decisões da sua aplicação; eles não comprovam o comportamento da API em produção nem a aceitação do CAPTCHA.

Teste também uma resposta que chega depois que a aplicação parou de esperar. A aplicação deve preservar seu estado de parada em vez de permitir que um resultado tardio retome um formulário abandonado. Mantenha o resultado associado à tentativa original.

As verificações deste artigo estabelecem a interpretação documentada de respostas e um caminho real de validação/registro MCP. Elas não constituem um benchmark de resolução paga, um estudo de caso implantado em cliente ou uma medição de taxas de sucesso de agentes.

Construa Fluxos de Automação Confiáveis com CapSolver

Torne o resultado de CAPTCHA acionável preservando seu estado real e verificando o resultado no navegador. O CapSolver fornece a interface de solver documentada para essa etapa. Experimente o CapSolver com um fluxo de teste permitido e mantenha a verificação final da aplicação separada.

FAQ

P: isError falso significa que o CAPTCHA foi resolvido?

Não. Significa que a resposta da ferramenta não foi marcada como erro de execução da ferramenta. Inspecione o resultado de negócio documentado no payload e então verifique a tarefa do navegador separadamente.

P: O agente deve receber o token completo de CAPTCHA?

Apenas se o componente que consome o token realmente precisar dele. Muitos designs podem manter o valor no estado da aplicação e fornecer ao modelo apenas um status curto.

P: Posso usar o mesmo parser de resultado para REST e MCP?

Somente após adaptar explicitamente seus diferentes contratos de resposta. Um resultado de tarefa REST e um envelope de ferramenta MCP não são objetos intercambiáveis.

P: O que devo retornar quando o resultado ainda está em processamento?

Retorne um status pendente no formato da sua aplicação e continue recuperando a tarefa existente dentro do seu prazo. Não o rotule como concluído nem crie outra tarefa apenas porque a primeira não foi finalizada.

P: E se o solver retornar um resultado mas o formulário falhar?

Registre a conclusão do solver e a falha da aplicação separadamente. Inspecione a rejeição da página e o contexto atual da tarefa antes de decidir se uma nova tentativa de CAPTCHA é apropriada.