ادغام CapSolver در LangChain توقف عامل‌های هوشمند در برابر reCAPTCHA v2 را حذف

اگر امروز یک عامل هوشمند برای جمع‌آوری داده‌های وب طراحی می‌کنید، احتمالاً با دیوار مسدودکنندهٔ reCAPTCHA v2 مواجه شده‌اید که کل فرآیند را متوقف می‌کند. باید بدانید که اکنون این مانع با یک ابزار تخصصی به بخشی از زنجیره استدلال مدل تبدیل شده است.

عامل‌های خودکار که از لنگ‌چین (LangChain) استفاده می‌کنند، اغلب هنگام مواجهه با reCAPTCHA v2 متوقف می‌شوند؛ زیرا این لایه‌های امنیتی دقیقاً برای مسدود کردن نشست‌های مرورگر اسکریپتی طراحی شده‌اند که عامل‌ها به آن‌ها متکی هستند. طبق یک راهنمای فنی منتشر شده در ۹ جولای ۲۰۲۶، ادغام کپ‌سالور (CapSolver) تضمین می‌کند که عامل‌ها بتوانند این چالش‌ها بدون شکستن حلقهٔ اجرا حل کنند. این قابلیت به عامل‌ها اجازه می‌دهد تا حتی در مواجهه با چالش‌های چک‌باکس یا اعلان‌های نامرئی، یک جریان کاری مستمر و بدون وقفه را حفظ کنند.

عامل‌های مبتنی بر مرورگر اکنون وظایف پیچیده‌ای از جمله جمع‌آوری داده‌های ساختاریافته، ارسال فرم‌ها و پیمایش در پورتال‌های وب چندمرحله‌ای را بر عهده دارند. از آنجا که این عامل‌ها اغلب در محیط‌های بدون رابط گرافیکی (Headless)، نشست‌های مرورگر اسکریپتی یا با الگوهای تکراری عمل می‌کنند، به‌طور مکرر باعث فعال شدن بررسی‌های تأیید هویت می‌شوند. برای عامل‌های لنگ‌چین، این توقف‌ها معمولاً در سناریوهای زیر رخ می‌دهد:

• جریان‌های کاری مربوط به ورود به حساب کاربری یا مدیریت حساب‌ها.
• جمع‌آوری داده از صفحاتی که به‌طور اجباری نیاز به تأیید هویت دارند.
• انجام وظایف جست‌وجو و رزرو آنلاین.
• فرآیندهای پرداخت و تسویه حساب (Checkout).
• پیمایش در پورتال‌هایی که در میانهٔ یک فرآیند چندمرحله‌ای، درخواست تأیید هویت ظاهر می‌شود.

این وقفه‌ها معمولاً به یکی از دو شکل ظاهر می‌شوند. اولین مورد، چالش کلاسیک چک‌باکس است. دومین مورد، reCAPTCHA «نامرئی» است که ممکن است در پس‌زمینه اجرا شود و تنها زمانی فعال گردد که صفحه تصمیم بگیرد تأییدیه اضافی مورد نیاز است. در هر دو حالت، صفحه وب منتظر یک توکن معتبر است که معمولاً از طریق فیلد g-recaptcha-response ارسال می‌شود.

بدون داشتن مکانیزم مناسب برای درخواست و تزریق یک توکن تأیید معتبر، یک زنجیره در لنگ‌چین به محض رسیدن به یک صفحه محافظت‌شده، به‌سادگی شکست می‌خورد. به نقل از راهنمای dev.to، راهکار این مشکل در فراهم کردن یک ابزار تخصصی برای عامل نهفته است تا بتواند با API کپ‌سالور تعامل کرده و توکن g-recaptcha-response مورد نیاز را بازیابی کند. این ادغام باعث می‌شود مدیریت کپچا به بخشی از استدلال عادی و حلقهٔ اجرای عامل تبدیل شود. برای دستیابی به این یکپارچگی، از بسته capsolver-agent برای پشتیبانی بی‌سروصدا از ابزارهای لنگ‌چین استفاده می‌شود.

پیش‌نیازهای فنی

برای شروع این ادغام، توسعه‌دهندگان باید بسته‌های ضروری را از طریق pip نصب کنند:

• 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

پیکربندی سیستم نیازمند تعریف دو متغیر محیطی اصلی برای احراز هویت سرویس‌ها است:

• export CAPSOLVER_API_KEY="your-capsolver-api-key"
• export OPENAI_API_KEY="your-openai-api-key"

