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

TL;DR

• Đăng ký một hàm Python solve_turnstile hẹp với AutoGen thay vì để các tác nhân viết mã giải quyết tùy ý.
• Sử dụng nhiệm vụ được tài liệu hóa AntiTurnstileTaskProxyLess của CapSolver với websiteURL và websiteKey.
• Bao gồm tùy chọn hành động và cdata của Turnstile chỉ khi chúng hiện diện trên trang được phép.
• Trả về token giải quyết cho lớp trình duyệt xác định, lớp này nên chèn nó và gửi lại quy trình ban đầu.
• Giữ khóa API, phiên đăng nhập trình duyệt và quyền truy cập mục tiêu bên ngoài prompt của mô hình ngôn ngữ.

Giới thiệu

Cách an toàn nhất để giải Cloudflare Turnstile trong AutoGen là đăng ký CapSolver như một công cụ hàm có kiểu và phạm vi hẹp. AutoGen có thể quyết định khi quy trình cần giải quyết Turnstile, nhưng mã Python xác định nên kiểm tra URL đích và khóa trang web, tạo nhiệm vụ được tài liệu hóa AntiTurnstileTaskProxyLess, và chỉ trả về token kết quả. Lớp trình duyệt sau đó áp dụng token này vào cùng quy trình được phép và tiếp tục. Kiến trúc này tuân theo ranh giới "mô hình quyết định, lõi thực thi" được tài liệu hóa bởi tài liệu AI Agent của CapSolver và mô hình đăng ký công cụ chính thức của AutoGen. Trong hướng dẫn này, bạn sẽ tạo hàm giải quyết, đăng ký nó với các tác nhân gọi và thực thi, xử lý dữ liệu tùy chọn của widget, thêm các lần thử lặp có giới hạn, và thiết kế các biện pháp kiểm soát sản xuất để ngăn chặn việc các thông tin xác thực hoặc mục tiêu không được kiểm soát đến mô hình.

Tại sao sử dụng công cụ thay vì mã do tác nhân tạo ra?

Các công cụ AutoGen là các hàm được định nghĩa trước mà các tác nhân có thể gọi. hướng dẫn sử dụng công cụ AutoGen chính thức giải thích rằng các công cụ hạn chế những gì một tác nhân có thể làm hiệu quả hơn việc để nó tạo mã thực thi tùy ý. Các chú thích kiểu và mô tả ngắn gọn được sử dụng để tạo sơ đồ công cụ tự động.

Ranh giới này đặc biệt quan trọng đối với xử lý thách thức. Tác nhân không nên nhận khóa API CapSolver của bạn, chọn các trang tùy ý hoặc kiểm soát ngữ cảnh trình duyệt trực tiếp. Nó chỉ nên yêu cầu giải pháp cho trang đã được kiểm tra và phê duyệt bởi quy trình tự động hóa.

Bài viết trên blog AI của CapSolver đề cập các mô hình hướng đến tác nhân, trong khi FAQ AI và tự động hóa của CapSolver giải thích cách các công cụ giải quyết phù hợp vào tự động hóa có kiểm soát.

Các tham số Cloudflare Turnstile Bạn Cần

Tài liệu chính thức của CapSolver về Turnstile xác định loại nhiệm vụ không cần proxy là AntiTurnstileTaskProxyLess. Các tham số bắt buộc là websiteURL và websiteKey. Dữ liệu tùy chọn có thể bao gồm các giá trị action và cdata của widget.

Cloudflare tài liệu các chế độ widget được quản lý, không tương tác và vô hình. Giới thiệu về Cloudflare Turnstile mô tả cách widget đánh giá tín hiệu trình duyệt và phát hành token để xác thực phía máy chủ. CapSolver xử lý các kiểu con được hỗ trợ tự động, vì vậy nhiệm vụ không cần trường kiểu con.

Cài đặt AutoGen và CapSolver

pip install pyautogen capsolver

Lưu trữ thông tin xác thực trong biến môi trường:

export CAPSOLVER_API_KEY="CAP-xxxxxxxxxxxxxxxx"
export OPENAI_API_KEY="sk-xxxxxxxxxxxxxxxx"

Đối với kiến trúc tác nhân CapSolver mới được mô tả trong tài liệu do người dùng cung cấp, các nhóm cũng có thể cài đặt các gói lõi và bộ chuyển đổi:

pip install git+https://github.com/capsolver-ai/capsolver-core.git
pip install git+https://github.com/capsolver-ai/capsolver-agent.git

Hàm capsolver.solve() trực tiếp bên dưới sử dụng các trường nhiệm vụ Turnstile chính thức và được bao bọc thành công cụ AutoGen. Điều này giữ cho tích hợp khung dễ dàng và làm cho tải nhiệm vụ dễ kiểm toán.

Tạo Hàm Giải Quyết Turnstile Có Kiểu

Mô hình chỉ nên nhận đầu vào không chứa thông tin mật. Khóa CapSolver vẫn nằm trong môi trường chạy của hàm.

import os
from typing import Annotated
from urllib.parse import urlparse

import capsolver

capsolver.api_key = os.environ["CAPSOLVER_API_KEY"]

ALLOWED_HOSTS = {
    "staging.example.com",
    "app.example.com",
}


def solve_turnstile(
    website_url: Annotated[str, "URL trang được phê duyệt chứa Turnstile"],
    website_key: Annotated[str, "Khóa trang Turnstile từ widget"],
    action: Annotated[str, "Giá trị data-action tùy chọn"] = "",
    cdata: Annotated[str, "Giá trị data-cdata tùy chọn"] = "",
) -> dict:
    """Giải Turnstile cho trang được phê duyệt và trả về token."""
    parsed = urlparse(website_url)
    if parsed.scheme != "https" or parsed.hostname not in ALLOWED_HOSTS:
        return {
            "success": False,
            "error": "Mục tiêu không nằm trong danh sách cho phép",
        }

    if not website_key.startswith("0x4"):
        return {
            "success": False,
            "error": "Định dạng khóa trang Turnstile không mong đợi",
        }

    task = {
        "type": "AntiTurnstileTaskProxyLess",
        "websiteURL": website_url,
        "websiteKey": website_key,
    }

    metadata = {}
    if action:
        metadata["action"] = action
    if cdata:
        metadata["cdata"] = cdata
    if metadata:
        task["metadata"] = metadata

    try:
        solution = capsolver.solve(task)
        token = solution.get("token")
        if not token:
            return {"success": False, "error": "Không có token Turnstile được trả về"}
        return {
            "success": True,
            "token": token,
            "solution_type": solution.get("type", "turnstile"),
        }
    except Exception as exc:
        return {"success": False, "error": str(exc)}

Danh sách cho phép là có chủ đích. Nếu không, một prompt có thể hướng dẫn tác nhân gửi các mục tiêu không liên quan. Các hệ thống sản xuất có thể xây dựng danh sách cho phép từ cấu hình khách hàng, quyền hạn công việc hoặc bản ghi công việc đã ký.

Đăng ký Hàm Với AutoGen

API AgentChat truyền thống của AutoGen tách biệt giữa tác nhân đề xuất gọi công cụ và tác nhân thực thi. Tài liệu chính thức cung cấp register_function() như một cách thuận tiện để đăng ký cùng một hàm với cả hai tác nhân.

import os
from autogen import ConversableAgent, register_function

assistant = ConversableAgent(
    name="TurnstileCoordinator",
    system_message=(
        "Tiếp tục các quy trình tự động hóa được phê duyệt. "
        "Gọi solve_turnstile chỉ khi ứng dụng báo cáo widget Turnstile "
        "và cung cấp URL trang chính xác và khóa trang. "
        "Không bao giờ tạo mục tiêu hoặc yêu cầu thông tin xác thực. "
        "Nếu công cụ thất bại hai lần, dừng lại và yêu cầu xem xét của người vận hành."
    ),
    llm_config={
        "config_list": [{
            "model": "gpt-4o-mini",
            "api_key": os.environ["OPENAI_API_KEY"],
        }]
    },
)

