Alat CAPTCHA AI Pydantic: Input yang Diketik dan Hasil Pemecah

TL;DR

• Pydantic AI dapat mengekspos penyelesaian CAPTCHA sebagai alat fungsi Python yang diberi tipe yang didukung oleh adapter agen CapSolver resmi.
• Jaga wrapper tetap kecil: terima parameter yang telah didokumentasikan, panggil eksekutor, dan kembalikan hasil struktur yang telah dihasilkan tanpa menciptakan jawaban yang berhasil.
• Contoh di bawah ini menjalankan loop agen Pydantic AI nyata dengan TestModel dan memanggil katalog tipe yang didukung oleh adapter yang terpasang.
• Fungsi penyelesaian telah terdaftar tetapi secara sengaja dikeluarkan dari pengujian ini; tidak ada permintaan model-penyedia atau penyelesaian berbayar yang terjadi.
• Validasi tipe membantu menggambarkan input alat. Aplikasi Anda tetap memutuskan halaman dan operasi mana yang disetujui serta apakah tugas browser akhirnya berhasil.

Sebuah alat CAPTCHA Pydantic AI memberi agen operasi yang ditentukan ketika tugas browser yang disetujui mencapai tantangan yang didukung. Model tidak perlu menciptakan algoritma penyelesaian, dan aplikasi tidak perlu klien CAPTCHA baru untuk setiap kerangka kerja agen.

Adapter agen CapSolver menyediakan lapisan eksekusi. Pydantic AI menyediakan antarmuka fungsi alat. Panduan ini menunjukkan bagaimana bagian-bagian ini terhubung, menggunakan contoh yang berasal dari repositori Pydantic AI CapSolver yang dikelola dan pengujian lokal yang menjalankan operasi katalog adapter nyata.

Apa yang ditambahkan integrasi Pydantic AI?

Integrasi Pydantic AI mengubah fungsi Python yang diberi tipe biasa menjadi alat yang tersedia bagi agen. Fungsi menerima argumen bernama, mendelegasikan operasi CAPTCHA, dan mengembalikan hasil yang dapat diperiksa oleh agen.

Untuk formulir QA yang dikelola, urutan yang berguna adalah konkret: browser mengidentifikasi tantangan yang didukung, aplikasi menyediakan parameter halaman, alat penyelesaian mengembalikan hasilnya, dan browser melanjutkan upaya formulir yang sama. Penegasan akhir milik alur kerja formulir.

Perpustakaan API mengemas panggilan layanan di bawahnya. Dalam kasus ini, dokumentasi CapSolver agent-tools menjelaskan eksekutor yang mengirimkan operasi bernama ke implementasi intinya.

Dokumentasi fungsi alat Pydantic AI menjelaskan bagaimana tanda tangan fungsi dan anotasi berkontribusi pada definisi alat. Tiga string yang diberi anotasi dapat menggambarkan bentuk input yang diperlukan, tetapi mereka tidak menetapkan bahwa URL disetujui atau bahwa kunci situs milik halaman saat ini.

Mengapa menggunakan adapter resmi alih-alih klien HTTP lainnya?

Gunakan adapter resmi ketika Anda ingin wrapper kerangka kerja kecil di sekitar implementasi penyelesaian yang telah didokumentasikan. Hal ini menjaga wrapper fokus pada antarmuka agen alih-alih menyalin pembuatan tugas, pengambilan, dan konversi hasil.

CapSolver memelihara repositori Pydantic AI menggunakan create_executor, Agent, dan @agent.tool_plain. Ini adalah aplikasi contoh, bukan paket tambahan yang dinamai sesuai repositori.

Contoh dalam artikel ini mempertahankan fungsi penyelesaian tiga-argumen dan panggilan eksekutor dari repositori. Ia mengubah lingkungan demonstrasi untuk menggunakan TestModel Pydantic AI dan panggilan katalog tipe yang didukung. Hal ini memungkinkan koneksi alat diuji tanpa menyediakan kunci model atau menciptakan tugas penyelesaian berbayar.

