如何在 LangGraph 代理中解决 reCAPTCHA
Ethan Collins
Pattern Recognition Specialist
TL;DR
- 通过 LangChain 的额外组件安装
capsolver-agent，并使用get_langchain_tools()加载其预设工具。 - 将这些工具绑定到聊天模型，并在 LangGraph 的
ToolNode中执行它们。 - 对于 reCAPTCHA v2 的 token 模式，提供精确的授权页面 URL 和站点密钥；返回的 token 是 API 级别的
gRecaptchaResponse。 - 在工具节点周围添加允许列表、重试限制、密钥隔离和人工审核路由。
- 当动态页面需要检测和在同一会话中注入 token 时，使用浏览器模式恢复。
引言
在 LangGraph 代理中解决 reCAPTCHA 的最易维护方法是将挑战恢复视为类型化的工具节点，而不是在模型提示中嵌入网络逻辑。CapSolver 的 Agent SDK 提供了与 LangChain 兼容的工具，而 LangGraph 提供了显式的状态、路由、错误处理和可恢复性。模型可以决定支持的挑战会阻止下一步授权操作，但确定性的工具会验证页面参数，调用求解器，并返回结构化结果。这种架构将 API 密钥排除在消息之外，使重试可观察，并防止提交无关目标。本教程构建了一个最小图，展示了如何路由工具调用，解释了 reCAPTCHA v2 的参数，并为浏览器自动化、QA、RPA 和经批准的公共数据工作流添加了生产保障措施。
CapSolver 在 LangGraph 状态机中的位置
LangGraph 专为有状态的工作流设计，其中节点执行有限的工作，边控制下一步操作。CapSolver 自然地融入到专用工具节点中：
text
用户引导的任务
↓
推理节点识别支持的挑战
↓
工具节点执行 CapSolver 工具
↓
结构化解决方案或标准化错误
↓
浏览器恢复、重试或请求人工审核模型应决定 何时 需要恢复。它不应决定秘密的存储位置、哪些主机被授权，或允许多少次重试。这些决定应属于确定性的应用代码。
CapSolver AI 博客 包含代理集成模式，CapSolver AI 和自动化 FAQ 解释了恢复层如何补充现有的代理堆栈。
安装代理工具和 LangGraph
用户提供的 CapSolver 代理文档指定 capsolver-agent 依赖于 capsolver-core。首先安装核心，然后使用其 LangChain 集成安装代理包。
bash
pip install git+https://github.com/capsolver-ai/capsolver-core.git
pip install "capsolver-agent[langchain] @ git+https://github.com/capsolver-ai/capsolver-agent.git"
pip install langchain-openai langgraph通过运行时环境配置凭证：
bash
export CAPSOLVER_API_KEY="CAP-xxxxxxxxxxxxxxxx"
export OPENAI_API_KEY="sk-xxxxxxxxxxxxxxxx"官方 CapSolver 代理仓库记录了此导入路径：
python
from capsolver_agent.langchain_tools import get_langchain_tools
tools = get_langchain_tools(api_key="YOUR_API_KEY")返回的对象是与 LangChain 兼容的 BaseTool 实例。官方 LangChain 工具指南 解释了工具如何向模型暴露定义的输入和输出，而类型信息和描述有助于模型选择正确的操作。
理解 reCAPTCHA v2 任务参数
对于标准无代理的 reCAPTCHA v2 任务，所需输入是页面 URL 和站点密钥。CapSolver 的 官方 reCAPTCHA v2 文档 列出了内置代理路径的 ReCaptchaV2TaskProxyLess，以及当页面使用 reCAPTCHA 企业版时的独立企业任务类型。
| 字段 | 要求 | 指南 |
|---|---|---|
captcha_type |
代理工具所需 | 使用 SDK 的文档化 reCAPTCHA v2 标识符 |
website_url |
必填 | 发送授权页面的完整 URL |
website_key |
必填 | 使用页面加载的精确站点密钥 |
| 企业版负载 | 可选 | 仅在目标的文档配置要求时包含 |
| 隐形标志或操作 | 可选 | 保留授权页面检测到的值 |
在 REST 任务级别，解决方案 token 作为 solution.gRecaptchaResponse 返回。Agent SDK 将核心结果包装在结构化字典中，以便图可以路由成功或失败而无需解析任意文本。
有关参数发现，请参阅 CapSolver 浏览器扩展指南 和 reCAPTCHA v2 实现指南。
使用 CapSolver 工具构建 LangGraph
以下示例加载官方 CapSolver 工具，将它们绑定到聊天模型，并将其放入 ToolNode 中。每次工具响应后，图会返回到推理节点。
python
import os
from typing import Literal
from capsolver_agent.langchain_tools import get_langchain_tools
from langchain_openai import ChatOpenAI
from langgraph.graph import START, StateGraph
from langgraph.graph.message import MessagesState
from langgraph.prebuilt import ToolNode, tools_condition
capsolver_tools = get_langchain_tools(
api_key=os.environ["CAPSOLVER_API_KEY"]
)
model = ChatOpenAI(
model="gpt-4o-mini",
temperature=0,
).bind_tools(capsolver_tools)
def agent_node(state: MessagesState):
response = model.invoke(state["messages"])
return {"messages": [response]}
def safe_tool_error(error: Exception) -> str:
return (
"挑战工具失败。不要自动重试。"
"将工作流返回给操作员审核。"
)
builder = StateGraph(MessagesState)
builder.add_node("agent", agent_node)
builder.add_node(
"tools",
ToolNode(
capsolver_tools,
handle_tool_errors=safe_tool_error,
),
)
builder.add_edge(START, "agent")
builder.add_conditional_edges("agent", tools_condition)
builder.add_edge("tools", "agent")
graph = builder.compile()LangGraph ToolNode 参考 文档说明 ToolNode 接受 BaseTool 实例，执行工具调用，并支持可配置的错误处理。这使其适用于必须可观察和可预测的恢复分支。
给代理一个狭窄的指令
模型需要足够的上下文来调用正确的工具，但不应获得无限制的权限。从验证的应用程序数据构造消息：
python
request = {
"website_url": "https://staging.example.com/approved-form",
"website_key": "6LcXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
}
messages = [
(
"system",
"您仅在经批准的工作流中操作。如果支持的 reCAPTCHA 阻止下一步，请使用应用程序提供的精确 URL 和站点密钥调用 CapSolver solve_captcha 工具一次。"
"永远不要发明目标或请求凭证。如果解决失败，请停止并请求操作员审核。",
),
(
"user",
"继续经批准的预发布任务。浏览器报告在 {request['website_url']} 处有站点密钥 {request['website_key']} 的 reCAPTCHA v2。",
),
]
result = graph.invoke(
{"messages": messages},
config={"recursion_limit": 6},
)递归限制可防止不受控制的图循环。在生产中，还应在构造消息前限制允许的主机名，并避免在跟踪中存储解决方案 token。
在图之前添加主机允许列表
CapSolver 工具解决它们被要求解决的问题；您的应用程序必须决定哪些工作是授权的。在模型外部验证页面 URL：
python
from urllib.parse import urlparse
ALLOWED_HOSTS = {
"staging.example.com",
"qa.example.com",
}
def validate_target(url: str) -> str:
parsed = urlparse(url)
if parsed.scheme != "https":
raise ValueError("仅允许 HTTPS 目标")
if parsed.hostname not in ALLOWED_HOSTS:
raise PermissionError("目标主机未获批准")
return url当多个客户共享同一平台时，使用特定租户的允许列表或签名的工作流清单。不要允许自然语言指令修改此策略。
路由成功、失败和人工审核
有用的恢复图需要三种结果，而不仅仅是“解决”和“崩溃”。将工具输出标准化为工作流决策：
python
from typing import TypedDict
class RecoveryDecision(TypedDict):
status: Literal["continue", "retry", "review"]
reason: str
def classify_recovery(result: dict, attempt: int) -> RecoveryDecision:
if result.get("success"):
return {"status": "continue", "reason": "返回解决方案"}
error = str(result.get("error", "未知错误"))
if attempt == 0 and "timeout" in error.lower():
return {"status": "retry", "reason": "允许一次有限重试"}
return {"status": "review", "reason": error}当浏览器可以直接使用 token 时，不要在模型消息中暴露原始 token。理想的边界是：工具结果 → 受信任的浏览器控制器 → 提交结果 → 向图返回已脱敏状态。
CapSolver 错误和故障排除 FAQ 提供常见诊断路径，而 CapSolver 响应 API 指南 解释结果处理。
Token 模式与浏览器模式
| 模式 | 最佳情况 | 图接收 | 主要操作关注点 |
|---|---|---|---|
| Token 模式 | 已知 URL 和站点密钥 | 结构化 token 结果 | 正确参数和及时消费 |
| 浏览器模式 | 小部件参数是动态的 | 解决的页面/会话状态 | 同一页会话连续性 |
| 人工审核 | 重复或不支持的失败 | 已脱敏错误和截图参考 | 防止无限制重试 |
Token 模式通常适用于已知的 reCAPTCHA 参数。当授权的 Playwright 流需要在同一会话中使用 detect() 和 solve_on_page() 时，浏览器模式很有用。CapSolver Agent 文档将 solve_captcha 映射到核心 token 求解，将 solve_on_page 映射到浏览器恢复。
可观察性而不泄露秘密
记录图转换和操作指标，而不是敏感值。有用的字段包括：
python
safe_event = {
"workflow_id": "wf_01J...",
"node": "tools",
"tool": "solve_captcha",
"target_host": "staging.example.com",
"challenge_type": "recaptcha_v2",
"attempt": 1,
"duration_ms": 6420,
"outcome": "success",
}永远不要记录 CapSolver API 密钥、完整解决方案 token、认证 cookie 或表单数据。在将事件发送到外部可观测性系统之前应用跟踪脱敏。
附加代码：在 CapSolver 仪表板 上使用代码 WEBS 可以在每次充值时获得额外 5% 的奖金。
生产检查清单
生产级 LangGraph reCAPTCHA 求解器应具有主机名允许列表、固定任务策略、短 token 生命周期处理、有限重试、跟踪脱敏、显式停止条件和操作员审核节点。在将其连接到无人值守自动化之前，先在授权的预发布页面上对其进行测试。
CapSolver CAPTCHA 求解 FAQ 覆盖任务行为，CapSolver Python 爬虫指南 提供浏览器自动化实践。
负责任的使用
仅在您拥有、测试或获得明确授权的系统上使用此工作流。挑战求解不授予访问权限。尊重网站条款、速率限制、隐私义务和用途限制。在图提交表单、更改账户数据或执行任何高影响操作之前，要求人工确认。
结论
当求解是具有严格路由的显式工具节点时，LangGraph reCAPTCHA 求解器最可靠。加载 CapSolver 的预设 LangChain 工具，将它们绑定到模型，通过 ToolNode 执行它们，并将授权、秘密、重试和 token 消费保留在确定性的应用代码中。这为代理提供了恢复能力，而不会给予它无限制的控制。
从 CapSolver 开始，将图与经批准的预发布工作流进行验证，并在扩展之前添加跟踪脱敏和人工审核。
FAQ
与 LangGraph 一起使用时，我应该使用哪个 CapSolver 导入？
使用 from capsolver_agent.langchain_tools import get_langchain_tools，然后调用 get_langchain_tools(api_key=...) 以获得可传递给 ToolNode 的 LangChain 兼容工具。
reCAPTCHA v2 token 模式需要哪些输入？
页面 URL 和 reCAPTCHA 站点密钥是必需的。仅在授权页面实际使用时才包括企业版、隐形、操作或会话字段。
LangGraph 模型应该接收解决方案 token 吗？
优先将 token 直接从受信任的工具层发送到浏览器控制器。在可能的情况下，仅向推理图返回已脱敏的成功或失败事件。
图应该允许多少次自动重试？
通常一次有限的重试就足够应对瞬时超时。重复拒绝应路由到人工审核，因为 URL、密钥、会话或页面配置可能有误。
这种模式可以处理动态浏览器挑战吗？
是的。当工作流需要在同一 Playwright 会话中进行检测和页面级恢复时，通过受控工具使用浏览器功能的 CapSolver 核心方法。