Haystack Agents में CAPTCHA पहचान उपकरण कैसे जोड़ें

सारांश

• Haystack टूल मौजूदा ब्राउज़र पेज पर CAPTCHA पैरामीटर जाँचने के लिए आधिकारिक CapSolver Core SDK को कॉल कर सकता है।
• निरीक्षण टूल के ज़रिए एजेंट को मनचाहे URL पर घुमाने की बजाय, टूल को उसी पेज से बाँधें जिसे आपका ऐप पहले से नियंत्रित कर रहा है।
• उदाहरण runnable कोड, Google के reCAPTCHA v2 टेस्ट विजेट वाले स्थानीय पेज से CAPTCHA का प्रकार, पेज URL और पब्लिक साइट की लौटाता है।
• यह एक नैटिव Python इंटीग्रेशन है: MCP सर्वर या किसी ट्रांसपोर्ट की ज़रूरत नहीं है।
• डिटेक्शन न तो solver टास्क बनाता है, न टोकन लौटाता है, न यह साबित करता है कि ऐप्लिकेशन ने वेरिफ़िकेशन स्वीकार कर लिया है।

जब किसी ब्राउज़र-आधारित एजेंट के काम में CAPTCHA बाधा डालता है, तो उसे उपयोगी जानकारी की ज़रूरत होती है। केवल पेज टाइटल या स्क्रीनशॉट से यह साफ़ नहीं होता कि कौन-सा CAPTCHA परिवार मौजूद है या अगले कदम को किन पैरामीटरों की ज़रूरत होगी। एक छोटा structured परिणाम लौटाने से ऐप्लिकेशन को CAPTCHA सॉल्यूशन मांगने से पहले साफ़ निर्णय बिंदु मिल जाता है।

Haystack Python फ़्रेमवर्क है जो AI ऐप्लिकेशन, रिट्रीवल पाइपलाइन और एजेंट बनाने के लिए इस्तेमाल होता है। इसके नैटिव टूल्स उन फ़ंक्शनों को wrap कर सकते हैं जिन्हें ये ऐप्लिकेशन उपयोग करते हैं। यह गाइड एक ख़ास कार्य के लिए Haystack टूल को CapSolver से जोड़ता है: मौजूदा ब्राउज़र पेज को inspect कर CAPTCHA पैरामीटर लौटाना। उदाहरण में एक डेवलपमेंट पेज का उपयोग किया गया है और कोई paid solving रिक्वेस्ट नहीं की जाती। यह आपको एक काम करने वाला inspection कंपोनेंट देता है जिसे आप अलग से अधिकृत solving स्टेप से पहले रख सकते हैं।

Haystack वर्कफ़्लो में CAPTCHA टूल की जगह

CAPTCHA inspection टूल उस ब्राउज़र ऐक्शन और decision code के बीच आता है जो वेरिफ़िकेशन checkpoint तक पहुँचता है और जो तय करता है कि इस checkpoint को कैसे हैंडल करना है। नेविगेशन और current page पर स्वामित्व ब्राउज़र का रहता है। Haystack टूल इंटरफ़ेस देता है; Core SDK समर्थित CAPTCHA जानकारी पढ़ता है।

उदाहरण के लिए, अपनी ही फ़ॉर्म का परीक्षण कर रही टीम ब्राउज़र से फ़ॉर्म तक पहुँचने दे सकती है, फिर inspection टूल invoke कर सकती है और लौटाए गए type और site key की जाँच कर सकती है। इसके बाद टेस्ट हार्नेस अपने अप्रूव्ड test-key path या अलग से कॉन्फ़िगर solver चेक चुन सकता है। CAPTCHA विजेट को स्वयं फ़ॉर्म की बिज़नेस content के रूप में नहीं लेना चाहिए।

यह Haystack की documented Tool abstraction का इस्तेमाल करने वाला डेवलपर इंटीग्रेशन है, न कि किसी dedicated Haystack प्लग‑इन का दावा। टूल का उद्देश्य संकरा है और इसे चलने के लिए LLM की ज़रूरत नहीं। इसे सीधे कॉल करना model‑driven tool selection जोड़ने से पहले उपयोगी है।

