कैसे हल करें क्लाउडफ़ेयर टर्नस्टाइल लैंगग्राफ एजेंट्स में

TL;DR

• एक LangGraph Cloudflare Turnstile समाधान एक नियंत्रित पुनर्जीवन नोड के रूप में CAPTCHA प्रबंधन का मॉडल करना चाहिए, न कि प्रत्येक रास्ते पर असीमित उपकरण के रूप में।
• CapSolver के capsolver-agent को capsolver-core के ऊपर उपकरण-अनुकूलन परत के रूप में दस्तावेज़ किया गया है, जिसमें LangChain उपकरण एजेंट फ्रेमवर्क के लिए हैं और Playwright सत्र के लिए ब्राउज़र विधियां हैं।
• ग्राफ में नेविगेशन निर्णय रखें, निश्चित प्राधिकरण एप्लिकेशन कोड में रखें, और पहचान को CapSolver सेवा में रखें।
• पहचान, समाधान, भरना-वापस और अंतिम पृष्ठ पुष्टि के माध्यम से एक ब्राउज़र सत्र को बरकरार रखें; कभी-भी मॉडल को क्रमशः टोकन न वापस करें।
• सीमित पुनर्प्रयास, स्पष्ट अंतिम अवस्थाएं, रेडैक्टेड ट्रेसिंग, और अस्पष्ट कार्रवाई के लिए मानव समीक्षा का उपयोग करें।
• नीचे दिए गए उदाहरण ग्राफ में राज्य परिभाषाएं, नीति राउटिंग, एक CapSolver पुनर्जीवन नोड, विफलता नियंत्रण, और सत्यापन शामिल हैं।

एक LangGraph Cloudflare Turnstile एकीकरण क्या करना चाहिए

एक LangGraph Cloudflare Turnstile एकीकरण एजेंट के लिए अनुमोदित ब्राउज़र वर्कफ़्लो में एक सत्यापन चरण से पुनर्जीवित होने की अनुमति देता है और फिर मूल कार्य को जारी रखता है। ग्राफ मॉडल को बटन दबाने या विज़ुअल विकल्प के माध्यम से तर्क देने के लिए नहीं पूछता है। बल्कि, मॉडल या ब्राउज़र नियंत्रक यह निर्धारित करता है कि वर्कफ़्लो ब्लॉक हो गया है, ग्राफ नीति का मूल्यांकन करता है, और निश्चित अनुकूलन द्वारा दस्तावेज़ किए गए CapSolver क्षमता का उपयोग करता है।

CapSolver अपने एजेंट उपकरण गाइड में इस कार्य विभाजन का वर्णन करता है: मॉडल नेविगेशन और निर्णय का नियंत्रण करता है, capsolver-agent उपकरण स्कीमा और एक्सीक्यूटर प्रस्तुत करता है, और capsolver-core पहचान, समाधान और ब्राउज़र भरना-वापस करता है।

इस व्यवस्था LangGraph के लिए एक उपयोगी भूमिका प्रदान करती है। यह पुनर्जीवन को दृश्य बना सकता है, पुनर्प्रयास बजट को लागू कर सकता है, संवेदनशील कार्रवाई को मानव के लिए राउट कर सकता है, और ग्राफ जारी रखने से पहले ब्राउज़र द्वारा सफलता की पुष्टि कर सकता है।

अपेक्षित आवश्यकताएं और समर्थित एकीकरण मार्ग

एक अलग पायथन वातावरण का उपयोग करें। CapSolver की वर्तमान आधिकारिक गाइड में कोर और एजेंट पैकेज को गिट हब से स्थापित किया जाता है:

python -m venv .venv
source .venv/bin/activate
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 playwright
playwright install chromium

CAPSOLVER_API_KEY और कोई मॉडल प्रमाणीकरण एक अनुमोदित सीक्रेट स्टोर में रखें। ग्राफ राज्य, चेकपॉइंट, प्रॉम्प्ट, ट्रेसिंग घटनाएं या स्रोत फाइल में वास्तविक मान न लिखें।

आपके पास भी होना चाहिए:

