Cách giải quyết AWS WAF trong LangChain với CapSolver

TL;DR

• AWS WAF có thể trả về một phản hồi 202 Challenge hoặc 405 CAPTCHA khi một yêu cầu không mang theo token hợp lệ; hãy kiểm tra cả trạng thái và tiêu đề x-amzn-waf-action trước khi định tuyến một agent.
• Một quy trình LangChain đáng tin cậy tách biệt suy nghĩ của mô hình khỏi xác thực chắc chắn, xử lý thử thách, lưu trữ phiên và kiểm tra trang cuối cùng.
• CapSolver ghi chú một bộ thích ứng agent trên capsolver-core, với các công cụ LangChain sẵn có và phương pháp phát hiện và điền lại có hướng trình duyệt.
• Giữ cookie, thông tin xác thực, token giải pháp và đối tượng trình duyệt bên ngoài prompt và trạng thái agent. Chỉ cung cấp cho mô hình một kết quả nhỏ, có kiểu như resolved, not_needed, review, hoặc denied.
• Xem xét việc hoàn thành thử thách là một kết quả trung gian. Quy trình nên lặp lại yêu cầu mong muốn và kiểm tra điều kiện thành công cụ thể của ứng dụng trước khi tiếp tục.
• Các ví dụ dưới đây dành cho hệ thống sở hữu hoặc được ủy quyền rõ ràng. Chúng được kiểm tra cú pháp, nhưng một lần chạy end-to-end thực tế vẫn cần trang thử nghiệm được phê duyệt và thông tin xác thực thực tế.

Cách AWS WAF ảnh hưởng đến agent LangChain

Hành vi của các hành động Challenge và CAPTCHA của AWS WAF thay đổi con đường yêu cầu bình thường. Theo tài liệu hành động AWS WAF, một yêu cầu có token hợp lệ sẽ tiếp tục đến quy tắc tiếp theo. Một yêu cầu không có token hợp lệ có thể nhận được phản hồi thử thách.

Đối với Challenge, AWS ghi chú tiêu đề phản hồi x-amzn-waf-action: challenge và trạng thái HTTP 202. Đối với CAPTCHA, nó ghi chú x-amzn-waf-action: captcha và trạng thái 405. Khi khách hàng kỳ vọng HTML, AWS WAF có thể trả về một trang trung gian JavaScript. Tương tác thành công cập nhật token và gửi lại yêu cầu gốc.

Hành vi này quan trọng đối với agent vì một khách hàng HTTP thông thường có thể hiểu phản hồi là trang bình thường, lỗi máy chủ tạm thời hoặc kết quả trống. Một mô hình ngôn ngữ không nên đoán trường hợp nào xảy ra. Ứng dụng chủ sở hữu nên phân loại phản hồi, kiểm tra xác thực và định tuyến quy trình thông qua bước phục hồi được kiểm soát.

Mục tiêu không phải là làm cho việc xử lý thử thách trở nên vô hình. Mục tiêu là làm cho nó rõ ràng, có giới hạn, quan sát được và chỉ giới hạn ở tự động hóa hợp pháp trên các hệ thống mà người vận hành sở hữu hoặc có quyền kiểm tra.

Kiến trúc cho LangChain, AWS WAF và CapSolver

Một thiết kế sản xuất có năm trách nhiệm riêng biệt:

1. Agent LangChain: chọn hành động kinh doanh tiếp theo từ tập công cụ hạn chế.
2. Khách hàng HTTP hoặc trình duyệt: sở hữu phiên hiện tại, cookie, tiêu đề và trạng thái trang.
3. Cổng chính sách: kiểm tra tên miền, mục đích, hành động và ngân sách thử lại.
4. Bộ thích ứng CapSolver: cung cấp khả năng nhận dạng được ghi chú và phương pháp điền lại trình duyệt.
5. Bộ xác minh: lặp lại thao tác mong muốn và kiểm tra điều kiện thành công cụ thể của ứng dụng.

Hướng dẫn công cụ agent chính thức của CapSolver ghi chú capsolver-agent là một bộ thích ứng mỏng trên capsolver-core. Gói core thực hiện các thao tác như solve, detect và solve_on_page; gói agent cung cấp các lược đồ công cụ thân thiện với khung. Đường dẫn LangChain được ghi chú cung cấp các công cụ sẵn có thông qua get_langchain_tools().

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

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

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)

