AI代理 reCAPTCHA v3 求解器：集成指南和示例

简要说明

• AI代理的reCAPTCHA v3求解器必须保留授权工作流使用的精确页面操作和浏览器上下文。
• 官方代理层涵盖reCAPTCHA v2、reCAPTCHA v3（包括企业版）和Cloudflare Turnstile。
• 对于已知站点参数使用令牌模式，当需要检测并填充实时页面时使用浏览器模式。
• 路由更改、动作不匹配、重复挑战或应用断言失败必须进入审核，而不是自主重试。

介绍

AI代理的reCAPTCHA v3求解器只有在代理保留产生挑战的操作、页面、浏览器会话和授权上下文时才可靠。CapSolver通过Core SDK、Agent Tools和MCP提供经过文档记录的CAPTCHA基础设施层。代理仍然拥有策略、重试和原始任务确认的控制权。本指南解释了reCAPTCHA v3（包括企业版）的生产级集成，不将返回的令牌视为最终成功信号。它展示了真实的包和方法名称，区分了浏览器模式和令牌模式，并定义了过期页面、更改操作、不支持的挑战和重复失败的停止条件。仅在您被授权访问的系统和数据上使用此工作流进行合法、合理、负责任的自动化。

仅使用官方AI CAPTCHA界面

AI代理reCAPTCHA v3求解器的产品边界由CapSolver for AI Agents、Core SDK、Agent Tools、MCP Service定义。Core SDK提供create_capsolver、detect、get_captcha_info、solve和solve_on_page。Agent Tools提供get_all_tools、create_executor及其记录的执行路径。MCP暴露solve_captcha、detect_captchas、solve_on_page、get_balance和get_supported_captchas。仅使用capsolver-core、capsolver-agent和capsolver-mcp及其真实名称。当前代理层仅限于reCAPTCHA v2、reCAPTCHA v3（包括企业版）和Cloudflare Turnstile。

输入是经过批准的HTTPS页面URL、公开站点密钥和观察到的页面操作。执行器返回的结构化工具结果必须与该页面上下文绑定。当批准的URL或操作缺失时，本地包装器在调用前停止，协调器在一次应用检查失败或任何上下文更改后必须停止。

import os
from capsolver_agent.schema import get_all_tools, create_executor

executor = create_executor(api_key=os.environ["CAPSOLVER_API_KEY"])
tools = [tool.to_openai_function() for tool in get_all_tools()]

async def run_recaptcha_v3(website_url, website_key, page_action):
    if not website_url.startswith("https://") or not page_action:
        return {"state": "REVIEW", "reason": "missing approved URL or action"}
    result = await executor.execute("solve_captcha", {
        "captcha_type": "reCaptchaV3",
        "website_url": website_url,
        "website_key": website_key,
        "page_action": page_action,
    })
    return {"state": "VERIFY_APPLICATION", "result": result}

选择令牌模式或浏览器模式

AI代理reCAPTCHA v3求解器在此阶段需要定义集成路径。记录已知站点参数、实时Playwright页面、页面操作、企业标志、浏览器所有权和最终断言作为一个检查点，而不是不相关的日志消息。这些值解释了自动化所相信的内容、观察到的内容以及为何被允许继续。操作规则是在代理调用工具前选择一个控制平面。保守边界是当调用者无法证明哪个浏览器上下文拥有挑战时停止。没有该边界，技术上成功的API调用可能被错误地附加到错误的页面、错误的账户、错误的业务对象或过期的浏览器会话。

必要证据：已知站点参数

从已知站点参数开始，然后将其绑定到实时Playwright页面、页面操作和企业标志。使用类型化字段和显式未知值。每条记录应包含观察到的时间戳、关联ID、授权目的和做出决策的组件。避免将凭证、完整Cookie、原始解决方案值或不必要的页面内容复制到记录中。缺失的证据必须保持缺失；方便的默认值永远不能看起来像真实观察。

当前数据包应与同一授权工作单元的最后一个有效数据包进行比较。实时Playwright页面的变化可能是预期的，而页面操作的变化可能会使任务失效。发出一个小的状态集，如ACCEPT、RETRY_ONCE、REVIEW或STOP，并附带原因代码。操作遥测可以遵循W3C追踪上下文，同时将凭证、Cookie、原始解决方案值和不必要的页面内容排除在日志之外。