उदाहरण चलाने से पहले क्या चाहिए

आपको Python, Haystack पैकेज, Playwright dependency के साथ CapSolver Core SDK और Playwright के लिए Chromium इंस्टॉल होना चाहिए। नीचे दिया गया उदाहरण Python 3.12, haystack-ai 3.4.0, capsolver-core 0.1.1 और Playwright 1.64.0 के साथ चलाया गया। ये tested versions हैं, यह दावा नहीं कि ये सबसे नए रिलीज़ हैं।

ब्राउज़र को Google का public reCAPTCHA script लोड करने में सक्षम होना चाहिए। लोकल पेज Google की documented development site key का उपयोग करता है; यह production key नहीं है और इसे production में deploy नहीं करना चाहिए। Google की reCAPTCHA टेस्टिंग गाइडेंस टेस्ट keys और production verification के बीच अंतर समझाती है।

इस inspection-only उदाहरण के लिए CapSolver API key या किसी model‑provider key की ज़रूरत नहीं है। बाद में solving ऑपरेशन के लिए वैध CapSolver account key चाहिए होगी। बाद में LLM‑driven Haystack Agent के लिए अपनी कॉन्फ़िगर की हुई model provider ज़रूरी होगी। ये अलग‑अलग prerequisites हैं, इसलिए CAPTCHA पैरामीटर बदलकर missing model credentials की troubleshooting न करें।

Tested पैकेज इंस्टॉल करें

एक virtual environment बनाएँ और पैकेज वहीं इंस्टॉल करें। Chromium इंस्टॉलेशन भी उसी Python interpreter से चलाएँ ताकि ब्राउज़र dependency Playwright के साथ aligned रहे।

python3 -m venv .venv
.venv/bin/python -m pip install "haystack-ai==3.4.0" "capsolver-core[playwright]==0.1.1" "playwright==1.64.0"
.venv/bin/python -m playwright install chromium

ऊपर दिए गए कमांड POSIX‑स्टाइल environment path का उपयोग करते हैं। अगर आपका OS अलग virtual‑environment लेआउट उपयोग करता है, तो उसी environment के Python executable का उपयोग करें। Playwright Python installation guide इसके ब्राउज़र इंस्टॉलेशन requirements को कवर करती है।

मौजूदा पेज को inspect करने वाला टूल बनाएँ

यह टूल आधिकारिक Core SDK के get_captcha_info(page) को wrap करता है। पेज फ़ंक्शन के द्वारा capture किया जाता है, इसलिए टूल में कोई नेविगेशन argument नहीं है। इसकी JSON parameter schema कोई input field स्वीकार नहीं करती।

निम्न को haystack_captcha_inspection.py के रूप में सेव करें। लोकल HTML response Playwright routing से आता है; यह डेवलपमेंट fixture है, remotely hosted ऐप्लिकेशन नहीं। reCAPTCHA script खुद Google से लोड होती है। प्रोग्राम विजेट पर क्लिक किए बिना या फ़ॉर्म सबमिट किए बिना पैरामीटर पढ़ता है।

import asyncio
import json

from capsolver_core import create_capsolver
from haystack.tools import Tool
from playwright.async_api import async_playwright

TEST_PAGE = """<!doctype html><html><body>
<div id="captcha" class="g-recaptcha"
     data-sitekey="6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI"></div>
<script src="https://www.google.com/recaptcha/api.js" async defer></script>
</body></html>"""


