Cách giải quyết Cloudflare Turnstile trong các tác nhân LangGraph

TL;DR

• Một tích hợp LangGraph Cloudflare Turnstile nên mô hình xử lý CAPTCHA như một nút phục hồi được kiểm soát, không phải là công cụ không giới hạn có sẵn trên mọi tuyến đường.
• CapSolver mô tả capsolver-agent là lớp thích ứng công cụ trên capsolver-core, với các công cụ LangChain cho khung agent và phương pháp trình duyệt cho phiên bản Playwright.
• Giữ quyết định điều hướng trong đồ thị, xác thực xác định trong mã ứng dụng, và nhận dạng trong dịch vụ CapSolver.
• Bảo tồn một phiên trình duyệt duy nhất qua phát hiện, giải quyết, điền lại, và kiểm tra trang cuối; không bao giờ trả lại token thô cho mô hình.
• Sử dụng thử lại có giới hạn, trạng thái kết thúc rõ ràng, theo dõi bị che khuất, và kiểm tra của con người cho các hành động thay đổi trạng thái hoặc không rõ ràng.
• Biểu đồ ví dụ dưới đây bao gồm định nghĩa trạng thái, định tuyến chính sách, nút phục hồi CapSolver, xử lý lỗi, và xác minh.

Một tích hợp LangGraph Cloudflare Turnstile nên làm gì

Một tích hợp LangGraph Cloudflare Turnstile cho phép agent phục hồi từ bước xác minh bên trong một quy trình trình duyệt được ủy quyền và sau đó tiếp tục nhiệm vụ ban đầu. Đồ thị không nên yêu cầu mô hình ngôn ngữ nhấp chuột hoặc suy nghĩ qua widget. Thay vào đó, mô hình hoặc bộ điều khiển trình duyệt phát hiện rằng quy trình bị chặn, đồ thị đánh giá chính sách, và bộ thích ứng xác định gọi khả năng được mô tả của CapSolver.

CapSolver mô tả phân chia công việc này trong hướng dẫn công cụ agent: mô hình xử lý điều hướng và quyết định, capsolver-agent tiết lộ các lược đồ công cụ và trình thực thi, và capsolver-core thực hiện phát hiện, giải quyết và điền lại trình duyệt.

Kiến trúc này mang lại vai trò hữu ích cho LangGraph. Nó có thể làm cho phục hồi có thể quan sát được, thực thi ngân sách thử lại, định tuyến các hành động nhạy cảm đến con người, và đảm bảo trình duyệt xác minh thành công trước khi đồ thị tiếp tục.

Yêu cầu tiên quyết và con đường tích hợp được hỗ trợ

Sử dụng môi trường Python cô lập. Hướng dẫn chính thức hiện tại của CapSolver cài đặt các gói core và agent từ GitHub:

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

Đặt CAPSOLVER_API_KEY và bất kỳ chứng chỉ mô hình nào trong kho lưu trữ bí mật được phê duyệt. Không ghi giá trị thực vào trạng thái đồ thị, điểm kiểm tra, lời nhắc, sự kiện theo dõi hoặc tệp nguồn.

Bạn cũng cần:

• một mục tiêu được sở hữu hoặc được ủy quyền rõ ràng;
• một danh sách trắng tên miền;
• một mục đích kinh doanh được xác định;
• một bộ lưu trữ phiên trình duyệt;
• một số lần thử lại tối đa;
• một ngân sách thời gian chờ;
• một kiểm tra trang cuối;
• một quy tắc kiểm tra của con người cho các hành động có hậu quả.

Thiết kế trạng thái LangGraph

Giữ chỉ dữ liệu vận hành không mật trong trạng thái đồ thị:

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

Không thêm chứng chỉ CapSolver, token giải quyết, cookie hoặc nội dung trang thô. Lưu trữ các đối tượng trình duyệt trong bộ lưu trữ do ứng dụng sở hữu, được khóa bằng page_id; các điểm kiểm tra đồ thị nên chứa chỉ định danh duy nhất.

Xây dựng nút xác thực xác định

Xác thực nên chạy trước bất kỳ công cụ thách thức nào:

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"}

Nút này được xác minh cú pháp và độc lập với mô hình. Trong sản xuất, tải chính sách từ cấu hình được đánh số phiên bản và từ chối các trường không biết.

