如何返回可供 AI 代理使用的 CAPTCHA 工具结果

摘要

• 返回的 CAPTCHA 工具结果需要能区分：工具错误、服务错误、任务进行中以及浏览器可用的解决方案。
• MCP 响应成功到达并不代表 CAPTCHA 操作本身成功。
• 使用直连 API 时，在解读 status 或 solution 之前先检查 errorId。
• 将求解器的结果与浏览器任务的完成状态分开处理。
• 只给代理一个简短的操作性摘要；不要在常规对模型可见的日志中暴露凭证和完整解题数据。

浏览器代理可能收到一个语义上“有效”的工具响应，但下一步仍然无事可做：该响应可能只包含校验错误、尚未完成的任务，或者一个页面尚未接受的解决方案。如果把这三种情况都统一包装成“完成”的消息，就会让代理过早继续后续步骤。

CapSolver 通过直连 API 和代理接口暴露 CAPTCHA 操作。你选择的接口会决定结果的结构。本指南说明如何解读这些结构，并在不虚构新字段的前提下设计一个小型应用摘要。

本文的具体场景是：一个代理操作自有的测试表单。浏览器访问到受支持的 CAPTCHA，选择好的求解器开始运行，应用随后决定是继续等待、修正输入、应用结果，还是停止。问题在于：哪些证据应该驱动这个决策。

你到底在读哪一层结果？

在阅读名为 success 或 status 的字段之前，先确认你在解读哪一层响应。

有三层有用的结果：工具传输层、CAPTCHA 操作层和浏览器任务层。API 定义了具体接口；其响应应在该契约内解读。工具封装器可能会再加一层包裹，而应用则可能添加自己的工作流状态。

层级	回答的问题	无法单独确定的内容
MCP/工具传输	工具调用是否返回，还是报出工具错误？	是否存在可用的 CAPTCHA 解题结果
CAPTCHA 服务	求解操作是失败、仍在进行中，还是已输出文档说明的结果？	目标表单或页面是否接受了该结果
浏览器/应用	目标操作是否达到预期状态？	之前每一步诊断是否都被正确记录

保留原始结果用于调试。如果你的应用会对结果进行归一化处理，请将这些字段标注为应用自有字段。不要把类似 workflow_state 这样内部便捷字段当作 CapSolver API 的官方字段对外展示。

如何解读 MCP CAPTCHA 响应？

先检查 MCP 工具错误信号，再按照工具自己的契约检查负载内容。

MCP 工具规范 描述了工具结果的内容和 isError 标志。客户端库可能会用不同语言风格的名字暴露这些内容。例如，FastMCP 工具结果 提供 .is_error、.content 以及解析后的数据。

不要假设每个工具响应都是一个裸 JSON 字典。有些服务器会返回包含序列化 JSON 的文本内容，有些还会提供结构化内容。先读取文档中定义的客户端属性，然后只解析真正包含 JSON 的那一层。对整个响应字符串搜索 “success” 一词是不可靠的。

在一次使用 FastMCP 3.4.11 和 capsolver-mcp 0.1.3 的本地连接测试中，一个刻意缺少参数的 solve_captcha 调用返回了工具错误，指出缺少 website_url 和 website_key 输入。而一次单独的注册表调用则顺利返回。这些观察只证明了错误读取路径和注册表执行路径是通的，而不是说明付费求解成功。

工具也可能返回一个正常的 MCP 外层结构，内部却包含服务级失败结果。因此，“没有工具异常”只是第一道检查。接着要检查该工具自己文档化的业务结果。不要凭想象把直连 API 的字段硬映射成 MCP 字段。

关于特定框架的注册示例，Pydantic AI 工具指南 涵盖了类型化输入和适配器执行。本文关注的是响应到达之后的决策步骤，而不管工具是由哪个框架注册的。

如何解读直连 CAPTCHA API 结果？

使用直连 API 时，从 errorId 开始，再按文档规定的任务状态继续判断。

createTask 参考文档 和 getTaskResult 参考文档 定义了基本流程。任务创建成功时，返回的可能是一个任务标识符，用于后续结果拉取。此标识符只是操作句柄，而不是最终的解题答案。

在轮询结果时，必须先处理错误响应，再去读取解决方案。文档中的 idle 和 processing 都属于未完成状态。应在配置的时限内继续现有的结果拉取流程；参考文档建议在收到 processing 状态后等待三秒再重试。就绪结果仍然必须包含该任务类型文档化的解决方案字段结构。

响应现象	含义	应用行为
errorId 非零	服务报告错误	记录 errorCode 和 errorDescription；决定是纠正还是停止
任务已接受，结果仍在处理	尚无最终解决方案	在文档规定的限制内继续轮询同一任务
就绪结果包含预期的解决方案字段	候选解决方案可用	将其传给负责同一挑战的组件
结果字段缺失或与预期不符	契约未成立	停止解读并检查响应；不要伪造 token
浏览器确认预期任务完成	应用结果已确定	单独记录工作流完成状态

有些任务类型可以同步完成。按照所选任务类型的文档化返回格式来处理，而不是强行把所有任务都拉进一个轮询循环。反之，也不要因为异步结果暂未就绪，就反复调用 createTask。

reCAPTCHA v2 参考文档 说明了其解决方案字段。其他任务家族可能返回不同的数据。如果封装器武断地假设每个结果都包含同一个 token 字段，就可能悄悄丢弃一个有效答案，或者错把无关字段当成 token。

兑换你的 CapSolver 优惠码

立即提升你的自动化预算！
充值 CapSolver 账号时使用优惠码 CAP26，每次充值都可额外获得 5% 奖金，无次数上限。
现在就前往 CapSolver 控制台 兑换