• एक स्वामित्व या स्पष्ट अनुमति वाला लक्ष्य;
• एक डोमेन अनुमति सूची;
• एक परिभाषित व्यावसायिक उद्देश्य;
• एक ब्राउज़र सत्र रजिस्टर;
• अधिकतम पुनर्प्रयास संख्या;
• एक समय सीमा बजट;
• अंतिम पृष्ठ पुष्टि;
• अहम कार्रवाई के लिए मानव-समीक्षा नियम।

LangGraph राज्य डिज़ाइन करें

ग्राफ राज्य में केवल गैर-गोपनीय ऑपरेशनल डेटा रखें:

from typing import Literal, TypedDict

class AgentState(TypedDict, total=False):
    request_id: str
    purpose: str
    page_id: str
    current_url: str
    step: str
    challenge_detected: bool
    challenge_attempts: int
    challenge_status: Literal[
        "not-needed", "pending", "resolved", "review", "denied"
    ]
    error_code: str | None
    final_assertion_passed: bool

CapSolver प्रमाणीकरण, समाधान टोकन, कुकीज़ या कच्चा पृष्ठ सामग्री न जोड़ें। ब्राउज़र ऑब्जेक्ट को एक एप्लिकेशन-मालिक रजिस्टर में संग्रहीत करें जो page_id द्वारा कुंजीकृत है; ग्राफ चेकपॉइंट केवल अस्पष्ट पहचानकर्ता में शामिल होना चाहिए।

निश्चित प्राधिकरण नोड बनाएं

प्रत्येक चुनौती उपकरण से पहले प्राधिकरण चलाएं:

from urllib.parse import urlparse

ALLOWED_HOSTS = {"staging.example.com", "research.example.com"}
ALLOWED_PURPOSES = {"qa-validation", "public-data-research"}

def authorize_challenge(state: AgentState) -> AgentState:
    host = urlparse(state["current_url"]).hostname
    attempts = state.get("challenge_attempts", 0)

    if host not in ALLOWED_HOSTS:
        return {**state, "challenge_status": "denied", "error_code": "domain"}
    if state.get("purpose") not in ALLOWED_PURPOSES:
        return {**state, "challenge_status": "denied", "error_code": "purpose"}
    if attempts >= 2:
        return {**state, "challenge_status": "review", "error_code": "retry-limit"}
    return {**state, "challenge_status": "pending"}

इस नोड को सिंटैक्स-सत्यापित किया गया है और मॉडल से स्वतंत्र है। उत्पादन में, संस्करणीकृत विनिर्देशों से नीति लोड करें और अज्ञात क्षेत्रों को अस्वीकृत करें।

ग्राफ राज्य के बाहर ब्राउज़र सत्र पंजीकृत करें

class BrowserRegistry:
    def __init__(self):
        self._pages = {}

    def register(self, page_id: str, page) -> None:
        self._pages[page_id] = page

    def get(self, page_id: str):
        if page_id not in self._pages:
            raise KeyError("browser page is not registered")
        return self._pages[page_id]

    async def remove(self, page_id: str) -> None:
        page = self._pages.pop(page_id, None)
        if page is not None:
            await page.close()

रजिस्टर एक Playwright Page के सीरियलाइजेशन को रोकता है और होस्ट के लिए एक ही स्थान पर साफ़ करने के नियम लागू करता है।

अपना CapSolver बोनस कोड बदलें

अपने स्वचालन बजट को तत्काल बढ़ाएं!
CapSolver खाता में जमा करते समय बोनस कोड CAP26 का उपयोग करें ताकि प्रत्येक भुगतान पर 5% बोनस मिले — कोई सीमा नहीं।
अपने CapSolver डैशबोर्ड में अब इसे बदलें

CapSolver पुनर्जीवन नोड कार्यान्वित करें

CapSolver के कोर SDK में detect(page) और solve_on_page(page) के लिए ब्राउज़र मोड के लिए दस्तावेज़ किया गया है। नीचे दिए गए अनुकूलन इन विधियों का उपयोग करता है और केवल एक ग्राफ निर्णय वापस करता है:

import os
from capsolver_core import create_capsolver