async def main():
    async with async_playwright() as pw:
        browser = await pw.chromium.launch()
        try:
            page = await browser.new_page()
            await page.route("http://127.0.0.1:8765/", lambda route: route.fulfill(
                status=200, content_type="text/html", body=TEST_PAGE))
            await page.goto("http://127.0.0.1:8765/")
            await page.wait_for_function(
                "() => window.___grecaptcha_cfg && "
                "Object.keys(window.___grecaptcha_cfg.clients || {}).length > 0")
            async with create_capsolver() as cap:
                async def inspect_captcha():
                    infos = await cap.get_captcha_info(page)
                    return {"captchas": [
                        {"type": info.type.value,
                         "website_url": info.website_url,
                         "website_key": info.website_key}
                        for info in infos
                    ]}

                captcha_tool = Tool(
                    name="inspect_current_page_captcha",
                    description="Read CAPTCHA types and public parameters from the current approved page; does not solve or submit.",
                    parameters={"type": "object", "properties": {},
                                "additionalProperties": False},
                    async_function=inspect_captcha,
                )
                result = await captcha_tool.invoke_async()
                print(json.dumps(result, indent=2))
        finally:
            await browser.close()


if __name__ == "__main__":
    asyncio.run(main())

async_function argument महत्वपूर्ण है क्योंकि SDK और Playwright ऑपरेशन asynchronous हैं। Haystack की Tool API reference इस path के लिए invoke_async() डॉक्युमेंट करती है। किसी coroutine को synchronous‑only call path में डालने से CAPTCHA inspection शुरू होने से पहले ही विफलता हो सकती है।

Context managers और finally ब्लॉक SDK और ब्राउज़र resources को बंद करते हैं। उदाहरण को किसी लंबे समय तक चलने वाले ऐप में ढालते समय भी यह cleanup रखें; नहीं तो असफल पेज लोड के बाद ब्राउज़र processes पीछे छूट सकते हैं।

अपना CapSolver बोनस कोड रिडीम करें

अपने ऑटोमेशन बजट को तुरंत बढ़ाएँ!
CapSolver अकाउंट recharge करते समय बोनस कोड CAP26 का उपयोग करें और हर recharge पर अतिरिक्त 5% बोनस पाएँ — बिना किसी लिमिट के।
इसे अभी अपने CapSolver Dashboard में रिडीम करें।

Inspection चलाएँ और परिणाम समझें

स्क्रिप्ट चलाने पर Haystack टूल सीधे invoke होता है और लौटाई गई dictionary को प्रिंट करता है। उदाहरण में dictionary में captchas नाम की एक list है जिसमें एक reCAPTCHA v2 entry है।

.venv/bin/python haystack_captcha_inspection.py

लोकल रन में type reCaptchaV2, website_url http://127.0.0.1:8765/ और HTML में configured public test site key लौटी। ये फ़ील्ड असली SDK और ब्राउज़र के माध्यम से पढ़ी गईं, किसी mocked टूल response में हाथ से नहीं भरी गईं।

परिणाम जानबूझकर छोटा रखा गया है। पूरा SDK descriptor में अतिरिक्त फ़ील्ड हो सकते हैं, लेकिन एजेंट को केवल वही मिलना चाहिए जिसकी अगली decision के लिए ज़रूरत हो। Site key एक public widget identifier है; यह CapSolver account key या साइट का private verification secret नहीं है।

यह रन यह स्थापित करता है कि Haystack async फ़ंक्शन invoke कर सकता है, ब्राउज़र डेवलपमेंट विजेट लोड कर सकता है और Core SDK उसके पैरामीटर पढ़ सकता है। यह यह स्थापित नहीं करता कि मॉडल‑आधारित tool selection सही काम कर रहा है, हर साइट पर production CAPTCHA detection सफल है, टोकन generation सफल है या वेबसाइट के backend ने उसे स्वीकार कर लिया। इनके लिए असली ऐप्लिकेशन के साथ अलग‑अलग जाँच की ज़रूरत है।

Inspected पेज को मौजूदा एजेंट से जोड़ें

जब इस क्षमता को अपने Haystack Agent में जोड़ें, तो वही Tool object और page binding रखें। Haystack Agent documented tools कॉन्फ़िगरेशन के ज़रिए tools स्वीकार करता है। इस object को उन tools के साथ register करें जिन्हें आपका ऐप पहले से उपयोग कर रहा है, और कॉल की अवधि तक ब्राउज़र पेज को ज़िंदा रखें।

