Cara menyelesaikan Cloudflare Turnstile dalam Agen AutoGen

TL;DR

• Daftarkan fungsi Python solve_turnstile yang sempit dengan AutoGen alih-alih memungkinkan agen menulis kode penyelesaian arbitrer.
• Gunakan tugas AntiTurnstileTaskProxyLess yang terdokumentasi dari CapSolver dengan websiteURL dan websiteKey.
• Sertakan opsi Turnstile action dan cdata hanya ketika mereka hadir di halaman yang diizinkan.
• Kembalikan token solusi ke lapisan browser yang deterministik, yang harus menyisipkannya dan mengirimkan alur kerja asli.
• Pertahankan kunci API, sesi browser, dan izin target di luar prompt model bahasa.

Pendahuluan

Cara yang paling aman untuk menyelesaikan Cloudflare Turnstile di AutoGen adalah dengan mendaftarkan CapSolver sebagai alat fungsi yang terbatas dan sempit. AutoGen dapat memutuskan kapan alur kerja membutuhkan solusi Turnstile, tetapi kode Python yang deterministik harus memvalidasi URL target dan kunci situs, membuat AntiTurnstileTaskProxyLess yang terdokumentasi, dan hanya mengembalikan token yang dihasilkan. Lapisan browser kemudian menerapkan token tersebut ke alur kerja yang sama yang diizinkan dan melanjutkannya. Arsitektur ini mengikuti batas "model memutuskan, inti mengeksekusi" dari dokumentasi CapSolver AI Agent dan model pendaftaran alat AutoGen resmi. Dalam panduan ini, Anda akan membuat fungsi penyelesaian, mendaftarkannya dengan agen pemanggil dan executor, menangani metadata widget opsional, menambahkan ulang terbatas, dan merancang kontrol produksi yang mencegah kredensial atau target yang tidak dibatasi mencapai model.

Mengapa Menggunakan Alat Daripada Kode yang Dihasilkan Agen?

Alat AutoGen adalah fungsi yang telah ditentukan sebelumnya yang dapat dipanggil oleh agen. Guia penggunaan alat AutoGen resmi menjelaskan bahwa alat membatasi apa yang dapat dilakukan agen lebih efektif daripada memungkinkannya menulis kode eksekusi arbitrer. Tanda tipe dan deskripsi yang singkat digunakan untuk membuat skema alat secara otomatis.

Batas ini terutama penting untuk penanganan tantangan. Agen tidak boleh menerima kunci API CapSolver Anda, memilih situs arbitrer, atau mengontrol konteks browser secara langsung. Ia hanya boleh meminta solusi untuk halaman yang telah divalidasi dan disetujui oleh alur kerja otomasi.

Blog CapSolver menjelaskan pola-pola yang berfokus pada agen, sementara FAQ CapSolver AI dan otomasi menjelaskan bagaimana alat penyelesaian cocok dalam otomasi yang terkendali.

Parameter Cloudflare Turnstile yang Anda Butuhkan

Dokumentasi resmi Turnstile CapSolver menentukan jenis tugas tanpa proxy AntiTurnstileTaskProxyLess. Parameter yang diperlukan adalah websiteURL dan websiteKey. Metadata opsional dapat mencakup nilai widget action dan cdata.

Cloudflare mendokumentasikan mode widget yang dikelola, non-interop, dan tidak terlihat. Ringkasan Turnstile Cloudflare menjelaskan bagaimana widget mengevaluasi sinyal browser dan menerbitkan token untuk validasi server-side. CapSolver menangani subjenis yang didukung secara otomatis, sehingga tugas tidak perlu field subjenis.

Instal AutoGen dan CapSolver

pip install pyautogen capsolver

Simpan kredensial dalam variabel lingkungan:

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

Untuk arsitektur agen CapSolver yang lebih baru yang dijelaskan dalam dokumentasi yang diberikan pengguna, tim juga dapat menginstal paket inti dan adapter:

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

Fungsi capsolver.solve() langsung di bawah ini menggunakan bidang tugas Turnstile resmi dan dibungkus sebagai alat AutoGen. Ini menjaga integrasi kerangka kerja sederhana dan membuat payload tugas mudah diaudit.

Buat Fungsi Penyelesaian Turnstile Bertipe

