Cara Menyelesaikan reCAPTCHA dalam OpenAI Agents SDK

SDK Agens OpenAI menyediakan kerangka kerja yang siap produksi untuk membangun agen AI dengan kemampuan pemanggilan alat. Ketika agen-agen ini berinteraksi dengan situs web yang dilindungi oleh reCAPTCHA, mereka membutuhkan cara untuk menyelesaikan tantangan verifikasi secara programatis. Paket capsolver-agent dari CapSolver terintegrasi dengan SDK Agens OpenAI melalui dekorator @function_tool, memungkinkan agen Anda menyelesaikan tantangan reCAPTCHA v2 dan v3 sebagai bagian dari alur kerja otonomnya.

TL;DR

• SDK Agens OpenAI menggunakan @function_tool untuk mendaftarkan alat yang dapat dipanggil — CapSolver sesuai dengan pola ini secara native
• Fungsi execute_tool() dari capsolver-agent mengemas penyelesaian menjadi panggilan asinkron tunggal yang kompatibel dengan SDK
• Mendukung reCAPTCHA v2 (kotak centang dan tidak terlihat), reCAPTCHA v3 (berbasis skor), dan varian Enterprise
• Mode token tidak memerlukan browser — hanya kunci situs dan URL
• Agen secara otomatis menentukan kapan mengaktifkan penyelesaian CAPTCHA berdasarkan konteks tugas

Mengapa Agens OpenAI Membutuhkan Penyelesaian reCAPTCHA

SDK Agens OpenAI memungkinkan pengembang membangun agen yang mengeksekusi tugas multi-langkah menggunakan alat. Ketika tugas agen melibatkan interaksi web — mengakses data di balik login, mengirim formulir, atau mengumpulkan informasi dari halaman yang dilindungi — tantangan reCAPTCHA menghambat kemajuan. Agen dapat mempertimbangkan apa yang harus dilakukan selanjutnya, tetapi tanpa alat penyelesaian, ia tidak dapat menghasilkan token verifikasi yang diperlukan untuk melanjutkan.

reCAPTCHA sangat umum di situs yang agen butuh akses: portal login, API data dengan pembatasan kecepatan, basis data pemerintah, dan platform SaaS. Dokumentasi reCAPTCHA Google menunjukkan bahwa lebih dari 5 juta situs menggunakan reCAPTCHA secara global, membuatnya menjadi tantangan verifikasi yang paling mungkin dihadapi oleh agen Anda.

Arsitektur CapSolver selaras sempurna dengan desain SDK Agens OpenAI: agen menentukan apa yang dilakukan (termasuk kapan menyelesaikan CAPTCHA), dan CapSolver menangani penyelesaiannya melalui layanan AI-nya. Pemisahan tanggung jawab ini menjaga logika agen tetap bersih sambil menambahkan kemampuan menghilangkan verifikasi.

Apa yang Perlu Anda Siapkan Sebelum Memulai

Instal paket yang diperlukan:

# Mesin inti CapSolver
pip install git+https://github.com/capsolver-ai/capsolver-core.git

# Alat agen CapSolver
pip install git+https://github.com/capsolver-ai/capsolver-agent.git

# SDK Agens OpenAI
pip install openai-agents

Atur variabel lingkungan:

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

Anda membutuhkan akun CapSolver dengan kredit. SDK saat ini mendukung reCAPTCHA v2, reCAPTCHA v3 (termasuk Enterprise), dan Cloudflare Turnstile — menutupi jenis verifikasi yang sering dihadapi agen.

Langkah 1 — Daftarkan Penyelesaian CAPTCHA sebagai Fungsi Alat

Apa yang Harus Dilakukan

SDK Agens OpenAI menggunakan @function_tool untuk mendefinisikan alat yang dapat dipanggil oleh agen. Bungkus executor CapSolver ke dalam pola ini:

from agents import Agent, Runner, function_tool
from capsolver_agent.schema import execute_tool