Nhận mã thưởng CapSolver của bạn

Tăng ngân sách tự động hóa của bạn ngay lập tức!
Sử dụng mã thưởng CAP26 khi nạp tiền vào tài khoản CapSolver để nhận thêm 5% thưởng trên mỗi lần nạp tiền — không giới hạn.
Nhận mã thưởng ngay bây giờ trong Bảng điều khiển CapSolver

Thêm cổng chính sách xác định

Việc xử lý thử thách không nên có sẵn cho mọi URL mà mô hình có thể đề cập. Kiểm tra mục tiêu trước khi bất kỳ công cụ agent nào được thực thi:

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")

Giữ hàm này bên ngoài mô hình ngôn ngữ. Trong sản xuất, tải các tên miền và mục đích được phê duyệt từ cấu hình có phiên bản, từ chối chuyển hướng đến tên miền khác và ghi lại chỉ dữ liệu quyết định không nhạy cảm.

Đăng ký công cụ CapSolver cho LangChain

Gói agent được ghi chú có thể phơi bày các công cụ tương thích LangChain. Một thiết lập tối thiểu trông như sau:

import os
from capsolver_agent.langchain import get_langchain_tools


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

API xây dựng agent có thể thay đổi qua các phiên bản LangChain và LangGraph. Giữ việc thu thập công cụ CapSolver trong một mô-đun thích ứng nhỏ, cố định phiên bản phụ thuộc được kiểm tra và kết nối capsolver_tools thông qua người xây dựng agent được hỗ trợ bởi các phiên bản đó.

Không cung cấp mọi công cụ cho mọi agent. Mẫu an toàn hơn là phơi bày các công cụ thử thách chỉ bên trong một đồ thị phục hồi hoặc người thực thi chuyên dụng chạy sau khi authorize_recovery() trả về allowed=True.

CapSolver ghi chú bản đồ công cụ agent ở cấp độ cao:

• solve_captcha gọi khả năng solve của core;
• detect_captchas gọi khả năng detect của core;
• solve_on_page gọi khả năng solve_on_page của core;
• các công cụ cân bằng và loại được hỗ trợ cung cấp thông tin về tài khoản hoặc khả năng.

Chỉ sử dụng công cụ nhỏ nhất cần thiết cho tích hợp. Đối với phiên trình duyệt sống, quy trình phát hiện và điền lại có hướng trình duyệt thường bảo tồn nhiều ngữ cảnh hơn so với việc mô hình thao tác giải pháp thô.

Giữ phiên trình duyệt bên ngoài trạng thái agent

Token AWS WAF là một phần của phiên khách hàng. Tài liệu token AWS WAF giải thích rằng các hành động Challenge và CAPTCHA sử dụng token để theo dõi tương tác thành công. Thay thế trình duyệt hoặc mất cookie của nó giữa phát hiện và thử lại có thể xóa trạng thái đó.

Không serialize đối tượng Playwright Page vào tin nhắn LangChain hoặc điểm kiểm tra đồ thị. Lưu trữ nó trong một thư viện do ứng dụng sở hữu:

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()

Trạng thái agent nên chứa chỉ page_id mờ, URL hiện tại, mục đích, số lần thử và trạng thái. Loại bỏ cookie, bộ nhớ cục bộ, token giải pháp, khóa API và HTML thô.

Định tuyến quy trình LangChain với kết quả có kiểu

Sử dụng kiểu kết quả nhỏ để mô hình không thể tái diễn một phản hồi cấp thấp:

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"

Nút phục hồi có thể gọi công cụ trình duyệt CapSolver được phê duyệt, nhưng nó nên trả về chỉ trạng thái và mã lỗi ổn định. Không đặt phản hồi công cụ thô vào prompt tiếp theo của mô hình.

Xác minh thành công sau bước thử thách

Hoàn thành thử thách không chứng minh rằng thao tác kinh doanh ban đầu đã thành công. Lặp lại điều hướng hoặc yêu cầu mong muốn trong cùng phiên và kiểm tra tín hiệu ứng dụng sở hữu:

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

Chọn một điểm đánh dấu ổn định do ứng dụng kiểm soát: ID kiểm tra, phản hồi API cụ thể hoặc chuyển tiếp trạng thái đã biết. Tránh các tuyên bố rộng như "trang chứa văn bản" vì trang lỗi có thể chứa các từ tương tự.