برای کسانی که از حالت توکنی (Token mode) استفاده می‌کنند، کلید سایت (Site Key) مربوط به reCAPTCHA نیز باید شناسایی شود. این کلید را می‌توان با بازرسی سورس صفحه، استفاده از ابزارهای توسعه‌دهنده مرورگر (Developer Tools) یا با بهره‌گیری از افزونه مرورگر کپ‌سالور برای شناسایی پارامترهای خاص کپچا پیدا کرد.

شناسایی کلید سایت

در reCAPTCHA v2، کلید سایت معمولاً در یک ویژگی به نام data-sitekey در کد HTML ذخیره شده است. یک چک‌باکس مرئی معمولی به این شکل است: <div class="g-recaptcha" data-sitekey="6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI"></div>. نسخه‌های نامرئی نیز از همین الگو پیروی می‌کنند اما ویژگی data-size="invisible" را شامل می‌شوند، مانند: <div class="g-recaptcha" data-sitekey="6LeIxAcT..." data-size="invisible"></div>.

ثبت دقیق مقادیر زیر بسیار حیاتی است:

• آدرس کامل صفحه (URL).
• مقدار دقیق و کامل data-sitekey.
• اینکه صفحه از reCAPTCHA مرئی استفاده می‌کند یا نامرئی.

توکن باید دقیقاً برای پیکربندی همان صفحه تولید شود، زیرا کلیدهای سایت حتی در یک دامنه واحد نیز می‌توانند متفاوت باشند. اگر از Playwright استفاده کنید، کتابخانه capsolver-core می‌تواند این جزئیات را به‌صورت برنامه‌نویسی شده تشخیص دهد. با استفاده از نمونه create_capsolver و متد get_captcha_info(page)، سیستم می‌تواند به‌طور خودکار info.type و info.website_key را چاپ کند و نیاز به بازرسی دستی را کاملاً از بین ببرد.

حالت توکنی: حل هدفمند

حالت توکنی بهینه‌ترین مسیر است، به‌ویژه زمانی که عامل از پیش آدرس URL هدف و کلید سایت مربوطه را می‌داند. در این حالت، عامل لنگ‌چین کپ‌سالور را به عنوان یک ابزار فراخوانی کرده و توکنی را دریافت می‌کند تا آن را همراه با فرم ارسال کند.

جزئیات پیاده‌سازی:

• سازوکار: عامل با استفاده از ابزارهایی که از طریق get_langchain_tools(api_key="...") بازیابی شده‌اند، کپ‌سالور را فراخوانی می‌کند. در یک جریان عامل ری‌اکت (ReAct) با استفاده از create_react_agent- مدل‌های زبانی بزرگ (مانند gpt-4o با دمای ۰) می‌توانند با دریافت دستور «Solve the reCAPTCHA v2 for [URL]» و دریافت کلید سایت، توکن پاسخ را برگردانند. 이러한 خودکارسازی گام‌های متوالی یادآور رویکرد حالت goal در Grok Build است که کدنویسی چندمرحله‌ای را به همین شکل ساده کرده است.
• کارایی: این حالت بسیار سبک است زیرا برای تولید توکن نیازی به باز کردن یک نشست فعال مرورگر ندارد؛ در واقع این یک درخواست مستقیم API است.
• اجرای مستقیم: برای توسعه‌دهندگانی که ترجیح می‌دهند کنترل کاملی روی حلقه تصمیم‌گیری LLM داشته باشند، رابط create_executor از capsolver_agent.schema اجازه فراخوانی مستقیم را می‌دهد: executor.execute("solve_captcha", {"captcha_type": "reCaptchaV2", "website_url": "...", "website_key": "..."}).
• کاربرد: این روش برای جریان‌های کاری استاتیک که زیرساخت هدف و پارامترهای آن از قبل شناخته شده‌اند، ایده‌آل است.

پس از دریافت توکن از فیلد result["solution"]["token"] در پاسخ API، جریان کاری باید این توکن را از طریق فیلد g-recaptcha-response که توسط صفحه انتظار می‌رود، ارسال کند.

حالت مرورگر: تشخیص پویا

برای عامل‌هایی که به‌صورت پویا در صفحات وب پیمایش می‌کنند، بسته capsolver-agent حالت مرورگر (Browser mode) را ارائه می‌دهد. این حالت زمانی ضروری است که جریان کاری از پیش نمی‌داند آیا یک صفحه حاوی کپچا هست یا خیر.

جریان عملیاتی:

• فرآیند: با استفاده از چارچوب async_playwright- عامل یک مرورگر کرومیوم را اجرا می‌کند (اغلب در حالت headless=True)، به URL هدف می‌رود و منتظر می‌ماند تا وضعیت بارگذاری صفحه به networkidle برسد.
• تشخیص: به‌جای استخراج دستی کلید سایت، متد solve_on_page(page) در SDK به‌طور خودکار صفحه زنده را بازرسی کرده و انواع کپچاهای پشتیبانی‌شده را شناسایی می‌کند. این یکپارچگی در محیط‌های وب، مشابه استانداردسازی محیط‌های چندعاملی در کتابخانه acp-components است که اجرای هم‌زمان ابزارها را بر روی وب تسهیل می‌کند.
• جای‌گذاری (Fill-back): پس از یافتن راه حل، SDK توکن پاسخ را مستقیماً در عناصر DOM صفحه زنده جای‌گذاری می‌کند. شیء نتیجه (Result object) از طریق result.solution پیگیری می‌کند که آیا فرآیند موفق بوده و آیا توکن در صفحه filled شده است یا خیر.
• اجرا: پس از جای‌گذاری توکن، عامل می‌تواند دکمه ارسال را پیدا کند — که معمولاً با button[type="submit"] شناسایی می‌شود — و با کلیک روی آن، عملیات را تکمیل کند.

این رویکرد به‌ویژه برای عامل‌هایی که به‌صورت پویا صفحات را می‌گردند مفید است و به کمک‌های سطح مرورگر اجازه می‌دهد تا تشخیص کپچا را در حین پیمایش به‌صورت یکپارچه مدیریت کنند.

مدیریت reCAPTCHA v2 نامرئی

چالش‌های نامرئی یک مانع منحصربه‌فرد هستند زیرا اغلب با بازخوردهای جاوااسکریپت (Callbacks) گره خورده‌اند. صرفاً تزریق توکن به فیلد g-recaptcha-response در بسیاری از موارد کافی نیست، زیرا reCAPTCHAهای نامرئی اغلب از طریق کلیک روی یک دکمه یا یک رویداد خاص فرم فعال می‌شوند.

برای غلبه بر این مشکل، توسعه‌دهندگان باید از یک اسکریپت ارزیابی صفحه (page.evaluate) برای فعال کردن بازخورد مورد انتظار استفاده کنند. این سازوکار شامل مراحل زیر است:

۱. یافتن عنصر g-recaptcha-response و تنظیم innerHTML آن به مقدار توکن.
۲. بررسی وجود شیء ___grecaptcha_cfg در محیط صفحه.
۳. پیمایش در شیء clients برای یافتن یک بازخورد (Callback) کاربردی (بررسی مسیرهایی مانند client.callback یا client.L.L.callback یا client.l.l.callback).
۴. اجرای تابع بازخورد یافته با استفاده از توکن به عنوان آرگومان ورودی.

از آنجا که ساختارهای Callback بسته به پیاده‌سازی هر وب‌سایت به‌شدت متفاوت است، بازرسی دقیق و تست در محیط‌های کنترل‌شده برای اطمینان از پذیرفته شدن توکن ضروری است.

الگوهای پیاده‌سازی در محیط عملیاتی

در یک محیط تولید (Production)، مدیریت کپچا باید در یک عامل ReAct (Reasoning and Acting) ادغام شود. این کار به مدل‌های زبانی مانند GPT-4o اجازه می‌دهد تا بر اساس وضعیت صفحه‌ای که مشاهده می‌کند، تصمیم بگیرد چه زمانی ابزار حل کپچا را فراخوانی کند. چنین رویکردی برای بهبود پایداری عملیاتی در سیستم‌های AI حیاتی است تا از توقفات ناگهانی در محیط‌های حساس جلوگیری شود.

حفاظ‌های عملیاتی (Production Safeguards):

• منطق تکرار (Retry Logic): پیاده‌سازی مکانیزم‌هایی برای مدیریت شکست‌های گذرا در API تا از کرش کردن کل زنجیره جلوگیری شود.
• زمان‌بندی (Timing): توکن‌های reCAPTCHA حساس به زمان هستند. عامل‌ها باید درخواست حل را تا حد ممکن نزدیک به لحظه ارسال فرم بفرستند؛ اگر عامل پس از حل کپچا مراحل اضافی را انجام می‌دهد، باید توکن تازه‌ای درخواست شود تا از انقضای آن جلوگیری شود.
• دامنه (Scope): اتوماسیون باید تنها روی جریان‌های کاری و حساب‌های مجاز اعمال شود. اگر عامل به صفحه‌ای غیرمجاز برخورد کرد، رفتار درست این است که متوقف شود، موضوع را گزارش دهد یا وظیفه را برای بازبینی انسانی ارسال کند.
• ثبت وقایع (Logging): نگهداری لاگ‌های شفاف در مورد نوع کپچا، وضعیت حل و زمان کل پاسخ‌دهی.
• مدیریت انواع (Variant Handling): منطق جداگانه‌ای برای نسخه‌های مختلف نیاز است. reCAPTCHA v3 معمولاً به یک مقدار page_action نیاز دارد و اغلب با پارامتر اسکریپت render=SITE_KEY بارگذاری می‌شود. نسخه‌های Enterprise ممکن است به فیلدهای تخصصی بیشتری نیاز داشته باشند.

