Cara Menyelesaikan CAPTCHA dengan TinyFish AgentQL – Panduan Langkah demi Langkah Menggunakan CapSolver

Ketika otomatisasi web berbasis AI Anda menghadapi dinding CAPTCHA, seluruh pipeline terhenti. Halaman tidak dapat dimuat, formulir tidak dapat dikirim, dan ekstraksi data berhenti total — semua karena tantangan yang dirancang untuk menghalangi bot. TinyFish AgentQL adalah kumpulan alat yang kuat untuk menghubungkan AI ke web, yang mencakup query berbahasa alami, integrasi Playwright, dan ekstraksi data terstruktur dalam skala perusahaan. Namun, seperti kerangka otomatisasi browser lainnya, ia terjebak pada CAPTCHA.

CapSolver mengubah ini sepenuhnya. Dengan memuat ekstensi CapSolver Chrome ke dalam konteks browser Playwright AgentQL, CAPTCHA diselesaikan secara otomatis dan tidak terlihat di latar belakang. Tidak ada penyelesaian manual. Tidak ada orkestrasi API kompleks di sisi Anda. Skrip otomatisasi Anda terus berjalan seolah CAPTCHA tidak pernah ada.

Bagian terbaiknya? Query dan skrip AgentQL Anda tidak perlu baris pun kode terkait CAPTCHA. Ekstensi menangani deteksi, penyelesaian, dan injeksi token sepenuhnya sendiri sementara agen Anda fokus pada apa yang dilakukannya dengan baik — mengekstrak data dan mengotomasi alur kerja.

Apa itu TinyFish AgentQL?

TinyFish AgentQL adalah alat toolkit berbasis perusahaan untuk menghubungkan agen AI dan LLM ke lingkungan web langsung. Dikembangkan oleh TinyFish, ini menyediakan bahasa query yang didukung AI yang memungkinkan Anda menemukan elemen halaman dan mengekstrak data terstruktur menggunakan bahasa alami — tanpa memerlukan selektor CSS atau XPaths yang rapuh.

Fitur Utama

• Bahasa Query yang Didukung AI: Temukan elemen secara intuitif berdasarkan konten halaman. Query akan pulih sendiri seiring perubahan UI.
• Integrasi Playwright: SDK Python dan JavaScript terintegrasi secara mulus dengan Playwright untuk otomatisasi browser lanjutan.
• Ekstraksi Data Terstruktur: Tetapkan bentuk output dan dapatkan data bersih yang terstruktur dari halaman mana pun — publik atau pribadi, statis atau dinamis.
• REST API: Jalankan query tanpa SDK melalui endpoint REST.
• Browser Debugger: Ekstensi Chrome untuk menguji dan menyempurnakan query secara real-time.
• Ketahanan Silang Situs: Bekerja di berbagai situs yang mirip tanpa modifikasi, menyesuaikan secara dinamis terhadap perubahan halaman.
• Skala Perusahaan: Dirancang untuk beban kerja tinggi, menjalankan ratusan tugas secara paralel.

AgentQL beroperasi di halaman mana pun — termasuk konten yang diotentikasi dan halaman yang dihasilkan secara dinamis — membuatnya ideal untuk otomatisasi web skala besar, pengumpulan data, dan alur kerja agen AI.

Apa itu CapSolver?

CapSolver adalah layanan penyelesaian CAPTCHA berbasis AI yang secara otomatis menyelesaikan berbagai tantangan CAPTCHA. Dengan respons cepat dan kompatibilitas luas, CapSolver terintegrasi secara mulus ke dalam alur kerja otomatis.

Jenis CAPTCHA yang Didukung

• reCAPTCHA v2 (checkbox dan invisible)
• reCAPTCHA v3 & v3 Enterprise
• Cloudflare Turnstile
• Cloudflare 5-second Challenge
• AWS WAF CAPTCHA
• Lainnya

Mengapa Integrasi Ini Berbeda

Sebagian besar integrasi penyelesaian CAPTCHA memerlukan Anda menulis kode boilerplate: membuat tugas, memantau hasil, dan menyisipkan token ke bidang tersembunyi. Itu adalah pendekatan standar dengan skrip Playwright atau Puppeteer.

AgentQL + CapSolver mengambil pendekatan yang secara fundamental berbeda:

Insight utama: Ekstensi CapSolver berjalan di dalam konteks browser Playwright AgentQL. Ketika AgentQL mengunjungi halaman dengan CAPTCHA, ekstensi mendeteksinya, menyelesaikannya di latar belakang, dan menyisipkan token — semua sebelum skrip Anda berinteraksi dengan formulir. Kode otomatisasi Anda tetap bersih, fokus, dan bebas CAPTCHA.

Prasyarat

Sebelum mengatur integrasi, pastikan Anda memiliki:

• TinyFish AgentQL terinstal (SDK Python atau JavaScript)
• Akun CapSolver dengan kunci API (daftar di sini)
• Node.js 16+ dan Python 3.8+ (tergantung pada pilihan SDK Anda)
• Playwright terinstal dengan Chromium

Penting: Ekstensi Chrome hanya berfungsi di Chromium dengan konteks persisten dalam Playwright. Ini adalah persyaratan Playwright, bukan keterbatasan AgentQL.

Pengaturan Langkah demi Langkah

Langkah 1: Instal AgentQL

SDK Python:

pip install agentql
playwright install chromium

SDK JavaScript:

npm install agentql
npx playwright install chromium

Langkah 2: Unduh Ekstensi CapSolver Chrome

Unduh ekstensi CapSolver Chrome dan ekstrak ke direktori khusus:

1. Kunjungi CapSolver Chrome Extension v1.17.0 release
2. Unduh CapSolver.Browser.Extension-chrome-v1.17.0.zip
3. Ekstrak zip:

mkdir -p ~/capsolver-extension
unzip CapSolver.Browser.Extension-chrome-v*.zip -d ~/capsolver-extension/

4. Verifikasi ekstraksi berhasil:

ls ~/capsolver-extension/manifest.json

Anda harus melihat manifest.json — ini memastikan ekstensi berada di tempat yang benar.

Langkah 3: Konfigurasikan Kunci API CapSolver Anda

Buka file konfigurasi ekstensi di ~/capsolver-extension/assets/config.js dan ganti nilai apiKey dengan milik Anda:

export const defaultConfig = {
  apiKey: 'CAP-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX', // ← ganti dengan kunci Anda
  useCapsolver: true,
  // ... sisa konfigurasi
};

Anda dapat mendapatkan kunci API dari dashboard CapSolver.

Langkah 4: Jalankan AgentQL dengan Ekstensi CapSolver

Langkah kritis adalah menjalankan Chromium Playwright dengan konteks persisten yang memuat ekstensi CapSolver.

Contoh Python:

import agentql
from playwright.sync_api import sync_playwright
import time
import os

# Jalur ke ekstensi CapSolver
CAPSOLVER_EXTENSION_PATH = os.path.expanduser("~/capsolver-extension")

def main():
    with sync_playwright() as p:
        # Jalankan Chromium dengan konteks persisten dan ekstensi CapSolver
        context = p.chromium.launch_persistent_context(
            user_data_dir="./browser-data",
            headless=False,  # Ekstensi memerlukan mode headless
            args=[
                f"--disable-extensions-except={CAPSOLVER_EXTENSION_PATH}",
                f"--load-extension={CAPSOLVER_EXTENSION_PATH}",
            ],
        )

        # Wrap halaman dengan AgentQL untuk query berbasis AI
        page = agentql.wrap(context.pages[0])

        # Navigasi ke halaman target
        page.goto("https://example.com/protected-page")

        # Tunggu CapSolver mendeteksi dan menyelesaikan CAPTCHA
        time.sleep(30)

        # Cari dan klik tombol submit menggunakan query berbahasa alami AgentQL
        response = page.query_elements("""
        {
            submit_button
        }
        """)

        # Klik tombol submit — CAPTCHA sudah diselesaikan!
        response.submit_button.click()

        # Ekstrak data setelah pengiriman
        result = page.query_data("""
        {
            confirmation_message
        }
        """)

        print(f"Hasil: {result['confirmation_message']}")

        context.close()

if __name__ == "__main__":
    main()

Contoh JavaScript:

const { chromium } = require('playwright');
const agentql = require('agentql');
const path = require('path');
const os = require('os');

const CAPSOLVER_EXTENSION_PATH = path.join(os.homedir(), 'capsolver-extension');