executor = ConversableAgent(
    name="TurnstileToolExecutor",
    llm_config=False,
    human_input_mode="NEVER",
)

register_function(
    solve_turnstile,
    caller=assistant,
    executor=executor,
    name="solve_turnstile",
    description=(
        "Giải Cloudflare Turnstile cho trang HTTPS được phê duyệt bằng khóa trang chính xác "
        "và các giá trị action/cdata tùy chọn."
    ),
)

AutoGen tạo sơ đồ công cụ từ chữ ký hàm và chú thích kiểu. Giữ mô tả mang tính vận hành và cụ thể để mô hình hiểu khi nào công cụ phù hợp.

Đối với các mẫu khung khác, xem các hướng dẫn tự động hóa của CapSolver và trang sản phẩm của CapSolver.

Bắt Đầu Cuộc Trò Chuyện Gọi Công Cụ

Lớp trình duyệt hoặc lớp điều phối nên phát hiện widget và cung cấp tham số chính xác. Mô hình không nên kiểm tra thông tin mật hoặc quét các trang tùy ý để phát hiện mục tiêu.

chat_result = executor.initiate_chat(
    assistant,
    message=(
        "Quy trình thử nghiệm được phê duyệt gặp phải Cloudflare Turnstile.\n"
        "website_url=https://staging.example.com/account-check\n"
        "website_key=0x4AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA\n"
        "action=account_check\n"
        "cdata=\n"
        "Gọi công cụ đã đăng ký một lần và trả về kết quả cấu trúc."
    ),
    max_turns=4,
)

Trong thiết kế sản xuất, mã ứng dụng cấu trúc nên xây dựng thông điệp này từ dữ liệu thời gian chạy đã được kiểm tra. Không chấp nhận khóa trang hoặc URL đích trực tiếp từ đầu vào tự nhiên không đáng tin cậy.

Áp Dụng Token Trong Lớp Trình Duyệt

Một token Turnstile thường được sử dụng bởi biểu mẫu gốc hoặc yêu cầu máy chủ. Cách tích hợp chính xác phụ thuộc vào ứng dụng được phê duyệt. Đối với quy trình trình duyệt, hãy truyền token đã trả về lại mã xác định biết widget và đường dẫn gửi.

async def apply_turnstile_token(page, token: str):
    await page.evaluate(
        """
        (token) => {
          const response = document.querySelector(
            'input[name="cf-turnstile-response"]'
          );
          if (!response) {
            throw new Error('Không tìm thấy trường phản hồi Turnstile');
          }
          response.value = token;
          response.dispatchEvent(new Event('input', { bubbles: true }));
          response.dispatchEvent(new Event('change', { bubbles: true }));
        }
        """,
        token,
    )

Một số ứng dụng sử dụng trình bày dựa trên callback hoặc gửi bởi máy chủ. Kiểm tra với ứng dụng thử nghiệm của bạn và tuân theo tích hợp được hỗ trợ thay vì giả định rằng việc đặt trường ẩn là đủ. Tài liệu kiểm tra phía máy chủ của Cloudflare giải thích rằng chủ sở hữu trang phải xác minh token với Siteverify.

Hướng dẫn Turnstile của CapSolver cung cấp bối cảnh triển khai bổ sung, và FAQ chẩn đoán của CapSolver giúp xác định token bị từ chối hoặc không hợp lệ.

Thêm Lặp Lại Có Giới Hạn và Lỗi Cấu Trúc

Không cho phép tác nhân lặp lại vô hạn. Giới hạn số lần thử và phân loại lỗi để tự động hóa có thể dừng an toàn.

import asyncio

MAX_ATTEMPTS = 2