失败边界：当调用者无法证明哪个浏览器上下文拥有挑战时停止

停止条件是实现的一部分。当工作流必须在调用者无法证明哪个浏览器上下文拥有挑战时停止时，取消待处理的子任务，保留经过脱敏的证据摘要，释放队列锁，并防止后台重试继续使用过期状态。后续的操作员批准运行应从新的浏览器或任务检查点开始并重新评估范围。这使得AI代理reCAPTCHA v3求解器在负载下可解释，并防止单个模糊页面变成重试风暴。

reCAPTCHA v3评分诊断增加了相邻的实现上下文，而此工作流保持了更窄的集成路径合同明确。此阶段的输出是机器可读的决策和重现所需的最小证据。这不是忽略条款、访问控制、数据权利、速率限制或账户边界的许可。当证据不完整时，审核状态是有效结果。

捕获v3操作和企业上下文

AI代理reCAPTCHA v3求解器在此阶段需要定义参数保真度。记录网站URL、网站密钥、页面操作、企业状态、可选的s值和观察时间作为一个检查点，而不是不相关的日志消息。这些值解释了自动化所相信的内容、观察到的内容以及为何被允许继续。操作规则是从授权的实时页面读取参数。保守边界是将不完整或矛盾的企业证据发送到审核。没有该边界，技术上成功的API调用可能被错误地附加到错误的页面、错误的账户、错误的业务对象或过期的浏览器会话。

类型化检查点：网站URL

从网站URL开始，然后将其绑定到网站密钥、页面操作和企业状态。使用类型化字段和显式未知值。每条记录应包含观察到的时间戳、关联ID、授权目的和做出决策的组件。避免将凭证、完整Cookie、原始解决方案值或不必要的页面内容复制到记录中。缺失的证据必须保持缺失；方便的默认值永远不能看起来像真实观察。

当前数据包应与同一授权工作单元的最后一个有效数据包进行比较。网站密钥的变化可能是预期的，而页面操作的变化可能会使任务失效。发出一个小的状态集，如ACCEPT、RETRY_ONCE、REVIEW或STOP，并附带原因代码。证据保留应符合OWASP日志指南，同时将凭证、Cookie、原始解决方案值和不必要的页面内容排除在日志之外。

一致性测试：发送不完整或矛盾的企业证据到审核

停止条件是实现的一部分。当工作流必须发送不完整或矛盾的企业证据到审核时，取消待处理的子任务，保留经过脱敏的证据摘要，释放队列锁，并防止后台重试继续使用过期状态。后续的操作员批准运行应从新的浏览器或任务检查点开始并重新评估范围。这使得AI代理reCAPTCHA v3求解器在负载下可解释，并防止单个模糊页面变成重试风暴。

OpenAI代理reCAPTCHA v3工作流增加了相邻的实现上下文，而此工作流保持了更窄的参数保真度合同明确。此阶段的输出是机器可读的决策和重现所需的最小证据。这不是忽略条款、访问控制、数据权利、速率限制或账户边界的许可。当证据不完整时，审核状态是有效结果。

仅暴露经过文档记录的代理工具

AI代理reCAPTCHA v3求解器在此阶段需要定义工具合同。记录get_all_tools输出、create_executor配置、solve_captcha输入、结构化结果、模型消息和策略门作为检查点，而不是不相关的日志消息。这些值解释了自动化所相信的内容、观察到的内容以及为何被允许继续。操作规则是保持工具模式稳定且策略在提示之外。保守边界是拒绝未识别的工具名称、字段或挑战家族。没有该边界，技术上成功的API调用可能被错误地附加到错误的页面、错误的账户、错误的业务对象或过期的浏览器会话。

决策记录：get_all_tools输出

从get_all_tools输出开始，然后将其绑定到create_executor配置、solve_captcha输入和结构化结果。使用类型化字段和显式未知值。每条记录应包含观察到的时间戳、关联ID、授权目的和做出决策的组件。避免将凭证、完整Cookie、原始解决方案值或不必要的页面内容复制到记录中。缺失的证据必须保持缺失；方便的默认值永远不能看起来像真实观察。