Đăng ký phiên trình duyệt bên ngoài trạng thái đồ thị

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()

Bộ lưu trữ ngăn việc tuần tự hóa một Page Playwright và cung cấp một nơi duy nhất để thực thi dọn dẹp.

Nhận mã thưởng CapSolver của bạn

Tăng ngân sách tự động hóa của bạn ngay lập tức!
Sử dụng mã thưởng CAP26 khi nạp tiền tài khoản CapSolver để nhận thêm 5% thưởng trên mỗi lần nạp tiền — không giới hạn.
Nhận mã thưởng ngay bây giờ trong Bảng điều khiển CapSolver

Triển khai nút phục hồi CapSolver

SDK Core của CapSolver mô tả detect(page) và solve_on_page(page) cho chế độ trình duyệt. Bộ thích ứng dưới đây sử dụng các phương pháp này và chỉ trả về một quyết định đồ thị:

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,
    }

Mã đã được kiểm tra cú pháp nhưng chưa chạy bằng chứng chỉ. Một bài kiểm tra thực tế yêu cầu trang được phê duyệt và bí mật. Đồ thị không bao giờ nhận được solution.token.

Xác minh kết quả trang

Một token đã điền là kết quả trung gian. Xác minh trạng thái mong đợi của ứng dụng:

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",
        }

Sử dụng một phép kiểm tra do ứng dụng của bạn sở hữu. Tránh các bộ chọn có thể tiết lộ nội dung trang cá nhân hoặc nhạy cảm trong nhật ký.

Lắp ráp quy trình 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()

Các hàm được chèn có thể đóng gói bộ lưu trữ trình duyệt. Việc tiêm phụ thuộc làm cho chính sách và các cạnh thất bại có thể kiểm tra mà không cần dịch vụ trực tiếp.

Thêm nút kiểm tra của con người

Người kiểm tra nên nhận được:

• ID yêu cầu;
• mục đích được phê duyệt;
• tên máy chủ;
• hành động đã thử;
• số lần thử lại;
• loại lỗi đã được làm mờ;
• tham chiếu hình ảnh an toàn, nếu được phép;
• bước tiếp theo đề xuất.

Người kiểm tra không nên nhận được chứng chỉ CapSolver hoặc token giải quyết. Một hành động thay đổi trạng thái như gửi, mua, thay đổi tài khoản hoặc gửi tin nhắn nên yêu cầu ủy quyền riêng ngay cả sau khi xác minh thành công.

Kiểm tra đồ thị mà không gọi dịch vụ bên ngoài

Các bài kiểm tra đơn vị có thể thay thế nút giải quyết bằng các mô phỏng xác định:

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",
    }

Kiểm tra tên miền được phê duyệt và bị từ chối, mục đích không được hỗ trợ, số lần thử lại hết, trang trình duyệt thiếu, thử thách được giải quyết nhưng kiểm tra trang thất bại, và dọn dẹp sau các trạng thái kết thúc.

Sử dụng chế độ token khi tham số trang đã biết

Chế độ trình duyệt phù hợp khi agent đã kiểm soát một trang Playwright. Chế độ token có thể đơn giản hơn khi ứng dụng biết URL trang Turnstile và khóa trang công khai. CapSolver mô tả nhiệm vụ AntiTurnstileTaskProxyLess với các tham số websiteURL và websiteKey bắt buộc, cùng với metadata.action và metadata.cdata tùy chọn.

Không để mô hình tạo các trường này. Trích xuất chúng xác định từ trang được phê duyệt hoặc cấu hình ứng dụng.

Quan sát mà không rò rỉ bí mật

Ghi nhật ký:

• nút đồ thị;
• ID yêu cầu;
• quyết định chính sách;
• tên máy chủ;
• loại thách thức;
• số lần thử;
• thời gian đã trôi qua;
• loại lỗi;
• boolean điền lại;
• boolean kiểm tra cuối.

Không ghi nhật ký các lời nhắc chứa chứng chỉ, cookie trình duyệt, token thô hoặc dữ liệu biểu mẫu chưa được làm mờ. Xác định quy tắc lưu trữ và truy cập cho hình ảnh và bằng chứng DOM.