Jalur ini berbeda dari menghubungkan server MCP. Fungsi memanggil adapter yang terpasang dalam aplikasi Python yang sama; tidak ada proses server MCP terpisah dalam contoh ini. Pilih antarmuka yang sesuai dengan agen yang sudah ada alih-alih menambahkan kedua antarmuka ke tugas kecil yang sama tanpa alasan.

Langkah 1: Pasang paket yang telah diuji

Pasang framework dan adapter dalam lingkungan Python terisolasi. Jalur yang direkam menggunakan Python 3.12.14, pydantic-ai-slim 2.44.0, capsolver-agent 0.1.1, dan capsolver-core 0.1.1.

Paket slim menyediakan fungsionalitas Pydantic AI inti yang digunakan oleh TestModel tanpa menginstal setiap integrasi model-penyedia. Versi berikut sesuai dengan jalur lokal:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install pydantic-ai-slim==2.44.0 capsolver-agent==0.1.1 capsolver-core==0.1.1

Panduan lingkungan virtual Python https://docs.python.org/3/library/venv.html menjelaskan pembuatan lingkungan dan aktivasi khusus shell. Pertahankan versi paket bersama proyek Anda sehingga demonstrasi dapat direproduksi sebelum meningkatkan versinya.

Demonstrasi katalog lokal tidak memerlukan kredensial penyelesaian. Panggilan solve_captcha nyata di masa depan memerlukan kunci API penyelesaian CapSolver Anda, dan percakapan model nyata memerlukan paket dan otorisasi penyedia yang Anda pilih. Itu adalah prasyarat terpisah.

Jangan gunakan kredensial MCP yang digunakan untuk penerbitan blog sebagai kunci penyelesaian. Kredensial layanan eksekutor harus berada di luar prompt model dan sumber yang dikirimkan.

Langkah 2: Daftarkan alat yang diberi tipe

Simpan berikut ini sebagai quickstart.py. Wrapper penyelesaian mengikuti repositori resmi; alat katalog dan konfigurasi TestModel adalah adaptasi yang dieksekusi secara lokal. Kode mendaftarkan alat penyelesaian tetapi tidak memanggilnya.

import asyncio
import json

from capsolver_agent import create_executor
from pydantic_ai import Agent, models
from pydantic_ai.models.test import TestModel

models.ALLOW_MODEL_REQUESTS = False
capsolver = create_executor()
agent = Agent(TestModel(call_tools=["get_supported_captchas"]))


@agent.tool_plain
async def get_supported_captchas() -> str:
    """Kembalikan tipe CAPTCHA yang terdaftar tanpa menyelesaikan tantangan."""
    return json.dumps(await capsolver.execute("get_supported_captchas", {}))


@agent.tool_plain
async def solve_captcha(captcha_type: str, website_url: str, website_key: str) -> str:
    """Selesaikan CAPTCHA yang didukung untuk alur kerja yang sah dan diizinkan pengguna."""
    result = await capsolver.execute(
        "solve_captcha",
        {
            "captcha_type": captcha_type,
            "website_url": website_url,
            "website_key": website_key,
        },
    )
    return json.dumps(result, ensure_ascii=False)


async def main() -> None:
    result = await agent.run("Daftar tipe CAPTCHA yang didukung.")
    print(result.output)


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

Jalankan file dengan interpreter Python lingkungan:

python quickstart.py

Skrip mengatur ALLOW_MODEL_REQUESTS ke false untuk mencegah panggilan ke model non-test secara tidak sengaja. Ia juga membatasi TestModel hanya pada alat katalog. Kedua pilihan ini penting: mencegah permintaan model berbeda dari mencegah alat dari menghubungi layanan eksternal.

Dokumentasi pengujian Pydantic AI menjelaskan bahwa TestModel dapat memanggil alat yang terdaftar menggunakan data input yang dihasilkan. Meninggalkan alat penyelesaian berbayar dalam pengujian yang tidak dibatasi akan menjadi operasi yang berbeda dari pemeriksaan katalog yang terkendali seperti yang ditunjukkan di sini.

Langkah 3: Baca hasil yang diamati dengan benar

