Cách Thêm Công Cụ Phát Hiện CAPTCHA vào Các Tác Tử Haystack

Tóm tắt nhanh

• Một công cụ Haystack có thể gọi CapSolver Core SDK chính thức để kiểm tra tham số CAPTCHA trên một trang trình duyệt hiện có.
• Gắn công cụ với trang mà ứng dụng của bạn đã kiểm soát, thay vì để một agent tự do điều hướng tới URL bất kỳ thông qua công cụ kiểm tra.
• Ví dụ runnable trả về loại CAPTCHA, URL trang và public site key từ một trang cục bộ dùng widget reCAPTCHA v2 test của Google.
• Đây là tích hợp Python thuần: không cần máy chủ MCP hoặc lớp truyền thông nào.
• Việc phát hiện không tạo tác vụ giải CAPTCHA, không trả về token, và không chứng minh ứng dụng đã chấp nhận việc xác minh.

Một agent chạy trong trình duyệt cần thông tin hữu ích khi CAPTCHA làm gián đoạn công việc của nó. Tiêu đề trang hoặc ảnh chụp màn hình thường không đủ để cho agent biết họ CAPTCHA nào đang hiện diện hoặc tham số nào bước tiếp theo cần dùng. Trả về một kết quả có cấu trúc nhỏ giúp ứng dụng có một điểm quyết định rõ ràng trước khi yêu cầu lời giải.

Haystack là framework Python để xây dựng ứng dụng AI, pipeline truy vấn và agent. Các tool native của nó có thể bọc những hàm do các ứng dụng đó sử dụng. Hướng dẫn này nối một Haystack tool với CapSolver cho một nhiệm vụ cụ thể: kiểm tra trang trình duyệt hiện tại và trả về tham số CAPTCHA. Ví dụ dùng một trang phát triển và không thực hiện yêu cầu giải trả phí. Nó cung cấp cho bạn một thành phần kiểm tra hoạt động để đặt trước một bước giải riêng biệt đã được cấp quyền.

CAPTCHA tool nằm ở đâu trong quy trình Haystack

Công cụ kiểm tra CAPTCHA nằm giữa hành động trình duyệt đi đến điểm kiểm tra xác minh và đoạn mã quyết định xử lý điểm kiểm tra đó ra sao. Trình duyệt vẫn sở hữu việc điều hướng và trang hiện tại. Haystack cung cấp giao diện tool; Core SDK đọc thông tin CAPTCHA được hỗ trợ.

Ví dụ, một nhóm đang test form của chính mình có thể để trình duyệt đi tới form, gọi công cụ kiểm tra và xem loại và site key được trả về. Bộ test sau đó có thể chọn đường đi test-key đã được phê duyệt hoặc một lần kiểm tra solver được cấu hình riêng. Nó không nên coi chính widget CAPTCHA là nội dung nghiệp vụ của form.

Đây là một tích hợp cho lập trình viên, sử dụng abstraction Tool được Haystack ghi chép, chứ không phải tuyên bố về một plugin Haystack chuyên dụng. Tool này có mục đích hẹp và không cần LLM để chạy. Gọi trực tiếp nó rất hữu ích trước khi thêm phần chọn tool do mô hình điều khiển.

Cần gì trước khi chạy ví dụ

Bạn cần Python, gói Haystack, CapSolver Core SDK với phụ thuộc Playwright, và Chromium đã cài cho Playwright. Ví dụ dưới đây chạy với Python 3.12, haystack-ai 3.4.0, capsolver-core 0.1.1 và Playwright 1.64.0. Đây là các phiên bản đã được test, không phải khẳng định chúng là bản phát hành mới nhất.

Trình duyệt phải có khả năng tải script reCAPTCHA công khai của Google. Trang cục bộ dùng development site key được Google ghi chép; đây không phải key production và không được triển khai như key production. Tài liệu hướng dẫn test reCAPTCHA của Google giải thích sự khác nhau giữa test key và xác minh production.

Ví dụ chỉ kiểm tra này không cần CapSolver API key hay key nhà cung cấp mô hình. Một bước giải sau đó cần key tài khoản CapSolver hợp lệ. Một Haystack Agent do LLM điều khiển sau này cần nhà cung cấp mô hình đã được cấu hình riêng. Đó là các điều kiện tiên quyết tách biệt, vì vậy đừng xử lý sự cố thiếu thông tin xác thực mô hình bằng cách thay đổi tham số CAPTCHA.

Cài đặt các gói đã được test

Tạo một virtual environment và cài các gói vào đó. Chạy lệnh cài Chromium bằng cùng trình thông dịch Python để giữ phụ thuộc trình duyệt khớp với 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

Các lệnh trên dùng đường dẫn môi trường kiểu POSIX. Nếu hệ điều hành của bạn dùng layout virtual environment khác, hãy dùng Python executable của môi trường đó. Hướng dẫn cài đặt Playwright cho Python bao quát yêu cầu cài đặt trình duyệt của nó.

Tạo một tool kiểm tra trang hiện tại