(async () => {
  // Jalankan Chromium dengan konteks persisten dan ekstensi CapSolver
  const context = await chromium.launchPersistentContext('./browser-data', {
    headless: false, // Ekstensi memerlukan mode headless
    args: [
      `--disable-extensions-except=${CAPSOLVER_EXTENSION_PATH}`,
      `--load-extension=${CAPSOLVER_EXTENSION_PATH}`,
    ],
  });

  // Dapatkan halaman pertama dan wrap dengan AgentQL
  const page = agentql.wrap(context.pages()[0]);

  // Navigasi ke halaman target
  await page.goto('https://example.com/protected-page');

  // Tunggu CapSolver menangani CAPTCHA
  await page.waitForTimeout(30000);

  // Gunakan query AgentQL untuk berinteraksi — CAPTCHA sudah diselesaikan
  const response = await page.queryElements(`{
    submit_button
  }`);

  await response.submit_button.click();

  // Ekstrak data hasil
  const result = await page.queryData(`{
    confirmation_message
  }`);

  console.log('Hasil:', result.confirmation_message);

  await context.close();
})();

Langkah 5: Verifikasi Ekstensi Dimuat

Setelah menjalankan browser, Anda dapat memverifikasi bahwa ekstensi CapSolver aktif dengan mengunjungi chrome://extensions di jendela browser. Anda harus melihat ekstensi CapSolver terdaftar dan diaktifkan.

Alternatifnya, periksa konsol browser untuk pesan log CapSolver yang menunjukkan layanan worker sedang berjalan.

Cara Menggunakannya

Setelah setup selesai, menggunakan CapSolver dengan AgentQL sangat sederhana.

Aturan Emas

Jangan tulis kode khusus CAPTCHA. Tambahkan waktu tunggu sebelum berinteraksi dengan formulir yang dilindungi CAPTCHA, dan biarkan ekstensi melakukan pekerjaannya.

Contoh 1: Pengiriman Form di Belakang reCAPTCHA

page.goto("https://example.com/contact")

# Isi formulir menggunakan query AgentQL
response = page.query_elements("""
{
    contact_form {
        name_field
        email_field
        message_field
        submit_button
    }
}
""")

response.contact_form.name_field.fill("John Doe")
response.contact_form.email_field.fill("john@example.com")
response.contact_form.message_field.fill("Hello, I have a question about your services.")

# Tunggu CapSolver menyelesaikan CAPTCHA
time.sleep(30)

# Kirim — token CAPTCHA sudah diinjeksikan
response.contact_form.submit_button.click()

Contoh 2: Halaman Login dengan Cloudflare Turnstile

page.goto("https://example.com/login")

# Tunggu CapSolver menyelesaikan tantangan Turnstile
time.sleep(25)

# Temukan elemen formulir login dengan AgentQL
response = page.query_elements("""
{
    login_form {
        email_input
        password_input
        login_button
    }
}
""")

# Isi formulir — Turnstile sudah ditangani
response.login_form.email_input.fill("me@example.com")
response.login_form.password_input.fill("mypassword123")

# Klik login
response.login_form.login_button.click()

Contoh 3: Ekstraksi Data dari Halaman yang Dilindungi

page.goto("https://example.com/data")

# Tunggu CAPTCHA selesai
time.sleep(30)

# Ekstrak data terstruktur dengan AgentQL
data = page.query_data("""
{
    products[] {
        name
        price
        rating
        availability
    }
}
""")

for product in data['products']:
    print(f"{product['name']}: ${product['price']} ({product['rating']} bintang)")

Waktu Tunggu yang Direkomendasikan

Tips: Jika ragu, gunakan 30 detik. Lebih baik menunggu sedikit lebih lama daripada mengirim terlalu dini. Waktu tambahan tidak memengaruhi hasil.

Cara Kerja di Balik Layar

Berikut yang terjadi ketika AgentQL berjalan dengan ekstensi CapSolver yang dimuat:

Skrip AgentQL Anda
───────────────────────────────────────────────────
page.goto("https://...")       ──► Chromium memuat halaman
                                           │
                                           ▼
                               ┌─────────────────────────────┐
                               │  Halaman dengan widget CAPTCHA     │
                               │                               │
                               │  Ekstensi CapSolver:         │
                               │  1. Skrip konten mendeteksi    │
                               │     CAPTCHA di halaman        │
                               │  2. Layanan worker memanggil   │
                               │     API CapSolver             │
                               │  3. Token diterima            │
                               │  4. Token diinjeksikan ke     │
                               │     bidang formulir tersembunyi │
                               └─────────────────────────────┘
                                           │
                                           ▼