async def solve_turnstile_node(
    state: AgentState,
    registry: BrowserRegistry,
) -> AgentState:
    page = registry.get(state["page_id"])
    attempts = state.get("challenge_attempts", 0) + 1

    async with create_capsolver(
        api_key=os.environ["CAPSOLVER_API_KEY"],
        default_timeout=120,
        polling_interval=5,
    ) as cap:
        detected = await cap.detect(page)
        if not detected:
            return {
                **state,
                "challenge_attempts": attempts,
                "challenge_status": "not-needed",
                "error_code": None,
            }

        results = await cap.solve_on_page(page)

    failures = [item for item in results if item.error or not item.filled]
    if failures:
        return {
            **state,
            "challenge_attempts": attempts,
            "challenge_status": "review" if attempts >= 2 else "pending",
            "error_code": "fill-back-failed",
        }

    return {
        **state,
        "challenge_attempts": attempts,
        "challenge_status": "resolved",
        "error_code": None,
    }

कोड सिंटैक्स-चेक किया गया है लेकिन ऑथेंटिकेशन चलाया गया नहीं है। एक लिव टेस्ट के लिए एक अनुमोदित पृष्ठ और सीक्रेट की आवश्यकता होती है। ग्राफ को कभी-भी solution.token नहीं मिलता।

पृष्ठ परिणाम की पुष्टि करें

भरा टोकन एक बीच का परिणाम है। एप्लिकेशन के अपेक्षित स्थिति की पुष्टि करें:

async def verify_page_node(
    state: AgentState,
    registry: BrowserRegistry,
) -> AgentState:
    page = registry.get(state["page_id"])
    try:
        await page.get_by_test_id("authorized-content").wait_for(timeout=15_000)
        return {
            **state,
            "final_assertion_passed": True,
            "step": "continue",
            "error_code": None,
        }
    except Exception:
        return {
            **state,
            "final_assertion_passed": False,
            "challenge_status": "review",
            "error_code": "page-assertion-failed",
        }

अपने एप्लिकेशन द्वारा स्वामित्व वाले असर्टिन का उपयोग करें। लॉग में व्यक्तिगत या संवेदनशील पृष्ठ सामग्री को उजागर करने वाले सेलेक्टर से बचें।

LangGraph वर्कफ़्लो जुड़ाएं

from langgraph.graph import END, StateGraph

def route_after_authorization(state: AgentState) -> str:
    if state["challenge_status"] == "pending":
        return "solve"
    if state["challenge_status"] in {"denied", "review"}:
        return "human_review"
    return "verify"

def route_after_solve(state: AgentState) -> str:
    if state["challenge_status"] == "resolved":
        return "verify"
    if state["challenge_status"] == "pending":
        return "authorize"
    return "human_review"

def build_graph(authorize, solve, verify, human_review):
    graph = StateGraph(AgentState)
    graph.add_node("authorize", authorize)
    graph.add_node("solve", solve)
    graph.add_node("verify", verify)
    graph.add_node("human_review", human_review)
    graph.set_entry_point("authorize")
    graph.add_conditional_edges(
        "authorize",
        route_after_authorization,
        {"solve": "solve", "verify": "verify", "human_review": "human_review"},
    )
    graph.add_conditional_edges(
        "solve",
        route_after_solve,
        {"authorize": "authorize", "verify": "verify", "human_review": "human_review"},
    )
    graph.add_edge("verify", END)
    graph.add_edge("human_review", END)
    return graph.compile()

इन्जेक्ट किए गए कार्य ब्राउज़र रजिस्टर के ऊपर बंधे हो सकते हैं। डिपेंडेंसी इंजेक्शन नीति और विफलता रास्ते के परीक्षण के लिए लाइव सेवा के बिना संभव है।

मानव-समीक्षा नोड जोड़ें

समीक्षक को प्राप्त करना चाहिए:

• अनुरोध पहचान;
• अनुमोदित उद्देश्य;
• होस्टनाम;
• प्रयास की कार्रवाई;
• पुनर्प्रयास संख्या;
• रेडैक्ट की गई त्रुटि श्रेणी;
• अनुमति के साथ सुरक्षित स्क्रीनशॉट संदर्भ, यदि अनुमत हो;
• प्रस्तावित अगला चरण।

