Cara Menyelesaikan AWS WAF di LangChain dengan CapSolver

TL;DR

• AWS WAF dapat mengembalikan respons 202 Challenge atau respons 405 CAPTCHA ketika permintaan tidak membawa token yang valid; periksa status dan header x-amzn-waf-action sebelum mengarahkan agen.
• Alur kerja LangChain yang andal memisahkan penalaran model dari otorisasi deterministik, penanganan tantangan, penyimpanan sesi, dan verifikasi halaman akhir.
• CapSolver mendokumentasikan adapter agen di atas capsolver-core, dengan alat LangChain yang siap pakai dan metode deteksi serta pengisian kembali berbasis browser.
• Simpan kuki, kredensial, token solusi, dan objek browser di luar prompt dan state agen. Berikan model hanya hasil kecil yang berjenis seperti resolved, not_needed, review, atau denied.
• Pertimbangkan penyelesaian tantangan sebagai hasil sementara. Alur kerja harus mengulang permintaan yang dimaksudkan dan memverifikasi kondisi keberhasilan aplikasi spesifik sebelum melanjutkan.
• Contoh di bawah ini untuk sistem yang dimiliki atau secara eksplisit diizinkan. Mereka telah diverifikasi sintaksnya, tetapi jalur end-to-end yang hidup masih memerlukan halaman uji yang disetujui dan kredensial nyata.

Bagaimana AWS WAF memengaruhi agen LangChain

Tindakan Challenge dan CAPTCHA AWS WAF mengubah jalur permintaan yang biasa. Menurut dokumentasi tindakan AWS WAF, permintaan dengan token yang valid terus ke aturan berikutnya. Permintaan tanpa token yang valid dapat menerima respons tantangan.

Untuk Challenge, AWS mendokumentasikan header respons x-amzn-waf-action: challenge dan status HTTP 202. Untuk CAPTCHA, ia mendokumentasikan x-amzn-waf-action: captcha dan status 405. Ketika klien mengharapkan HTML, AWS WAF dapat mengembalikan JavaScript interstitial. Interaksi yang berhasil memperbarui token dan mengirim ulang permintaan asli.

Perilaku ini penting bagi agen karena klien HTTP umum mungkin menganggap respons sebagai halaman biasa, kesalahan server sementara, atau hasil kosong. Model bahasa tidak boleh menebak kasus mana yang terjadi. Aplikasi host harus mengklasifikasikan respons, memeriksa otorisasi, dan mengarahkan alur kerja melalui langkah pemulihan yang terkendali.

Tujuannya bukan membuat penanganan tantangan tidak terlihat. Tujuannya adalah membuatnya jelas, terbatas, teramati, dan terbatas pada otomatisasi yang sah pada sistem yang dimiliki operator atau memiliki izin untuk diuji.

Arsitektur untuk LangChain, AWS WAF, dan CapSolver

Desain produksi memiliki lima tanggung jawab terpisah:

1. Agen LangChain: memilih tindakan bisnis berikutnya dari kumpulan alat terbatas.
2. Klien HTTP atau browser: mengelola sesi saat ini, kuki, header, dan state halaman.
3. Pintu kebijakan: memeriksa domain, tujuan, tindakan, dan anggaran ulang coba.
4. Adapter CapSolver: mengekspos kemampuan pengenalan yang terdokumentasi dan pengisian kembali browser.
5. Verifikator: mengulang operasi yang dimaksudkan dan memeriksa kondisi keberhasilan aplikasi spesifik.

Guia resmi CapSolver untuk alat agen menjelaskan capsolver-agent sebagai adapter tipis di atas capsolver-core. Paket inti melakukan operasi seperti solve, detect, dan solve_on_page; paket agen menyediakan skema alat yang ramah framework. Jalur LangChain yang terdokumentasi menyediakan alat siap pakai melalui get_langchain_tools().

Batas ini berguna. Model tidak perlu kredensial mentah, token, objek browser, atau fungsi jaringan tanpa batas. Ia menerima kontrak alat yang sempit sementara kode aplikasi deterministik mengontrol kapan alat dapat dijalankan.

Prasyarat untuk integrasi yang diizinkan

Sebelum menulis kode agen, tentukan batas operasional:

• daftar putih hostname yang dimiliki atau diizinkan secara eksplisit;
• tujuan yang disetujui seperti validasi QA atau penelitian data publik yang diizinkan;
• gudang rahasia untuk CAPSOLVER_API_KEY dan kredensial model;
• satu pemilik sesi untuk seluruh siklus permintaan dan tantangan;
• jumlah maksimum ulang coba dan anggaran waktu total;
• penegasan keberhasilan yang membuktikan operasi asli telah selesai;
• jalur ulasan manusia untuk domain yang tidak dikenal, kegagalan berulang, atau tindakan yang mengubah state;
• aturan redaksi untuk kuki, token, kredensial, dan konten halaman.

Gunakan lingkungan Python terpisah. Perintah instalasi di bawah ini mengikuti panduan agen CapSolver saat ini:

python -m venv .venv
source .venv/bin/activate

pip install git+https://github.com/capsolver-ai/capsolver-core.git
pip install "capsolver-agent[langchain] @ git+https://github.com/capsolver-ai/capsolver-agent.git"
pip install langchain-openai langgraph playwright

playwright install chromium

Simpan kredensial di luar kontrol sumber:

export CAPSOLVER_API_KEY="set-this-in-your-secret-manager"
export OPENAI_API_KEY="set-this-in-your-secret-manager"

Jangan tempelkan rahasia nyata ke dalam prompt, trace, notebook, isu, atau checkpoint. Variabel lingkungan nyaman untuk contoh lokal; gudang rahasia yang dikelola lebih disukai dalam sistem yang diterapkan.

Deteksi respons AWS WAF sebelum memanggil alat

Komponen deterministik pertama harus mengklasifikasikan respons. Contoh ini menggunakan kombinasi status dan header yang didokumentasikan oleh AWS:

from dataclasses import dataclass
from typing import Mapping, Literal

WafAction = Literal["challenge", "captcha", "none", "unknown"]


@dataclass(frozen=True)
class WafSignal:
    action: WafAction
    status_code: int
    needs_review: bool = False


def classify_aws_waf_response(
    status_code: int,
    headers: Mapping[str, str],
) -> WafSignal:
    normalized = {key.lower(): value.lower() for key, value in headers.items()}
    action = normalized.get("x-amzn-waf-action", "")

    if action == "challenge" and status_code == 202:
        return WafSignal(action="challenge", status_code=status_code)
    if action == "captcha" and status_code == 405:
        return WafSignal(action="captcha", status_code=status_code)
    if action in {"challenge", "captcha"}:
        return WafSignal(
            action="unknown",
            status_code=status_code,
            needs_review=True,
        )
    return WafSignal(action="none", status_code=status_code)

Butuhkan kedua sinyal. 202 sendirian bisa menjadi respons aplikasi yang valid, dan 405 sendirian bisa berarti endpoint tidak mengizinkan metode HTTP. Kombinasi yang tidak terduga harus dikirim ke ulasan alih-alih memicu loop pemulihan otomatis.

AWS juga mencatat bahwa JavaScript browser yang berjalan lintas asal tidak dapat membaca x-amzn-waf-action karena header ini tidak tersedia melalui CORS. Dalam situasi ini, klasifikasikan respons jaringan di lapisan otomatisasi browser atau gunakan integrasi same-origin yang dimiliki. Jangan menebak tantangan hanya dari teks halaman.

Klaim 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 penambahan dana — tanpa batas.
Klaim sekarang di Dashboard CapSolver Anda

Tambahkan pintu kebijakan deterministik

Penanganan tantangan tidak boleh tersedia untuk setiap URL yang dapat disebut model. Periksa target sebelum alat agen mana pun dijalankan:

from dataclasses import dataclass
from urllib.parse import urlparse


@dataclass(frozen=True)
class PolicyDecision:
    allowed: bool
    reason: str


ALLOWED_HOSTS = {"staging.example.com", "research.example.org"}
ALLOWED_PURPOSES = {"qa-validation", "authorized-research"}


def authorize_recovery(
    url: str,
    purpose: str,
    attempts: int,
) -> PolicyDecision:
    host = (urlparse(url).hostname or "").lower()

    if host not in ALLOWED_HOSTS:
        return PolicyDecision(False, "host-not-allowed")
    if purpose not in ALLOWED_PURPOSES:
        return PolicyDecision(False, "purpose-not-allowed")
    if attempts >= 2:
        return PolicyDecision(False, "retry-budget-exhausted")
    return PolicyDecision(True, "authorized")