Nếu xác minh thất bại, đừng gọi giải pháp lại ngay lập tức. Phân loại lại phản hồi hiện tại, kiểm tra xem phiên có thay đổi không, áp dụng ngân sách thử lại và gửi các trường hợp mơ hồ đến con người.

Xử lý thử lại và lỗi mà không có vòng lặp

Một quy trình có giới hạn nên phân biệt ít nhất các trường hợp sau:

Sử dụng backoff mũ cho lỗi truyền tải tạm thời, nhưng không sử dụng vòng lặp không giới hạn. Bộ đếm thử lại thuộc về trạng thái xác định, không phải bộ nhớ mô hình.

Ghi sự kiện như waf_signal_detected, policy_allowed, recovery_started, recovery_finished và page_verified. Bao gồm ID yêu cầu, tên miền, thời gian, số lần thử và mã lỗi. Loại bỏ thông tin xác thực, cookie, token, dữ liệu thử thách thô và nội dung trang nhạy cảm.

Giám sát hành vi của AWS WAF và agent

Các dấu vết của agent cho thấy workflow đã quyết định; các chỉ số AWS cho thấy điều lớp bảo vệ quan sát được. AWS liệt kê các chỉ số CloudWatch cho hoạt động Challenge và CAPTCHA, bao gồm số lượng yêu cầu, thử, giải quyết và token hợp lệ trong tham khảo chỉ số WAF.

Các câu hỏi vận hành hữu ích bao gồm:

• Khối lượng thử thách có thay đổi sau khi phát hành ứng dụng không?
• Các lần thử lại của agent có tập trung vào một đường dẫn nhất định không?
• Bộ xác minh ứng dụng có thất bại sau bước phục hồi không?
• Các từ chối chính sách có do chuyển hướng không mong muốn không?
• Các thời gian chờ có xảy ra ở trình duyệt, bộ thích ứng công cụ hay yêu cầu cuối cùng không?

Kết nối các hệ thống bằng ID yêu cầu nội bộ, không phải bằng chứng chỉ hoặc token. Một sự gia tăng đột ngột trong lưu lượng thử thách nên kích hoạt chẩn đoán, không phải ngân sách thử lại lớn hơn mặc định.

Những sai lầm phổ biến trong triển khai

Để mô hình suy luận thử thách từ nội dung trang

Nội dung trang dễ gây hiểu lầm và dễ thay đổi. Ưu tiên trạng thái phản hồi và tiêu đề được tài liệu hóa, sự kiện mạng trình duyệt hoặc tín hiệu do ứng dụng sở hữu.

Khởi động trình duyệt mới sau khi phát hiện

Một trình duyệt mới có thể mất cookie và trạng thái token. Giữ cùng phiên được phê duyệt qua phát hiện, phục hồi, thử lại và xác minh.

Trả về token thô cho agent

Mô hình không cần chúng. Giữ các giá trị nhạy cảm bên trong bộ chuyển đổi xác định và trả về trạng thái có kiểu.

Xem thành công công cụ là thành công workflow

Luôn lặp lại thao tác mong muốn và kiểm tra một sự xác nhận chuyên biệt cho lĩnh vực.

Cho phép công cụ truy cập bất kỳ đích nào

Áp dụng danh sách cho phép tên miền, kiểm tra mục đích, kiểm tra chuyển hướng, ngân sách thử lại và xem xét đường dẫn bên ngoài mô hình.

Sao chép ví dụ mà không cố định phiên bản

API xây dựng LangChain và LangGraph thay đổi theo thời gian. Cố định phiên bản đã vượt qua bài kiểm tra của bạn, cô lập dây chuyền khung phần mềm trong một mô-đun và chạy lại kiểm tra tích hợp trước khi nâng cấp.

Kiểm tra workflow trước khi sản xuất

Sử dụng trang thử nghiệm do bạn sở hữu và kiểm tra các trường hợp sau:

1. Phản hồi bình thường mà không có thử thách;
2. Tín hiệu thử thách được tài liệu hóa;
3. Tín hiệu CAPTCHA được tài liệu hóa;
4. Sự không khớp giữa trạng thái và tiêu đề;
5. Tên miền không được phê duyệt;
6. Chuyển hướng bên ngoài danh sách cho phép;
7. Phiên trình duyệt bị thiếu;
8. Thời gian chờ công cụ;
9. Xác nhận cuối cùng thất bại;
10. Ngân sách thử lại hết.