async def solve_with_policy(params: dict) -> dict:
    last_error = "lỗi không xác định"

    for attempt in range(1, MAX_ATTEMPTS + 1):
        result = solve_turnstile(**params)
        if result.get("success"):
            return {
                **result,
                "attempt": attempt,
            }

        last_error = result.get("error", last_error)
        if "allowlist" in last_error or "site-key" in last_error:
            break
        await asyncio.sleep(2 * attempt)

    return {
        "success": False,
        "error": last_error,
        "requires_operator_review": True,
    }

Ghi nhật ký chỉ dữ liệu an toàn: hostname mục tiêu, loại nhiệm vụ, thời gian, kết quả, lỗi được chuẩn hóa và số lần thử. Không ghi nhật ký token đầy đủ, khóa API, cookie phiên hoặc nội dung biểu mẫu.

Mã thưởng: Sử dụng mã WEBS tại Bảng điều khiển CapSolver để nhận thêm 5% tiền thưởng cho mỗi lần nạp tiền.

Danh sách Kiểm soát Sản xuất

FAQ giải CAPTCHA của CapSolver giải thích hành vi nhiệm vụ tổng quát, trong khi FAQ thu thập web của CapSolver đề cập các biện pháp vận hành cho thu thập tự động.

Sử Dụng Có Trách Nhiệm

Sử dụng quy trình này chỉ trên các ứng dụng bạn sở hữu, kiểm thử hoặc có quyền tự động hóa rõ ràng. Một token giải quyết không cấp quyền truy cập dữ liệu riêng, gửi giao dịch, tạo tài khoản hoặc bỏ qua điều khoản của trang. Áp dụng giới hạn tốc độ, giữ hồ sơ kiểm toán và yêu cầu xác nhận cho các hành động thay đổi dữ liệu hoặc ảnh hưởng đến người dùng.

Kết Luận

Để giải Cloudflare Turnstile trong AutoGen một cách đáng tin cậy, hãy làm cho CapSolver trở thành công cụ bị giới hạn thay vì logic tác nhân mở rộng. Trợ lý AutoGen quyết định khi nào công cụ phù hợp, executor chạy nhiệm vụ AntiTurnstileTaskProxyLess đã được kiểm tra, và lớp trình duyệt tiêu thụ token kết quả bên trong cùng quy trình được phê duyệt. Sự phân chia này làm cho tích hợp dễ kiểm thử, kiểm toán và bảo mật hơn.

Bắt đầu với CapSolver, kiểm tra luồng với trang thử nghiệm bạn kiểm soát, và thêm danh sách cho phép hostname, lặp lại có giới hạn và ghi nhật ký token an toàn trước khi triển khai sản xuất.

FAQ

Nhiệm vụ Turnstile của CapSolver có yêu cầu proxy không?

Loại nhiệm vụ được tài liệu là AntiTurnstileTaskProxyLess, vì vậy bạn không cần cung cấp proxy cho nhiệm vụ. Quy trình trình duyệt của bạn vẫn có thể có cấu hình mạng riêng.

Các trường nào là bắt buộc cho nhiệm vụ?

websiteURL và websiteKey là bắt buộc. metadata.action và metadata.cdata là tùy chọn và chỉ nên cung cấp khi widget sử dụng chúng.

AutoGen có thể phát hiện khóa trang tự động không?

Thiết kế an toàn hơn là lớp trình duyệt hoặc ứng dụng xác định để trích xuất và kiểm tra khóa trang, sau đó cung cấp nó cho công cụ. Không để mô hình tạo ra hoặc đoán giá trị.

Tại sao sử dụng các tác nhân gọi và thực thi riêng biệt?

Tác nhân gọi có thể đề xuất gọi công cụ, trong khi tác nhân thực thi chạy mã Python được kiểm soát mà không có LLM. Điều này giữ thông tin mật và quyền truy cập thời gian chạy xa khỏi tác nhân suy luận.

Điều gì sẽ xảy ra nếu token trả về bị từ chối?

Xác minh URL trang, khóa trang, hành động tùy chọn hoặc cdata, tính mới của token và đường dẫn gửi. Thử lại tối đa một hoặc hai lần, sau đó dừng lại để xem xét bởi người vận hành thay vì lặp lại.