Jalur lokal mengembalikan hasil katalog yang berhasil dari adapter CapSolver yang terpasang. Ia melaporkan handler yang dinamai recaptcha dan cloudflare, dengan nilai tipe reCaptchaV2, reCaptchaV3, dan cloudflare.

Output yang dicetak oleh TestModel berisi string JSON dari alat katalog di dalam ringkasan hasil alat. Tanda kutip yang diubah menjadi karakter khusus dalam ringkasan yang dicetak adalah konsekuensi dari mengembalikan JSON yang telah di-serialisasi dari fungsi; mereka bukan token CAPTCHA baru.

Wrapper resmi menggunakan json.dumps untuk mengembalikan hasil eksekutor sebagai string. Pertahankan perbedaan antara string ini dan kamus di bawahnya jika komponen lain mengonsumsinya. Parsing nilai JSON yang relevan secara sengaja alih-alih mengasumsikan setiap lapisan mengembalikan bentuk yang sama.

Uji ini menetapkan bahwa pendaftaran, eksekusi alat tanpa argumen, pengalihan adapter, dan pengembalian hasil bekerja bersama dalam versi yang terpasang. Ia tidak menetapkan bahwa LLM akan memilih alat penyelesaian yang benar atau bahwa formulir yang dilindungi tertentu akan menerima token.

Tukarkan Kode Bonus CapSolver Anda

Tingkatkan anggaran otomatisasi Anda secara instan!
Gunakan kode bonus CAP26 saat menambahkan dana ke akun CapSolver Anda untuk mendapatkan tambahan 5% bonus pada setiap penyetoran — tanpa batas.
Tukarkan sekarang di Dasbor CapSolver Anda

Bagaimana input berbasis tipe memetakan ke permintaan CAPTCHA?

Input berbasis tipe memetakan panggilan alat agen ke kamus argumen yang diterima oleh adapter. Wrapper penyelesaian minimal menerima captcha_type, website_url, dan website_key.

Nama-nama ini milik antarmuka adapter. Mereka bukan permintaan REST yang verbatim yang berisi clientKey dan objek task. Konsultasikan skema alat yang terpasang dan dokumentasi tugas reCAPTCHA v2 https://docs.capsolver.com/en/guide/captcha/ReCaptchaV2/ saat menghubungkan halaman nyata.

Wrapper tiga bidang secara sengaja minimal. Beberapa variasi memerlukan konteks tambahan. Jangan asumsikan bahwa setiap tantangan yang tercantum oleh layanan yang lebih luas dapat diselesaikan hanya dengan tiga string ini, atau bahwa nama tipe wrapper dapat diganti dengan nama tugas REST.

Anotasi string tidak membatasi URL ke hostname yang disetujui. Pastikan target dan operasi yang diizinkan dalam aplikasi yang menyediakan argumen alat. Konten halaman tidak boleh dapat menyetujui target baru hanya dengan meminta model untuk menggunakan satu.

Bagaimana agen harus menangani hasil solver?

Agen harus memeriksa hasil eksekutor dan menjaga hasil CAPTCHA terpisah dari hasil tugas bisnis. Adapter agen yang telah didokumentasikan mengembalikan amplop keberhasilan yang berisi solusi, atau amplop kegagalan yang menggambarkan kesalahan.

Pada kegagalan, aplikasi harus menyimpan informasi kesalahan yang relevan dan memutuskan apakah input yang diperbaiki, upaya baru, atau tinjauan operator sesuai. Jangan ubah kesalahan menjadi placeholder yang menyerupai token hanya untuk memenuhi bidang string di hulu.

Pada keberhasilan, kirim hasil ke komponen aplikasi yang bertanggung jawab atas upaya tantangan yang sama. Fungsi dalam panduan ini tidak mengontrol browser, menemukan bidang respons, mengirim formulir, atau menegaskan penerimaan aplikasi.

Untuk pengujian formulir yang dikelola, kriteria kelengkapan yang sesuai mungkin merupakan catatan konfirmasi uji yang diharapkan. Keberhasilan solver dan penolakan aplikasi harus tetap menjadi dua pengamatan terpisah. Pemisahan ini membuat kunci halaman yang salah dapat dibedakan dari kegagalan validasi formulir yang tidak terkait.

