Cara Menyelesaikan reCAPTCHA v3 di LlamaIndex Agens

TL;DR

• Bungkus fungsi CapSolver async yang sempit dengan LlamaIndex FunctionTool; jangan ekspos kunci API, kredensial proxy, kuki, atau objek browser mentah ke model.
• Baca websiteURL, websiteKey, dan pageAction dari alur kerja yang diotorisasi secara langsung. Jangan pernah biarkan agen membuatnya.
• Gunakan ReCaptchaV3TaskProxyLess untuk mode token server-proxy atau ReCaptchaV3Task saat proxy yang disetujui harus disediakan.
• Tangani token yang dikembalikan sebagai data runtime yang bersifat sementara, kirimkan segera melalui kode yang tepercaya, dan verifikasi status aplikasi sebelum melanjutkan.
• Batasi jumlah percobaan penyelesaian, arahkan ke ulasan operator untuk kegagalan berulang, dan catat hanya metadata yang telah direddact.

Pendahuluan

Solver reCAPTCHA v3 LlamaIndex yang andal adalah alat pemulihan yang terstruktur, bukan kemampuan penjelajahan yang tidak terbatas. Agen LlamaIndex harus menentukan kapan tugas yang disetujui terblokir, sementara kode yang tepercaya memvalidasi target, membaca kunci situs dan tindakan yang tepat dari halaman saat ini, memanggil CapSolver, mengirim token, dan memverifikasi status yang diharapkan. Pemisahan ini penting karena reCAPTCHA v3 berjalan tanpa checkbox interaktif dan mengevaluasi permintaan yang spesifik terhadap tindakan. Token yang dibuat untuk URL yang salah atau pageAction bisa ditolak bahkan ketika panggilan API itu sendiri berhasil. Panduan ini menunjukkan bidang tugas CapSolver resmi, FunctionTool LlamaIndex async, kontrol kebijakan sisi server, penanganan mode sesi, hasil yang terstruktur, ulang yang terbatas, verifikasi browser, dan observabilitas produksi.

Pahami Batas Alat LlamaIndex

Dokumentasi alat resmi LlamaIndex menjelaskan bahwa FunctionTool mengelilingi fungsi Python sinkron atau asinkron dan dapat menginfer skema fungsi. Ia juga mencatat bahwa nama alat, deskripsi, dan deskripsi argumen secara kuat memengaruhi bagaimana model memilih dan memanggil alat.

Untuk solver reCAPTCHA v3 LlamaIndex, pertahankan alat yang sempit:

Agen LlamaIndex
    ↓ memilih alat yang terstruktur
Pembungkus FunctionTool
    ↓ memvalidasi referensi yang tepercaya
Executor CapSolver
    ↓ mengembalikan solusi yang bersifat sementara
Layanan browser
    ↓ mengirim dan memverifikasi
Agen LlamaIndex melanjutkan alur kerja

Dokumentasi CapSolver AI Agents menjelaskan pembagian kerja yang sama: model menentukan, adapter mengekspos skema, dan inti mengeksekusi pekerjaan tantangan yang didukung.

Kenali Parameter reCAPTCHA v3 yang Diperlukan

Dokumentasi reCAPTCHA v3 CapSolver mendefinisikan empat tipe tugas:

Bidang dasar adalah:

< a href="https://developers.google.com/recaptcha/docs/v3" rel="nofollow">pedoman reCAPTCHA v3 Google menjelaskan nama tindakan sebagai bagian dari integrasi. Tindakan yang diamati di halaman harus dipertahankan secara tepat.

< a href="https://www.capsolver.com/blog/recaptcha" rel="nofollow">blog reCAPTCHA CapSolver memiliki panduan tambahan untuk penyelesaian masalah dan implementasi.

Jangan Biarkan Model Membuat Parameter Target

Berikan referensi ke state server, bukan nilai sembarangan.

from dataclasses import dataclass
from urllib.parse import urlparse

