如何将验证码求解器与LangGraph集成

TL;DR

• 一个LangGraph验证码求解器应建模为一个有限工具节点，而不是隐藏在代理的常规浏览提示中。
• 仅当授权的浏览器工作流检测到支持的reCAPTCHA或Cloudflare Turnstile检查点时，图表应暂停。
• 将页面URL、站点密钥、挑战类型和可选的操作元数据作为结构化状态传递；永远不要在图表消息中放置CapSolver API密钥。
• 通过显式边路由ready、failed和timeout结果，以防止代理无限重试。
• 在同一浏览器会话中验证返回的令牌，并在目标应用程序拒绝它时停止。

LangGraph集成的功能

LangGraph验证码求解器在授权的浏览器任务遇到支持的验证检查点时，为AI工作流提供受控的恢复路径。LangGraph仍负责编排，而CapSolver通过API或代理工具处理专门的验证码任务。

这种有用的设计是一个小型状态机：浏览、检测、请求解决方案、应用令牌、验证页面结果，然后继续或停止。这使验证码处理可观察，并防止模型随意调整参数或无限制地重复调用。

前提条件

仅在您有权自动化的网站和测试环境中使用此模式。您需要一个LangGraph应用程序、一个浏览器控制层、一个CapSolver账户，以及一个用于CAPSOLVER_API_KEY的服务器端密钥存储。浏览器步骤必须能够识别挑战类型并收集CapSolver文档中记录的参数。

CapSolver的AI代理指南描述了支持的代理工作流。Core SDK文档涵盖了程序化接口，而Agent Tools参考记录了面向工具的用法。

定义验证码状态契约

图表状态应仅包含路由和验证所需的值：

from typing import Literal, TypedDict

class AgentState(TypedDict, total=False):
    page_url: str
    captcha_type: Literal["recaptcha_v2", "recaptcha_v3", "turnstile"]
    website_key: str
    action: str
    task_id: str
    token: str
    captcha_status: Literal["not_found", "pending", "ready", "failed", "timeout"]
    attempts: int

将API密钥保留在此对象之外。图表状态可能会被记录或检查点保存，因此凭证应存储在环境变量或经批准的密钥管理器中。

创建求解节点

求解节点应将已知状态转换为一个支持的CapSolver任务。以下代码是一个示例边界；将其连接到您的服务当前使用的官方SDK或REST模式。

MAX_ATTEMPTS = 2

def solve_captcha(state: AgentState) -> AgentState:
    attempts = state.get("attempts", 0)
    if attempts >= MAX_ATTEMPTS:
        return {**state, "captcha_status": "timeout"}

    required = ("page_url", "website_key", "captcha_type")
    if any(not state.get(key) for key in required):
        return {**state, "captcha_status": "failed"}

    result = capsolver_client.solve({
        "type": state["captcha_type"],
        "websiteURL": state["page_url"],
        "websiteKey": state["website_key"],
        "action": state.get("action"),
    })
    return {
        **state,
        "attempts": attempts + 1,
        "token": result.get("token", ""),
        "captcha_status": "ready" if result.get("token") else "failed",
    }

不要让语言模型生成websiteKey、挑战类型或操作。从当前页面或应用配置中提取这些值，然后在工具调用前验证它们。

领取您的CapSolver优惠码

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

添加条件图边

LangGraph应根据观察到的状态进行路由，而不是根据自由格式的模型文本：

def route_after_detection(state: AgentState) -> str:
    if state.get("captcha_status") == "pending":
        return "solve_captcha"
    return "continue_browser"

def route_after_solve(state: AgentState) -> str:
    if state.get("captcha_status") == "ready":
        return "apply_token"
    return "stop_with_diagnostic"

apply_token节点应在检测到挑战的同一浏览器会话中运行。应用后，一个单独的验证节点应检查应用响应、预期导航或服务器端确认。仅凭令牌无法证明工作流成功。

无重试循环处理失败

在决定如何处理之前，先对失败进行分类。缺失的参数是配置问题。被拒绝的令牌可能表示令牌过期、页面URL、站点密钥、操作或浏览器上下文不匹配。服务超时是操作性的，可能值得进行一次有限的重试。

记录task_id、挑战类型、经过时间以及清理后的错误代码。不要在通用代理跟踪中存储令牌、cookies、凭证或敏感页面内容。当页面请求不应自动执行的操作时，应升级到人工处理。

生产检查清单

• 允许白名单授权域名和挑战类型。
• 设置硬性超时和最大尝试次数。
• 将凭证保留在提示和检查点之外。
• 在原始浏览器上下文中应用并验证令牌。
• 在登录、提交、支付或账户更改周围添加人工审批。
• 按原因跟踪完成率和失败率，而不仅仅是工具调用成功。

结论

可靠的LangGraph验证码集成是一个具有明确输入和停止条件的狭窄、可观察分支。将浏览器编排保留在LangGraph中，将验证码参数结构化，并在令牌应用后验证业务结果。CapSolver可以提供专门的验证码能力，而不会将整个代理变成不透明的恢复循环。

FAQ

Q: LangGraph能自己解决验证码吗？

不能。LangGraph协调节点和状态；专门的浏览器和验证码服务执行工作。

Q: 图表应支持哪些验证码类型？

仅支持当前CapSolver代理表面记录的类型，例如reCAPTCHA v2、reCAPTCHA v3和Cloudflare Turnstile。

Q: API密钥应存储在LangGraph状态中吗？

不应。将API密钥存储在服务器端环境变量或密钥管理器中，因为图表状态可能会被持久化或记录。

Q: 节点应重试多少次？

使用一到两次有限尝试，并在重复拒绝、参数缺失或授权不确定性时停止。