@function_tool
async def solve_recaptcha(
    website_url: str, 
    website_key: str, 
    captcha_type: str = "reCaptchaV2"
) -> str:
    """Menyelesaikan tantangan reCAPTCHA di situs web dan mengembalikan token verifikasi.
    
    Gunakan alat ini ketika Anda perlu melewati verifikasi reCAPTCHA di halaman web.
    
    Argumen:
        website_url: URL lengkap halaman yang mengandung reCAPTCHA
        website_key: kunci situs reCAPTCHA (ditemukan dalam atribut data-sitekey)
        captcha_type: Baik 'reCaptchaV2' atau 'reCaptchaV3' (default: reCaptchaV2)
    
    Mengembalikan:
        Token reCAPTCHA yang telah diselesaikan untuk dikirim sebagai g-recaptcha-response
    """
    result = await execute_tool("solve_captcha", {
        "captcha_type": captcha_type,
        "website_url": website_url,
        "website_key": website_key
    }, api_key="KUNCI_API_ANDA_CAPSOLVER")
    
    if result["success"]:
        return f"reCAPTCHA diselesaikan. Token: {result['solution']['token']}"
    return f"Penyelesaian gagal: {result['error']}"

Fungsi execute_tool() dari capsolver-agent adalah panggilan asinkron satu kali yang menangani seluruh siklus penyelesaian — membuat tugas, memantau hasil, dan mengembalikan output yang terstruktur. Ini dirancang khusus untuk skenario di mana Anda ingin satu penyelesaian tanpa membangun loop executor penuh.

Mengapa Ini Penting

Dekorator @function_tool SDK Agens OpenAI secara otomatis menghasilkan skema JSON yang diperlukan model untuk memahami parameter alat. Agen melihat deskripsi alat, memahami kapan menggunakannya, dan memanggilnya dengan argumen yang benar — semua melalui mekanisme pemanggilan fungsi yang sudah ada di SDK.

Kesalahan Umum yang Harus Dihindari

• Eksekusi sinkron: SDK Agens OpenAI bersifat asinkron. Selalu gunakan async def untuk fungsi alat dan await untuk panggilan CapSolver.
• Kurangnya petunjuk tipe: SDK menghasilkan skema dari petunjuk tipe. Sertakan anotasi tipe yang tepat untuk semua parameter.

Langkah 2 — Buat Agen dengan Kemampuan Penyelesaian reCAPTCHA

Apa yang Harus Dilakukan

Bangun agen OpenAI yang mencakup alat penyelesaian reCAPTCHA:

from agents import Agent, Runner

# Buat agen dengan kemampuan penyelesaian CAPTCHA
captcha_agent = Agent(
    name="Agen Akses Web",
    instructions="""Anda adalah agen akses web yang membantu pengguna berinteraksi dengan 
    situs web. Ketika tugas memerlukan mengakses halaman yang dilindungi reCAPTCHA, gunakan 
    alat solve_recaptcha untuk mendapatkan token verifikasi. 
    
    Untuk reCAPTCHA v2: gunakan captcha_type='reCaptchaV2'
    Untuk reCAPTCHA v3: gunakan captcha_type='reCaptchaV3'
    
    Selalu berikan website_url dan website_key yang tepat dari permintaan pengguna.""",
    tools=[solve_recaptcha]
)

# Jalankan agen
async def main():
    result = await Runner.run(
        captcha_agent,
        "Saya perlu mengakses https://example.com/login yang memiliki reCAPTCHA v2. "
        "Kunci situsnya adalah 6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI. "
        "Silakan selesaikan dan beri saya tokennya."
    )
    print(result.final_output)

import asyncio
asyncio.run(main())

Agen memproses permintaan, mengenali bahwa penyelesaian reCAPTCHA diperlukan, memanggil alat dengan parameter yang diberikan, dan mengembalikan token ke pengguna.

Mengapa Ini Penting

SDK Agens OpenAI menangani loop percakapan, pengiriman alat, dan integrasi hasil secara otomatis. Anda mendefinisikan alat sekali, dan runtime SDK mengelola kapan dan bagaimana alat tersebut dipanggil. Ini lebih sederhana daripada membangun loop pemanggilan fungsi secara manual.

Langkah 3 — Tangani reCAPTCHA v3 dengan Persyaratan Skor

Apa yang Harus Dilakukan

reCAPTCHA v3 berbasis skor dan tidak terlihat — memerlukan parameter page_action dan mengembalikan token dengan skor terkait. Buat alat khusus:

@function_tool
async def solve_recaptcha_v3(
    website_url: str,
    website_key: str,
    page_action: str = "verify",
    min_score: float = 0.7
) -> str:
    """Menyelesaikan tantangan reCAPTCHA v3 (tidak terlihat, berbasis skor).
    
    Gunakan ini ketika situs menggunakan reCAPTCHA v3 — tidak ada kotak centang terlihat,
    tetapi situs memvalidasi token berbasis skor di latar belakang.
    
    Argumen:
        website_url: URL lengkap halaman
        website_key: kunci situs reCAPTCHA v3
        page_action: nama tindakan untuk skoring (misalnya, 'login', 'submit', 'verify')
        min_score: skor minimal yang diterima (0.0-1.0, default 0.7)
    """
    result = await execute_tool("solve_captcha", {
        "captcha_type": "reCaptchaV3",
        "website_url": website_url,
        "website_key": website_key,
        "page_action": page_action,
        "min_score": min_score
    }, api_key="KUNCI_API_ANDA_CAPSOLVER")
    
    if result["success"]:
        return f"reCAPTCHA v3 diselesaikan dengan skor tinggi. Token: {result['solution']['token']}"
    return f"Penyelesaian gagal: {result['error']}"

Garis panduan penyelesaian reCAPTCHA v3 menjelaskan cara mengidentifikasi parameter page_action yang benar untuk berbagai situs. Tindakan umum termasuk login, submit, homepage, dan verify.

Langkah 4 — Bangun Agen Multi-Alat untuk Alur Kerja Web Lengkap

Apa yang Harus Dilakukan

Gabungkan penyelesaian reCAPTCHA dengan alat lain untuk agen yang melakukan tugas web lengkap:

from agents import Agent, Runner, function_tool

@function_tool
async def solve_recaptcha(website_url: str, website_key: str, captcha_type: str = "reCaptchaV2") -> str:
    """Menyelesaikan reCAPTCHA dan mengembalikan token."""
    result = await execute_tool("solve_captcha", {
        "captcha_type": captcha_type,
        "website_url": website_url,
        "website_key": website_key
    }, api_key="KUNCI_API_ANDA_CAPSOLVER")
    if result["success"]:
        return f"Token: {result['solution']['token']}"
    return f"Gagal: {result['error']}"

@function_tool
async def check_solver_balance() -> str:
    """Memeriksa kredit penyelesaian CAPTCHA yang tersisa."""
    result = await execute_tool("get_balance", {}, api_key="KUNCI_API_ANDA_CAPSOLVER")
    if result["success"]:
        return f"Saldo: ${result['balance']:.2f}"
    return "Tidak dapat memeriksa saldo"

# Agen multi-kemampuan
web_agent = Agent(
    name="Agen Web Otonom",
    instructions="""Anda membantu pengguna mengakses sumber daya web yang mungkin dilindungi oleh 
    reCAPTCHA. Anda dapat menyelesaikan reCAPTCHA v2 (kotak centang terlihat) dan v3 (tidak terlihat 
    berbasis skor). Selalu periksa saldo sebelum menyelesaikan jika pengguna bertanya tentang biaya.
    
    Ketika menyelesaikan reCAPTCHA:
    - v2: Gunakan captcha_type='reCaptchaV2' 
    - v3: Gunakan captcha_type='reCaptchaV3' dan sertakan page_action jika diketahui
    
    Kembalikan token secara jelas sehingga pengguna dapat mengirimkannya dengan formulir mereka.""",
    tools=[solve_recaptcha, check_solver_balance]
)

async def run_web_agent(task: str):
    result = await Runner.run(web_agent, task)
    return result.final_output

Pola ini berfungsi untuk agen yang perlu menangani versi reCAPTCHA yang berbeda di berbagai situs dalam sesi yang sama.

Dapatkan Kode Bonus Anda: Gunakan kode WEBS di Dasbor CapSolver untuk mendapatkan bonus tambahan 5% pada setiap recharge. Ideal untuk pengembang yang membangun Agens OpenAI dengan kemampuan akses web.

Langkah 5 — Pertimbangan Penyelesaian Produksi

Untuk Agens OpenAI produksi dengan penyelesaian reCAPTCHA:

import os
from agents import Agent, Runner, function_tool
from capsolver_agent.schema import create_executor

# Executor produksi dengan pengaturan kustom
executor = create_executor(
    api_key=os.environ["CAPSOLVER_API_KEY"],
    default_timeout=90,      # timeout 90 detik
    polling_interval=3       # polling setiap 3 detik
)