Model hanya menerima input yang tidak rahasia. Kunci CapSolver tetap berada di lingkungan runtime fungsi.

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 halaman yang disetujui yang mengandung Turnstile"],
    website_key: Annotated[str, "Kunci situs Turnstile dari widget"],
    action: Annotated[str, "Nilai data-action opsional"] = "",
    cdata: Annotated[str, "Nilai data-cdata opsional"] = "",
) -> dict:
    """Selesaikan Turnstile untuk halaman yang disetujui dan kembalikan token."""
    parsed = urlparse(website_url)
    if parsed.scheme != "https" or parsed.hostname not in ALLOWED_HOSTS:
        return {
            "success": False,
            "error": "Target tidak ada di daftar izin host yang disetujui",
        }

    if not website_key.startswith("0x4"):
        return {
            "success": False,
            "error": "Format kunci situs Turnstile yang tidak diharapkan",
        }

    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": "Tidak ada token Turnstile yang dikembalikan"}
        return {
            "success": True,
            "token": token,
            "solution_type": solution.get("type", "turnstile"),
        }
    except Exception as exc:
        return {"success": False, "error": str(exc)}

Daftar izin sengaja dibuat. Tanpa itu, prompt bisa mengarahkan agen untuk mengirim target yang tidak relevan. Sistem produksi dapat membangun daftar izin dari konfigurasi tenant, izin pekerjaan, atau manifest alur kerja yang ditandatangani.

Daftarkan Fungsi dengan AutoGen

API AgentChat klasik AutoGen memisahkan agen yang mengusulkan pemanggilan alat dari executor yang menjalankannya. Dokumentasi resmi menyediakan register_function() sebagai cara yang nyaman untuk mendaftarkan fungsi yang sama dengan kedua agen.

import os
from autogen import ConversableAgent, register_function

assistant = ConversableAgent(
    name="TurnstileCoordinator",
    system_message=(
        "Lanjutkan hanya alur kerja otomasi yang disetujui. "
        "Panggil solve_turnstile hanya ketika aplikasi melaporkan widget Turnstile "
        "dan memberikan URL halaman dan kunci situs yang tepat. "
        "Jangan pernah menciptakan target atau meminta kredensial. "
        "Jika alat gagal dua kali, berhenti dan minta tinjauan operator."
    ),
    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=(
        "Selesaikan Cloudflare Turnstile untuk halaman HTTPS yang disetujui menggunakan kunci situsnya "
        "dan nilai action/cdata opsional."
    ),
)

AutoGen menghasilkan skema alat dari tanda tipe dan anotasi fungsi. Pertahankan deskripsi operasional dan spesifik sehingga model memahami kapan alat cocok.

Untuk pola kerangka lain, tinjau tutori otomasi CapSolver dan halaman produk CapSolver.

Mulai Percakapan Pemanggilan Alat

Lapisan browser atau lapisan orkestrasi harus mendeteksi widget dan memberikan parameter yang tepat. Model tidak boleh memeriksa rahasia atau menggali halaman arbitrer untuk menemukan target.

chat_result = executor.initiate_chat(
    assistant,
    message=(
        "Alur kerja staging yang disetujui menghadapi Cloudflare Turnstile.\n"
        "website_url=https://staging.example.com/account-check\n"
        "website_key=0x4AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA\n"
        "action=account_check\n"
        "cdata=\n"
        "Panggil alat yang terdaftar sekali dan kembalikan hasil yang struktur."
    ),
    max_turns=4,
)

Dalam desain produksi, kode aplikasi yang struktur harus membangun pesan ini dari data runtime yang divalidasi. Jangan menerima kunci situs atau URL target secara langsung dari input alami yang tidak tepercaya.

Terapkan Token di Lapisan Browser

