如何在 LangChain Agent 中处理 reCAPTCHA

LangChain Agent 常被用于浏览器自动化、公开网页数据采集、表单提交、测试流程和多步骤业务工作流。进入真实网页环境后这类 Agent 很容易遇到 reCAPTCHA v2例如常见的 checkbox 验证以及页面在后台触发的 invisible reCAPTCHA。当 Agent 访问受 reCAPTCHA 保护的页面时如果没有专门的验证处理步骤整个链路就会停在当前页面。本文介绍如何在授权自动化场景下将 CapSolver 接入 LangChain让 Agent 可以通过可控的工具调用处理 reCAPTCHA v2。本文会覆盖两种方式Token mode已知页面 URL 和 site key 时直接请求 reCAPTCHA token。Browser modeAgent 正在用 Playwright 浏览页面时由 SDK 自动检测页面上的 CAPTCHA 并回填 token。下面的示例使用capsolver-agent和 LangChain 工具接口因此 CAPTCHA 处理可以成为 Agent 正常工具链的一部分。核心要点reCAPTCHA v2 是 LangChain 浏览器 Agent 经常遇到的验证类型。CapSolver 可以为 checkbox 和 invisible reCAPTCHA v2 返回可提交的 token。Token mode 适合已经知道页面 URL 和 site key 的场景。Browser mode 适合 Agent 动态访问页面并需要自动识别 CAPTCHA 的场景。capsolver-agent提供 LangChain 工具支持便于接入 ReAct Agent。请只在你拥有授权的网站、账号和自动化工作流中使用这些方法。为什么 reCAPTCHA 会打断 LangChain 工作流reCAPTCHA 的作用是判断当前请求是否来自真实、可信的用户会话。它会综合浏览器环境、交互行为、访问上下文和风险信号。LangChain Agent 通常运行在自动化浏览器、无头浏览器或重复任务流程中因此在访问某些页面时可能触发验证。常见触发场景包括采集公开网页数据时访问带验证的页面。登录或账号相关流程。表单提交、预约、搜索、查询等任务。多步骤浏览器任务中途进入受保护页面。QA、RPA 或自动化测试流程。reCAPTCHA v2 通常有两种形式。第一种是用户熟悉的 checkbox 验证第二种是 invisible reCAPTCHA它可能在用户点击按钮或提交表单时静默触发。无论是哪一种页面最终都需要一个有效的 token通常会通过g-recaptcha-response字段提交。如果 Agent 没有 token 处理能力链路就会失败。CapSolver 的作用是在授权场景下返回可提交的 token让工作流继续执行。准备工作先安装需要的依赖包pip install githttps://github.com/capsolver-ai/capsolver-core.git pip installcapsolver-agent[langchain] githttps://github.com/capsolver-ai/capsolver-agent.gitpip install langchain-openai langgraph然后配置环境变量exportCAPSOLVER_API_KEYyour-capsolver-api-keyexportOPENAI_API_KEYyour-openai-api-key如果使用 Token mode还需要从目标页面中找到 reCAPTCHA 的 site key。可以通过浏览器开发者工具查看页面源码也可以使用 CapSolver 浏览器扩展识别 CAPTCHA 参数。第一步找到 reCAPTCHA site key对 reCAPTCHA v2 来说site key 通常在data-sitekey属性中。divclassg-recaptcha>6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI /div如果是 invisible reCAPTCHA v2通常仍然会使用类似结构但会带有data-sizeinvisible。divclassg-recaptcha>6LeIxAcT...>sizeinvisible /div你需要记录三个信息完整页面 URL。data-sitekey的值。当前页面使用的是 visible reCAPTCHA 还是 invisible reCAPTCHA。如果你的工作流已经使用 Playwright也可以通过 CapSolver Core 在页面中自动检测 CAPTCHA 信息。fromcapsolver_coreimportcreate_capsolverfromplaywright.async_apiimportasync_playwrightasyncdefdetect_recaptcha(url:str): cap create_capsolver(api_keyYOUR_CAPSOLVER_API_KEY)asyncwithasync_playwright()asp: browser awaitp.chromium.launch() page awaitbrowser.new_page()awaitpage.goto(url) captcha_infos awaitcap.get_captcha_info(page)forinfoincaptcha_infos:print(ftype{info.type}, site_key{info.website_key})awaitbrowser.close()awaitcap.aclose()site key 很关键因为 token 必须针对具体页面和具体 CAPTCHA 配置生成。同一个域名下的不同页面也可能使用不同 site key因此不要直接复用。第二步在 LangChain 中用 Token mode 处理 reCAPTCHA v2当你已经知道页面 URL 和 site key 时Token mode 是最直接的方式。LangChain Agent 可以调用 CapSolver 工具获取一个可提交的 token然后继续后续表单或页面流程。import asynciofromlangchain_openai import ChatOpenAIfromlanggraph.prebuilt import create_react_agentfromcapsolver_agent.langchain import get_langchain_tools async def solve_recaptcha_with_langchain(): tools get_langchain_tools(api_keyYOUR_CAPSOLVER_API_KEY) llm ChatOpenAI(modelgpt-4o,temperature0) agent create_react_agent(llm,toolstools) result await agent.ainvoke({messages: [ (user,Solve the reCAPTCHA v2 for https://example.com/login. The site key is 6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI. Return the response token.) ] })print(result[messages][-1].content) asyncio.run(solve_recaptcha_with_langchain())如果你不希望让 Agent 自己决定何时调用工具也可以用 executor 直接执行这样更适合需要精确控制的生产系统。fromcapsolver_agent.schemaimportcreate_executorasyncdefsolve_recaptcha_directly(): executor create_executor(api_keyYOUR_CAPSOLVER_API_KEY) result awaitexecutor.execute(solve_captcha, {captcha_type:reCaptchaV2,website_url:https://example.com/login,website_key:6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI})ifnotresult[success]:print(fCaptcha solving failed:{result[error]})returnNonetoken result[solution][token]print(fReceived token:{token[:60]}...)returntoken拿到 token 后一般需要把它作为g-recaptcha-response字段提交给页面或接口。Token mode 的优势是轻量不需要启动浏览器实例。对于已经知道目标参数的 Agent 工作流它通常是更简单的方案。第三步处理 invisible reCAPTCHA v2从 API 调用角度看invisible reCAPTCHA v2 和 checkbox 版本使用同一个reCaptchaV2类型。result await executor.execute(solve_captcha, {captcha_type:reCaptchaV2,website_url:https://example.com/checkout,website_key:6Ld_SITE_KEY_HERE})差异主要在 token 返回之后。Invisible reCAPTCHA 通常绑定在按钮点击、表单提交或 JavaScript callback 上。浏览器自动化流程中除了写入 token有时还需要触发页面预期的 callback。await page.evaluate((token) {constresponse document.getElementById(g-recaptcha-response);if(response) { response.innerHTML token; }if(typeof___grecaptcha_cfg !undefined) {constclients ___grecaptcha_cfg.clients;for(constidinclients) {constclient clients[id];constcallback client?.callback || client?.L?.L?.callback || client?.l?.l?.callback;if(typeofcallback function) { callback(token);break; } } } },token, )不同网站的 callback 结构可能不同因此接入时需要在测试环境中确认页面逻辑。不要把 invisible reCAPTCHA 简单理解成“只填一个字段就一定完成”有些页面还会检查回调是否执行。第四步使用 Browser mode 自动检测和回填如果 LangChain Agent 是动态浏览页面并且事先不知道页面是否存在 CAPTCHA可以使用 Browser mode。SDK 会检查当前页面识别支持的 CAPTCHA 类型完成求解并把 token 回填到页面中。importasynciofromcapsolver_coreimportcreate_capsolverfromplaywright.async_apiimportasync_playwrightasyncdefsolve_recaptcha_on_page(target_url:str): cap create_capsolver(api_keyYOUR_CAPSOLVER_API_KEY)asyncwithasync_playwright()asp: browser awaitp.chromium.launch(headlessTrue) page awaitbrowser.new_page()awaitpage.goto(target_url)awaitpage.wait_for_load_state(networkidle) results awaitcap.solve_on_page(page)forresultinresults:ifresult.solution:print(fSolved{result.info.type})print(fFilled into page:{result.filled})else:print(fFailed to solve{result.info.type}:{result.error}) submit page.locator(button[typesubmit])ifawaitsubmit.count() 0:awaitsubmit.click()awaitpage.wait_for_load_state(networkidle)print(fCurrent page:{page.url})awaitbrowser.close()awaitcap.aclose() asyncio.run(solve_recaptcha_on_page(https://example.com/login))Browser mode 的价值在于它可以直接从 live DOM 中读取 CAPTCHA 参数不需要手动查找 site key。对于复杂页面、动态加载页面或 Agent 自主浏览任务这种方式更自然。第五步在生产级 LangChain Agent 中加入 reCAPTCHA 处理生产环境中CAPTCHA 处理不应该是一个完全开放的 Agent 行为而应该是受控工具的一部分。Agent 可以请求工具但应用层需要定义边界例如允许访问的来源、最大重试次数、日志字段和停止条件。下面是一个简化的 ReAct Agent 示例import asynciofromlangchain_openai import ChatOpenAIfromlanggraph.prebuilt import create_react_agentfromcapsolver_agent.langchain import get_langchain_tools async def run_authorized_agent_workflow(): capsolver_tools get_langchain_tools(api_keyYOUR_CAPSOLVER_API_KEY) llm ChatOpenAI(modelgpt-4o,temperature0) agent create_react_agent(llm,toolscapsolver_tools) response await agent.ainvoke({messages: [ (user,For my authorized test workflow, solve the reCAPTCHA v2 at https://example.com/gate. The site key is 6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI. Return the token.) ] }) return response[messages][-1].content result asyncio.run(run_authorized_agent_workflow())print(result)更完整的生产系统通常还需要临时失败后的 retry 逻辑。提交前重新获取 token 的机制。CAPTCHA 类型、求解状态、耗时和页面状态日志。敏感流程中的人工审核或停止条件。分别处理 reCAPTCHA v2、reCAPTCHA v3 和 Enterprise 变体。如果目标页面使用 reCAPTCHA v3参数会不同通常需要page_action。Enterprise 版本也可能需要额外字段。最佳实践是先识别 CAPTCHA 类型再传入对应参数。常见接入错误把 reCAPTCHA v2 和 v3 混用reCAPTCHA v2 和 v3 不是同一种任务。v2 常见形式是 checkbox 或 invisible challengev3 通常基于分数和 action并可能通过renderSITE_KEY的脚本参数加载。太早获取 tokenreCAPTCHA token 有时效性。应尽量在提交表单前再请求 token。如果 Agent 在求解后还要执行很多步骤建议在最终提交前重新获取。复用错误的 site key同一网站的不同页面可能使用不同 site key 或不同配置。应针对实际访问的 URL 检测或确认 site key。忽略 invisible reCAPTCHA 的 callbackInvisible reCAPTCHA 不一定只依赖g-recaptcha-response字段。有些页面还要求执行绑定的 callback。接入时需要验证页面端逻辑是否完整触发。把 CAPTCHA 求解当成通用兜底CAPTCHA 处理只应该用于授权工作流。如果 Agent 到达了不应自动化访问的页面正确做法是停止、报错或转人工处理而不是继续尝试。常见问题LangChain 可以不打开浏览器处理 reCAPTCHA 吗可以。Token mode 不需要浏览器。你只需要提供页面 URL 和 site keyCapSolver 会返回一个 token应用再把它提交到页面需要的字段。什么时候用 Browser mode当 Agent 已经通过 Playwright 浏览页面并且事先不知道 CAPTCHA 参数时适合使用 Browser mode。它可以在 live page 中自动检测并回填 token。invisible reCAPTCHA 也能用同样方式处理吗可以。Invisible reCAPTCHA v2 使用同样的reCaptchaV2task 类型。区别在于浏览器端可能需要额外触发 callback。token 过期怎么办重新请求 token并尽快提交。可靠的生产流程应该在接近最终表单提交时再求解 CAPTCHA。能处理 reCAPTCHA Enterprise 吗可以但 Enterprise 场景可能需要额外参数。应先识别页面的 CAPTCHA 配置再按实际需要传入字段。总结LangChain Agent 在真实浏览器自动化任务中经常会遇到 reCAPTCHA v2尤其是在登录、表单、搜索、查询和受保护页面中。通过 CapSolver 的 LangChain 工具可以把 CAPTCHA token 处理接入 Agent 工作流而不是让链路在验证页面中断。已知 URL 和 site key 时优先使用 Token mode。Agent 动态浏览页面时可以使用 Browser mode 做自动检测和回填。生产环境中要把这个能力放在授权、可审计、可停止的工具边界内并在提交前及时获取 token。参考文章https://www.capsolver.com/blog/langchain-recaptcha-solver-ai-agent-guide?utm_sourcecsdnutm_mediumarticleutm_campaignlangchain-recaptcha-solver-ai-agent-guide