Cara Menambahkan Alat Deteksi CAPTCHA ke Haystack Agents

TL;DR

• Sebuah tool Haystack dapat memanggil CapSolver Core SDK resmi untuk memeriksa parameter CAPTCHA pada halaman browser yang sudah terbuka.
• Ikat tool ke halaman yang sudah dikendalikan oleh aplikasi Anda, bukan membiarkan agen menavigasi ke URL sembarang lewat tool inspeksi.
• Contoh yang dapat dijalankan mengembalikan jenis CAPTCHA, URL halaman, dan public site key dari halaman lokal yang menggunakan widget uji reCAPTCHA v2 milik Google.
• Ini adalah integrasi Python native: tidak memerlukan server MCP atau transport apa pun.
• Deteksi tidak membuat task solver, tidak mengembalikan token, dan tidak membuktikan bahwa aplikasi telah menerima verifikasi.

Agen berbasis browser memerlukan informasi yang berguna ketika CAPTCHA mengganggu pekerjaannya. Judul halaman atau screenshot saja mungkin tidak memberi tahu agen keluarga CAPTCHA apa yang ada ataupun parameter apa yang dibutuhkan langkah berikutnya. Mengembalikan hasil terstruktur kecil memberi aplikasi titik keputusan yang jelas sebelum meminta solusi.

Haystack adalah framework Python untuk membangun aplikasi AI, pipeline retrieval, dan agen. Tool bawaannya dapat membungkus fungsi-fungsi yang digunakan aplikasi tersebut. Panduan ini menghubungkan tool Haystack dengan CapSolver untuk tugas spesifik: memeriksa halaman browser saat ini dan mengembalikan parameter CAPTCHA. Contohnya menggunakan halaman pengembangan dan tidak membuat permintaan solving berbayar. Ini memberi Anda komponen inspeksi yang siap pakai untuk ditempatkan sebelum langkah solving yang diotorisasi secara terpisah.

Posisi tool CAPTCHA dalam workflow Haystack

Tool inspeksi CAPTCHA berada di antara aksi browser yang mencapai checkpoint verifikasi dan kode yang memutuskan bagaimana menangani checkpoint tersebut. Browser tetap memegang kendali navigasi dan halaman saat ini. Haystack menyediakan antarmuka tool; Core SDK membaca informasi CAPTCHA yang didukung.

Sebagai contoh, sebuah tim yang menguji form miliknya sendiri dapat membiarkan browser mencapai form tersebut, memanggil tool inspeksi, dan memeriksa jenis dan site key yang dikembalikan. Harness pengujian kemudian dapat memilih jalur test-key yang disetujui atau pemeriksaan solver yang dikonfigurasi terpisah. Form CAPTCHA itu sendiri sebaiknya tidak diperlakukan sebagai konten bisnis dari form tersebut.

Ini adalah integrasi pengembang menggunakan abstraksi Tool terdokumentasi milik Haystack, bukan klaim adanya plugin Haystack khusus. Tool ini memiliki tujuan sempit dan tidak memerlukan LLM untuk berjalan. Memanggilnya secara langsung berguna sebelum menambahkan pemilihan tool yang digerakkan model.

Prasyarat sebelum menjalankan contoh

Anda memerlukan Python, paket Haystack, CapSolver Core SDK dengan dependensi Playwright, serta Chromium yang terpasang untuk Playwright. Contoh di bawah dijalankan dengan Python 3.12, haystack-ai 3.4.0, capsolver-core 0.1.1, dan Playwright 1.64.0. Ini adalah versi yang telah diuji, bukan klaim bahwa mereka adalah rilis terbaru.

Browser harus dapat memuat skrip reCAPTCHA publik milik Google. Halaman lokal menggunakan site key pengembangan yang didokumentasikan Google; ini bukan key produksi dan tidak boleh digunakan sebagai key produksi. Panduan pengujian reCAPTCHA Google menjelaskan perbedaan antara test key dan verifikasi produksi.

Tidak diperlukan CapSolver API key ataupun key penyedia model untuk contoh inspeksi saja ini. Operasi solving di tahap selanjutnya memerlukan CapSolver account key yang valid. Haystack Agent berbasis LLM di tahap berikutnya memerlukan penyedia model yang dikonfigurasi sendiri. Itu adalah prasyarat terpisah, jadi jangan memecahkan masalah kredensial model yang hilang dengan mengubah parameter CAPTCHA.