当前数据包应与同一授权工作单元的最后一个有效数据包进行比较。create_executor配置的变化可能是预期的，而solve_captcha输入的变化可能会使任务失效。发出一个小的状态集，如ACCEPT、RETRY_ONCE、REVIEW或STOP，并附带原因代码。控制边界与NIST AI风险管理框架一致，同时将凭证、Cookie、原始解决方案值和不必要的页面内容排除在日志之外。

停止条件：拒绝未识别的工具名称、字段或挑战家族

停止条件是实现的一部分。当工作流必须拒绝未识别的工具名称、字段或挑战家族时，取消待处理的子任务，保留经过脱敏的证据摘要，释放队列锁，并防止后台重试继续使用过期状态。后续的操作员批准运行应从新的浏览器或任务检查点开始并重新评估范围。这使得AI代理reCAPTCHA v3求解器在负载下可解释，并防止单个模糊页面变成重试风暴。

输出此阶段是机器可读的决策和重现所需的最小证据。这不是忽略条款、访问控制、数据权利、速率限制或账户边界的许可。当证据不完整时，审核状态是有效结果。

领取您的CapSolver优惠码

立即提升您的自动化预算！
在充值CapSolver账户时使用优惠码 CAP26，每次充值可获得额外 5% 的奖励 —— 无限制。
现在在您的 CapSolver仪表板 中领取

将结果绑定到相同的代理检查点

AI代理reCAPTCHA v3求解器在此阶段需要定义上下文绑定。记录运行ID、浏览器上下文、主机名、路由、操作、挑战时间戳和尝试次数作为检查点，而不是不相关的日志消息。这些值解释了自动化所相信的内容、观察到的内容以及为何被允许继续。操作规则是在结果使用前比较检查点。保守边界是导航、刷新、注销或操作漂移后丢弃结果。没有该边界，技术上成功的API调用可能被错误地附加到错误的页面、错误的账户、错误的业务对象或过期的浏览器会话。

验证数据包：运行ID

从运行ID开始，然后将其绑定到浏览器上下文、主机名、路由。使用类型化字段和显式未知值。每条记录应包含观察到的时间戳、关联ID、授权目的和做出决策的组件。避免将凭证、完整Cookie、原始解决方案值或不必要的页面内容复制到记录中。缺失的证据必须保持缺失；方便的默认值永远不能看起来像真实观察。

当前数据包应与同一授权工作单元的最后一个有效数据包进行比较。浏览器上下文的变化可能是预期的，而主机名的变化可能会使任务失效。发出一个小的状态集，如ACCEPT、RETRY_ONCE、REVIEW或STOP，并附带原因代码。

操作员交接：导航、刷新、注销或操作漂移后丢弃结果

停止条件是实现的一部分。当工作流必须在导航、刷新、注销或操作漂移后丢弃结果时，取消待处理的子任务，保留经过脱敏的证据摘要，释放队列锁，并防止后台重试继续使用过期状态。后续的操作员批准运行应从新的浏览器或任务检查点开始并重新评估范围。这使得AI代理reCAPTCHA v3求解器在负载下可解释，并防止单个模糊页面变成重试风暴。

此阶段的输出是机器可读的决策和重现所需的最小证据。这不是忽略条款、访问控制、数据权利、速率限制或账户边界的许可。当证据不完整时，审核状态是有效结果。

验证受保护的应用程序状态

AI代理reCAPTCHA v3求解器在此阶段需要定义成功标准。将预期路由、表单响应、账户状态、记录数、错误横幅和关联ID作为单一检查点记录，而不是作为不相关的日志消息。这些值解释了自动化认为什么、观察到什么以及为什么被允许继续。操作规则是断言原始授权结果。保守的边界是当工具成功但应用程序未成功时结束审查。没有这个边界，技术上成功的API调用可能被错误地关联到错误的页面、错误的账户、错误的业务对象或过时的浏览器会话。

恢复状态：预期路由

从预期路由开始，然后将其绑定到表单响应、账户状态和记录数。使用类型化字段和显式未知值。每条记录应包含观察到的时间戳、关联ID、授权目的以及做出决策的组件。避免将凭证、完整cookie、原始解决方案值或不必要的页面内容复制到记录中。缺失的证据必须保持缺失；便捷的默认值绝不能看起来像真实的观察结果。