应用应该向代理返回什么？

返回足够支撑代理执行下一步许可动作的信息，同时在消费服务数据的组件中保留详细信息。

一个小型应用摘要可以包括：当前操作阶段、归一化的结果状态、安全可暴露的解释以及下一步允许动作。这些都是应用自有字段，而不是对服务端响应的替代。

例如，在收到直连 API 的“处理中”响应后，摘要可以是：“CAPTCHA 任务正在处理；请继续等待现有任务。”在输入错误之后，可以是：“请求不完整；在下次尝试前获取缺失的页面参数。”在求解结果返回之后，可以是：“已有解题结果；等待浏览器验证。”

注意这些消息刻意避免了什么：没有任何一句声称表单已提交或数据请求已完成。浏览器必须在之后提供这些证据。

一个实用实现通常会维护两份记录：运行记录中存储任务引用、安全的诊断字段以及阶段变更；浏览器组件临时持有它需要的解决方案值；面向模型的摘要只指出下一步允许的操作，而不把完整 token 放进对话答案里。

如果应用允许模型返回结构化输出，请根据应用自己的 schema 校验这些输出。一个有效的 schema 只能保证“形状”正确，而不能证明内容真实。模型不应仅通过回传一个不同的状态字符串，就把“求解器仍在等待”改写成“浏览器已完成”。

哪些错误应该触发再次尝试？

根据错误描述和当前页面状态选择下一步动作，而不是依赖一条通用的“重试”规则。

官方错误参考 区分了：无效数据、不支持的任务、凭证问题、额度/限制以及求解失败。这几类情况需要不同处理。对同一无效请求 payload 反复重试，并不能修正其字段；开启新的付费任务也无法弥补缺失的凭证。

可以用一个简洁的决策序列：

1. 如果工具级校验失败，在再次调用前修正缺失或格式错误的参数。
2. 如果服务返回错误，记录其错误码和描述，并按文档中对该错误的建议进行处理。
3. 如果任务仍在处理，在其时限内继续既有的结果拉取流程。
4. 如果已存在解决方案，将其应用到当前浏览器尝试上，并验证页面是否达到预期状态。
5. 如果页面已变更或该任务已放弃，不要把旧结果应用到新的尝试中。

一次有界的停止本身就是有价值的结果。“无法完成该步骤”且原因准确，比一个空字符串要更能支撑代理做出正确行为；空字符串往往会让代理误以为求解成功。

什么才算证明浏览器任务完成？

应用必须在 CAPTCHA 步骤之后观察到原始任务的预期结果。

对于自有测试表单，在调用求解器之前就要定义这个条件：可能是一个已知的确认元素，以及相应的测试提交记录。iframe 消失、某个响应字段被填充、某个工具返回了 token，这些都只是有用的中间证据，但它们都不如“目标应用结果”本身有力。

Google 的 reCAPTCHA 验证文档 解释了服务器端验证步骤。这也是为什么“浏览器收到了一个 token”不应与“接收方应用已接受该请求”混为一谈。

当某个工作流失败时，应记录最后一次已确认的阶段。“求解器返回了结果；应用拒绝了它”与“求解器从未返回”是截然不同的情况。这个区分能避免在调试时去误改求解请求，而真正的问题其实是表单里另一项必填字段缺失。

在启用完整工作流之前应测试什么？

先独立测试各个结果分支，再使用真实凭证和自有页面做一次合规的端到端测试。

测试内容应包括：输入校验失败、服务错误样例、处理中响应、就绪响应、异常 payload，以及在获得候选解决方案后浏览器仍然拒绝的情形。样例只验证你的应用决策逻辑本身，并不能证明线上 API 行为或 CAPTCHA 接受情况。

还要测试这样一种情况：当应用已停止等待时才收到响应。此时应用应保持“已停止”的状态，而不是因为迟到的结果而重新唤醒一个已放弃的表单。要把结果与其原始尝试绑定在一起。

本文中的这些检查，旨在建立对文档化响应的正确解读方式，以及真实的 MCP 校验/注册路径。它们不构成任何付费求解性能基准、已部署客户案例或代理成功率测量。

使用 CapSolver 构建可靠的自动化工作流

通过保留 CAPTCHA 的真实状态并检查浏览器结果，可以让求解结果真正可用。CapSolver 为这一环节提供了文档化的求解接口。请在一个合规的测试工作流中试用 CapSolver，并将最终的应用检查与求解过程分离开来。

常见问题

问：isError 为 false 是否意味着 CAPTCHA 已被成功求解？

不意味着。它只表示工具响应未被标记为“工具执行错误”。你仍需检查负载中已文档化的业务结果，然后再单独验证浏览器任务。

问：代理是否应该接收到完整的 CAPTCHA token？

只有在真正消费该 token 的组件确实需要时才需要。很多设计都可以只在应用状态中保存该值，而只向模型给出一个简短状态。

问：我能否对 REST 和 MCP 使用同一个结果解析器？

只有在显式适配了它们不同的响应契约之后才可以。REST 任务结果和 MCP 工具包裹并不是可以互换的对象。

问：当结果仍在处理中时，我应该返回什么？

用你自己应用的格式返回一个“处理中”状态，并在时限内持续拉取该任务的结果。不要把它标记为“已完成”，也不要仅因为第一个任务还没完成就新建一个任务。

问：如果求解器返回了结果，但表单仍然失败怎么办？

分别记录“求解器已完成”和“应用失败”这两件事。在决定是否需要新的 CAPTCHA 尝试之前，先检查页面的拒绝原因以及当前任务上下文。