Instal paket yang telah diuji

Buat virtual environment dan instal paket-paket tersebut di environment itu. Jalankan instalasi Chromium melalui interpreter Python yang sama agar dependensi browser selaras dengan Playwright.

python3 -m venv .venv
.venv/bin/python -m pip install "haystack-ai==3.4.0" "capsolver-core[playwright]==0.1.1" "playwright==1.64.0"
.venv/bin/python -m playwright install chromium

Perintah di atas menggunakan path environment bergaya POSIX. Jika sistem operasi Anda menggunakan layout virtual-environment yang berbeda, gunakan executable Python milik environment tersebut. Panduan instalasi Playwright untuk Python membahas kebutuhan instalasi browser-nya.

Membuat tool yang memeriksa halaman saat ini

Tool ini membungkus get_captcha_info(page) dari Core SDK resmi. Objek page ditangkap oleh fungsi tersebut, sehingga tool tidak memiliki argumen navigasi. Skema parameter JSON-nya tidak menerima field input apa pun.

Simpan kode berikut sebagai haystack_captcha_inspection.py. Respons HTML lokal disuplai oleh routing Playwright; ini adalah fixture pengembangan, bukan aplikasi yang di-host secara remote. Skrip reCAPTCHA sendiri dimuat dari Google. Program membaca parameter tanpa mengklik widget atau mengirim form.

import asyncio
import json

from capsolver_core import create_capsolver
from haystack.tools import Tool
from playwright.async_api import async_playwright

TEST_PAGE = """<!doctype html><html><body>
<div id="captcha" class="g-recaptcha"
     data-sitekey="6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI"></div>
<script src="https://www.google.com/recaptcha/api.js" async defer></script>
</body></html>"""


async def main():
    async with async_playwright() as pw:
        browser = await pw.chromium.launch()
        try:
            page = await browser.new_page()
            await page.route("http://127.0.0.1:8765/", lambda route: route.fulfill(
                status=200, content_type="text/html", body=TEST_PAGE))
            await page.goto("http://127.0.0.1:8765/")
            await page.wait_for_function(
                "() => window.___grecaptcha_cfg && "
                "Object.keys(window.___grecaptcha_cfg.clients || {}).length > 0")
            async with create_capsolver() as cap:
                async def inspect_captcha():
                    infos = await cap.get_captcha_info(page)
                    return {"captchas": [
                        {"type": info.type.value,
                         "website_url": info.website_url,
                         "website_key": info.website_key}
                        for info in infos
                    ]}

                captcha_tool = Tool(
                    name="inspect_current_page_captcha",
                    description="Read CAPTCHA types and public parameters from the current approved page; does not solve or submit.",
                    parameters={"type": "object", "properties": {},
                                "additionalProperties": False},
                    async_function=inspect_captcha,
                )
                result = await captcha_tool.invoke_async()
                print(json.dumps(result, indent=2))
        finally:
            await browser.close()


if __name__ == "__main__":
    asyncio.run(main())

Argumen async_function penting karena operasi SDK dan Playwright bersifat asinkron. Referensi API Tool Haystack mendokumentasikan invoke_async() untuk jalur ini. Menempatkan coroutine ke jalur pemanggilan yang hanya sinkron dapat gagal sebelum inspeksi CAPTCHA apa pun terjadi.

Context manager dan blok finally menutup resource SDK dan browser. Pertahankan pembersihan ini saat mengadaptasi contoh ke aplikasi yang berjalan lebih lama; jika tidak, kegagalan pemuatan halaman dapat meninggalkan proses browser tertinggal.

Tukarkan Kode Bonus CapSolver Anda

Tingkatkan anggaran otomatisasi Anda seketika!
Gunakan kode bonus CAP26 saat mengisi saldo akun CapSolver untuk mendapatkan bonus 5% ekstra di setiap pengisian — tanpa batas.
Tukarkan sekarang di CapSolver Dashboard

Menjalankan inspeksi dan memahami hasilnya