Mô phỏng bộ phân loại, cổng chính sách và bộ xác minh trong kiểm tra đơn vị. Dành kiểm tra end-to-end có chứng chỉ cho môi trường được phê duyệt. Kiểm tra nhật ký cũng vậy: xác nhận rằng chứng chỉ, cookie và token không xuất hiện.

Hướng dẫn bắt đầu với CapSolver ghi lại chu kỳ cuộc sống nhiệm vụ và các danh mục CAPTCHA được hỗ trợ. Sử dụng tài liệu chính thức hiện tại khi chọn đường dẫn nhiệm vụ; không đoán các trường từ đoạn mã cũ hoặc bài viết của bên thứ ba.

Kết luận

Một tích hợp AWS WAF LangChain đáng tin cậy là một máy trạng thái được kiểm soát, không phải một "giải quyết" duy nhất. Phát hiện tín hiệu WAF được tài liệu hóa, xác minh mục đích và đích, gọi công cụ có phạm vi hẹp, giữ cùng phiên khách hàng, và xác nhận thao tác ban đầu trước khi agent tiếp tục.

Đối với tự động hóa được ủy quyền, CapSolver cung cấp lớp agent và lớp cốt lõi cần thiết để kết nối xử lý thử thách với LangChain trong khi giữ chính sách, bí mật và xác minh cuối cùng trong mã ứng dụng.

Xây dựng quy trình tự động đáng tin cậy với CapSolver

Sử dụng tài liệu của CapSolver để xác minh đường tích hợp hiện tại, sau đó thử CapSolver trên môi trường thử nghiệm do bạn sở hữu hoặc được ủy quyền rõ ràng. Áp dụng mã khuyến mãi CAP26 khi nạp tiền để nhận khuyến mãi 5% được cấu hình.

Câu hỏi thường gặp

Câu hỏi: Agent LangChain phát hiện thử thách AWS WAF như thế nào?

Kiểm tra sự kết hợp được tài liệu hóa của HTTP 202 và x-amzn-waf-action: challenge trong lớp HTTP hoặc trình duyệt xác định. Không yêu cầu mô hình ngôn ngữ suy luận điều kiện từ nội dung trang.

Câu hỏi: Trả lời nào cho thấy hành động CAPTCHA của AWS WAF?

AWS tài liệu hóa HTTP 405 với x-amzn-waf-action: captcha cho phản hồi CAPTCHA khi yêu cầu không có token hợp lệ. Xử lý sự không khớp giữa trạng thái và tiêu đề như không xác định và định tuyến nó đến xem xét.

Câu hỏi: API khóa CapSolver có nên được truyền đến mô hình LangChain không?

Không. Tải nó bên trong ứng dụng hoặc bộ thích ứng công cụ từ kho lưu trữ chứng chỉ được phê duyệt. Mô hình nên không bao giờ nhìn thấy khóa, cookie, token WAF hoặc giá trị giải quyết thô.

Câu hỏi: Agent có thể sử dụng trình duyệt mới sau khi thử thách được hoàn thành không?

Nên giữ cùng ngữ cảnh trình duyệt khi có thể vì trạng thái token WAF AWS liên quan đến phiên khách hàng. Thay thế phiên có thể xóa trạng thái cần thiết cho yêu cầu lặp lại.

Câu hỏi: Kết quả công cụ thử thách thành công có đủ để tiếp tục không?

Không. Lặp lại thao tác mong muốn và xác minh sự xác nhận thành công chuyên biệt cho ứng dụng. Kết quả công cụ chỉ là trạng thái trung gian.

Câu hỏi: Agent nên thử lại bao nhiêu lần?

Đặt ngân sách thử lại nhỏ và rõ ràng dựa trên rủi ro và giới hạn thời gian của workflow. Các ví dụ sử dụng hai lần thử như chính sách ứng dụng, không phải cam kết của CapSolver hoặc AWS.

Câu hỏi: Quy trình này có thể sử dụng trên bất kỳ trang web nào không?

Không. Chỉ sử dụng trên các hệ thống bạn sở hữu hoặc được ủy quyền rõ ràng để tự động hóa. Áp dụng kiểm tra đích và mục đích bên ngoài mô hình và định tuyến các trường hợp không chắc chắn đến xem xét của con người.