time.sleep(30)                   Ekstensi menyelesaikan CAPTCHA...
                                           │
                                           ▼
page.query_elements(...)         AgentQL menemukan elemen formulir
submit_button.click()            Form dikirim DENGAN token valid
                                           │
                                           ▼
                               "Verifikasi berhasil!"

Cara Ekstensi Dimuat

Ketika Playwright menjalankan Chromium dengan flag --load-extension:

1. Chromium dimulai dengan ekstensi CapSolver yang dimuat
2. Ekstensi aktif — service worker mulai berjalan dan skrip konten menyuntikkan ke setiap halaman
3. Di halaman dengan CAPTCHA — skrip konten mendeteksi widget, memanggil API CapSolver, dan menyisipkan token solusi ke halaman
4. AgentQL beroperasi normal — query, klik, dan ekstraksi data bekerja seperti biasa, dengan CAPTCHA sudah ditangani

Referensi Konfigurasi Lengkap

Berikut setup Python lengkap dengan semua opsi konfigurasi untuk integrasi AgentQL + CapSolver:

import agentql
from playwright.sync_api import sync_playwright
import os

# Konfigurasi
CAPSOLVER_EXTENSION_PATH = os.path.expanduser("~/capsolver-extension")
USER_DATA_DIR = "./browser-data"

with sync_playwright() as p:
    context = p.chromium.launch_persistent_context(
        user_data_dir=USER_DATA_DIR,
        headless=False,
        args=[
            f"--disable-extensions-except={CAPSOLVER_EXTENSION_PATH}",
            f"--load-extension={CAPSOLVER_EXTENSION_PATH}",
        ],
    )
    page = agentql.wrap(context.pages[0])
    # ... kode otomatisasi Anda di sini
    context.close()

Opsi Konfigurasi

Kunci API CapSolver dikonfigurasi langsung di file assets/config.js ekstensi (lihat Langkah 3 di atas).

Troubleshooting

Ekstensi Tidak Dimuat

Gejala: CAPTCHAs tidak diselesaikan secara otomatis.

Penyebab: Anda mungkin menggunakan konteks browser biasa alih-alih konteks persisten, atau menjalankan dalam mode headless.

Solusi: Ekstensi dalam Playwright memerlukan konteks persisten dan mode berbasis tampilan:

# ✅ Benar — konteks persisten, berbasis tampilan
context = p.chromium.launch_persistent_context(
    user_data_dir="./browser-data",
    headless=False,
    args=[...arg ekstensi...]
)

# ❌ Salah — konteks biasa (ekstensi tidak akan dimuat)
browser = p.chromium.launch()
context = browser.new_context()

CAPTCHA Tidak Diselesaikan (Form Gagal)

Kemungkinan penyebab:

• Waktu tunggu yang tidak cukup — Tingkatkan menjadi 60 detik
• Kunci API tidak valid — Periksa dashboard CapSolver Anda
• Saldo tidak cukup — Isi ulang akun CapSolver Anda
• Ekstensi tidak dimuat — Lihat "Ekstensi Tidak Dimuat" di atas

Mode Headless Tidak Didukung

Gejala: Skrip berjalan tetapi ekstensi tidak muncul.

Penyebab: Ekstensi Chrome tidak berjalan dalam mode headless.

Solusi: Gunakan mode berbasis tampilan dengan layar virtual di server:

# Instal Xvfb
sudo apt-get install xvfb

# Mulai layar virtual
Xvfb :99 -screen 0 1280x720x24 &

# Atur DISPLAY
export DISPLAY=:99

Kompatibilitas Google Chrome 137+

Gejala: Bendera ekstensi diabaikan.

Penyebab: Google Chrome 137+ menghapus dukungan untuk --load-extension dalam build bermerk.

Solusi: Gunakan Chromium Playwright (direkomendasikan) atau Chrome for Testing:

# Instal Chromium Playwright (direkomendasikan)
npx playwright install chromium

# Atau unduh Chrome for Testing
# Kunjungi: https://googlechromelabs.github.io/chrome-for-testing/

Praktik Terbaik

1. Selalu gunakan waktu tunggu yang cukup. Waktu tunggu yang lebih lama selalu lebih aman. CAPTCHA biasanya diselesaikan dalam 5-20 detik, tetapi latensi jaringan, tantangan kompleks, atau ulangan dapat menambah waktu. 30-60 detik adalah titik optimal.