@function_tool
async def solve_recaptcha_production(
    website_url: str,
    website_key: str,
    captcha_type: str = "reCaptchaV2"
) -> str:
    """Penyelesaian reCAPTCHA dengan logika ulang untuk produksi."""
    for attempt in range(3):
        result = await executor.execute("solve_captcha", {
            "captcha_type": captcha_type,
            "website_url": website_url,
            "website_key": website_key
        })
        if result["success"]:
            return f"Selesai (cobaan {attempt+1}). Token: {result['solution']['token']}"
        if attempt < 2:
            await asyncio.sleep(2)
    return f"Gagal setelah 3 kali: {result.get('error')}"

Pertimbangan produksi kunci:

• Konfigurasi timeout: Atur default_timeout berdasarkan kebutuhan waktu respons agen Anda
• Logika ulang: Masalah jaringan dan kegagalan sementara seharusnya memicu ulang, bukan kegagalan langsung
• Pemantauan saldo: Periksa saldo secara berkala untuk menghindari kegagalan tugas karena kredit tidak cukup
• Pelaporan kesalahan: Kembalikan pesan kesalahan yang jelas sehingga agen dapat mempertimbangkan pendekatan alternatif

Dokumentasi API CapSolver menutupi opsi konfigurasi tambahan untuk mengoptimalkan waktu penyelesaian di lingkungan produksi. Untuk mengidentifikasi parameter reCAPTCHA di situs target, ekstensi browser CapSolver menyediakan deteksi otomatis.

Kesimpulan

Mengintegrasikan penyelesaian reCAPTCHA ke dalam SDK Agens OpenAI memerlukan mendefinisikan @function_tool yang membungkus fungsi execute_tool() dari CapSolver, lalu menugaskannya ke agen Anda. Runtime SDK menangani pengiriman alat secara otomatis — agen menentukan kapan penyelesaian reCAPTCHA diperlukan dan memanggil alat dengan parameter yang sesuai. CapSolver menyediakan infrastruktur penyelesaian berbasis AI yang menghasilkan token valid untuk reCAPTCHA v2, v3, dan varian Enterprise.

Mulailah dengan alat solve_recaptcha tunggal, uji dengan agen Anda di target yang diketahui, lalu tambahkan dukungan v3 dan logika ulang produksi. Arsitektur asinkron SDK Agens OpenAI selaras secara alami dengan API asinkron CapSolver, membuat integrasi bersih dan efisien.

FAQ

Apakah SDK Agens OpenAI mendukung penyelesaian CAPTCHA asinkron?

Ya. SDK sepenuhnya asinkron, dan execute_tool() CapSolver adalah fungsi asinkron. Dekorator @function_tool mendukung fungsi async def secara native, sehingga penyelesaian CAPTCHA berjalan tanpa menghentikan loop acara agen.

Dapatkah agen menyelesaikan reCAPTCHA Enterprise dengan integrasi ini?

Ya. Kirimkan enterprise: true dalam parameter. reCAPTCHA Enterprise menggunakan tipe tugas yang sama dengan v2/v3 tetapi mungkin memerlukan parameter s token. CapSolver menangani varian Enterprise secara transparan melalui API yang sama.

Bagaimana agen mengetahui versi reCAPTCHA yang digunakan situs?

Sertakan panduan dalam instruksi agen tentang mengidentifikasi v2 vs v3. Alternatifnya, berikan jenis CAPTCHA dalam prompt tugas. Panduan identifikasi reCAPTCHA menjelaskan perbedaannya: v2 menampilkan widget terlihat, sementara v3 dimuat secara tidak terlihat melalui tag skrip.

Berapa biaya per penyelesaian reCAPTCHA?

reCAPTCHA v2 biayanya sekitar 2-3 per 1.000 penyelesaian, dan reCAPTCHA v3 biayanya 1-2 per 1.000. Untuk agen yang menyelesaikan 10 reCAPTCHA per sesi, biayanya sekitar $0,02-0,03 per sesi — sangat kecil dibandingkan nilai tugas yang diselesaikan secara otonom.

Dapatkah saya menggunakan ini dengan fitur handoff SDK Agens OpenAI?

Ya. Anda dapat membuat "agen penyelesaian CAPTCHA" khusus dan handoff kepadanya ketika agen utama menemui tantangan verifikasi. Agen penyelesaian menyelesaikan CAPTCHA dan mengembalikan ke agen utama dengan token. Ini menjaga tanggung jawab agen tetap terpisah dengan jelas.