Cara Menyelesaikan Cloudflare Turnstile di Agen LlamaIndex

TL;DR

• Bungkus fungsi CapSolver Turnstile yang sempit dengan LlamaIndex FunctionTool.from_defaults().
• Gunakan tugas yang telah dokumentasikan AntiTurnstileTaskProxyLess dengan URL halaman yang tepat dan kunci situs.
• Kirim action dan cdata hanya ketika halaman yang diizinkan mengekspos nilai opsional tersebut.
• Kembalikan token solusi ke kode browser deterministik alih-alih menyimpannya di memori agen jangka panjang.
• Tambahkan validasi host yang disetujui, satu ulang terbatas, redaksi jejak, dan cabang tinjauan manusia sebelum produksi.

Pendahuluan

Cara yang paling aman untuk menyelesaikan Cloudflare Turnstile dalam agen LlamaIndex adalah dengan mengekspos CapSolver sebagai alat fungsi ber-tipe sambil menjaga state browser, rahasia, dan pemeriksaan otorisasi di luar model. LlamaIndex dapat memutuskan bahwa tantangan yang didukung menghalangi langkah yang disetujui berikutnya, tetapi Python deterministik harus memvalidasi target, membangun AntiTurnstileTaskProxyLess yang telah dokumentasikan, dan mengembalikan token solusi yang pendek ke pengontrol browser. Ini mengikuti arsitektur agen CapSolver: model memutuskan, adapter alat menentukan tindakan, dan lapisan penyelesaian inti menjalankannya. Panduan ini menunjukkan bidang Turnstile yang tepat, implementasi FunctionTool LlamaIndex, alur kerja FunctionAgent, penyerahan token yang aman, ulang terbatas, dan kontrol penggunaan yang bertanggung jawab untuk QA, RPA, dan otomatisasi browser yang diizinkan.

Mengapa LlamaIndex FunctionTool Cocok

LlamaIndex memperlakukan alat sebagai API yang diakses oleh agen. dokumentasi alat resmi menjelaskan bahwa FunctionTool dapat membungkus fungsi Python sinkron atau asinkron dan menerka skema dari tanda tangan fungsi. Nama alat, deskripsi, anotasi, dan docstring mempengaruhi kapan model memanggilnya.

Batas ini berguna untuk pemulihan tantangan karena model tidak boleh menghasilkan kode penyelesaian arbitrer atau menerima kunci API CapSolver. Fungsi sempit dapat menerima hanya URL halaman yang disetujui, kunci situs Turnstile, dan metadata widget opsional.

Blog CapSolver menjelaskan integrasi agen, sementara FAQ CapSolver AI dan otomatisasi menjelaskan bagaimana pemulihan tantangan melengkapi tumpukan agen yang ada.

Memahami Tugas Turnstile Resmi

Dokumentasi Cloudflare Turnstile CapSolver menentukan AntiTurnstileTaskProxyLess. Tugas ini memerlukan websiteURL dan websiteKey. Metadata opsional dapat mencakup nilai action dan cdata widget.

CapSolver secara otomatis mendukung presentasi Turnstile yang dikelola, non-interop, dan tidak terlihat, sehingga tugas tidak memerlukan subjenis. Dokumentasi Turnstile Cloudflare menjelaskan widget dan proses validasi sisi server yang digunakan oleh pemilik situs.

Instal LlamaIndex dan CapSolver

pip install llama-index llama-index-llms-openai capsolver

Untuk arsitektur agen CapSolver yang lebih luas yang disediakan dalam dokumentasi pengguna, instal paket inti dan agen juga:

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

Konfigurasikan rahasia di luar prompt:

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

Contoh SDK langsung di bawah ini menggunakan bidang tugas Turnstile yang tepat. LlamaIndex menyediakan kerangka kerja; CapSolver melakukan tugasnya.

Buat Fungsi Turnstile Ber-tipe

Validasi URL sebelum mengirimkannya ke CapSolver. Model tidak boleh dapat memilih hostname arbitrer.

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",
    "qa.example.com",
}


