Cara menyelesaikan reCAPTCHA dalam Agen LangGraph

TL;DR

• Instal capsolver-agent dengan ekstra LangChain dan muat alat siap pakainya dengan get_langchain_tools().
• Hubungkan alat-alat ini ke model percakapan dan jalankan mereka di ToolNode LangGraph.
• Untuk mode token reCAPTCHA v2, berikan URL halaman yang diizinkan secara tepat dan kunci situs; token yang dikembalikan adalah gRecaptchaResponse di tingkat API.
• Tambahkan daftar izin, batas ulang coba, isolasi rahasia, dan rute tinjauan manusia di sekitar node alat.
• Gunakan mode browser recovery ketika halaman dinamis memerlukan deteksi dan penyisipan token dalam sesi yang sama.

Pengantar

Cara yang paling mudah dipelihara untuk menyelesaikan reCAPTCHA dalam agen LangGraph adalah dengan menganggap pemulihan tantangan sebagai node alat bertipe, bukan menyematkan logika jaringan dalam prompt model. SDK Agent CapSolver menyediakan alat yang kompatibel dengan LangChain, sementara LangGraph menyediakan state eksplisit, routing, penanganan kesalahan, dan kemampuan dilanjutkan. Model dapat memutuskan bahwa tantangan yang didukung menghambat langkah berikutnya yang diizinkan, tetapi alat yang deterministik memvalidasi parameter halaman, memanggil solver, dan mengembalikan hasil yang terstruktur. Arsitektur ini menjaga kunci API di luar pesan, membuat ulang coba teramati, dan mencegah target yang tidak terkait dikirimkan. Tutorial ini membangun grafik minimal, menunjukkan cara mengarahkan pemanggilan alat, menjelaskan parameter reCAPTCHA v2, dan menambahkan perlindungan produksi untuk otomasi browser, QA, RPA, dan alur kerja data publik yang disetujui.

Di Mana CapSolver Cocok dalam Mesin State LangGraph

LangGraph dirancang untuk alur kerja berstate di mana node melakukan pekerjaan terbatas dan tepi mengontrol apa yang terjadi berikutnya. CapSolver cocok secara alami ke dalam node alat khusus:

Tugas yang dipandu pengguna
      ↓
Node Reasoning mengidentifikasi tantangan yang didukung
      ↓
Node Alat menjalankan alat CapSolver
      ↓
Solusi terstruktur atau kesalahan yang dinormalisasi
      ↓
Browser melanjutkan, mengulang, atau meminta tinjauan manusia

Model harus memutuskan kapan pemulihan diperlukan. Ia tidak boleh memutuskan di mana rahasia disimpan, host mana yang diizinkan, atau berapa banyak ulang coba yang diizinkan. Keputusan-keputusan ini milik kode aplikasi yang deterministik.

Blog CapSolver AI mencakup pola integrasi agen, dan FAQ CapSolver AI dan otomasi menjelaskan bagaimana lapisan pemulihan melengkapi tumpukan agen yang ada.

Instal Alat Agent dan LangGraph

Dokumentasi CapSolver Agent yang diberikan pengguna menyatakan bahwa capsolver-agent bergantung pada capsolver-core. Instal intinya terlebih dahulu, lalu paket agent dengan integrasi LangChain.

pip install git+https://github.com/capsolver-ai/capsolver-core.git
pip install "capsolver-agent[langchain] @ git+https://github.com/capsolver-ai/capsolver-agent.git"
pip install langchain-openai langgraph

Konfigurasikan kredensial melalui lingkungan runtime:

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

Repositori resmi CapSolver Agent mencatat jalur impor ini:

from capsolver_agent.langchain_tools import get_langchain_tools

tools = get_langchain_tools(api_key="YOUR_API_KEY")

Objek yang dikembalikan adalah instansi BaseTool yang kompatibel dengan LangChain. Guia alat LangChain resmi menjelaskan bahwa alat mengekspos input dan output yang ditentukan ke model, sementara informasi tipe dan deskripsi membantu model memilih tindakan yang benar.

Pahami Parameter Tugas reCAPTCHA v2

Untuk tugas reCAPTCHA v2 tanpa proxy, input yang diperlukan adalah URL halaman dan kunci situs. Dokumentasi resmi CapSolver reCAPTCHA v2 mendaftarkan ReCaptchaV2TaskProxyLess untuk jalur proxy bawaan dan tipe tugas Enterprise terpisah ketika halaman menggunakan reCAPTCHA Enterprise.

Pada tingkat tugas REST, token solusi dikembalikan sebagai solution.gRecaptchaResponse. SDK Agent mengemas hasil inti dalam kamus terstruktur sehingga grafik dapat mengarahkan berdasarkan keberhasilan atau kegagalan tanpa memproses teks arbitrer.