Các chế độ lỗi và giải pháp

Không phát hiện thách thức

Xác nhận rằng trang đã tải xong, trình duyệt sử dụng phiên bản được chỉ định và phiên bản SDK hỗ trợ loại thách thức. Xem kết quả phát hiện trống là not-needed chỉ khi kiểm tra trang vẫn có thể thành công.

Nhiệm vụ thất bại trước khi sẵn sàng

Ghi lại loại lỗi, so sánh tham số với tài liệu CapSolver hiện tại và dừng sau ngân sách thử lại. Không tăng số lần thử tự động.

Điền lại token thất bại

Giữ cùng trang trình duyệt, xem lại hành vi gọi lại hoặc widget và xác minh rằng điều hướng trang không thay thế ngữ cảnh.

Đồ thị lặp vô hạn

Lưu và thực thi challenge_attempts. Định tuyến đến kiểm tra của con người sau giới hạn được cấu hình.

Xác minh thành công nhưng hành động kinh doanh thất bại

Giữ tách biệt phục hồi CAPTCHA khỏi hành động phía sau. Đồ thị nên hiển thị lỗi của hành động thay vì giải quyết lại thách thức.

Danh sách kiểm tra sản xuất

• Cố định phiên bản phụ thuộc hoặc commit.
• Sử dụng chính sách staging và sản xuất riêng biệt.
• Lưu trữ bí mật bên ngoài trạng thái đồ thị.
• Hạn chế tên miền và mục đích.
• Thiết lập thời gian chờ cho mỗi cuộc gọi và tổng thể.
• Giữ một phiên trình duyệt duy nhất.
• Che token và cookie.
• Xác minh trang sau khi điền lại.
• Thêm kiểm tra của con người cho các hành động có hậu quả.
• Kiểm tra dọn dẹp và hủy bỏ.
• Giám sát tỷ lệ từ chối, lỗi, phục hồi và xác minh.
• Xem xét các thay đổi chính sách như mã.

Kết luận: biến xử lý thách thức thành trạng thái phục hồi đồ thị

Một tích hợp LangGraph Cloudflare Turnstile đáng tin cậy nhất khi nó hoạt động như một quy trình phục hồi hữu hạn: phát hiện, xác thực, giải quyết, xác minh, tiếp tục hoặc dừng. Đồ thị cung cấp định tuyến và quan sát; mã xác định cung cấp chính sách; CapSolver cung cấp lớp nhận dạng được mô tả.

Sử dụng CapSolver chỉ cho tự động hóa hợp pháp và được ủy quyền. Xem tài liệu công cụ agent, hướng dẫn SDK Core và các bài viết blog liên quan của CapSolver trước khi cố định triển khai.

Câu hỏi thường gặp

Câu hỏi: LangGraph tự giải Cloudflare Turnstile sao?

Không. LangGraph kiểm soát trạng thái và định tuyến quy trình; bộ thích ứng CapSolver gọi dịch vụ nhận dạng và phương pháp trình duyệt.

Câu hỏi: Token giải quyết có được trả lại cho mô hình không?

Không. Áp dụng nó bên trong bộ thích ứng trình duyệt được kiểm soát và chỉ trả lại trạng thái, loại lỗi và kết quả xác minh.

Câu hỏi: Phương pháp CapSolver nào được sử dụng với Playwright?

SDK Core hiện tại mô tả detect(page), get_captcha_info(page) và solve_on_page(page) cho chế độ trình duyệt.

Câu hỏi: Đồ thị nên cho phép bao nhiêu lần thử lại?

Sử dụng ngân sách nhỏ rõ ràng dựa trên quy trình của bạn và định tuyến đến kiểm tra thay vì cho phép vòng lặp không giới hạn.

Câu hỏi: Agent có thể gọi nút phục hồi cho bất kỳ URL nào không?

Không. Áp dụng danh sách trắng tên miền và mục đích xác định trước khi nút có thể gọi CapSolver.

Câu hỏi: Điều gì chứng minh thách thức đã được xử lý thành công?
Một khẳng định ứng dụng cấp trang xác nhận phục hồi quy trình làm việc; trạng thái nhà cung cấp hoặc token đã điền chỉ riêng không đủ.