Jaga fungsi ini di luar model bahasa. Di produksi, muat host dan tujuan yang disetujui dari konfigurasi yang diberi versi, tolak redirect ke host berbeda, dan catat hanya metadata keputusan yang tidak sensitif.

Daftarkan alat CapSolver untuk LangChain

Paket agen yang terdokumentasi dapat mengekspos alat kompatibel LangChain. Setup minimal terlihat seperti ini:

import os
from capsolver_agent.langchain import get_langchain_tools


capsolver_tools = get_langchain_tools(
    api_key=os.environ["CAPSOLVER_API_KEY"],
)

API pembuatan agen yang tepat dapat berubah di antara rilis LangChain dan LangGraph. Jaga akuisisi alat CapSolver di modul adapter kecil, pin versi dependensi yang telah diuji, dan hubungkan capsolver_tools melalui pembangun agen yang didukung oleh versi tersebut.

Jangan berikan setiap agen setiap alat. Pola yang lebih aman adalah mengekspos alat tantangan hanya di dalam subgraf pemulihan atau executor khusus yang dijalankan setelah authorize_recovery() mengembalikan allowed=True.

CapSolver mendokumentasikan peta alat agen pada tingkat tinggi:

• solve_captcha memanggil kemampuan solve inti;
• detect_captchas memanggil kemampuan detect inti;
• solve_on_page memanggil kemampuan solve_on_page inti;
• alat saldo dan jenis yang didukung menyediakan informasi akun atau kemampuan.

Gunakan hanya alat terkecil yang diperlukan untuk integrasi. Untuk sesi browser yang hidup, alur deteksi dan pengisian kembali berbasis browser biasanya mempertahankan lebih banyak konteks daripada meminta model untuk memanipulasi solusi mentah.

Jaga sesi browser di luar state agen

Token AWS WAF adalah bagian dari sesi klien. Dokumentasi token AWS WAF menjelaskan bahwa tindakan Challenge dan CAPTCHA menggunakan token untuk melacak interaksi yang berhasil. Mengganti browser atau kehilangan kukinya antara deteksi dan ulang coba dapat menghilangkan state tersebut.

Jangan serialisasi objek Playwright Page ke dalam pesan LangChain atau checkpoint grafik. Simpannya di registri yang dimiliki aplikasi:

class BrowserRegistry:
    def __init__(self) -> None:
        self._pages: dict[str, object] = {}

    def register(self, page_id: str, page: object) -> None:
        self._pages[page_id] = page

    def get(self, page_id: str) -> object:
        if page_id not in self._pages:
            raise KeyError("browser page is not registered")
        return self._pages[page_id]

    async def close(self, page_id: str) -> None:
        page = self._pages.pop(page_id, None)
        if page is not None:
            await page.close()

State agen harus berisi hanya page_id yang tidak berarti, URL saat ini, tujuan, jumlah percobaan, dan status. Keluarkan kuki, penyimpanan lokal, token solusi, kunci API, dan HTML mentah.

Arahkan alur kerja LangChain dengan hasil berjenis

Gunakan tipe hasil kecil sehingga model tidak dapat mereinterpretasi respons tingkat rendah:

from typing import Literal, TypedDict

RecoveryStatus = Literal[
    "not_needed",
    "authorized",
    "resolved",
    "retry",
    "review",
    "denied",
]


class RecoveryState(TypedDict, total=False):
    request_id: str
    purpose: str
    current_url: str
    page_id: str
    attempts: int
    waf_action: str
    recovery_status: RecoveryStatus
    error_code: str | None
    final_assertion_passed: bool


def route_after_detection(state: RecoveryState) -> str:
    if state.get("waf_action") not in {"challenge", "captcha"}:
        return "continue"
    if state.get("recovery_status") == "authorized":
        return "recover"
    if state.get("recovery_status") in {"denied", "review"}:
        return "human_review"
    return "authorize"


def route_after_recovery(state: RecoveryState) -> str:
    status = state.get("recovery_status")
    if status == "resolved":
        return "verify"
    if status == "retry":
        return "authorize"
    return "human_review"