मौजूदा ब्राउज़र वर्कफ़्लो में, लोकल fixture setup को उस पेज से बदलें जिसे आपका ऐप पहले से खोल चुका है और inspect करने के लिए authorized है। ब्राउज़र नेविगेशन को इस टूल के बाहर ही रखें। इससे page selection explicit रहेगा और model‑generated URL inspection के target को चुपचाप बदल नहीं पाएगा।

टूल का नाम और विवरण सटीक रखें। उदाहरण में विवरण साफ़ कहता है कि यह CAPTCHA जानकारी पढ़ता है और न solve करता है, न submit। “finish verification” जैसा विवरण फ़ंक्शन की क्षमता से ज़्यादा वादा करेगा और एजेंट को समय से पहले सफलता रिपोर्ट करने के लिए उकसा सकता है।

एक उपयोगी ऐप्लिकेशन निर्णय यह हो सकता है: अगर परिणाम में ज़रूरी पैरामीटरों के साथ कोई पहचानने योग्य widget हो, तो उचित अगला स्टेप ऑफ़र करें; अगर सूची खाली या अधूरी हो, तो और सबूत इकट्ठा करें या मानव समीक्षा माँगें। ऐसा unconditional loop न जोड़ें जो अधूरे पेज को बार‑बार inspect करता रहे।

Detection और solving को अलग स्टेप बनाए रखें

Inspection परिणाम solver decision का इनपुट है, CAPTCHA समाधान नहीं। Core SDK solve(info) को token solving के लिए और solve_on_page(page) को व्यापक ब्राउज़र वर्कफ़्लो के लिए डॉक्युमेंट करता है। इनका असर get_captcha_info(page) से अलग है और इनके लिए अलग कॉन्फ़िगरेशन और authorization चाहिए।

इस गाइड के लिए inspection टूल का उद्देश्य केवल read‑only रखें। अगर बाद में solving टूल जोड़ते हैं, तो अपना ऐप detected type और current page validate करे, account credential model‑visible arguments के बाहर दे, और उस वर्कफ़्लो के अनुसार बजट व approval नियम लागू करे। परिणाम इस तरह लौटाएँ कि token और completed ऐप action के बीच साफ़ फ़र्क स्पष्ट हो।

लौटा हुआ token भी प्रासंगिक ऐप्लिकेशन handling माँगता है। साइट की verification और फ़ॉर्म का वास्तविक परिणाम यह निर्धारित करते हैं कि इच्छित ऑपरेशन सफल हुआ या नहीं। न तो non‑empty captchas list और न ही सफल Haystack टूल invocation इस बात का सबूत हैं कि ऐप्लिकेशन ने CAPTCHA response स्वीकार कर लिया।

अंदाज़ा लगाए बिना कनेक्शन troubleshoot करें

Troubleshooting में यह पहचानना चाहिए कि कौन‑सी लेयर विफल हुई: पैकेज इंस्टॉलेशन, ब्राउज़र स्टार्टअप, विजेट लोडिंग, SDK inspection या टूल invocation। उसी लेयर में बदलाव करें जिसे error support करता है, बजाय इसके कि एक साथ कई कंपोनेंट बदलें।

ब्राउज़र executable missing है

Active virtual environment से Playwright कमांड के साथ Chromium इंस्टॉल करें। सफल pip install सिर्फ Python पैकेज इंस्टॉल करता है; यह अपने आप यह साबित नहीं करता कि matching ब्राउज़र binary उपलब्ध है।

Widget wait time‑out हो जाता है

जाँचें कि ब्राउज़र ने Google script लोड किया या नहीं, और टेस्ट पेज ने विजेट बनाया या नहीं। इस उदाहरण में wait initialized widget clients को खोजता है। नेटवर्क विफलता SDK के inspect करने से पहले हो सकती है; solver को दोबारा चलाने से यह समस्या हल नहीं होगी।

टूल खाली list लौटाता है