当前数据包应与同一授权工作单元的最后一个有效数据包进行比较。表单响应的变化可能是预期的，而账户状态的变化可能会使任务失效。发出一个小型状态集，如ACCEPT、RETRY_ONCE、REVIEW或STOP，并附带原因代码。

质量门禁：当工具成功但应用程序未成功时结束审查

停止条件是实现的一部分。当工作流必须在工具成功但应用程序未成功时结束时，取消待处理的子任务，保留脱敏证据摘要，释放队列锁，并防止后台重试继续使用过时状态。后续由操作员批准的运行应从新的浏览器或任务检查点开始，并重新评估范围。这使AI代理reCAPTCHA v3求解器在负载下可解释，并防止单个模糊页面变成重试风暴。

此阶段的输出是机器可读的决策和重现所需的最小证据。这不是忽略条款、访问控制、数据权利、速率限制或账户边界的许可。当证据不完整时，审查状态是一个有效的结果。

测试分数、超时和重复挑战

AI代理reCAPTCHA v3求解器在此阶段需要定义测试矩阵。将v3标准、v3企业版、延迟工具、低分拒绝、过时页面、重复挑战和不支持的测试用例作为单一检查点记录，而不是作为不相关的日志消息。这些值解释了自动化认为什么、观察到什么以及为什么被允许继续。操作规则是在预发布环境中测试每个终端分支。保守的边界是当同一检查点出现两次时暂停自动化。没有这个边界，技术上成功的API调用可能被错误地关联到错误的页面、错误的账户、错误的业务对象或过时的浏览器会话。

生产控制：v3标准

从v3标准开始，然后将其绑定到v3企业版、延迟工具和低分拒绝。使用类型化字段和显式未知值。每条记录应包含观察到的时间戳、关联ID、授权目的以及做出决策的组件。避免将凭证、完整cookie、原始解决方案值或不必要的页面内容复制到记录中。缺失的证据必须保持缺失；便捷的默认值绝不能看起来像真实的观察结果。

当前数据包应与同一授权工作单元的最后一个有效数据包进行比较。v3企业版的变化可能是预期的，而延迟工具的变化可能会使任务失效。发出一个小型状态集，如ACCEPT、RETRY_ONCE、REVIEW或STOP，并附带原因代码。

运维规则：当同一检查点出现两次时暂停自动化

停止条件是实现的一部分。当工作流必须在相同检查点出现两次时暂停自动化时，取消待处理的子任务，保留脱敏证据摘要，释放队列锁，并防止后台重试继续使用过时状态。后续由操作员批准的运行应从新的浏览器或任务检查点开始，并重新评估范围。这使AI代理reCAPTCHA v3求解器在负载下可解释，并防止单个模糊页面变成重试风暴。

此阶段的输出是机器可读的决策和重现所需的最小证据。这不是忽略条款、访问控制、数据权利、速率限制或账户边界的许可。当证据不完整时，审查状态是一个有效的结果。

结论

只有在每个阶段都有定义的输入、类型化输出、脱敏证据记录和终端停止条件时，AI代理reCAPTCHA v3求解器才能在生产环境中运行。保留授权页面和业务上下文，使用经过验证的CapSolver方法或API字段，保持重试有限，并在恢复后验证原始应用程序结果。运行合法和授权自动化的团队可以评估CapSolver以记录的CAPTCHA层，同时在其系统中保留确定性策略、数据质量和人工审查控制。

FAQ

Q: 什么是AI代理reCAPTCHA v3求解器？

AI代理reCAPTCHA v3求解器是一个受控工具层，为授权代理工作流获取v3结果，并将控制权返回到原始应用程序状态。

Q: 官方代理层是否支持reCAPTCHA企业版？

是的。当前CapSolver AI文档涵盖了reCAPTCHA v2和v3，包括企业版，以及Cloudflare Turnstile。

Q: 哪些方法和工具是官方的？

使用capsolver-core方法，如detect、get_captcha_info、solve和solve_on_page，或记录的代理工具和MCP工具，如solve_captcha。

Q: 返回的结果是否证明代理任务成功？

不。受保护的应用程序仍必须接受结果并达到预期的授权状态。

Q: 代理应在何时停止？

在范围更改、缺少操作上下文、不支持的挑战类型、重复检查点、尝试耗尽或应用程序验证失败时停止。