Node pemulihan dapat memanggil alat browser CapSolver yang disetujui, tetapi harus mengembalikan hanya status dan kode kesalahan yang stabil. Jangan tempatkan respons alat mentah ke dalam prompt model berikutnya.

Verifikasi keberhasilan setelah langkah tantangan

Penyelesaian tantangan tidak membuktikan bahwa operasi bisnis asli berhasil. Ulangi navigasi atau permintaan yang dimaksudkan dalam sesi yang sama dan verifikasi sinyal aplikasi yang dimiliki:

async def verify_expected_page(page, expected_url_prefix: str) -> bool:
    await page.wait_for_load_state("domcontentloaded")

    if not page.url.startswith(expected_url_prefix):
        return False

    marker = page.get_by_test_id("authorized-content")
    try:
        await marker.wait_for(state="visible", timeout=15_000)
        return True
    except Exception:
        return False

Pilih marker stabil yang dikontrol oleh aplikasi Anda: ID tes, respons API spesifik, atau transisi state yang diketahui. Hindari asersi luas seperti "halaman berisi teks" karena halaman kesalahan dapat berisi kata-kata yang mirip.

Jika verifikasi gagal, jangan langsung memanggil solver lagi. Klasifikasikan ulang respons saat ini, periksa apakah sesi berubah, terapkan anggaran ulang coba, dan kirim kasus ambigu ke manusia.

Tangani ulang coba dan kegagalan tanpa loop

Alur kerja terbatas harus membedakan setidaknya kasus-kasus berikut:

Gunakan backoff eksponensial untuk kesalahan transportasi sementara, tetapi jangan gunakan loop tanpa batas. Penjelasan ulang coba milik state deterministik, bukan memori model.

Lacak peristiwa seperti waf_signal_detected, policy_allowed, recovery_started, recovery_finished, dan page_verified. Sertakan ID permintaan, host, durasi, jumlah percobaan, dan kode kesalahan. Keluarkan kredensial, kuki, token, payload tantangan mentah, dan konten halaman sensitif.

Pantau perilaku AWS WAF dan agen

Agent traces menunjukkan apa yang telah diputuskan oleh alur kerja; metrik AWS menunjukkan apa yang diamati oleh lapisan perlindungan. AWS mencantumkan metrik CloudWatch untuk aktivitas Challenge dan CAPTCHA, termasuk jumlah permintaan, percobaan, penyelesaian, dan token yang valid dalam referensi metrik WAF.

Pertanyaan operasional yang berguna termasuk:

• Apakah volume challenge berubah setelah rilis aplikasi?
• Apakah ulang percobaan agen terpusat pada satu rute?
• Apakah verifikasi aplikasi gagal setelah langkah pemulihan?
• Apakah penolakan kebijakan disebabkan oleh redirect yang tidak terduga?
• Apakah timeout terjadi di browser, tool adapter, atau permintaan akhir?

Korelasikan sistem dengan ID permintaan internal, bukan kredensial atau token. Peningkatan tajam pada lalu lintas challenge harus memicu diagnosis, bukan anggaran ulang yang lebih besar secara default.

Kesalahan implementasi umum

Membiarkan model menebak challenge dari teks halaman

Teks bersifat ambigu dan mudah berubah. Lebih baik menggunakan respons status dan header yang telah didokumentasikan, peristiwa jaringan browser, atau sinyal yang dimiliki aplikasi.

Memulai browser baru setelah deteksi

Browser baru dapat kehilangan kuki dan status token. Pertahankan sesi yang disetujui yang sama selama deteksi, pemulihan, ulang, dan verifikasi.

Mengembalikan token mentah ke agen

Model tidak membutuhkannya. Simpan nilai sensitif di dalam adapter deterministik dan kembalikan status yang berjenis.

Menganggap keberhasilan tool sebagai keberhasilan alur kerja

Selalu ulangi operasi yang dimaksudkan dan periksa asersi khusus domain.

Memberikan target yang tidak terbatas kepada tool

Pastikan daftar izin hostname, pemeriksaan tujuan, pemeriksaan redirect, anggaran ulang, dan tinjauan rute di luar model.

Menyalin contoh tanpa menetapkan versi

API konstruksi LangChain dan LangGraph berkembang. Tetapkan versi yang lulus uji Anda, pisahkan kabel framework dalam satu modul, dan jalankan kembali uji integrasi sebelum pembaruan.

