Cara Menyelesaikan reCAPTCHA v3 di Agen CrewAI dengan CapSolver
Emma Foster
Machine Learning Engineer
TL;DR
- Solver reCAPTCHA v3 CrewAI seharusnya menjadi alat yang sempit, bukan browser umum atau fungsi URL arbitrer.
- Selesaikan URL target, kunci situs, tindakan halaman yang diharapkan, dan kebijakan skor dari daftar sisi server, bukan dari teks yang dihasilkan model.
- Gunakan parameter tugas reCAPTCHA v3 yang terdokumentasi dari CapSolver dan pertahankan pengaturan Enterprise, proxy, dan sesi secara eksplisit.
- Kirim token yang dikembalikan di dalam kode aplikasi yang tepercaya; kembalikan hanya objek status yang diremehkan ke agen CrewAI.
- Pertimbangkan hasil solver sebagai langkah antara dan pastikan bahwa keadaan halaman yang dimaksud berubah sebelum kru melanjutkan.
Pendahuluan
Cara paling aman untuk menyelesaikan reCAPTCHA v3 di CrewAI adalah dengan mengekspos CapSolver melalui alat yang berjenis dan dikendalikan kebijakan. CrewAI harus menentukan kapan tugas perlu verifikasi, tetapi kode aplikasi yang tepercaya harus menyelesaikan target yang disetujui, kunci situs, tindakan halaman, mode proxy, dan kebijakan skor. Dokumentasi reCAPTCHA v3 CapSolver mendefinisikan jenis tugas dan parameter yang didukung, sementara SDK Agent yang disediakan pengguna memetakan panggilan alat terstruktur ke capsolver-core. Alat tersebut harus mengirim token di sisi server, memverifikasi keadaan halaman yang dihasilkan, dan memberikan hasil kecil seperti verified, review_required, atau stopped kepada kru. Desain ini mencegah pergeseran URL, tebakan tindakan, kebocoran rahasia, penyelesaian ganda, dan sinyal keberhasilan palsu.
Mengapa reCAPTCHA v3 Membutuhkan Alat CrewAI yang Berbeda
reCAPTCHA v3 berbasis skor dan biasanya berjalan tanpa checkbox yang terlihat. Aplikasi target memanggil tindakan, menerima token, dan mengevaluasi token tersebut di sisi server. Oleh karena itu, alur kerja CrewAI dapat gagal bahkan ketika tidak pernah melihat tantangan visual.
Penyebab umumnya bersifat operasional, bukan komunikasi:
- alat menggunakan kunci situs yang salah;
pageActiontidak sesuai dengan tindakan runtime halaman;- token dikirim ke rute atau keadaan browser yang berbeda;
- jenis tugas tidak sesuai dengan Standar atau Enterprise;
- kru menganggap penyelesaian tugas sebagai verifikasi aplikasi;
- langkah yang sama menciptakan beberapa token tanpa perubahan keadaan.
Blog reCAPTCHA CapSolver https://www.capsolver.com/blog/recaptcha memiliki panduan implementasi pendukung, sementara FAQ AI dan otomasi https://www.capsolver.com/faq/ai-and-automation membantu menentukan batas agen yang aman.
Pisahkan Peran Crew dari Otoritas Solver
Kru multi-agent bekerja paling baik ketika tanggung jawabnya jelas.
| Peran | Tanggung jawab yang diizinkan | Tidak boleh mengontrol |
|---|---|---|
| Navigator | Mengamati keadaan aplikasi yang disetujui | Kunci API, kredensial proxy, token mentah |
| Perencana Verifikasi | Memutuskan apakah langkah yang disetujui memerlukan alat | URL atau kunci situs arbitrer |
| Alat CapSolver | Menyelesaikan kebijakan, membuat satu tugas, mengirim token | Pengulangan tak terbatas atau penjelajahan yang tidak terkait |
| Validator Keadaan | Memastikan rute dan penanda semantik yang diharapkan | Keputusan persetujuan bisnis |
| Peninjau | Memeriksa bukti yang diremehkan pada kegagalan | Materi sesi rahasia |
Model dapat memilih ID target yang terdaftar. Ia tidak boleh membuat URL target atau parameter tantangan.
Gunakan Pola Alat CrewAI Resmi
Dokumentasi alat kustom CrewAI mendukung BaseTool dengan args_schema Pydantic, dekorator @tool, hasil berjenis, dan alat asinkron untuk operasi I/O-bound.
Dokumentasi CapSolver Agent yang disediakan pengguna menjelaskan bahwa capsolver-agent mengelilingi capsolver-core: create_executor() membuat executor, dan executor.execute("solve_captcha", args) mengirimkan permintaan berjenis ke mesin inti.
Instal paket yang terdokumentasi:
bash
pip install git+https://github.com/capsolver-ai/capsolver-core.git
pip install git+https://github.com/capsolver-ai/capsolver-agent.git
pip install crewai
export CAPSOLVER_API_KEY="CAP-..."Simpan kunci di penyimpanan rahasia runtime. Jangan tempatkan mereka di prompt kru, deskripsi tugas, atau hasil alat.
Tetapkan Daftar Target yang Tepercaya
python
from dataclasses import dataclass
@dataclass(frozen=True)
class RecaptchaV3Policy:
target_id: str
website_url: str
website_key: str
page_action: str
minimum_score: float
enterprise: bool
proxy_profile: str | None
allowed_crew_role: str
max_attempts: int = 1
TARGETS = {
"approved_login_test": RecaptchaV3Policy(
target_id="approved_login_test",
website_url="https://approved.example.com/login",
website_key="PUBLIC_SITE_KEY",
page_action="login",
minimum_score=0.7,
enterprise=False,
proxy_profile=None,
allowed_crew_role="verification_specialist",
)
}Kunci situs publik bukan rahasia akun, tetapi tetap harus berasal dari konfigurasi tepercaya sehingga model tidak dapat mengarahkan alat.
Amati pageAction Daripada Menebaknya
Dokumentasi reCAPTCHA v3 CapSolver reCAPTCHA v3 dokumentasi menyebutkan pageAction sebagai bidang tugas opsional dan menjelaskan bahwa nilai tersebut dapat ditemukan dalam panggilan grecaptcha.execute halaman.
python
@dataclass(frozen=True)
class PageObservation:
target_id: str
current_url: str
observed_action: str
observed_site_key: str
form_state: str
observed_at: str
def validate_observation(
observation: PageObservation,
policy: RecaptchaV3Policy,
) -> None:
if observation.current_url != policy.website_url:
raise PermissionError("URL yang diamati tidak sesuai dengan kebijakan")
if observation.observed_site_key != policy.website_key:
raise ValueError("Kunci situs yang diamati tidak sesuai dengan kebijakan")
if observation.observed_action != policy.page_action:
raise ValueError("Tindakan halaman yang diamati tidak sesuai dengan kebijakan")
if observation.form_state != "READY_FOR_VERIFICATION":
raise ValueError("Keadaan aplikasi tidak siap")Alat harus menolak ketidakcocokan daripada membuat token untuk parameter yang tidak pasti.
Pahami Parameter CapSolver v3
| Parameter | Tujuan | Aturan kebijakan |
|---|---|---|
captcha_type |
Memilih reCAPTCHA v3 dalam SDK Agent | Tetapkan ke reCaptchaV3 |
website_url |
Halaman yang menampilkan tantangan | Dimuat dari daftar |
website_key |
Kunci situs publik | Dimuat dari daftar dan diverifikasi terhadap halaman |
page_action |
Tindakan v3 runtime | Harus sesuai dengan pengamatan |
min_score |
Skor minimum yang diminta | Diatur oleh kebijakan target |
enterprise |
Jalur Standar atau Enterprise | Tetapkan oleh konfigurasi integrasi |
proxy |
Identitas jaringan opsional | Diselesaikan dari profil rahasia jika diperlukan |
CapSolver mendokumentasikan varian tugas Standar, Enterprise, proxy, dan tanpa proxy. Hasilnya dapat berisi gRecaptchaResponse, data user-agent, dan nilai sesi ketika mode relevan diaktifkan.
Halaman produk CapSolver https://www.capsolver.com/products membantu memverifikasi keluarga tugas yang didukung sebelum implementasi.
Buat Alat CrewAI Berjenis
python
import os
from typing import Literal
from crewai.tools import tool
from pydantic import BaseModel, Field
from capsolver_agent.schema import create_executor
executor = create_executor(api_key=os.environ["CAPSOLVER_API_KEY"])
class SolveRequest(BaseModel):
target_id: str = Field(description="Identifikasi target yang terdaftar")
crew_role: str = Field(description="Peran yang meminta verifikasi")
observed_action: str = Field(description="Tindakan yang diamati di halaman hidup")
observed_site_key: str = Field(description="Kunci situs yang diamati di halaman hidup")
state_id: str = Field(description="Identifikasi keadaan aplikasi sisi server yang tidak terlihat")
class SolveResult(BaseModel):
status: Literal["verified", "review_required", "stopped"]
target_id: str
state_id: str
reason: str
task_attempted: boolModel hasil secara sengaja tidak mencakup token, kunci API, proxy, cookie, atau respons penyedia mentah.
Selesaikan Rahasia dan Kirim Token Sisi Server
python
PROXY_VAULT = {
"approved_proxy": os.environ.get("APPROVED_PROXY")
}
async def submit_token_and_verify(
*,
state_id: str,
token: str,
policy: RecaptchaV3Policy,
) -> bool:
"""Fungsi submit dan periksa yang dimiliki aplikasi."""
response = await application_sessions.submit_recaptcha_v3(
state_id=state_id,
token=token,
expected_action=policy.page_action,
)
return (
response.current_url.startswith("https://approved.example.com/account")
and response.semantic_marker == "AUTHENTICATED_ACCOUNT_PAGE"
and response.challenge_present is False
)application_sessions mewakili layanan sesi browser atau HTTP yang sah Anda. Solver tool menggunakannya, tetapi model tidak menerima kredensialnya.
Implementasikan Alat Asinkron
python
@tool("Selesaikan reCAPTCHA v3 yang disetujui", result_schema=SolveResult)
async def solve_approved_recaptcha_v3(
target_id: str,
crew_role: str,
observed_action: str,
observed_site_key: str,
state_id: str,
) -> dict:
"""Selesaikan satu langkah reCAPTCHA v3 yang terdaftar dan verifikasi keadaan aplikasi."""
policy = TARGETS.get(target_id)
if policy is None:
return SolveResult(
status="stopped",
target_id=target_id,
state_id=state_id,
reason="Target tidak dikenal",
task_attempted=False,
).model_dump()
if crew_role != policy.allowed_crew_role:
return SolveResult(
status="stopped",
target_id=target_id,
state_id=state_id,
reason="Peran tidak diizinkan memanggil alat ini",
task_attempted=False,
).model_dump()
if observed_action != policy.page_action:
return SolveResult(
status="review_required",
target_id=target_id,
state_id=state_id,
reason="Tindakan yang diamati tidak sesuai dengan kebijakan target",
task_attempted=False,
).model_dump()
if observed_site_key != policy.website_key:
return SolveResult(
status="review_required",
target_id=target_id,
state_id=state_id,
reason="Kunci situs yang diamati tidak sesuai dengan kebijakan target",
task_attempted=False,
).model_dump()
args = {
"captcha_type": "reCaptchaV3",
"website_url": policy.website_url,
"website_key": policy.website_key,
"page_action": policy.page_action,
"min_score": policy.minimum_score,
"enterprise": policy.enterprise,
}
if policy.proxy_profile:
args["proxy"] = PROXY_VAULT[policy.proxy_profile]
result = await executor.execute("solve_captcha", args)
if not result.get("success"):
return SolveResult(
status="review_required",
target_id=target_id,
state_id=state_id,
reason="Tugas CapSolver tidak selesai",
task_attempted=True,
).model_dump()
solution = result.get("solution") or {}
token = solution.get("token")
if not token:
return SolveResult(
status="review_required",
target_id=target_id,
state_id=state_id,
reason="Hasil tugas tidak mengandung token",
task_attempted=True,
).model_dump()
verified = await submit_token_and_verify(
state_id=state_id,
token=token,
policy=policy,
)
return SolveResult(
status="verified" if verified else "review_required",
target_id=target_id,
state_id=state_id,
reason="Keadaan aplikasi diverifikasi" if verified else "Keadaan aplikasi tidak diverifikasi",
task_attempted=True,
).model_dump()Implementasi ini menjaga kredensial di dalam kode yang tepercaya dan memberikan kru hanya status yang aman kebijakan.
Hubungkan Alat ke Satu Agen
python
from crewai import Agent, Crew, Process, Task
verification_agent = Agent(
role="verification_specialist",
goal="Selesaikan hanya langkah verifikasi yang terdaftar dan laporkan keadaan yang diverifikasi",
backstory=(
"Anda mengoperasikan alat verifikasi yang disetujui. Anda tidak pernah menciptakan ID target, "
"kunci situs, tindakan, kredensial, atau keadaan keberhasilan."
),
tools=[solve_approved_recaptcha_v3],
allow_delegation=False,
verbose=True,
)
verification_task = Task(
description=(
"Untuk target yang terdaftar dalam pengamatan yang disediakan, panggil alat sekali "
"hanya jika URL, kunci situs, tindakan, dan keadaan dikonfirmasi. Kembalikan "
"hasil terstruktur tanpa rahasia."
),
expected_output="Hasil terstruktur verified, review_required, atau stopped.",
agent=verification_agent,
)
crew = Crew(
agents=[verification_agent],
tasks=[verification_task],
process=Process.sequential,
verbose=True,
)Jangan hubungkan alat solver ke setiap agen. Batasi hanya ke satu peran membuat otorisasi dan audit lebih jelas.
Cegah Pemanggilan Alat Ganda
python
from datetime import datetime, timedelta, timezone
ATTEMPTS: dict[tuple[str, str], datetime] = {}
def claim_attempt(target_id: str, state_id: str) -> bool:
key = (target_id, state_id)
now = datetime.now(timezone.utc)
prior = ATTEMPTS.get(key)
if prior and now - prior < timedelta(minutes=2):
return False
ATTEMPTS[key] = now
return TruePanggil claim_attempt() sebelum executor.execute(). Pesan kru yang berulang tidak boleh menciptakan token kedua untuk keadaan aplikasi yang sama.
Jaga Token Jauh dari Memori Crew
Memori CrewAI, jejak, dan log verbose mungkin menyimpan output alat. Kembalikan hanya:
json
{
"status": "verified",
"target_id": "approved_login_test",
"state_id": "state_7c19",
"reason": "Keadaan aplikasi diverifikasi",
"task_attempted": true
}Jangan pernah mengembalikan token, kunci API CapSolver, nilai proxy, cookie browser, HTML mentah, kata sandi, atau data formulir pribadi.
FAQ kesalahan dan pemecahan masalah CapSolver https://www.capsolver.com/faq/errors-and-troubleshooting dapat mendukung klasifikasi kesalahan penyedia tanpa mengungkap respons mentah ke kru.
Validasi Halaman Setelah Pengiriman
Validator harus membutuhkan beberapa sinyal independen:
python
@dataclass(frozen=True)
class StateCheck:
expected_path_prefix: str
required_marker: str
forbidden_markers: tuple[str, ...]
def is_verified(page, check: StateCheck) -> bool:
return (
page.url.path.startswith(check.expected_path_prefix)
and page.has_semantic_marker(check.required_marker)
and not any(page.contains(marker) for marker in check.forbidden_markers)
and page.http_status == 200
)Perubahan URL saja tidak cukup. Harus ada rute yang diharapkan, penanda semantik, status, dan ketiadaan keadaan tantangan atau kesalahan yang diketahui.
Tangani Mode Enterprise dan Sesi Secara Eksplisit
CapSolver mendokumentasikan varian Enterprise dan mode sesi opsional. Jangan biarkan kru menebak opsi ini.
python
@dataclass(frozen=True)
class RecaptchaV3Policy:
target_id: str
website_url: str
website_key: str
page_action: str
minimum_score: float
enterprise: bool
is_session: bool
proxy_profile: str | None
allowed_crew_role: str
max_attempts: int = 1Jika target yang disetujui menggunakan Enterprise, simpan fakta tersebut dalam kebijakan. Jika mode sesi diperlukan, tangani nilai sesi yang dikembalikan di dalam layanan sesi aplikasi dan jangan biarkan mereka muncul di output kru.
Ringkasan Perbandingan
| Desain | Integritas parameter | Keamanan rahasia | Jaminan state halaman | Rekomendasi |
|---|---|---|---|---|
| Model menyediakan URL, kunci, dan aksi | Rendah | Rendah | Rendah | Hindari |
| Alat mengembalikan token ke kru | Menengah | Rendah | Rendah | Hindari |
| Alat yang diselesaikan melalui registri mengirim dan memverifikasi | Tinggi | Tinggi | Tinggi | Disarankan |
| Langkah verifikasi hanya manusia | Tinggi | Tinggi | Tinggi | Gunakan untuk state sensitif atau tidak pasti |
Desain yang disarankan memberikan otoritas keputusan kepada model tetapi menjaga otoritas eksekusi di dalam kode yang tepercaya.
Tambahkan Metrik Operasional
Lacak bidang yang dihapus seperti:
- target ID;
- peran kru;
- kecocokan aksi yang diamati;
- tugas yang dicoba;
- kategori status penyedia;
- durasi pengiriman;
- halaman diverifikasi;
- alasan ulasan manual.
python
SAFE_FIELDS = {
"target_id",
"crew_role",
"action_match",
"task_attempted",
"provider_category",
"duration_ms",
"verified",
"review_reason",
}
def safe_event(event: dict) -> dict:
return {key: event[key] for key in SAFE_FIELDS if key in event}Halaman status CapSolver https://status.capsolver.com/status/capsolver dapat membantu membedakan ketersediaan penyedia dari kegagalan aplikasi spesifik.
Uji Alat Sebelum Produksi
python
import pytest
@pytest.mark.asyncio
async def test_unknown_target_stops_before_task():
result = await solve_approved_recaptcha_v3.run(
target_id="unknown",
crew_role="verification_specialist",
observed_action="login",
observed_site_key="x",
state_id="state-1",
)
assert result["status"] == "stopped"
assert result["task_attempted"] is False
@pytest.mark.asyncio
async def test_action_mismatch_requests_review():
result = await solve_approved_recaptcha_v3.run(
target_id="approved_login_test",
crew_role="verification_specialist",
observed_action="checkout",
observed_site_key="PUBLIC_SITE_KEY",
state_id="state-2",
)
assert result["status"] == "review_required"
assert result["task_attempted"] is FalseJuga uji pemblokiran percobaan ganda, penghapusan rahasia, penanganan token yang hilang, kebijakan Enterprise, dan kegagalan verifikasi halaman.
Kode Bonus: Gunakan kode WEBS di Dashboard CapSolver untuk mendapatkan bonus tambahan 5% pada setiap pengisian ulang.
Daftar Periksa Produksi
- Daftarkan setiap URL target, kunci situs, aksi, skor, dan pengaturan Enterprise di sisi server.
- Izinkan satu peran CrewAI memanggil alat solver.
- Validasi URL yang diamati, kunci situs, aksi, dan state sebelum pembuatan tugas.
- Gunakan parameter reCAPTCHA v3 yang telah didokumentasikan oleh CapSolver.
- Kirim token di dalam kode aplikasi yang tepercaya.
- Kembalikan hanya hasil yang direkam secara terstruktur ke kru.
- Izinkan satu percobaan per state aplikasi yang diamati.
- Verifikasi rute, penanda semantik, status, dan ketidakhadiran tantangan.
- Jaga agar kunci, token, data proxy, cookie, dan data formulir tidak muncul di memori dan jejak.
- Arahkan state yang tidak pasti atau sensitif ke peninjau manusia.
FAQ penyelesaian CAPTCHA CapSolver menyediakan panduan tambahan tentang siklus hidup tugas.
Penggunaan Bertanggung Jawab
Hanya gunakan solver reCAPTCHA v3 CrewAI pada situs yang Anda miliki, uji, atau memiliki izin eksplisit untuk otomatisasi. Hormati ketentuan, batas kecepatan, batas otorisasi, kewajiban privasi, dan kebijakan akses internal. Kunci situs publik tidak memberikan izin untuk mengakses alur kerja yang dilindungi. Jaga agar pengiriman yang berdampak, pembayaran, perubahan akun, dan keputusan data sensitif di belakang kontrol persetujuan terpisah.
Kesimpulan
Solver reCAPTCHA v3 CrewAI produksi harus spesifik, berjenis, dan dikendalikan kebijakan. CrewAI dapat mengidentifikasi kebutuhan verifikasi, tetapi kode yang tepercaya harus menyelesaikan target, kunci situs, aksi halaman, skor, mode Enterprise, dan pengaturan jaringan. CapSolver harus dijalankan sekali untuk state yang diverifikasi, token harus dikirim di sisi server, dan kru harus menerima hanya hasil yang direkam setelah halaman yang dimaksud diverifikasi.
Mulai implementasi yang diizinkan dengan CapSolver, uji di halaman yang terkendali, dan tambahkan uji parameter, panggilan duplikat, penghapusan, dan state halaman sebelum penggunaan produksi.
FAQ
Apakah CrewAI dapat memanggil CapSolver langsung?
CrewAI dapat memanggil alat yang berjenis yang mengalihkan ke eksekutor CapSolver yang telah didokumentasikan. Jaga resolusi target, rahasia, pengiriman token, dan verifikasi di dalam kode aplikasi yang tepercaya.
Parameter reCAPTCHA v3 apa yang diperlukan?
URL target dan kunci situs diperlukan. Aksi halaman, skor minimum, pengaturan Enterprise, mode sesi, dan proxy tergantung pada konfigurasi target yang disetujui.
Apakah model memilih aksi halaman?
Tidak. Amati aksi dari halaman yang disetujui dan bandingkan dengan nilai kebijakan sisi server.
Apakah token CapSolver dikembalikan ke kru?
Tidak. Kirimnya di dalam kode yang tepercaya dan kembalikan hanya status yang diverifikasi, diperlukan ulasan, atau dihentikan.
Berapa jumlah percobaan yang harus dilakukan satu tugas CrewAI?
Gunakan satu percobaan per state aplikasi yang diamati secara default. Percobaan kedua harus memerlukan pengamatan baru dan keputusan kebijakan eksplisit.
Lihat Lebih Banyak
AISep 01, 2026
Ulasan CloakBrowser 2026: Fitur, Harga, Kelebihan dan Kekurangan
Ulasan CloakBrowser untuk 2026 yang mencakup fitur, harga, lisensi, opsi penyebaran, kelebihan, keterbatasan, alternatif, dan kasus penggunaan ideal.
AIAug 31, 2026
Pemecah CAPTCHA CloakBrowser: Cara Mengintegrasikan CapSolver dengan Otomatisasi Browser Playwright
Integrasikan CloakBrowser dengan CapSolver melalui otomatisasi Python yang kompatibel dengan Playwright, termasuk reCAPTCHA v2, tugas gambar, kode, dan penyelesaian masalah.