Cara menyelesaikan reCAPTCHA di LangChain

reCAPTCHA adalah tantangan verifikasi yang paling umum yang dihadapi agen AI saat menjelajahi web. Agen LangChain yang melakukan pengumpulan data, pengiriman formulir, atau alur kerja multi-langkah menemui kotak centang reCAPTCHA v2 dan tantangan yang tidak terlihat di halaman masuk, hasil pencarian, dan konten yang dilindungi. Tutorial ini menunjukkan cara menyelesaikan reCAPTCHA v2 secara khusus dalam LangChain menggunakan paket capsolver-agent dari CapSolver, dengan contoh kode lengkap untuk mode Token dan mode Browser.

TL;DR

• reCAPTCHA v2 adalah jenis CAPTCHA yang paling sering dijumpai oleh agen web LangChain
• Alat LangChain CapSolver menyelesaikan reCAPTCHA v2 (kotak centang dan tidak terlihat) dalam rata-rata 5-12 detik
• Mode Token hanya memerlukan kunci situs dan URL — tidak diperlukan browser
• Mode Browser mendeteksi reCAPTCHA secara otomatis di halaman mana pun dan mengisi token kembali ke DOM
• Paket capsolver-agent menyediakan implementasi BaseTool native untuk agen ReAct LangChain

Mengapa reCAPTCHA Memblokir Agen LangChain

reCAPTCHA v2 dipasang di jutaan situs web untuk membedakan pengguna manusia dari lalu lintas otomatis. Ketika agen LangChain mengunjungi halaman yang dilindungi — baik untuk penguatan prospek, ekstraksi data, atau otomatisasi alur kerja — mesin analisis risiko Google mengevaluasi sesi tersebut. Browser otomatis, lingkungan tanpa antarmuka grafis, dan pola navigasi cepat memicu tantangan reCAPTCHA, menghentikan eksekusi agen.

Tantangan ini muncul dalam dua bentuk: kotak centang yang terlihat ("Saya bukan robot") yang memerlukan interaksi, dan varian yang tidak terlihat yang memicu secara diam-diam berdasarkan skor risiko. Kedua bentuk ini memerlukan pengiriman token yang valid untuk melanjutkan. Tanpa mekanisme penyelesaian, agen LangChain tidak dapat melanjutkan tugasnya, dan seluruh rantai gagal.

Dokumentasi reCAPTCHA Google mengonfirmasi bahwa sistem ini menggunakan analisis risiko lanjutan termasuk pemeriksaan lingkungan browser, pola interaksi, dan perilaku historis. Ini membuat reCAPTCHA terutama menantang bagi agen otomatis yang tidak memiliki pola penjelajahan seperti manusia.

Layanan penyelesaian AI CapSolver menangani reCAPTCHA v2 dengan menghasilkan token yang valid melalui infrastruktur cloud-nya, menghindari kebutuhan untuk interaksi pixel-perfect atau pengenalan gambar dalam jendela konteks agen.

Apa yang Perlu Anda Siapkan Sebelum Memulai

Instal paket yang diperlukan:

# Mesin inti (dependensi yang diperlukan)
pip install git+https://github.com/capsolver-ai/capsolver-core.git

# Alat agen dengan dukungan LangChain
pip install "capsolver-agent[langchain] @ git+https://github.com/capsolver-ai/capsolver-agent.git"

# Runtime LangChain
pip install langchain-openai langgraph

Atur variabel lingkungan:

export CAPSOLVER_API_KEY="your-capsolver-api-key"
export OPENAI_API_KEY="your-openai-api-key"

Anda juga memerlukan kunci situs reCAPTCHA dari halaman target Anda. Gunakan ekstensi browser CapSolver untuk mengidentifikasinya, atau periksa sumber halaman untuk atribut data-sitekey. Panduan identifikasi reCAPTCHA https://www.capsolver.com/blog/reCAPTCHA/how-to-identify-recaptcha-types menjelaskan cara membedakan antara varian v2 kotak centang, v2 tidak terlihat, dan v3.

Langkah 1 — Identifikasi Parameter reCAPTCHA v2 di Halaman Target

Apa yang Harus Dilakukan

Temukan kunci situs reCAPTCHA di halaman target Anda. Buka alat pengembang browser dan cari sumber halaman:

<!-- reCAPTCHA v2 yang terlihat (kotak centang) -->
<div class="g-recaptcha" data-sitekey="6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI"></div>