@dataclass(frozen=True)
class CaptchaContext:
    context_id: str
    website_url: str
    website_key: str
    page_action: str
    enterprise: bool = False
    proxy_profile: str | None = None
    session_mode: bool = False

TRUSTED_CONTEXTS: dict[str, CaptchaContext] = {}
ALLOWED_HOSTS = {"staging.example.com", "portal.example.org"}


def get_trusted_context(context_id: str) -> CaptchaContext:
    context = TRUSTED_CONTEXTS.get(context_id)
    if context is None:
        raise ValueError("Konteks CAPTCHA tidak dikenal")

    host = urlparse(context.website_url).hostname
    if host not in ALLOWED_HOSTS:
        raise PermissionError("Target di luar kebijakan host yang disetujui")

    if not context.website_key or not context.page_action:
        raise ValueError("Konteks tepercaya kehilangan parameter v3 yang diperlukan")

    return context

Model hanya menerima context_id. Layanan browser memiliki halaman saat ini, kunci situs, tindakan, dan ikatan proxy.

Instal Paket yang Didukung

Dokumentasi CapSolver Agent yang disediakan pengguna menentukan instalasi paket inti sebelum paket agen:

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

Atur kunci API di lingkungan runtime:

export CAPSOLVER_API_KEY="kunci-api-capsolver-anda"

Jangan tempel kunci ke prompt, notebook, dataset skenario, atau jejak. FAQ CapSolver AI dan otomatisasi menjelaskan model integrasi.

Buat Executor CapSolver Sisi Server

capsolver-agent menyediakan create_executor() untuk batas model–adapter–core.

import os
from capsolver_agent.schema import create_executor

executor = create_executor(
    api_key=os.environ["CAPSOLVER_API_KEY"],
    default_timeout=120,
)

Executor mengirim solve_captcha ke CapSolver Core dan mengembalikan hasil yang terstruktur. Pertahankan di kode aplikasi yang tepercaya.

Tulis Fungsi Selesaikan Async yang Sempit

Fungsi menyelesaikan konteks tepercaya, memilih tipe tugas resmi, dan memanggil executor.

from typing import Annotated

async def solve_recaptcha_v3(
    context_id: Annotated[
        str,
        "ID yang tidak terlihat untuk konteks CAPTCHA browser yang disetujui dan saat ini"
    ],
) -> dict:
    """Selesaikan reCAPTCHA v3 untuk konteks browser yang disetujui.

    Hanya gunakan ketika alur kerja saat ini melaporkan checkpoint reCAPTCHA v3 yang didukung.
    Jangan tebak atau ubah URL, kunci situs, atau tindakan target.
    """
    context = get_trusted_context(context_id)

    captcha_type = (
        "reCaptchaV3Enterprise"
        if context.enterprise
        else "reCaptchaV3"
    )

    args = {
        "captcha_type": captcha_type,
        "website_url": context.website_url,
        "website_key": context.website_key,
        "page_action": context.page_action,
    }

    if context.proxy_profile:
        args["proxy"] = resolve_proxy(context.proxy_profile)

    result = await executor.execute("solve_captcha", args)
    if not result.get("success"):
        return {
            "success": False,
            "context_id": context_id,
            "error": normalize_error(result.get("error")),
        }

    solution = result.get("solution") or {}
    token = solution.get("token")
    if not token:
        return {
            "success": False,
            "context_id": context_id,
            "error": "solusi tidak mengandung token",
        }

    receipt = await submit_solution_and_verify(
        context_id=context_id,
        token=token,
        session_cookie=extract_session_cookie(solution),
    )

    return {
        "success": receipt["verified"],
        "context_id": context_id,
        "verified": receipt["verified"],
        "next_state": receipt["next_state"],
    }

resolve_proxy, normalize_error, dan submit_solution_and_verify adalah adapter kebijakan yang dimiliki aplikasi. Mereka tidak boleh terlihat oleh model.

Bungkus Fungsi dengan LlamaIndex FunctionTool

from llama_index.core.tools import FunctionTool