Menjalankan skrip akan memanggil Tool Haystack secara langsung dan mencetak dictionary yang dikembalikannya. Dalam contoh ini, dictionary tersebut berisi list captchas dengan satu entri reCAPTCHA v2.

.venv/bin/python haystack_captcha_inspection.py

Hasil run lokal mengembalikan type bernilai reCaptchaV2, website_url bernilai http://127.0.0.1:8765/, dan public test site key yang dikonfigurasi di HTML. Field-field ini dibaca melalui SDK dan browser nyata, bukan diisi ke respons tool yang dimock.

Hasilnya sengaja dibuat kecil. Descriptor lengkap SDK dapat menyertakan field tambahan, tetapi agen sebaiknya hanya menerima apa yang dibutuhkan untuk keputusan berikutnya. Site key adalah pengenal widget publik; ini bukan CapSolver account key ataupun secret verifikasi privat milik situs.

Run ini menegaskan bahwa Haystack dapat memanggil fungsi async, browser dapat memuat widget pengembangan, dan Core SDK dapat membaca parameternya. Ini tidak menegaskan pemilihan tool berbasis model, deteksi CAPTCHA produksi di setiap situs, keberhasilan pembuatan token, atau penerimaan oleh backend situs web. Hal-hal tersebut memerlukan pemeriksaan tersendiri bersama aplikasi sebenarnya.

Mengaitkan halaman yang diperiksa ke agen yang sudah ada

Pertahankan objek Tool dan binding page yang sama saat menambahkan kapabilitas ini ke Haystack Agent Anda. Agent Haystack menerima tools melalui konfigurasi tools yang terdokumentasi. Daftarkan objek ini berdampingan dengan tools yang sudah digunakan aplikasi Anda, sambil menjaga halaman browser tetap hidup selama pemanggilan.

Dalam workflow browser yang sudah ada, ganti setup fixture lokal dengan halaman yang sudah dibuka dan diotorisasi untuk diperiksa oleh aplikasi Anda. Pertahankan navigasi browser di luar tool ini. Hal tersebut membuat pemilihan halaman menjadi eksplisit dan mencegah URL yang dihasilkan model diam-diam mengubah target inspeksi.

Beri nama dan deskripsikan tool secara akurat. Deskripsi dalam contoh menyatakan bahwa tool membaca informasi CAPTCHA dan tidak melakukan solving atau submit. Deskripsi seperti “selesaikan verifikasi” akan menjanjikan lebih dari yang dilakukan fungsi tersebut dan dapat mendorong agen untuk melaporkan keberhasilan terlalu dini.

Keputusan aplikasi yang berguna adalah: jika hasil berisi widget yang dikenali dengan parameter yang diperlukan, tawarkan langkah berikut yang sesuai; jika kosong atau tidak lengkap, kumpulkan bukti lebih lanjut atau minta tinjauan manusia. Jangan menambahkan loop tanpa syarat yang terus memeriksa halaman tidak lengkap yang sama.

Pisahkan langkah deteksi dan solving

Hasil inspeksi adalah input untuk keputusan solver, bukan solusi CAPTCHA. Core SDK mendokumentasikan solve(info) untuk solving token dan solve_on_page(page) untuk workflow browser yang lebih luas. Keduanya memiliki efek berbeda dari get_captcha_info(page) dan memerlukan konfigurasi serta otorisasi terpisah.

Untuk panduan ini, pertahankan tool inspeksi hanya-baca. Jika nanti Anda menambahkan tool solving, biarkan aplikasi memvalidasi jenis yang terdeteksi dan halaman saat ini, menyuplai kredensial akun di luar argumen yang terlihat oleh model, dan menerapkan aturan anggaran serta persetujuan yang sesuai dengan workflow tersebut. Kembalikan hasil yang jelas yang membedakan token dari aksi aplikasi yang telah diselesaikan.

Token yang dikembalikan tetap memerlukan penanganan aplikasi yang relevan. Verifikasi milik situs dan hasil form menentukan apakah operasi yang dimaksud berhasil. Baik list captchas yang tidak kosong maupun pemanggilan Tool Haystack yang berhasil bukan bukti bahwa aplikasi menerima respons CAPTCHA.

Memecahkan masalah koneksi tanpa menebak