<!-- reCAPTCHA v2 yang tidak terlihat -->
<div class="g-recaptcha" data-sitekey="6LeIxAcT..." data-size="invisible"></div>

Catat tiga nilai: data-sitekey, URL halaman lengkap, dan apakah itu terlihat atau tidak terlihat (periksa data-size="invisible").

Untuk deteksi programatik menggunakan SDK CapSolver:

from capsolver_core import create_capsolver
from playwright.async_api import async_playwright

async def detect_recaptcha(url: str):
    cap = create_capsolver(api_key="YOUR_API_KEY")
    async with async_playwright() as p:
        browser = await p.chromium.launch()
        page = await browser.new_page()
        await page.goto(url)
        
        # Deteksi otomatis semua CAPTCHAs di halaman
        infos = await cap.get_captcha_info(page)
        for info in infos:
            print(f"Jenis: {info.type}, Kunci: {info.website_key}")
        
        await browser.close()
    await cap.aclose()

Mengapa Ini Penting

Kunci situs adalah parameter esensial untuk penyelesaian reCAPTCHA. Tanpa itu, layanan penyelesaian tidak dapat menghasilkan token yang valid untuk situs tertentu. Halaman berbeda di domain yang sama mungkin menggunakan kunci situs yang berbeda, jadi selalu verifikasi per halaman.

Kesalahan Umum yang Harus Dihindari

• Menggunakan kunci uji di produksi: Google menyediakan kunci uji (seperti 6LeIxAcT...) yang selalu berhasil. Situs nyata menggunakan kunci unik yang memerlukan penyelesaian nyata.
• Mengacaukan v2 dengan v3: reCAPTCHA v3 menggunakan tipe tugas yang berbeda dan memerlukan page_action. Periksa sumber skrip — v3 dimuat melalui ?render=SITE_KEY daripada elemen div.

Langkah 2 — Selesaikan reCAPTCHA v2 dengan Alat LangChain (Mode Token)

Apa yang Harus Dilakukan

Gunakan alat LangChain capsolver-agent untuk menyelesaikan reCAPTCHA v2 dalam alur kerja agen Anda:

import asyncio
from langchain_openai import ChatOpenAI
from langgraph.prebuilt import create_react_agent
from capsolver_agent.langchain import get_langchain_tools

async def solve_recaptcha_with_agent():
    # Dapatkan alat LangChain CapSolver
    tools = get_langchain_tools(api_key="YOUR_CAPSOLVER_API_KEY")
    
    # Buat agen ReAct
    llm = ChatOpenAI(model="gpt-4o", temperature=0)
    agent = create_react_agent(llm, tools=tools)
    
    # Minta agen menyelesaikan reCAPTCHA
    result = await agent.ainvoke({
        "messages": [("user", 
            "Selesaikan reCAPTCHA v2 di https://example.com/login. "
            "Kunci situsnya adalah 6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI. "
            "Kembalikan token yang bisa saya gunakan untuk mengirim formulir."
        )]
    })
    
    print(result["messages"][-1].content)

asyncio.run(solve_recaptcha_with_agent())

Untuk eksekusi langsung tanpa loop agen (saat Anda ingin kontrol programatik):

from capsolver_agent.schema import create_executor

async def solve_recaptcha_direct():
    executor = create_executor(api_key="YOUR_CAPSOLVER_API_KEY")
    
    result = await executor.execute("solve_captcha", {
        "captcha_type": "reCaptchaV2",
        "website_url": "https://example.com/login",
        "website_key": "6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI"
    })
    
    if result["success"]:
        token = result["solution"]["token"]
        print(f"reCAPTCHA diselesaikan! Token: {token[:60]}...")
        # Kirim token ini sebagai 'g-recaptcha-response' dalam permintaan POST formulir
        return token
    else:
        print(f"Gagal: {result['error']}")
        return None

Token yang dikembalikan harus dikirim sebagai bidang g-recaptcha-response dalam permintaan POST formulir. Dokumentasi penyelesaian reCAPTCHA v2 memberikan detail tambahan tentang pola pengiriman token.

Mengapa Ini Penting

Mode Token adalah pendekatan tercepat untuk reCAPTCHA v2 — rata-rata waktu penyelesaian adalah 5-12 detik tanpa beban browser. Untuk agen LangChain yang sudah mengetahui parameter situs target, ini memberikan penyelesaian CAPTCHA instan tanpa memulai instansi browser.

Kesalahan Umum yang Harus Dihindari