समीक्षक को CapSolver प्रमाणीकरण या समाधान टोकन नहीं मिलना चाहिए। एक अहम कार्रवाई जैसे जमा, खरीद, खाता बदलाव, या संदेश भेजना चाहिए, यहां तक कि सत्यापन सफल होने के बाद भी अपनी ही प्राधिकरण की आवश्यकता होती है।

बाहरी सेवाओं को कॉल किए बिना ग्राफ का परीक्षण करें

इकाई परीक्षण विलेख के स्थान पर समाधान नोड को निश्चित स्टब द्वारा बदल सकते हैं:

async def solved_stub(state: AgentState) -> AgentState:
    return {
        **state,
        "challenge_attempts": state.get("challenge_attempts", 0) + 1,
        "challenge_status": "resolved",
        "error_code": None,
    }

async def failed_stub(state: AgentState) -> AgentState:
    return {
        **state,
        "challenge_attempts": state.get("challenge_attempts", 0) + 1,
        "challenge_status": "review",
        "error_code": "fixture-failure",
    }

अनुमोदित और अस्वीकृत डोमेन, अस्वीकृत उद्देश्य, पुनर्प्रयास समाप्ति, कम ब्राउज़र पृष्ठ, एक समाधान चुनौती के साथ असफल पृष्ठ पुष्टि, और अंतिम अवस्थाओं के बाद साफ़ करें।

पृष्ठ विवरण ज्ञात होने पर टोकन मोड का उपयोग करें

ब्राउज़र मोड तब उपयुक्त है जब एजेंट के पास एक Playwright पृष्ठ नियंत्रण है। टोकन मोड जब आपके एप्लिकेशन को टर्नस्टाइल पृष्ठ URL और सार्वजनिक साइट कुंजी ज्ञात होती है, तो आसान हो सकता है। CapSolver द्वारा AntiTurnstileTaskProxyLess कार्य के साथ आवश्यक websiteURL और websiteKey के साथ दस्तावेज़ किया गया है, साथ ही वैकल्पिक metadata.action और metadata.cdata है।

मॉडल को इन क्षेत्रों को आविष्कार न करने दें। उन्हें अनुमोदित पृष्ठ या एप्लिकेशन कॉन्फ़िगरेशन से निश्चित रूप से निकालें।

गोपनीयता उल्लंघन के बिना दृश्यता

ट्रेस:

• ग्राफ नोड;
• अनुरोध पहचान;
• नीति निर्णय;
• होस्टनाम;
• चुनौती प्रकार;
• प्रयास संख्या;
• लगा समय;
• त्रुटि श्रेणी;
• भरना-वापस बूलियन;
• अंतिम पुष्टि बूलियन।

प्रमाणीकरण, ब्राउज़र कुकीज़, कच्चा टोकन, या अनुरेखित फॉर्म डेटा वाले प्रॉम्प्ट न ट्रेस करें। स्क्रीनशॉट और DOM साक्ष्य के लिए रखे जाने वाले नियम निर्धारित करें।

विफलता मोड और समाधान

कोई चुनौती पता नहीं चली

पृष्ठ के लोड होने की पुष्टि करें, ब्राउज़र के इच्छित सत्र का उपयोग करें, और SDK संस्करण चुनौती प्रकार के समर्थन करता है। एक खाली निरीक्षण परिणाम को केवल तभी not-needed के रूप में मानें जब पृष्ठ पुष्टि के साथ अभी भी पास हो सकती है।

तैयार होने से पहले कार्य विफल हो जाता है

त्रुटि श्रेणी दर्ज करें, पैरामीटर की तुलना वर्तमान CapSolver दस्तावेज़ के साथ करें, और पुनर्प्रयास बजट के बाद रुक जाएं। अपने आप के पुनर्प्रयास न बढ़ाएं।

टोकन भरना-वापस विफल हो जाता है

वही ब्राउज़र पृष्ठ रखें, समीक्षा कॉलबैक या विज़ुअल विकल्प व्यवहार की समीक्षा करें, और पुष्टि करें कि पृष्ठ नेविगेशन एक संदर्भ बदल दिया है।

ग्राफ अनंत रूप से घूमता है

challenge_attempts के भंडारण और लागू करें। निर्धारित सीमा के बाद मानव समीक्षा के लिए रास्ता रखें।