def solve_turnstile(
    website_url: Annotated[str, "Halaman HTTPS yang disetujui yang mengandung Turnstile"],
    website_key: Annotated[str, "Kunci situs Turnstile yang tepat dari halaman"],
    action: Annotated[str, "Nilai data-action opsional"] = "",
    cdata: Annotated[str, "Nilai data-cdata opsional"] = "",
) -> dict:
    """Selesaikan Cloudflare 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 berada di luar daftar izin hostname yang disetujui",
        }

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

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

Pemeriksaan format adalah peringatan dini yang berguna, tetapi tidak menggantikan ekstraksi parameter yang tepat dari halaman yang diizinkan. Gunakan panduan ekstensi browser CapSolver ketika Anda perlu memeriksa konfigurasi widget selama pengembangan.

Bungkus Fungsi dengan LlamaIndex

FunctionTool.from_defaults() mengubah tanda tangan fungsi dan docstring menjadi skema alat agen.

from llama_index.core.tools import FunctionTool

turnstile_tool = FunctionTool.from_defaults(
    fn=solve_turnstile,
    name="solve_turnstile",
    description=(
        "Selesaikan Cloudflare Turnstile hanya untuk halaman HTTPS yang disetujui. "
        "Gunakan URL halaman yang tepat, kunci situs, dan action/cdata opsional "
        "yang disediakan oleh pengontrol browser yang tepercaya."
    ),
)

Jaga nama singkat dan deskripsi operasional. Jangan deskripsikan alat sebagai mekanisme akses umum. Model harus memahami bahwa itu adalah tindakan pemulihan di dalam alur kerja yang sudah disetujui.

Tambahkan Alat ke LlamaIndex FunctionAgent

FunctionAgent LlamaIndex menggunakan kemampuan pemanggilan alat LLM untuk memilih dan menjalankan alat.

from llama_index.core.agent.workflow import FunctionAgent
from llama_index.llms.openai import OpenAI

llm = OpenAI(model="gpt-4o-mini", temperature=0)

agent = FunctionAgent(
    tools=[turnstile_tool],
    llm=llm,
    system_prompt=(
        "Anda hanya beroperasi pada alur kerja browser yang disetujui. "
        "Panggil solve_turnstile hanya ketika aplikasi tepercaya menyediakan "
        "URL halaman dan kunci yang tepat. Jangan menciptakan target, kunci, "
        "action, atau cdata. Panggil alat sekali. Jika gagal, berhenti dan "
        "minta tinjauan operator."
    ),
)

Mulai jalankan dengan parameter yang dihasilkan oleh kode browser deterministik:

import asyncio

async def main():
    response = await agent.run(
        "Alur kerja staging yang disetujui menemukan Turnstile di "
        "https://staging.example.com/account-check dengan kunci situs "
        "0x4AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA dan action "
        "account_check. Panggil alat yang terdaftar sekali dan kembalikan "
        "hasil yang struktur."
    )
    print(response)

asyncio.run(main())

Dalam produksi, hindari membuat pesan ini langsung dari teks pengguna yang tidak tepercaya. Pengontrol browser harus mengekstrak, memvalidasi, dan mengserialisasi nilai-nilainya.

Pertahankan Konsumsi Token di Luar Model

Token Turnstile bersifat sementara dan terkait dengan alur kerja situs. Serahkan langsung dari hasil alat yang tepercaya ke kode browser deterministik ketika memungkinkan.

async def apply_turnstile_token(page, token: str) -> None:
    await page.evaluate(
        """
        (token) => {
          const field = document.querySelector(
            'input[name="cf-turnstile-response"]'
          );
          if (!field) {
            throw new Error('Field respons Turnstile tidak ditemukan');
          }
          field.value = token;
          field.dispatchEvent(new Event('input', { bubbles: true }));
          field.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. Dokumentasi Siteverify Cloudflare menjelaskan bahwa pemilik situs memvalidasi token sisi server.

Panduan Turnstile CapSolver memberikan konteks implementasi, dan FAQ CapSolver penyelesaian masalah membantu mendiagnosis solusi yang ditolak.

Tambahkan Satu Ulang Terbatas

Jangan biarkan agen berulang tak terbatas. Klasifikasikan kegagalan validasi sebagai akhir, dan izinkan maksimal satu ulang untuk waktu habis sementara.

import asyncio

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

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

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

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

Lacak hostname, jenis tugas, durasi, jumlah percobaan, dan hasil yang dinormalisasi. Jangan lacak token penuh, kunci API, cookie, atau konten formulir.

Mode Token vs Mode Browser

Dokumentasi CapSolver yang disediakan pengguna memetakan solve_captcha ke penyelesaian token inti dan solve_on_page ke pemulihan browser. Jika halaman dinamis, instal ekstra browser dan pertahankan sesi browser asli:

pip install "capsolver-agent[browser] @ git+https://github.com/capsolver-ai/capsolver-agent.git"

Gunakan tutorial otomatisasi CapSolver untuk alur kerja browser terkait dan halaman produk CapSolver untuk kategori solusi yang didukung.

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

Kontrol Produksi

Integrasi Turnstile LlamaIndex produksi harus menggunakan daftar izin host yang disetujui, penyimpanan rahasia terisolasi, penyerahan token berumur pendek, satu ulang terbatas, redaksi jejak, tinjauan operator, dan pemisahan ketat antara otomatisasi baca-saja dan tindakan berdampak tinggi.

FAQ penyelesaian CAPTCHA CapSolver menjelaskan siklus tugas, dan FAQ web-scraping CapSolver mencakup pertimbangan operasional.

Penggunaan Bertanggung Jawab

Gunakan integrasi ini hanya pada aplikasi yang Anda miliki, uji, atau memiliki izin eksplisit untuk otomatisasi. Penyelesaian tantangan tidak memberikan otorisasi untuk mengakses data pribadi, membuat akun, mengirim transaksi, atau mengabaikan syarat situs. Terapkan batas kecepatan, pertahankan tumpukan audit, dan minta konfirmasi sebelum tindakan apa pun yang mengubah data atau memengaruhi pengguna.

Kesimpulan

Untuk menyelesaikan Cloudflare Turnstile secara andal dalam LlamaIndex, buat CapSolver sebagai FunctionTool yang sempit dan pertahankan otorisasi, rahasia, ulang, dan konsumsi token dalam kode deterministik. Agen LlamaIndex memutuskan kapan pemulihan diperlukan, alat membuat AntiTurnstileTaskProxyLess yang telah dokumentasikan, dan browser melanjutkan alur kerja yang sama yang disetujui dengan token yang dikembalikan.

Mulai dengan CapSolver, validasi integrasi terhadap halaman staging yang Anda kendalikan, dan tambahkan daftar izin dan redaksi jejak sebelum produksi.

FAQ

Alat LlamaIndex kelas apa yang harus saya gunakan?

Gunakan FunctionTool.from_defaults() untuk membungkus fungsi Python sinkron atau asinkron yang ber-tipe. Untuk model pemanggilan alat, kirim alat yang dihasilkan ke FunctionAgent.

Apakah tugas Turnstile memerlukan proxy?

Tugas yang telah dokumentasikan AntiTurnstileTaskProxyLess menggunakan jalur tugas tanpa proxy dari CapSolver, jadi Anda tidak perlu menyediakan proxy dalam tugas.

Bidang apa yang wajib diisi?

websiteURL dan websiteKey wajib diisi. Sertakan metadata.action dan metadata.cdata hanya ketika widget yang diizinkan mengeksposnya.

Apakah token harus disimpan dalam memori LlamaIndex?

Tidak. Lebih baik serahkan langsung ke kode browser yang tepercaya dan kembalikan hanya status keberhasilan atau kegagalan yang di-redaksi ke agen.

Apa yang harus terjadi setelah kegagalan berulang?

Verifikasi URL, kunci situs, metadata opsional, dan state halaman. Setelah satu ulang terbatas, berhenti dan arahkan alur kerja ke tinjauan operator.