Untuk penemuan parameter, lihat panduan ekstensi browser CapSolver dan panduan implementasi reCAPTCHA v2.

Bangun LangGraph dengan Alat CapSolver

Contoh di bawah ini memuat alat CapSolver resmi, menghubungkannya ke model percakapan, dan menempatkannya dalam ToolNode. Grafik kembali ke node reasonings setelah setiap respons alat.

import os
from typing import Literal

from capsolver_agent.langchain_tools import get_langchain_tools
from langchain_openai import ChatOpenAI
from langgraph.graph import START, StateGraph
from langgraph.graph.message import MessagesState
from langgraph.prebuilt import ToolNode, tools_condition

capsolver_tools = get_langchain_tools(
    api_key=os.environ["CAPSOLVER_API_KEY"]
)

model = ChatOpenAI(
    model="gpt-4o-mini",
    temperature=0,
).bind_tools(capsolver_tools)


def agent_node(state: MessagesState):
    response = model.invoke(state["messages"])
    return {"messages": [response]}


def safe_tool_error(error: Exception) -> str:
    return (
        "Alat tantangan gagal. Jangan ulang otomatis. "
        "Kembalikan alur kerja ke tinjauan operator."
    )

builder = StateGraph(MessagesState)
builder.add_node("agent", agent_node)
builder.add_node(
    "tools",
    ToolNode(
        capsolver_tools,
        handle_tool_errors=safe_tool_error,
    ),
)
builder.add_edge(START, "agent")
builder.add_conditional_edges("agent", tools_condition)
builder.add_edge("tools", "agent")

graph = builder.compile()

Referensi ToolNode LangGraph mencatat bahwa ToolNode menerima instansi BaseTool, menjalankan pemanggilan alat, dan mendukung penanganan kesalahan yang dapat dikonfigurasi. Ini membuatnya cocok untuk cabang pemulihan yang harus teramati dan dapat diprediksi.

Berikan Instruksi Sempit kepada Agen

Model membutuhkan konteks yang cukup untuk memanggil alat yang benar, tetapi tidak boleh menerima otoritas yang tidak terbatas. Bangun pesan dari data aplikasi yang divalidasi:

request = {
    "website_url": "https://staging.example.com/approved-form",
    "website_key": "6LcXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
}

messages = [
    (
        "system",
        "Anda hanya beroperasi pada alur kerja yang disetujui. Jika reCAPTCHA "
        "yang didukung menghambat langkah berikutnya, panggil alat solve_captcha CapSolver sekali "
        "dengan URL dan kunci situs yang tepat yang diberikan oleh aplikasi. "
        "Jangan pernah menciptakan target atau meminta kredensial. Jika penyelesaian gagal, "
        "hentikan dan minta tinjauan operator.",
    ),
    (
        "user",
        "Lanjutkan tugas staging yang disetujui. Browser melaporkan reCAPTCHA v2 di "
        f"{request['website_url']} dengan kunci situs {request['website_key']}.",
    ),
]

result = graph.invoke(
    {"messages": messages},
    config={"recursion_limit": 6},
)

Batas rekursi mencegah loop grafik yang tidak terkendali. Di produksi, batasi hostname yang diizinkan sebelum membangun pesan dan hindari menyimpan token solusi dalam jejak.

Tambahkan Daftar Izin Host Sebelum Grafik

Alat CapSolver menyelesaikan apa yang diminta; aplikasi Anda harus memutuskan pekerjaan mana yang diizinkan. Validasi URL halaman di luar model:

from urllib.parse import urlparse

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


def validate_target(url: str) -> str:
    parsed = urlparse(url)
    if parsed.scheme != "https":
        raise ValueError("Hanya target HTTPS yang diizinkan")
    if parsed.hostname not in ALLOWED_HOSTS:
        raise PermissionError("Host target tidak disetujui")
    return url

Gunakan daftar izin khusus tenant atau manifest alur kerja yang ditandatangani ketika banyak pelanggan berbagi platform yang sama. Jangan izinkan instruksi dalam bahasa alami mengubah kebijakan ini.

Arahkan Keberhasilan, Kegagalan, dan Tinjauan Manusia

Grafik pemulihan yang berguna membutuhkan tiga hasil, bukan hanya "selesai" dan "crashed." Normalisasi output alat menjadi keputusan alur kerja:

from typing import TypedDict

class RecoveryDecision(TypedDict):
    status: Literal["continue", "retry", "review"]
    reason: str


def classify_recovery(result: dict, attempt: int) -> RecoveryDecision:
    if result.get("success"):
        return {"status": "continue", "reason": "solusi dikembalikan"}

    error = str(result.get("error", "kesalahan tidak diketahui"))
    if attempt == 0 and "timeout" in error.lower():
        return {"status": "retry", "reason": "satu ulang coba terbatas diizinkan"}

    return {"status": "review", "reason": error}