Uji alur kerja sebelum produksi

Gunakan halaman staging yang dimiliki dan cakup kasus-kasus ini:

1. respons normal tanpa challenge;
2. sinyal Challenge yang telah didokumentasikan;
3. sinyal CAPTCHA yang telah didokumentasikan;
4. perbedaan status dan header;
5. hostname yang tidak disetujui;
6. redirect di luar daftar izin;
7. sesi browser yang hilang;
8. timeout tool;
9. asersi akhir yang gagal;
10. anggaran ulang habis.

Palsukan klasifikator, gate kebijakan, dan verifikator dalam pengujian unit. Cadangkan pengujian end-to-end yang menggunakan kredensial untuk lingkungan yang disetujui. Uji log juga: pastikan kredensial, kuki, dan token tidak hadir.

Panduan mulai cepat CapSolver mendokumentasikan siklus tugasnya dan kategori CAPTCHA yang didukung. Gunakan dokumentasi resmi terkini saat memilih jalur tugas; jangan menebak bidang dari potongan lama atau posting pihak ketiga.

Kesimpulan

Integrasi AWS WAF LangChain yang andal adalah mesin keadaan yang terkendali, bukan satu "solve" prompt. Deteksi sinyal WAF yang telah didokumentasikan, verifikasi target dan tujuan, panggil alat yang sempit, pertahankan sesi klien yang sama, dan konfirmasi operasi asli sebelum agen melanjutkan.

Untuk otomatisasi yang diizinkan, CapSolver menyediakan lapisan agen dan inti yang diperlukan untuk menghubungkan penanganan challenge ke LangChain sambil menjaga kebijakan, rahasia, dan verifikasi akhir dalam kode aplikasi.

Bangun Alur Kerja Otomatis yang Handal dengan CapSolver

Gunakan dokumentasi CapSolver untuk memvalidasi jalur integrasi saat ini, lalu coba CapSolver di lingkungan pengujian yang dimiliki atau secara eksplisit diizinkan. Gunakan kode bonus CAP26 saat menambahkan dana untuk menerima bonus 5% yang dikonfigurasi.

FAQ

P: Bagaimana agen LangChain mendeteksi AWS WAF Challenge?

Periksa kombinasi HTTP 202 dan x-amzn-waf-action: challenge yang telah didokumentasikan di lapisan HTTP atau browser yang deterministik. Jangan meminta model bahasa untuk menebak kondisi dari teks halaman.

P: Apa respons yang menunjukkan tindakan AWS WAF CAPTCHA?

AWS mendokumentasikan HTTP 405 dengan x-amzn-waf-action: captcha untuk respons CAPTCHA ketika permintaan tidak memiliki token yang valid. Anggap kombinasi status dan header yang tidak sesuai sebagai tidak diketahui dan arahkan ke tinjauan.

P: Apakah kunci API CapSolver harus dikirim ke model LangChain?

Tidak. Muat di dalam aplikasi atau adapter alat dari penyimpanan rahasia yang disetujui. Model tidak boleh melihat kunci, kuki, token WAF, atau nilai solusi mentah.

P: Apakah agen dapat menggunakan browser baru setelah challenge selesai?

Sebaiknya pertahankan konteks browser yang sama jika memungkinkan karena status token WAF AWS terkait dengan sesi klien. Mengganti sesi dapat menghilangkan status yang diperlukan untuk permintaan ulang.

P: Apakah hasil alat challenge yang sukses cukup untuk melanjutkan?

Tidak. Ulangi operasi yang dimaksudkan dan periksa asersi keberhasilan khusus domain. Hasil alat hanya merupakan keadaan sementara.

P: Berapa kali agen seharusnya mengulang?

Atur anggaran ulang kecil yang eksplisit berdasarkan risiko dan batas waktu alur kerja. Contoh menggunakan dua percobaan sebagai kebijakan aplikasi, bukan jaminan CapSolver atau AWS.

P: Apakah alur kerja ini dapat digunakan di situs web apa pun?

Tidak. Gunakan hanya pada sistem yang Anda miliki atau diizinkan secara eksplisit untuk otomatisasi. Pastikan pemeriksaan target dan tujuan di luar model dan arahkan kasus yang tidak pasti ke tinjauan manusia.