• Tidak mengirim token secara cepat: token reCAPTCHA berlaku selama sekitar 120 detik. Kirim formulir segera setelah menerima token.
• Melewatkan flag tidak terlihat: Untuk reCAPTCHA v2 yang tidak terlihat, pendekatan penyelesaian sama, tetapi Anda mungkin perlu memicu callback pengiriman formulir setelah penyisipan.

Langkah 3 — Tangani reCAPTCHA v2 yang Tidak Terlihat

Apa yang Harus Dilakukan

reCAPTCHA v2 yang tidak terlihat bekerja sama dari perspektif API — tipe tugas reCaptchaV2 yang sama menangani kedua varian:

# reCAPTCHA v2 yang tidak terlihat — panggilan API yang sama
result = await executor.execute("solve_captcha", {
    "captcha_type": "reCaptchaV2",
    "website_url": "https://example.com/checkout",
    "website_key": "6Ld_SITE_KEY_HERE"
    # Tidak diperlukan flag tambahan — CapSolver menangani tidak terlihat secara otomatis
})

Perbedaannya adalah bagaimana Anda menyisipkan token. reCAPTCHA yang tidak terlihat biasanya terikat dengan klik tombol atau peristiwa pengiriman formulir. Setelah mendapatkan token, aktifkan callback:

# Dalam konteks Playwright/browser setelah menyelesaikan:
await page.evaluate(f"""() => {{
    document.getElementById('g-recaptcha-response').innerHTML = '{token}';
    // Aktifkan callback yang terikat
    if (typeof ___grecaptcha_cfg !== 'undefined') {{
        const clients = ___grecaptcha_cfg.clients;
        for (const key in clients) {{
            const client = clients[key];
            // Cari dan panggil callback
            if (client && client.L && client.L.L && client.L.L.callback) {{
                client.L.L.callback('{token}');
            }}
        }}
    }}
}}""")

Panduan identifikasi callback reCAPTCHA menjelaskan cara menemukan fungsi callback yang benar untuk situs apa pun.

Langkah 4 — Gunakan Mode Browser untuk Deteksi dan Penyelesaian reCAPTCHA Otomatis

Apa yang Harus Dilakukan

Ketika agen LangChain menggerakkan browser dan menemui reCAPTCHA secara dinamis, gunakan solve_on_page() untuk deteksi dan pengisian otomatis:

import asyncio
from capsolver_core import create_capsolver
from playwright.async_api import async_playwright

async def auto_solve_recaptcha(target_url: str):
    """Deteksi dan selesaikan reCAPTCHA di halaman mana pun secara otomatis."""
    cap = create_capsolver(api_key="YOUR_CAPSOLVER_API_KEY")
    
    async with async_playwright() as p:
        browser = await p.chromium.launch(headless=True)
        page = await browser.new_page()
        await page.goto(target_url)
        await page.wait_for_load_state("networkidle")
        
        # Satu panggilan menangani semuanya: deteksi → selesaikan → isi kembali
        results = await cap.solve_on_page(page)
        
        for r in results:
            if r.solution:
                print(f"Selesai {r.info.type}: token={r.solution.token[:50]}...")
                print(f"Token diisi ke halaman: {r.filled}")
            else:
                print(f"Gagal menyelesaikan {r.info.type}: {r.error}")
        
        # Setelah menyelesaikan, halaman siap — kirim formulir
        submit_button = page.locator('button[type="submit"]')
        if await submit_button.count() > 0:
            await submit_button.click()
            await page.wait_for_navigation()
            print(f"Formulir dikirim. URL saat ini: {page.url}")
        
        await browser.close()
    await cap.aclose()

asyncio.run(auto_solve_recaptcha("https://example.com/login"))

Mode Browser sangat kuat karena membaca parameter reCAPTCHA langsung dari DOM yang aktif — tidak perlu ekstraksi kunci situs manual. SDK mengidentifikasi jenis CAPTCHA, membaca data-sitekey, menyelesaikannya, dan menulis token kembali ke textarea g-recaptcha-response secara otomatis.

Dapatkan Kode Bonus Anda: Gunakan kode WEBS di Dashboard CapSolver untuk mendapatkan bonus tambahan 5% pada setiap recharge. Ideal untuk pengembang LangChain yang membangun agen yang menangani tantangan reCAPTCHA.

Langkah 5 — Bangun Agen LangChain Produksi dengan Penanganan reCAPTCHA

Apa yang Harus Dilakukan