Tool bọc get_captcha_info(page) từ Core SDK chính thức. Trang được hàm thu nhận, nên tool không có tham số điều hướng. JSON schema cho tham số của nó không nhận trường input nào.

Lưu nội dung sau dưới tên haystack_captcha_inspection.py. Phản hồi HTML cục bộ được cung cấp bởi Playwright routing; đây là fixture phát triển, không phải ứng dụng được host từ xa. Bản thân script reCAPTCHA được tải từ Google. Chương trình đọc tham số mà không nhấp vào widget hoặc gửi 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())

Tham số async_function rất quan trọng vì các thao tác của SDK và Playwright là bất đồng bộ. Tài liệu tham chiếu Tool API của Haystack ghi chép invoke_async() cho đường đi này. Đưa một coroutine vào luồng gọi chỉ đồng bộ có thể khiến lỗi xảy ra trước khi bất kỳ kiểm tra CAPTCHA nào được thực hiện.

Các context manager và khối finally đóng tài nguyên SDK và trình duyệt. Hãy giữ phần dọn dẹp này khi bạn điều chỉnh ví dụ cho ứng dụng chạy lâu hơn; nếu không, một lần tải trang thất bại có thể để lại các tiến trình trình duyệt phía sau.

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

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

Chạy việc kiểm tra và hiểu kết quả

Chạy script sẽ gọi trực tiếp Haystack tool và in ra dictionary mà nó trả về. Trong ví dụ, dictionary này chứa một danh sách captchas với một mục reCAPTCHA v2.

.venv/bin/python haystack_captcha_inspection.py

Lần chạy cục bộ trả về type bằng reCaptchaV2, website_url bằng http://127.0.0.1:8765/, và public test site key được cấu hình trong HTML. Các trường này được đọc thông qua SDK và trình duyệt thật, không phải được điền sẵn trong phản hồi tool giả lập.

Kết quả được giữ cố ý nhỏ gọn. Descriptor đầy đủ từ SDK có thể chứa thêm trường, nhưng một agent chỉ nên nhận những gì nó cần cho quyết định tiếp theo. Site key là định danh widget công khai; nó không phải key tài khoản CapSolver hay bí mật xác minh riêng của site.

Lần chạy này xác nhận rằng Haystack có thể gọi hàm async, trình duyệt có thể tải widget phát triển, và Core SDK có thể đọc tham số của nó. Nó không xác nhận việc chọn tool bằng mô hình, phát hiện CAPTCHA production trên mọi site, tạo token thành công, hay được backend của website chấp nhận. Những điều đó cần các kiểm tra riêng với ứng dụng thực tế.

Gắn trang đã kiểm tra vào agent hiện có của bạn

Giữ nguyên đối tượng Tool và liên kết với trang khi thêm khả năng này vào Haystack Agent của bạn. Agent của Haystack nhận tool thông qua cấu hình tools được ghi chép. Đăng ký đối tượng này cùng với những tool mà ứng dụng của bạn đã dùng, đồng thời giữ phiên trang trình duyệt sống trong suốt thời gian gọi.

Trong quy trình trình duyệt sẵn có, hãy thay phần thiết lập fixture cục bộ bằng trang mà ứng dụng của bạn đã mở và được phép kiểm tra. Giữ việc điều hướng trình duyệt bên ngoài tool này. Điều đó làm cho việc chọn trang trở nên rõ ràng và ngăn một URL do mô hình sinh ra âm thầm thay đổi mục tiêu kiểm tra.

Đặt tên và mô tả tool chính xác. Mô tả trong ví dụ nói rằng nó đọc thông tin CAPTCHA và không giải hay gửi. Một mô tả kiểu “hoàn tất xác minh” sẽ hứa hẹn nhiều hơn chức năng thực sự và có thể khiến agent báo cáo thành công quá sớm.

Một quyết định ứng dụng hữu ích là: nếu kết quả chứa một widget đã nhận diện với tham số cần thiết, hãy đưa ra bước tiếp theo phù hợp; nếu rỗng hoặc không đầy đủ, hãy thu thập thêm bằng chứng hoặc yêu cầu con người xem xét. Đừng thêm vòng lặp vô điều kiện cứ tiếp tục kiểm tra cùng một trang chưa đầy đủ.

Giữ việc phát hiện và giải là hai bước riêng

Kết quả kiểm tra là đầu vào cho quyết định dùng solver, không phải lời giải CAPTCHA. Core SDK ghi chép solve(info) cho việc giải token và solve_on_page(page) cho workflow rộng hơn trên trình duyệt. Chúng có tác động khác với get_captcha_info(page) và cần cấu hình, cấp quyền riêng.

Trong hướng dẫn này, hãy giữ tool kiểm tra ở mục đích chỉ-đọc. Nếu sau đó bạn thêm tool giải, hãy để ứng dụng xác thực loại CAPTCHA được phát hiện và trang hiện tại, cung cấp thông tin xác thực tài khoản bên ngoài các tham số hiển thị với mô hình, và áp dụng quy tắc ngân sách, phê duyệt phù hợp với workflow đó. Trả về kết quả rõ ràng phân biệt token với một hành động ứng dụng đã hoàn tất.