Hindari menyimpan kredensial atau token penuh dalam jejak rutin. Jika agen membutuhkan ringkasan yang dapat dibaca, pertahankan status operasional dan bidang diagnostik yang aman sambil menjaga nilai hasil dalam komponen yang benar-benar mengonsumsinya.

Bagaimana cara beralih dari TestModel ke agen nyata?

Beralih ke agen nyata dengan mengonfigurasi penyedia model yang diinginkan, menyediakan otorisasinya, dan mengaktifkan hanya operasi live yang dibutuhkan aplikasi. Pertahankan wrapper alat yang telah diuji dan periksa panggilan alat nyata dari model baru.

TestModel dalam demonstrasi adalah infrastruktur pengujian prosedural, bukan model bahasa. Pemilihan katalog yang berhasil tidak mengukur penalaran model. Percakapan nyata mungkin menghasilkan parameter yang hilang, memilih alat yang salah, atau meminta operasi lain, jadi aplikasi masih harus memeriksa inputnya.

Mulai dengan satu halaman QA yang dikelola dan variasi tantangan yang telah didokumentasikan. Sediakan URL halaman nyata dan kunci situs publik dari aplikasi, lalu validasi hasil solver dan respons akhir formulir. Catat kegagalan berdasarkan tahap alih-alih mengurangi seluruh eksperimen menjadi apakah teks muncul dalam jawaban agen.

Panduan penyelesaian CAPTCHA perusahaan membahas adopsi tim. Contoh kerangka ini menetapkan fondasi yang lebih sempit: pendaftaran fungsi berbasis tipe dan eksekusi adapter nyata dengan operasi yang terkendali, bukan penyelesaian.

Tes CapSolver untuk tantangan yang didukung dalam tugas yang disetujui setelah memahami koneksi lokal ini. Pertahankan cakupan setiap pengujian secara eksplisit: pendaftaran alat, pemilihan model, penyelesaian berbayar, dan penerimaan browser adalah pengecekan yang berbeda.

FAQ

Q: Apakah ada paket pydantic-ai-capsolver terpisah?

Repositori yang dirujuk berisi contoh yang menggunakan Pydantic AI dan pustaka agen CapSolver resmi. Tutorial ini menginstal perpustakaan tersebut secara langsung alih-alih mengasumsikan bahwa nama repositori adalah paket.

Q: Apakah TestModel memanggil layanan CAPTCHA nyata?

TestModel dapat menjalankan alat yang terdaftar, jadi alat yang dipilih menentukan apa yang terjadi. Contoh ini secara eksplisit hanya memanggil katalog tipe yang didukung dan tidak memanggil permintaan penyelesaian.

Q: Apakah input string berbasis tipe cukup untuk menyetujui halaman target?

Tidak. Anotasi tipe menggambarkan bentuk input. Aplikasi harus memaksakan URL, tugas, dan konteks yang diizinkan secara terpisah.

Q: Mengapa hasil yang dicetak mengandung JSON yang diubah menjadi karakter khusus?

Wrapper mengembalikan JSON yang telah di-serialisasi, dan TestModel menyertakan string ini dalam ringkasan outputnya. Tangani setiap lapisan serialisasi secara sengaja alih-alih mengasumsikan ringkasan adalah objek solusi yang murni.

Q: Apakah wrapper ini dapat menangani setiap variasi CAPTCHA?

Tidak ada cakupan yang ditetapkan di sini. Fungsi minimal menerima tiga parameter; variasi yang memerlukan konteks tambahan memerlukan bidang dan validasi yang sesuai.

Q: Apakah CAPTCHA nyata diselesaikan selama pengujian?

Tidak. Kerangka kerja dan adapter yang terpasang menjalankan operasi katalog nyata menggunakan TestModel. Penyelesaian nyata dan penerimaan oleh aplikasi yang dikelola tetap menjadi pengujian terpisah yang memerlukan kredensial dan halaman yang tepat.