2. Jaga skrip otomasi Anda tetap bersih. Jangan tambahkan logika khusus CAPTCHA ke dalam query AgentQL Anda. Ekstensi menangani semuanya — kode Anda harus fokus hanya pada ekstraksi data dan interaksi.

3. Pantau saldo CapSolver Anda. Setiap penyelesaian CAPTCHA memakan kredit. Periksa saldo Anda di capsolver.com/dashboard secara teratur untuk menghindari gangguan.

4. Gunakan konteks persisten secara konsisten. Selalu mulai dengan launch_persistent_context() ketika Anda membutuhkan ekstensi. Ini juga mempertahankan cookie dan data sesi antar eksekusi, yang dapat mengurangi frekuensi CAPTCHA.

5. Gunakan Xvfb di server headless. Ekstensi Chrome memerlukan konteks tampilan. Atur Xvfb untuk lingkungan server di mana tidak ada layar fisik yang tersedia.

Kesimpulan

Integrasi TinyFish AgentQL + CapSolver membawa penyelesaian CAPTCHA yang tidak terlihat ke salah satu toolkit otomasi web paling kuat yang tersedia. Alih-alih menulis kode penanganan CAPTCHA yang kompleks, Anda hanya perlu:

1. Unduh ekstensi CapSolver dan konfigurasikan kunci API Anda
2. Jalankan browser AgentQL Playwright dengan ekstensi yang dimuat melalui konteks persisten
3. Tulis skrip otomasi Anda seperti biasa — tambahkan waktu tunggu sebelum mengirim formulir

Ekstensi CapSolver menangani sisanya — mendeteksi CAPTCHA, menyelesaikannya melalui API CapSolver, dan menyisipkan token ke halaman. Skrip AgentQL Anda tidak pernah perlu tahu tentang CAPTCHA sama sekali.

Ini adalah bentuk penyelesaian CAPTCHA ketika Anda menggabungkan otomasi web berbasis AI dengan penyelesaian CAPTCHA berbasis AI: tidak terlihat, otomatis, dan bebas kode.

Siap memulai? Daftar di CapSolver dan gunakan kode bonus AGENTQL untuk mendapatkan tambahan 6% pada top-up pertama Anda!

FAQ

Apakah saya perlu menulis kode khusus CAPTCHA di skrip AgentQL saya?

Tidak. Ekstensi CapSolver bekerja sepenuhnya di latar belakang dalam konteks browser Playwright. Tambahkan time.sleep() atau waitForTimeout() sebelum mengirim formulir, dan ekstensi menangani deteksi, penyelesaian, dan penyisipan token secara otomatis.

Mengapa saya membutuhkan konteks persisten?

Playwright hanya mendukung ekstensi Chrome ketika menggunakan launch_persistent_context(). Ini adalah persyaratan arsitektur Playwright. Konteks browser biasa yang dibuat melalui browser.new_context() tidak dapat memuat ekstensi.

Apakah saya bisa menjalankan ini dalam mode headless?

Tidak. Ekstensi Chrome memerlukan browser berbasis tampilan. Untuk lingkungan server tanpa layar, gunakan Xvfb (X Virtual Framebuffer) untuk membuat layar virtual.

Jenis CAPTCHA apa yang didukung CapSolver?

CapSolver mendukung reCAPTCHA v2 (checkbox dan invisible), reCAPTCHA v3, Cloudflare Turnstile, AWS WAF CAPTCHA, dan lainnya. Ekstensi secara otomatis mendeteksi jenis CAPTCHA dan menyelesaikannya sesuai.

Berapa biaya CapSolver?

CapSolver menawarkan harga kompetitif berdasarkan jenis CAPTCHA dan volume. Kunjungi capsolver.com untuk harga terkini.

Apakah TinyFish AgentQL gratis?

AgentQL menawarkan tier gratis dan berbayar. SDK dan bahasa query tersedia untuk pengembangan dan pengujian. Kunjungi tinyfish.ai untuk detail harga.

Berapa lama saya harus menunggu untuk CAPTCHA diselesaikan?

Untuk kebanyakan CAPTCHA, 30-60 detik sudah cukup. Waktu penyelesaian sebenarnya biasanya 5-20 detik, tetapi menambahkan buffer ekstra memastikan keandalan. Jika ragu, gunakan 30 detik.