tool = FunctionTool.from_defaults(
    async_fn=solve_recaptcha_v3,
    name="solve_recaptcha_v3",
    description=(
        "Selesaikan reCAPTCHA v3 untuk konteks browser yang disetujui. "
        "Input harus ID konteks yang tidak terlihat yang disediakan oleh layanan browser. "
        "Jangan panggil untuk halaman yang tidak didukung atau host yang tidak disetujui."
    ),
)

Periksa skema selama pengembangan:

schema = tool.metadata.get_parameters_dict()
print(schema)

Ini mengikuti pola FunctionTool LlamaIndex yang telah didokumentasikan sambil mengurangi permukaan argumen model menjadi satu identifikasi yang tidak terlihat.

Hubungkan Alat ke Agen LlamaIndex

from llama_index.core.agent.workflow import FunctionAgent

agent = FunctionAgent(
    llm=llm,
    tools=[tool],
    system_prompt=(
        "Jalankan hanya alur kerja browser yang disetujui. Ketika layanan browser "
        "melaporkan checkpoint reCAPTCHA v3 yang didukung, panggil "
        "solve_recaptcha_v3 dengan konteks_id yang disediakan. Panggil sekali. "
        "Lanjutkan hanya jika verified=true; jika tidak, minta ulasan."
    ),
)

Jalankan alur kerja dengan pengamatan browser yang tepercaya:

response = await agent.run(
    "Alur kerja staging yang disetujui menunggu di checkpoint reCAPTCHA v3. "
    "Gunakan context_id ctx_7f19 dan lanjutkan hanya jika verified."
)

Agen tidak pernah melihat kunci API, proxy mentah, token, atau kuki.

Baca pageAction dari Halaman yang Aktif

Solver reCAPTCHA v3 LlamaIndex yang andal tidak boleh menggunakan tindakan umum seperti login untuk semua target. Layanan browser harus membaca integrasi target saat ini.

async def collect_v3_context(page, context_id: str) -> CaptchaContext:
    website_url = page.url
    host = urlparse(website_url).hostname
    if host not in ALLOWED_HOSTS:
        raise PermissionError("Target tidak disetujui")

    values = await page.evaluate("""
    () => {
      const scripts = Array.from(document.scripts)
        .map(s => s.textContent || '')
        .join('\n');

      const siteKey =
        document.querySelector('[data-sitekey]')?.getAttribute('data-sitekey')
        || null;

      const actionMatch = scripts.match(
        /grecaptcha(?:\.enterprise)?\.execute\([^,]+,\s*\{\s*action:\s*['\"]([^'\"]+)/
      );

      return {
        siteKey,
        pageAction: actionMatch ? actionMatch[1] : null,
        enterprise: scripts.includes('grecaptcha.enterprise')
      };
    }
    """)

    if not values["siteKey"] or not values["pageAction"]:
        raise RuntimeError("Tidak dapat membaca parameter v3 yang diperlukan")

    return CaptchaContext(
        context_id=context_id,
        website_url=website_url,
        website_key=values["siteKey"],
        page_action=values["pageAction"],
        enterprise=values["enterprise"],
    )

Untuk integrasi yang kompleks, gunakan panduan ekstensi CapSolver untuk memeriksa parameter halaman selama pengembangan dan pengujian yang disetujui.

Kelola Mode Sesi dengan Cermat

Dokumentasi resmi v3 CapSolver mencatat bahwa beberapa target dapat mengembalikan recaptcha-ca-t saat isSession diaktifkan. Tangani sebagai materi sesi yang sensitif dan bersifat sementara.

SESSION_KEYS = {
    "recaptcha-ca-t",
    "recaptcha_ca_t",
}


def extract_session_cookie(solution: dict) -> str | None:
    raw = solution.get("raw") or {}
    for key in SESSION_KEYS:
        value = solution.get(key) or raw.get(key)
        if value:
            return value
    return None