Token Turnstile biasanya dikonsumsi oleh formulir asli atau permintaan server. Integrasi yang tepat tergantung pada aplikasi yang disetujui. Untuk alur kerja browser, kembalikan token yang dikembalikan ke kode deterministik yang mengetahui widget dan jalur pengiriman.

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('Field respons Turnstile tidak ditemukan');
          }
          response.value = token;
          response.dispatchEvent(new Event('input', { bubbles: true }));
          response.dispatchEvent(new Event('change', { bubbles: true }));
        }
        """,
        token,
    )

Beberapa aplikasi menggunakan rendering berbasis callback atau pengiriman yang dikelola server. Uji terhadap aplikasi staging Anda sendiri dan ikuti integrasi yang didukung alih-alih mengasumsikan bahwa mengatur bidang tersembunyi cukup. Dokumentasi validasi sisi server Cloudflare menjelaskan bahwa pemilik situs harus memvalidasi token dengan Siteverify.

Guia Turnstile CapSolver menyediakan konteks implementasi tambahan, dan FAQ penyelesaian masalah CapSolver membantu mendiagnosis token yang tidak valid atau ditolak.

Tambahkan Ulang Terbatas dan Kesalahan Terstruktur

Jangan biarkan agen melakukan ulang tanpa batas. Batasi percobaan dan klasifikasikan kegagalan sehingga otomasi dapat berhenti dengan aman.

import asyncio

MAX_ATTEMPTS = 2

async def solve_with_policy(params: dict) -> dict:
    last_error = "kesalahan tidak diketahui"

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

Lacak hanya metadata yang aman: hostname target, jenis tugas, durasi, hasil, kesalahan yang dinormalisasi, dan jumlah percobaan. Jangan lacak token lengkap, kunci API, cookie sesi, atau konten formulir.

Kode Bonus: Gunakan kode WEBS di Dasbor CapSolver untuk mendapatkan bonus tambahan 5% pada setiap recharge.

Daftar Pemeriksaan Produksi

FAQ Penyelesaian CAPTCHA CapSolver menjelaskan perilaku tugas umum, sementara FAQ CapSolver tentang penggalian web menutupi kontrol operasional untuk pengumpulan otomatis.

Penggunaan Bertanggung Jawab

Gunakan alur kerja ini hanya pada aplikasi yang Anda miliki, uji, atau memiliki izin eksplisit untuk otomasi. Token penyelesaian tidak memberikan otorisasi untuk mengakses data pribadi, mengirim transaksi, membuat akun, atau mengabaikan ketentuan situs. Terapkan batas kecepatan, simpan catatan audit, dan minta konfirmasi untuk tindakan yang mengubah data atau memengaruhi pengguna.

Kesimpulan

Untuk menyelesaikan Cloudflare Turnstile di AutoGen secara andal, buat CapSolver sebagai alat yang terbatas alih-alih logika agen yang tidak terbatas. Asisten AutoGen memutuskan kapan alat cocok, executor menjalankan AntiTurnstileTaskProxyLess yang divalidasi, dan lapisan browser mengonsumsi token yang dihasilkan di dalam alur kerja yang sama yang disetujui. Pembagian ini membuat integrasi lebih mudah diuji, diaudit, dan dijaga keamanannya.

Mulai dengan CapSolver, validasi alur kerja terhadap halaman staging yang Anda kendalikan, dan tambahkan izin host, ulang terbatas, dan logging token yang aman sebelum deployment produksi.

FAQ

Apakah tugas Turnstile CapSolver memerlukan proxy?

Tipe tugas yang terdokumentasi adalah AntiTurnstileTaskProxyLess, jadi Anda tidak perlu menyediakan proxy ke tugas. Alur kerja browser Anda mungkin masih memiliki konfigurasi jaringan sendiri.

Bidang apa yang diperlukan untuk tugas?

websiteURL dan websiteKey diperlukan. metadata.action dan metadata.cdata opsional dan harus disediakan hanya ketika widget menggunakan mereka.

Apakah AutoGen dapat menemukan kunci situs secara otomatis?

Desain yang lebih aman adalah lapisan browser atau aplikasi yang deterministik mengekstrak dan memvalidasi kunci situs, lalu memberikannya ke alat. Jangan biarkan model menciptakan atau menebak nilainya.

Mengapa menggunakan agen pemanggil dan executor terpisah?

Pemanggil dapat mengusulkan pemanggilan alat, sementara executor menjalankan kode Python yang dikendalikan tanpa LLM. Ini menjaga rahasia dan izin runtime jauh dari agen yang berpikir.

Apa yang harus terjadi jika token yang dikembalikan ditolak?

Konfirmasikan URL halaman, kunci situs, tindakan opsional atau cdata, kemutakhiran token, dan jalur pengajuan. Ulangi maksimal sekali atau dua kali, lalu jeda untuk tinjauan operator alih-alih berulang.