खाली परिणाम का मतलब है कि इस inspection ने उस समय उस पेज पर कोई supported descriptor नहीं पाया। यह यह साबित नहीं करता कि पेज पर verification mechanism नहीं है। पेज timing, आपने जो page object पास किया, और actual widget की जाँच करें। CAPTCHA parameter inspection guide ब्राउज़र state inspect करने का पूरक तरीका प्रदान करता है।

टूल सीधे काम करता है, एजेंट में नहीं

जाँचें कि वही Tool object register है, एजेंट का मॉडल इच्छित tool workflow को सपोर्ट करता है और ब्राउज़र सत्र अभी भी खुला है। सफल direct invocation को अलग checkpoint के रूप में रखें ताकि model कॉन्फ़िगरेशन समस्या को CAPTCHA API विफलता के रूप में गलत न बताया जाए।

Inspection परिणाम को उपयोगी बनाएँ

छोटा‑सा CAPTCHA inspection टूल Haystack ऐप्लिकेशन को solving से पहले ठोस checkpoint देता है। Tested development पेज से शुरू करें, async call और cleanup को बरक़रार रखें, फिर टूल को उस पेज से attach करें जिसे आपका मौजूदा वर्कफ़्लो नियंत्रित करता है। इसकी ज़िम्मेदारियाँ तभी बढ़ाएँ जब हर अतिरिक्त ऑपरेशन का इनपुट स्पष्ट हो, व्यवहार verify किया जा चुका हो और परिणाम observible हो।

CapSolver के साथ विश्वसनीय ऑटोमेशन वर्कफ़्लो बनाएँ

किसी ऐसे वर्कफ़्लो में, जिसे चलाने के लिए आप authorized हैं, उसके supported CAPTCHA स्टेप के लिए CapSolver का उपयोग करें। ब्राउज़र, solver परिणाम और ऐप्लिकेशन outcome को अलग‑अलग जाँच के रूप में रखें ताकि सफल tool call किसी असफल task को छुपा न दे।

FAQ

प्रश्न: क्या इस इंटीग्रेशन के लिए MCP ज़रूरी है?

नहीं। उदाहरण में एक native Haystack टूल और Python Core SDK को एक ही ऐप्लिकेशन में उपयोग किया गया है। यह MCP सर्वर स्टार्ट नहीं करता।

प्रश्न: स्क्रिप्ट चलाने के लिए क्या मुझे LLM API key चाहिए?

नहीं। स्क्रिप्ट टूल को सीधे invoke करती है। जब आप उसी टूल के चारों ओर LLM‑driven एजेंट जोड़ेंगे, तब model‑provider credential प्रासंगिक हो जाएँगे।

प्रश्न: क्या उदाहरण test CAPTCHA solve करता है?

नहीं। यह विजेट लोड करता है और public पैरामीटर पढ़ता है। यह न solver token मांगता है और न फ़ॉर्म submit करता है।

प्रश्न: क्या यही तरीका मौजूदा Playwright पेज inspect कर सकता है?

हाँ। टूल को मौजूदा authorized पेज से bind करें और invocation के दौरान उस पेज को ज़िंदा रखें। Supported descriptor फ़ील्ड इस पर निर्भर करते हैं कि SDK उस पेज पर क्या detect कर सकता है।
प्रश्न: बिना किसी आर्ग्युमेंट वाला टूल क्यों उपयोग करें?

फ़ंक्शन को पहले से ही वर्तमान स्वीकृत पेज के बारे में पता होता है। खाली इनपुट स्कीमा नेविगेशन और पेज चयन को एप्लिकेशन के नियंत्रण में रखता है।

प्रश्न: क्या खाली परिणाम का मतलब है कि पेज को सामान्य सामग्री की तरह प्रोसेस करना सुरक्षित है?

नहीं। आगे बढ़ने से पहले पेज की स्थिति की जाँच करें। खाली डिटेक्शन परिणाम टाइमिंग, असमर्थित मैकेनिज़्म, या अधूरी विजेट इनिशियलाइज़ेशन को भी दर्शा सकता है।