Hanya aktifkan mode sesi ketika integrasi target membutuhkannya dan alur kerja diotorisasi. Simpan nilai tersebut dalam memori proses atau penyimpanan terenkripsi sementara; jangan tempatkan di konteks LlamaIndex.

Kirim dan Verifikasi dalam Kode Browser yang Tepercaya

< a href="https://developers.google.com/recaptcha/docs/verify" rel="nofollow">dokumentasi verifikasi sisi server Google menjelaskan bahwa situs memvalidasi token di backend-nya. Otomatisasi Anda harus mengirim token melalui alur aplikasi yang disetujui, lalu memverifikasi status halaman yang dihasilkan.

async def submit_solution_and_verify(
    context_id: str,
    token: str,
    session_cookie: str | None,
) -> dict:
    browser_state = BROWSER_CONTEXTS[context_id]
    page = browser_state.page

    if session_cookie:
        await browser_state.context.add_cookies([{
            "name": "recaptcha-ca-t",
            "value": session_cookie,
            "domain": urlparse(page.url).hostname,
            "path": "/",
            "secure": True,
        }])

    await page.evaluate(
        """({ token }) => {
          let input = document.querySelector(
            'textarea[name="g-recaptcha-response"]'
          );
          if (!input) {
            input = document.createElement('textarea');
            input.name = 'g-recaptcha-response';
            input.style.display = 'none';
            document.body.appendChild(input);
          }
          input.value = token;
          input.dispatchEvent(new Event('change', { bubbles: true }));
        }""",
        {"token": token},
    )

    await trigger_trusted_callback(page, browser_state.callback_name)

    try:
        await page.locator(browser_state.success_selector).wait_for(
            state="visible",
            timeout=15000,
        )
        return {"verified": True, "next_state": "continue"}
    except Exception:
        return {"verified": False, "next_state": "operator_review"}

Penemuan callback adalah spesifik target. Tangkap di konteks browser yang tepercaya daripada meminta model untuk menghasilkan JavaScript.

< a href="https://www.capsolver.com/blog/reCAPTCHA/captcha-solver-response-api" rel="nofollow">panduan API respons reCAPTCHA CapSolver menjelaskan pola penanganan respons yang umum.

Terapkan Satu Percobaan dan Status yang Jelas

from enum import Enum

class RecoveryState(str, Enum):
    DETECTED = "detected"
    SOLVING = "solving"
    VERIFIED = "verified"
    REVIEW_REQUIRED = "review_required"

ATTEMPTS: dict[str, int] = {}

async def guarded_solve(context_id: str) -> dict:
    attempts = ATTEMPTS.get(context_id, 0)
    if attempts >= 1:
        return {
            "success": False,
            "context_id": context_id,
            "next_state": RecoveryState.REVIEW_REQUIRED,
            "error": "anggaran pemulihan habis",
        }

    ATTEMPTS[context_id] = attempts + 1
    return await solve_recaptcha_v3(context_id)

Panggilan berulang sering menandakan parameter usang, tindakan yang salah, state browser yang kedaluwarsa, atau jalur yang tidak didukung. Hentikan loop dan kumpulkan diagnostik.

Catat Observabilitas yang Direddact

Catat metadata operasional, bukan rahasia.

from datetime import datetime, timezone


def recovery_event(context: CaptchaContext, result: dict) -> dict:
    return {
        "event": "recaptcha_v3_recovery",
"context_id": context.id_konteks,
        "host": urlparse(context.url_website).hostname,
        "page_action": context.tindakan_halaman,
        "enterprise": context.enterprise,
        "session_mode": context.mode_sesi,
        "success": result.get("success", False),
        "next_state": str(result.get("next_state")),
        "observed_at": datetime.now(timezone.utc).isoformat(),
    }

Jangan log websiteKey jika kebijakan Anda menganggapnya sebagai konfigurasi, dan jangan pernah log token solusi, kuki sesi, kunci API, proxy mentah, atau HTML halaman pribadi lengkap.