पुष्टि सफल होती है लेकिन व्यावसायिक कार्रवाई विफल हो जाती है

कैप्चा पुनर्जीवन को नीचे की कार्रवाई से अलग रखें। ग्राफ चुनौती के पुनर्समाधान के बजाय कार्रवाई के अपने त्रुटि को सतह पर लाएगा।

उत्पादन चेकलिस्ट

• डिपेंडेंसी संस्करण या कॉमिट बांधें।
• अलग स्टेजिंग और उत्पादन नीति का उपयोग करें।
• ग्राफ राज्य में सीक्रेट न रखें।
• डोमेन और उद्देश्य को सीमित करें।
• प्रत्येक कॉल और कुल समय सीमा निर्धारित करें।
• एक ब्राउज़र सत्र बरकरार रखें।
• टोकन और कुकीज़ रेडैक्ट करें।
• भरना-वापस के बाद पृष्ठ पुष्टि करें।
• अहम कार्रवाई के लिए मानव समीक्षा जोड़ें।
• साफ़ करें और रद्द करें के परीक्षण करें।
• अस्वीकृति, त्रुटि, पुनर्जीवन और पुष्टि दर की निगरानी करें।
• कोड के समान नीति बदलाव की समीक्षा करें।

निष्कर्ष: चुनौती प्रबंधन को ग्राफ पुनर्जीवन अवस्था के रूप में बनाएं

एक LangGraph Cloudflare Turnstile एकीकरण तब सबसे विश्वसनीय होता है जब यह एक सीमित पुनर्जीवन कार्य प्रक्रिया के रूप में व्यवहार करता है: पता लगाएं, प्राधिकरण, समाधान, पुष्टि, जारी रखें, या रुकें। ग्राफ राउटिंग और दृश्यता प्रदान करता है; निश्चित कोड नीति प्रदान करता है; CapSolver दस्तावेज़ किए गए पहचान परत प्रदान करता है।

CapSolver केवल कानूनी, अनुमोदित स्वचालन के लिए उपयोग करें। एक निर्माण निर्धारित करने से पहले वर्तमान एजेंट उपकरण दस्तावेज़, कोर SDK गाइड और संबंधित CapSolver ब्लॉग ट्यूटोरियल की समीक्षा करें।

एफक्यूए (प्रायः पूछे जाने वाले प्रश्न)

प्रश्न: क्या LangGraph अकेले Cloudflare Turnstile हल करता है?

नहीं। LangGraph कार्य प्रक्रिया राज्य और राउटिंग का नियंत्रण करता है; CapSolver अनुकूलन स्वीकृति सेवा और ब्राउज़र विधियों का उपयोग करता है।

प्रश्न: क्या समाधान टोकन मॉडल को वापस करना चाहिए?

नहीं। इसे नियंत्रित ब्राउज़र अनुकूलन में लागू करें और केवल स्थिति, त्रुटि श्रेणी और पुष्टि परिणाम वापस करें।

प्रश्न: Playwright के साथ कौन सी CapSolver विधि उपयोग की जाती है?

वर्तमान कोर SDK detect(page), get_captcha_info(page) और solve_on_page(page) के लिए ब्राउज़र मोड के लिए दस्तावेज़ करता है।

प्रश्न: ग्राफ कितने पुनर्प्रयास अनुमति देना चाहिए?

एक छोटा स्पष्ट बजट उपयोग करें जो आपके कार्य प्रक्रिया पर आधारित हो और असीमित लूप के बजाय समीक्षा के लिए रास्ता रखें।

प्रश्न: क्या एजेंट किसी भी URL के लिए पुनर्जीवन नोड कॉल कर सकता है?

नहीं। नोड के आगे CapSolver का उपयोग करने से पहले निश्चित डोमेन और उद्देश्य अनुमति सूची के लिए बाध्य करें।

प्रश्न: क्या चुनौती के सफल रूप से प्रबंधन के प्रमाण हैं?
एक पृष्ठ-स्तर के एप्लिकेशन दावा कार्यप्रवाह पुनर्प्राप्ति के प्रमाण है; एक प्रदाता स्थिति या भरा हुआ टोकन अकेले पर्याप्त नहीं है।