اشتباهات رایج در ادغام

توسعه‌دهندگان برای تضمین پایداری باید از چندین اشتباه رایج پرهیز کنند:

• نوع اشتباه: reCAPTCHA v2 و v3 قابل جایگزینی نیستند. v2 به صورت چک‌باکس یا نامرئی است، در حالی که v3 از یک سیستم امتیازدهی (Score-based) برای تشخیص عمل می‌کند.
• استفاده مجدد از کلید سایت: استفاده مجدد از کلیدهای سایت در صفحات مختلف یک دامنه ریسک‌آور است، زیرا پیکربندی‌ها ممکن است بین URLهای مختلف متفاوت باشد.
• نادیده گرفتن بازخوردها: در چالش‌های نامرئی، نادیده گرفتن Callback جاوااسکریپت منجر به این می‌شود که فرم حتی پس از تزریق موفق توکن، ارسال نشود.
• جایگزین جهانی (Universal Fallback): برخورد با حل کپچا به عنوان یک راهکار کلی به‌جای یک ابزار هدفمند برای جریان‌های مجاز، می‌تواند منجر به این شود که عامل‌ها سعی کنند صفحاتی را اتوماتیک کنند که نباید به آن‌ها دسترسی داشته باشند.

پرسش‌های متداول

آیا لنگ‌چین می‌تواند بدون مرورگر reCAPTCHA را حل کند؟ بله، حالت توکنی (Token mode) اجازه بازیابی توکن از طریق URL و کلید سایت را بدون نیاز به نشست مرورگر می‌دهد که آن را سریع و سبک می‌کند.

چه زمانی حالت مرورگر ترجیح داده می‌شود؟ زمانی که از Playwright استفاده می‌شود و پارامترهای کپچا از پیش شناخته شده نیستند و نیاز به تشخیص خودکار و جای‌گذاری (fill-back) است.

آیا همین روش برای reCAPTCHA نامرئی هم کار می‌کند؟ بله، از همان نوع وظیفه reCaptchaV2 استفاده می‌کند، هرچند ارسال در سمت مرورگر اغلب نیازمند مدیریت خاص Callback است.

سرعت حل reCAPTCHA v2 چقدر است؟ زمان حل به نوع چالش هدف و بار سرویس بستگی دارد؛ جریان‌های عملیاتی باید برای یک انتظار کوتاه بین درخواست و دریافت توکن برنامه‌ریزی کنند.

این سیستم با reCAPTCHA Enterprise چگونه برخورد می‌کند؟ پشتیبانی می‌شود، اما ادغام‌های Enterprise بسته به پیکربندی خاص صفحه ممکن است به پارامترهای اضافی نیاز داشته باشند.

این تغییر رویکرد به توسعه‌دهندگان لنگ‌چین اجازه می‌دهد تا از اسکریپت‌های شکننده که با اولین نشانه کپچا متوقف می‌شوند، به سمت عامل‌های تاب‌آوری حرکت کنند که تأیید هویت را صرفاً به عنوان یکی دیگر از گام‌های فرآیند استدلال خود می‌بینند. این امر فرض قدیمی مبنی بر اینکه عامل‌های وب‌اسکراپر هنگام فعال شدن سیستم‌های امنیتی باید به‌صورت دستی کمک شوند را تغییر می‌دهد.

گام بعدی شما

• اگر از Playwright استفاده می‌کنید، متد solve_on_page را جایگزین استخراج دستی کلیدهای سایت کنید تا نرخ خطای شناسایی کاهش یابد.
• برای چالش‌های نامرئی، حتماً اسکریپت page.evaluate را برای پیدا کردن و اجرای Callbackهای جاوااسکریپت پیاده‌سازی کنید.
• منطق Retry را به زنجیره ReAct خود اضافه کنید تا نوسانات API کپ‌سالور باعث توقف کل عملیات جمع‌آوری داده نشود.

اما داستان سخت‌افزاری این تحول حتی شگفت‌انگیزتر است — به تحلیل ما درباره‌ی تراشه‌های Blackwell مراجعه کنید.