Pertanyaan yang Sering Diajukan tentang Kesalahan CapSolver (https://www.capsolver.com/faq/errors-and-troubleshooting) dapat membantu menormalkan kategori kesalahan.

Kode Bonus: Gunakan kode WEBS di Dashboard CapSolver untuk mendapatkan bonus tambahan 5% pada setiap pengisian ulang.

Ringkasan Perbandingan

Pola konteks yang tidak terlihat memberi agen LlamaIndex cukup kontrol untuk meminta pemulihan tanpa memungkinkannya mengubah parameter sensitif atau spesifik tujuan.

Daftar Periksa Produksi

• Simpan kunci API dan profil proxy di manajer rahasia.
• Izinkan hanya host yang disetujui dan tujuan alur kerja yang tepat.
• Baca websiteKey dan pageAction dari halaman saat ini.
• Sesuaikan Enterprise dan pengaturan sesi dengan integrasi target.
• Kirim token secara langsung melalui kode browser yang tepercaya.
• Verifikasi status aplikasi yang diharapkan sebelum melanjutkan.
• Izinkan satu percobaan penyelesaian, lalu arahkan ke tinjauan operator.
• Redakt token, kuki, proxy, dan kredensial dari jejak.
• Uji ulang skema alat setiap kali SDK atau prompt berubah.

Halaman produk CapSolver (https://www.capsolver.com/products) mencantumkan kategori solusi yang didukung, sementara blog CapSolver AI (https://www.capsolver.com/blog/ai) membahas pola integrasi agen terkait.

Penggunaan Bertanggung Jawab

Gunakan alur kerja ini hanya pada aplikasi yang Anda miliki, uji, atau memiliki izin eksplisit untuk otomatisasi. Kemampuan teknis tidak memberi akses. Hormati ketentuan tujuan, batas kecepatan, persyaratan privasi, dan batas otentikasi. Jangan gunakan alat agen untuk mengakses akun pribadi, catatan terbatas, atau alur kerja pihak ketiga tanpa izin. Letakkan tindakan berdampak tinggi seperti pengiriman, pembayaran, pemesanan, dan perubahan akun di belakang langkah kebijakan dan konfirmasi terpisah.

Kesimpulan

Solver reCAPTCHA v3 LlamaIndex produksi harus mengekspos satu fungsi pemulihan yang sempit dan berjenis. Layanan browser menyediakan ID konteks yang tepercaya, kode sisi server mempertahankan URL, kunci situs, tindakan, mode Enterprise, dan kebijakan proxy, CapSolver mengembalikan solusi berumur pendek, dan browser memverifikasi status yang diharapkan sebelum agen melanjutkan.

Mulai integrasi LlamaIndex yang disetujui dengan CapSolver, uji di alur kerja staging yang dikendalikan, dan tambahkan penguatan parameter dan asersi ulang sebelum produksi.

FAQ

Apakah reCAPTCHA v3 memerlukan klik kotak centang?

Tidak. reCAPTCHA v3 berbasis skor dan biasanya berjalan di latar belakang. Alur kerja harus mempertahankan kunci situs, URL, dan tindakan target.

Mengapa pageAction penting?

Tindakan mengidentifikasi operasi yang dievaluasi, seperti login atau kirim. Gunakan tindakan yang tepat yang dibaca dari integrasi saat ini daripada nilai umum.

Apakah agen LlamaIndex menerima token?

Lebih baik pengiriman sisi server dan hanya kembalikan status yang diverifikasi. Token adalah data runtime berumur pendek dan tidak boleh masuk ke konteks model atau log.

Kapan mode sesi harus diaktifkan?

Aktifkan hanya ketika target yang sah membutuhkan nilai sesi yang dikembalikan. Simpan nilai tersebut di penyimpanan runtime yang dienkripsi berumur pendek.

Apa yang harus terjadi setelah percobaan gagal?

Berhenti setelah anggaran percobaan yang ditentukan, catat peristiwa diagnostik yang telah direkam, perbarui parameter halaman yang tepercaya jika sesuai, dan arahkan alur kerja ke tinjauan operator.