Jangan ekspos token langsung dalam pesan model ketika browser dapat mengonsumsinya secara langsung. Batas idealnya: hasil alat → kontroler browser yang tepercaya → hasil pengiriman → status yang dihapus kembali ke grafik.

FAQ kesalahan dan pemecahan masalah CapSolver menyediakan jalur diagnostik umum, sementara panduan API respons CapSolver menjelaskan penanganan hasil.

Mode Token vs Mode Browser

Mode token biasanya lebih sederhana untuk parameter reCAPTCHA yang diketahui. Mode browser berguna ketika alur Playwright yang diizinkan memerlukan detect() dan solve_on_page() dalam sesi yang sama. Dokumentasi Agent CapSolver memetakan solve_captcha ke penyelesaian token inti dan solve_on_page ke pemulihan browser.

Observabilitas Tanpa Bocornya Rahasia

Lacak transisi grafik dan metrik operasional, bukan nilai sensitif. Bidang yang berguna termasuk:

safe_event = {
    "workflow_id": "wf_01J...",
    "node": "tools",
    "tool": "solve_captcha",
    "target_host": "staging.example.com",
    "challenge_type": "recaptcha_v2",
    "attempt": 1,
    "duration_ms": 6420,
    "outcome": "success",
}

Jangan pernah mencatat kunci API CapSolver, token solusi lengkap, kuki yang diautentikasi, atau data formulir. Terapkan redaksi jejak sebelum mengirimkan acara ke sistem observabilitas eksternal.

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

Daftar Periksa Produksi

Solver reCAPTCHA LangGraph produksi harus memiliki daftar izin hostname, kebijakan tugas tetap, penanganan umur token pendek, ulang coba terbatas, redaksi jejak, kondisi berhenti eksplisit, dan node tinjauan operator. Uji dengan halaman staging yang disetujui sebelum menghubungkannya ke otomasi tanpa pengawasan.

FAQ penyelesaian CAPTCHA CapSolver mencakup perilaku tugas, dan panduan scraping Python CapSolver menyediakan praktik otomasi browser.

Penggunaan yang Bertanggung Jawab

Gunakan alur kerja ini hanya pada sistem yang Anda miliki, uji, atau memiliki izin eksplisit untuk otomasi. Penyelesaian tantangan tidak memberikan akses. Hormati ketentuan situs, batas kecepatan, kewajiban privasi, dan pembatasan tujuan. Pastikan konfirmasi manusia sebelum grafik mengirimkan formulir, mengubah data akun, atau melakukan tindakan berdampak tinggi.

Kesimpulan

Solver reCAPTCHA LangGraph paling andal ketika penyelesaian adalah node alat eksplisit dengan routing yang ketat. Muat alat LangChain siap pakai CapSolver, hubungkan ke model, jalankan melalui ToolNode, dan jaga otorisasi, rahasia, ulang coba, dan konsumsi token dalam kode aplikasi yang deterministik. Ini memberi agen kemampuan pemulihan tanpa memberinya kontrol yang tidak terbatas.

Mulai dengan CapSolver, validasi grafik terhadap alur kerja staging yang disetujui, dan tambahkan redaksi jejak dan tinjauan manusia sebelum memperluas.

FAQ

Impor CapSolver apa yang harus saya gunakan dengan LangGraph?

Gunakan from capsolver_agent.langchain_tools import get_langchain_tools, lalu panggil get_langchain_tools(api_key=...) untuk mendapatkan alat yang kompatibel dengan LangChain yang dapat diberikan ke ToolNode.

Apa input yang diperlukan untuk mode token reCAPTCHA v2?

URL halaman dan kunci reCAPTCHA diperlukan. Bidang Enterprise, tidak terlihat, tindakan, atau sesi harus dimasukkan hanya ketika halaman yang diizinkan benar-benar menggunakannya.

Apakah model LangGraph menerima token solusi?

Lebih baik mengirimkan token langsung dari lapisan alat yang tepercaya ke kontroler browser. Kembalikan hanya peristiwa keberhasilan atau kegagalan yang dihapus ke grafik pemikiran ketika mungkin.

Berapa banyak ulang coba otomatis yang harus grafik izinkan?

Biasanya satu ulang coba terbatas sudah cukup untuk timeout sementara. Penolakan berulang harus diarahkan ke tinjauan manusia karena URL, kunci, sesi, atau konfigurasi halaman mungkin salah.

Apakah pola ini dapat menangani tantangan browser dinamis?

Ya. Gunakan metode inti CapSolver yang mendukung browser melalui alat yang dikendalikan ketika alur kerja memerlukan deteksi dan pemulihan tingkat halaman dalam sesi Playwright yang sama.