Proses troubleshooting sebaiknya mengidentifikasi lapisan mana yang gagal: instalasi paket, startup browser, pemuatan widget, inspeksi SDK, atau pemanggilan tool. Ubah lapisan yang didukung oleh error alih-alih mengganti beberapa komponen sekaligus.

Browser executable tidak ditemukan

Instal Chromium dengan perintah Playwright dari virtual environment yang aktif. pip install yang berhasil memasang paket Python tetapi tidak dengan sendirinya membuktikan bahwa binary browser yang cocok tersedia.

Waktu tunggu widget habis (timeout)

Periksa apakah browser memuat skrip Google dan apakah halaman uji membuat widget. Tunggu dalam contoh ini mencari klien widget yang telah diinisialisasi. Kegagalan jaringan dapat terjadi sebelum SDK memiliki apa pun untuk diperiksa; mengulang solver tidak akan mengatasi kegagalan tersebut.

Tool mengembalikan list kosong

Hasil kosong berarti inspeksi ini tidak menemukan descriptor yang didukung pada halaman tersebut pada saat itu. Ini tidak membuktikan bahwa halaman tidak memiliki mekanisme verifikasi. Periksa timing halaman, objek page yang Anda berikan, dan widget yang sebenarnya. Panduan inspeksi parameter CAPTCHA menyediakan cara pelengkap untuk memeriksa state browser.

Tool bekerja langsung tetapi tidak di dalam agent

Periksa bahwa objek Tool yang sama diregistrasikan, bahwa model agent mendukung workflow tool yang dimaksud, dan bahwa sesi browser masih terbuka. Pertahankan pemanggilan langsung yang berhasil sebagai checkpoint terpisah sehingga masalah konfigurasi model tidak dilaporkan keliru sebagai kegagalan API CAPTCHA.

Membuat hasil inspeksi menjadi berguna

Tool inspeksi CAPTCHA kecil memberi aplikasi Haystack checkpoint konkret sebelum solving. Mulailah dari halaman pengembangan yang telah diuji, pertahankan pemanggilan async dan pembersihan resource, lalu kaitkan tool ke halaman yang dikendalikan workflow Anda saat ini. Perluas tanggung jawabnya hanya ketika setiap operasi tambahan memiliki input yang jelas, perilaku yang terverifikasi, dan hasil yang dapat diamati.

Bangun Workflow Otomatisasi Andal dengan CapSolver

Gunakan CapSolver untuk langkah CAPTCHA yang didukung dalam workflow yang Anda berwenang untuk menjalankannya. Pertahankan browser, hasil solver, dan outcome aplikasi sebagai pemeriksaan terpisah sehingga pemanggilan tool yang berhasil tidak menyembunyikan task yang gagal.

FAQ

T: Apakah integrasi ini memerlukan MCP?

Tidak. Contoh ini menggunakan Tool Haystack native dan Python Core SDK dalam aplikasi yang sama. Ia tidak menjalankan server MCP.

T: Apakah saya memerlukan LLM API key untuk menjalankan skrip?

Tidak. Skrip memanggil Tool secara langsung. Kredensial penyedia model menjadi relevan ketika Anda menambahkan agent berbasis LLM di sekitar tool tersebut.

T: Apakah contoh ini menyelesaikan CAPTCHA uji?

Tidak. Contoh ini memuat widget dan membaca parameter publik. Ia tidak meminta token solver dan tidak mengirim form.

T: Bisakah pendekatan yang sama memeriksa halaman Playwright yang sudah ada?

Ya. Ikat tool ke halaman berotorisasi yang sudah ada dan pertahankan halaman itu tetap hidup selama pemanggilan. Field descriptor yang didukung bergantung pada apa yang dapat dideteksi SDK di halaman tersebut.
T: Mengapa menggunakan tool tanpa argumen?

Fungsi tersebut sudah mengetahui halaman yang disetujui saat ini. Skema input kosong menjaga navigasi dan pemilihan halaman tetap berada di bawah kendali aplikasi.

T: Apakah hasil kosong berarti halaman aman untuk diproses sebagai konten normal?

Tidak. Periksa status halaman sebelum melanjutkan. Hasil deteksi kosong juga dapat mencerminkan masalah waktu, mekanisme yang tidak didukung, atau inisialisasi widget yang belum lengkap.