Một token được trả về vẫn cần được ứng dụng xử lý phù hợp. Việc xác minh và kết quả form của chính site quyết định xem thao tác dự định có thành công không. Một danh sách captchas không rỗng hay một lần gọi tool Haystack thành công đều không phải là bằng chứng rằng ứng dụng đã chấp nhận phản hồi CAPTCHA.

Xử lý sự cố kết nối mà không đoán mò

Xử lý sự cố nên xác định rõ lớp nào bị lỗi: cài gói, khởi động trình duyệt, tải widget, kiểm tra bằng SDK hay gọi tool. Hãy thay đổi lớp tương ứng với lỗi thay vì thay luôn nhiều thành phần cùng lúc.

Thiếu executable trình duyệt

Cài Chromium bằng lệnh Playwright từ virtual environment đang hoạt động. Một lần pip install thành công chỉ cài gói Python, không tự thân chứng minh binary trình duyệt phù hợp đã có.

Widget chờ quá thời gian

Kiểm tra xem trình duyệt có tải script Google hay không và trang test có tạo widget hay không. Lệnh chờ trong ví dụ này tìm các client của widget đã được khởi tạo. Lỗi mạng có thể xảy ra trước khi SDK có gì đó để kiểm tra; thử lại solver sẽ không xử lý được lỗi đó.

Tool trả về danh sách rỗng

Kết quả rỗng nghĩa là lần kiểm tra này không tìm thấy descriptor được hỗ trợ nào trên trang tại thời điểm đó. Điều đó không chứng minh rằng trang không có cơ chế xác minh. Hãy kiểm tra thời điểm trang, đối tượng trang bạn truyền vào, và widget thực tế. Hướng dẫn kiểm tra tham số CAPTCHA cung cấp một cách bổ sung để xem trạng thái trình duyệt.

Tool hoạt động khi chạy trực tiếp nhưng không trong agent

Hãy kiểm tra xem cùng một đối tượng Tool có được đăng ký hay không, mô hình của agent có hỗ trợ workflow tool dự kiến không, và phiên trình duyệt có còn mở không. Giữ việc gọi trực tiếp đã thành công như một checkpoint riêng để cấu hình mô hình lỗi không bị báo nhầm thành lỗi CAPTCHA API.

Làm cho kết quả kiểm tra trở nên hữu ích

Một tool kiểm tra CAPTCHA nhỏ giúp ứng dụng Haystack có checkpoint cụ thể trước khi giải. Bắt đầu bằng trang phát triển đã được test, giữ nguyên lệnh gọi async và dọn dẹp, rồi gắn tool vào trang mà quy trình hiện có của bạn đang kiểm soát. Chỉ mở rộng trách nhiệm của nó khi mỗi thao tác bổ sung đều có input rõ ràng, hành vi đã được kiểm chứng và kết quả có thể quan sát.

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

Hãy dùng CapSolver cho bước CAPTCHA được hỗ trợ trong một workflow mà bạn được phép chạy. Giữ trình duyệt, kết quả solver và kết quả ứng dụng là các lần kiểm tra riêng biệt để một lần gọi tool thành công không che giấu một tác vụ thất bại.

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

Hỏi: Tích hợp này có cần MCP không?

Không. Ví dụ dùng Haystack Tool native và Python Core SDK trong cùng một ứng dụng. Nó không khởi chạy máy chủ MCP.

Hỏi: Tôi có cần LLM API key để chạy script không?

Không. Script gọi Tool trực tiếp. Thông tin xác thực của nhà cung cấp mô hình chỉ trở nên cần thiết khi bạn thêm một agent do LLM điều khiển xung quanh tool đó.

Hỏi: Ví dụ có giải CAPTCHA test không?

Không. Nó tải widget và đọc tham số công khai. Nó không yêu cầu token solver cũng không gửi form.

Hỏi: Cùng cách tiếp cận này có thể kiểm tra một trang Playwright hiện có không?

Có. Gắn tool với trang đã được cấp quyền hiện có và giữ trang đó sống trong quá trình gọi. Các trường descriptor được hỗ trợ phụ thuộc vào những gì SDK có thể phát hiện trên trang đó.
Hỏi: Tại sao dùng một công cụ không có đối số?

Hàm đã biết sẵn trang đã được phê duyệt hiện tại. Một lược đồ đầu vào rỗng giúp việc điều hướng và chọn trang luôn nằm trong tầm kiểm soát của ứng dụng.

Hỏi: Kết quả rỗng có nghĩa là trang an toàn để xử lý như nội dung bình thường không?

Không. Hãy kiểm tra trạng thái trang trước khi tiếp tục. Một kết quả phát hiện rỗng cũng có thể phản ánh vấn đề về thời điểm, một cơ chế không được hỗ trợ, hoặc việc khởi tạo widget chưa hoàn tất.