Gabungkan penyelesaian reCAPTCHA dengan alat lain untuk alur kerja produksi lengkap:

import asyncio
from langchain_openai import ChatOpenAI
from langgraph.prebuilt import create_react_agent
from capsolver_agent.langchain import get_langchain_tools

async def production_agent():
    capsolver_tools = get_langchain_tools(api_key="YOUR_CAPSOLVER_API_KEY")
    llm = ChatOpenAI(model="gpt-4o", temperature=0)
    agent = create_react_agent(llm, tools=capsolver_tools)
    
    # Tugas multi-langkah yang memerlukan penyelesaian reCAPTCHA
    result = await agent.ainvoke({
        "messages": [("user",
            "Saya perlu mengakses sumber daya yang dilindungi. "
            "Pertama, selesaikan reCAPTCHA v2 di https://example.com/gate "
            "(kunci situs: 6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI), "
            "kemudian beri tahu saya token agar saya bisa melanjutkan permintaan saya."
        )]
    })
    
    return result["messages"][-1].content

asyncio.run(production_agent())

Untuk agen yang perlu menangani versi reCAPTCHA yang berbeda di berbagai situs, alat yang sama menangani v2 dan v3 — cukup ubah parameter captcha_type dari reCaptchaV2 ke reCaptchaV3.

Pasokan CapSolver menampilkan semua jenis CAPTCHA yang didukung dan tarifnya, membantu Anda memperkirakan biaya untuk penggunaan agen LangChain Anda.

Kesimpulan

Menyelesaikan reCAPTCHA dalam LangChain memerlukan paket capsolver-agent dengan ekstra LangChain, yang menyediakan implementasi BaseTool native. Mode Token menangani kunci situs yang diketahui dalam 5-12 detik tanpa browser, sementara mode Browser mendeteksi dan mengisi token reCAPTCHA di halaman mana pun. CapSolver menyediakan infrastruktur penyelesaian AI, mendukung varian kotak centang dan tidak terlihat reCAPTCHA melalui antarmuka yang seragam.

Mulailah dengan mengidentifikasi kunci situs di halaman target Anda, lalu integrasikan get_langchain_tools() ke dalam agen ReAct Anda. Loop penalaran agen secara alami memutuskan kapan mengaktifkan penyelesaian reCAPTCHA, membuat penanganan verifikasi menjadi bagian yang transparan dari alur kerja otomatisasi Anda.

FAQ

Berapa tingkat keberhasilan menyelesaikan reCAPTCHA v2 dengan CapSolver?

CapSolver mencapai tingkat keberhasilan 95-99% pada tantangan reCAPTCHA v2. Layanan penyelesaian berbasis AI menangani varian kotak centang dan tidak terlihat. Gagalnya upaya tidak dikenakan biaya, dan respons error yang terstruktur memungkinkan agen Anda untuk mencoba ulang secara otomatis.

Berapa lama waktu yang dibutuhkan untuk menyelesaikan reCAPTCHA v2?

Waktu penyelesaian rata-rata untuk reCAPTCHA v2 adalah 5-12 detik. Ini mencakup waktu putar jaringan ke layanan CapSolver dan proses pengenalan AI. Untuk alur kerja yang sensitif terhadap waktu, SDK mendukung timeout dan interval polling yang dapat dikonfigurasi.

Apakah alat LangChain dapat menangani reCAPTCHA Enterprise?

Ya. Kirim enterprise: true dalam parameter saat memanggil solve_captcha. reCAPTCHA Enterprise menggunakan tipe tugas yang sama v2/v3 tetapi mungkin memerlukan parameter tambahan seperti token s. Layanan CapSolver menangani varian Enterprise secara transparan.
Tidak. Mode Token berjalan tanpa browser apa pun — Anda memberikan kunci situs dan URL, lalu menerima token kembali. Mode Browser (memerlukan Playwright) bersifat opsional dan digunakan ketika Anda ingin deteksi otomatis dan pengisian kembali di halaman live. Mayoritas integrasi LangChain menggunakan Mode Token untuk kesederhanaan dan kecepatan.

Bagaimana cara saya menangani kedaluwarsa token reCAPTCHA?

Token reCAPTCHA kedaluwarsa setelah sekitar 120 detik. Minta token secepat mungkin sebelum pengiriman formulir. Jika alur kerja Anda memiliki penundaan antara penyelesaian dan pengiriman, terapkan pola "selesaikan tepat sebelum mengirim" daripada menyelesaikan lebih awal dalam pipeline.