Stagehand 验证码处理：浏览器操作 vs 求解器

简要说明

• Stagehand 浏览器操作和验证码解决有不同的职责：一个控制页面，另一个处理支持的验证挑战。
• 在添加解决者之前，请检查浏览器运行的位置；托管会话可能已经启用了验证码处理。
• Browserbase 文档说明了对支持的验证码的自动解决，但这并不意味着每个本地 Stagehand 浏览器都是托管解决会话。
• 需要明确的集成边界，例如 CapSolver；返回的令牌不是完成的浏览器任务。
• 选择一个组件处理每个挑战，然后在代理继续之前验证预期的页面结果。

AI 代理可以在需要验证码检查点帮助时找到搜索字段、输入查询并选择结果。改进指令“完成搜索”并不能定义如何处理该检查点。

对于考虑将 CapSolver 与 Stagehand 一起使用的团队，第一个决定是验证码解决属于哪个部分。本指南比较了职责和部署选择。这是一份选择指南，而不是声称特定的 Stagehand 到 CapSolver 适配器已安装和测试。

Stagehand 在验证码出现前做什么？

Stagehand 提供浏览器自动化原语，使应用程序可以描述交互并提取页面数据。

官方 Stagehand act 文档 描述了页面交互，而 提取文档 描述了检索结构化信息。这些是构建如读取已批准的产品目录或检查自有应用程序信息等任务的有用组件。

一个典型的任务有明确的业务目标：打开产品页面并返回指定型号的可用性。验证码处理是该任务中的可能中断。它不应取代任务的目标。

这种区别在 AI 网络爬虫 中很重要。代理可以成功从错误的页面提取文本。如果显示的是验证屏幕而不是产品列表，生成结构良好的答案并不能证明请求的数据已被检索。

因此，应用程序必须识别页面状态和需要的结果。“工具返回”和“正确的产品被读取”是不同的声明。

浏览器操作与验证码解决者：哪个组件负责什么？

浏览器操作负责导航和交互，而验证码解决者负责其分配的支持挑战操作。

责任	浏览器操作层	验证码解决层
打开请求的页面	在允许的任务内导航	不替代导航
选择预期的表单或记录	使用当前页面上下文	需要正确的挑战上下文
处理支持的验证码	根据工作流暂停或委托	生成或应用文档解决方案
恢复业务任务	在检查点解决后继续	不决定业务结果
确认请求的结果	检查正确的页面和数据	解决者完成本身不足

这些角色可以由浏览器提供商打包在一起。也可以分别实现。打包更改了谁维护连接，但不会消除挑战结果和请求业务结果之间的区别。

例如，目录代理应返回所选型号的可用性。解决者结果无法告诉应用程序型号、国家或变体是否正确。这些检查属于任务本身。

避免让两个层拥有不受控制的权限以继续尝试。一个页面操作不断点击，而另一个组件处理挑战会使工作流难以诊断。在该间隔期间定义哪个组件负责。

浏览器环境如何改变选择？

浏览器环境决定了哪些验证码功能已可用，以及哪些功能需要您的应用程序提供。

Stagehand 的 当前浏览器配置文档 描述了托管的 Browserbase 浏览器、本地浏览器和通过 CDP 连接到现有 Chromium 浏览器。实际起点是确定您的实际运行使用哪种环境。

不要从框架名称推断环境。开发机器和托管部署可能使用不同的浏览器服务，即使业务任务看起来相同。

Stagehand 在 Browserbase 会话中

Browserbase 的 验证码解决文档 说明其会话默认启用解决，并描述了过程的开始和结束事件。它还记录了禁用该行为的配置。

对于已经使用此环境的团队，在添加第二个提供者之前，请检查会话设置和记录的解决行为。确定挑战是否受支持，以及浏览器是否已开始处理它。

当其支持的行为符合您的需求且您希望维护更少组件时，托管选项是一个合理的首选。根据您实际使用的允许页面评估它。不要假设功能描述保证每个挑战或每个网站的最终接受。

Stagehand 与本地或单独托管的浏览器

本地浏览器不会因为 Stagehand 控制它而获得 Browserbase 的托管功能。

如果您的选择浏览器环境不提供所需解决功能，则可能需要单独集成。应用程序需要一种方法来识别挑战、提供文档输入、接收结果并在正确的浏览器上下文中应用它。

这项工作应被视为一个集成项目，并带有小的验收测试。不要将托管会话示例复制到本地设置中并假设周围服务存在。

对于现有的远程浏览器，还要确定谁控制连接和浏览器生命周期。与不同标签页或被遗弃会话关联的解决操作不会证明代理的当前任务可以继续。

CapSolver 如何融入 Stagehand 工作流？

CapSolver 可以通过精心设计的浏览器集成提供支持的验证码服务。

CapSolver 自动化集成概述 描述了浏览器自动化的 API 和扩展方法。API 方法将文档请求和结果处理的责任交给应用程序代码。扩展方法依赖于适当的浏览器环境及其扩展支持。

根据您运行的浏览器、挑战类型和所需控制来选择。产品在浏览器自动化中可用并不能证明它是原生的 Stagehand 插件或通用的一行设置。

CapSolver Core SDK 提供了用于检测、参数读取、令牌解决和浏览器回填的 Python 方法。其文档中的令牌模式覆盖包括 reCAPTCHA v2/v3 和 Turnstile；它不会点击图像网格或拖动滑块。当决定特定组件是否适合您的挑战时，这一范围很重要。

同一文档以 Playwright 页面的方式描述了浏览器方法。不要假设其他框架中的任何名为“page”的对象都可以互换。如果您的设计跨 SDK 或语言，应在将其作为操作集成之前证明所提议的连接有效。

即使没有大量构建，仍可以进行有用的评估：记录确切的浏览器、支持的挑战、选定的 CapSolver 路径和最终页面条件。然后在拥有或明确批准的环境中测试最小的完整路径。

领取您的 CapSolver 奖励代码

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

当代理遇到挑战时应该发生什么？

挑战应触发受控的交接并有明确的返回条件。

考虑一个假设的分销商目录工作流。代理必须打开已批准的产品页面并报告特定零件的可用性。以下序列是一个建议的设计，而不是已部署的客户集成记录：

1. 导航到目标目录页面并识别请求的零件。
2. 确定页面是否准备好进行业务操作或显示验证码。
3. 如果存在支持的、允许的挑战，请将选定的解决组件控制该步骤。
4. 等待明确的结果或有限的失败，而不是继续无关的页面操作。
5. 重新检查当前页面，然后读取请求的零件和可用性。
6. 如果挑战或业务步骤仍未解决，返回不完整的结果。

此序列在解决者之后留下两个有用的检查：页面是否进入预期状态，数据是否属于请求的项目？

保持代理的指令专注于这些可观察的结果。一个广泛的指令“继续尝试直到成功”没有有用限制，也没有可靠的完成定义。

对于更广泛的中断模式，为什么 AI 代理任务会卡在验证码上 的指南解释了为什么重复的导航和解决可能形成循环。在 Stagehand 设计中，相应的问题是哪个组件可以下一步行动，什么证据允许它继续。

如何比较成本和维护？

比较完整的工作流成本和集成工作量，而不是将单个解决请求视为整个任务。

托管选项可能减少团队维护的连接数量。单独的解决者可以提供对服务调用、任务诊断和供应商选择的直接控制。两者对您的工作负载来说并不自动更便宜。

评估您可以观察的实际成本：浏览器运行时间、模型调用、解决者使用、未成功尝试和工程师花费在诊断失败上的时间。不要将不可用页面上的解决挑战视为成功的业务结果。

还要考虑变更所有权。当挑战停止工作时，您的团队能否确定原因是浏览器配置、请求字段、服务故障还是应用验证？一种暴露必要证据的方法可能比仅出于短期设置示例选择的方法更容易维护。

使用代表性的、授权的试点，而不是来自无关网站的性能声明。在评估替代方案时，保持浏览器任务、预期输出和接受条件一致。

您应该选择哪种方法？

选择适合您现有浏览器环境并能以最少不必要的集成工作量演示所需页面结果的方法。

当托管浏览器的支持处理已存在并满足任务时，从它开始。当您需要当前环境不提供的支持验证码功能或服务控制时，考虑单独的 CapSolver 集成。

在接受任何方法之前，回答四个实际问题：

• 指定的自动化是否允许在此页面上进行？
• 所选解决路径是否支持实际挑战？
• 工作流能否保留页面并干净地返回控制？
• 应用程序能否区分完整结果和未解决的检查点？

试点应包括正常页面、支持的挑战和未解决的挑战。未解决的情况很有价值：它显示代理是报告有用限制还是虚构成功。

避免在没有明确协调的情况下为同一挑战启用多个解决路径。如果以后引入回退，请定义转换并在下一个组件接管之前验证第一个尝试已结束。

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

Stagehand 为代理提供了与页面交互的方法；验证码解决需要自己的支持路径和工作流中的明确位置。浏览器环境决定了该路径有多少已经存在。

将 CapSolver 与特定的、授权的浏览器任务进行对比。保持集成足够小以验证，并仅在代理到达正确页面并返回请求结果时接受。

常见问题

Q: Stagehand 是否会自动解决每个验证码？

使用 Stagehand 不会带来普遍保证。验证码处理取决于浏览器环境、其配置和支持的挑战。Browserbase 为其会话记录了自动解决；本地浏览器需要自己的合适路径。

Q: 我可以通过更改 Stagehand 提示来解决验证码吗？

提示可以告诉代理何时暂停和检查哪个结果，但它不会创建支持的验证码解决服务。工作流仍需要适当的浏览器功能或集成。

Q: CapSolver Core SDK 是原生的 Stagehand 插件吗？

引用的 Core SDK 文档描述了 Python SDK 和基于 Playwright 的浏览器方法。它并未建立原生的 Stagehand 插件。任何提议的连接都应针对涉及的确切运行时和接口进行验证。

Q: 我应该同时启用托管解决者和 CapSolver 吗？

为每个挑战提供一个活动处理路径。在没有协调的情况下同时运行两者会使所有权和故障诊断变得模糊。通过明确的交接评估第二个提供者，而不是同时尝试。

Q: 什么证明验证码处理对您的代理有效？

解决步骤必须适当完成，然后应用程序必须达到预期的页面状态并返回正确的任务结果。令牌、工具响应或提供者事件本身是不够的。