Công cụ CAPTCHA AI Pydantic: Đầu vào có kiểu và Kết quả giải

TL;DR

• Pydantic AI có thể mở rộng giải quyết CAPTCHA thành một công cụ hàm Python có kiểu được hỗ trợ bởi trình điều phối CapSolver chính thức.
• Giữ cho lớp bao nhỏ: nhận các tham số được tài liệu hóa, gọi trình thực thi và trả về kết quả được cấu trúc mà không tự tạo ra câu trả lời thành công.
• Ví dụ dưới đây chạy một vòng lặp agent Pydantic AI thực tế với TestModel và gọi danh mục các kiểu được hỗ trợ của trình điều phối đã cài đặt.
• Hàm giải quyết được đăng ký nhưng bị loại trừ chủ ý khỏi lần kiểm tra này; không có yêu cầu đến nhà cung cấp mô hình hoặc giải quyết có phí nào xảy ra.
• Kiểm tra kiểu giúp mô tả đầu vào công cụ. Ứng dụng của bạn vẫn quyết định trang và thao tác nào được phê duyệt và liệu nhiệm vụ trình duyệt cuối cùng có thành công hay không.

Một công cụ CAPTCHA của Pydantic AI cung cấp cho agent một thao tác được xác định khi một nhiệm vụ trình duyệt được phê duyệt đạt đến một thách thức được hỗ trợ. Mô hình không cần phải tự tạo ra thuật toán giải quyết, và ứng dụng không cần một khách hàng CAPTCHA mới cho mỗi khung công tác agent.

Trình điều phối agent CapSolver cung cấp lớp thực thi. Pydantic AI cung cấp giao diện công cụ hàm. Hướng dẫn này cho thấy cách các phần này kết nối, sử dụng một ví dụ được lấy từ kho lưu trữ Pydantic AI được duy trì bởi CapSolver và một kiểm tra cục bộ thực thi thao tác danh mục của trình điều phối thực tế.

Pydantic AI tích hợp thêm điều gì?

Tích hợp Pydantic AI biến một hàm Python có kiểu thông thường thành một công cụ có sẵn cho một agent. Hàm nhận các tham số có tên, ủy thác thao tác CAPTCHA và trả về kết quả mà agent có thể kiểm tra.

Đối với một biểu mẫu QA được sở hữu, chuỗi hữu ích là cụ thể: trình duyệt nhận diện một thách thức được hỗ trợ, ứng dụng cung cấp tham số trang, công cụ giải quyết trả về kết quả của nó và trình duyệt tiếp tục thử nghiệm biểu mẫu đó. Kết luận cuối cùng thuộc về quy trình biểu mẫu.

Một thư viện API đóng gói các cuộc gọi dịch vụ nền tảng. Trong trường hợp này, tài liệu agent-tools của CapSolver mô tả một trình thực thi phân phát các thao tác được đặt tên đến triển khai cốt lõi.

Tài liệu công cụ hàm của Pydantic AI giải thích cách các chữ ký hàm và ghi chú góp phần vào các định nghĩa công cụ. Ba chuỗi được ghi chú có thể mô tả hình dạng đầu vào cần thiết, nhưng chúng không thiết lập rằng một URL được phê duyệt hay rằng một khóa trang thuộc về trang hiện tại.

Tại sao nên sử dụng trình điều phối chính thức thay vì khách hàng HTTP khác?

Sử dụng trình điều phối chính thức khi bạn muốn một lớp bao nhỏ xung quanh triển khai giải quyết được tài liệu hóa. Điều này giữ cho lớp bao tập trung vào giao diện agent thay vì sao chép việc tạo nhiệm vụ, truy xuất và chuyển đổi kết quả.

CapSolver duy trì một kho lưu trữ ví dụ Pydantic AI sử dụng create_executor, Agent và @agent.tool_plain. Đó là một ứng dụng ví dụ, không phải một gói bổ sung được đặt tên theo kho lưu trữ.

Ví dụ trong bài viết này giữ nguyên hàm giải quyết ba tham số và cuộc gọi trình thực thi của kho lưu trữ. Nó thay đổi phần mô phỏng xung quanh để sử dụng TestModel của Pydantic AI và một cuộc gọi danh mục kiểu được hỗ trợ. Điều này cho phép kiểm tra kết nối công cụ mà không cần cung cấp khóa mô hình hoặc tạo nhiệm vụ giải quyết có phí.

Lối đi này khác với việc gắn máy chủ MCP. Các hàm gọi trình điều phối đã cài đặt trong cùng ứng dụng Python; không có quy trình máy chủ MCP riêng biệt trong ví dụ này. Chọn giao diện phù hợp với agent hiện có thay vì thêm cả hai giao diện vào cùng một nhiệm vụ nhỏ mà không có lý do.

Bước 1: Cài đặt các gói được kiểm tra

Cài đặt khung và trình điều phối trong môi trường Python cô lập. Chạy ghi lại sử dụng Python 3.12.14, pydantic-ai-slim 2.44.0, capsolver-agent 0.1.1 và capsolver-core 0.1.1.

Gói slim cung cấp chức năng Pydantic AI cốt lõi được TestModel sử dụng mà không cần cài đặt mọi tích hợp nhà cung cấp mô hình. Các phiên bản sau khớp với chạy cục bộ:

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

Hướng dẫn môi trường Python về môi trường ảo mô tả việc tạo môi trường và kích hoạt theo shell. Giữ phiên bản gói cùng dự án để có thể tái tạo màn trình diễn trước khi nâng cấp.

Màn trình diễn danh mục cục bộ không cần chứng chỉ giải quyết. Một cuộc gọi solve_captcha thực tế sau này yêu cầu khóa API giải quyết CapSolver của bạn, và một cuộc trò chuyện mô hình thực sự cần gói và xác thực của nhà cung cấp được chọn. Đó là các yêu cầu tiên quyết riêng biệt.

Không sử dụng chứng chỉ MCP được công bố trên blog làm khóa giải quyết. Chứng chỉ dịch vụ của trình thực thi nằm bên ngoài prompt mô hình và mã được ghi lại.

Bước 2: Đăng ký các công cụ có kiểu

Lưu phần sau dưới dạng quickstart.py. Hàm bao giải quyết tuân theo kho lưu trữ chính thức; công cụ danh mục và cấu hình TestModel là sự thích ứng được thực thi cục bộ. Mã đăng ký công cụ giải quyết nhưng không gọi nó.

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:
    """Trả về các loại CAPTCHA được đăng ký mà không giải quyết một thách thức."""
    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:
    """Giải quyết một CAPTCHA được hỗ trợ cho quy trình hợp pháp, được ủy quyền bởi người dùng."""
    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("Liệt kê các loại CAPTCHA được hỗ trợ.")
    print(result.output)


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

Chạy tệp với trình thông dịch Python của môi trường:

python quickstart.py

Bộ xử lý đặt ALLOW_MODEL_REQUESTS thành false để ngăn gọi tình cờ đến mô hình không kiểm tra. Nó cũng giới hạn TestModel chỉ đến công cụ danh mục. Cả hai lựa chọn đều quan trọng: ngăn gọi mô hình khác với ngăn công cụ liên hệ dịch vụ bên ngoài.

Tài liệu kiểm tra của Pydantic AI giải thích rằng TestModel có thể gọi các công cụ được đăng ký bằng dữ liệu được tạo. Việc để lại công cụ giải quyết có phí trong chạy kiểm tra không giới hạn sẽ là một thao tác khác với kiểm tra danh mục được kiểm soát được hiển thị ở đây.

Bước 3: Đọc kết quả quan sát đúng cách

Chạy cục bộ trả về kết quả danh mục thành công từ trình điều phối CapSolver đã cài đặt thực tế. Nó báo cáo các trình xử lý có tên recaptcha và cloudflare, với giá trị kiểu reCaptchaV2, reCaptchaV3 và cloudflare.

Kết quả in của TestModel chứa chuỗi JSON từ công cụ danh mục bên trong tóm tắt kết quả công cụ. Các dấu ngoặc kép được trốn trong tóm tắt in là hệ quả của việc trả về JSON được serial hóa từ hàm; chúng không phải là một mã CAPTCHA mới được tạo.

Trình điều phối chính thức sử dụng json.dumps để trả về kết quả trình thực thi dưới dạng chuỗi. Giữ sự phân biệt giữa chuỗi này và từ điển cơ sở nếu một thành phần khác tiêu thụ nó. Phân tích giá trị JSON phù hợp một cách chủ động thay vì giả định mọi lớp đều trả về cùng một hình dạng.

Kiểm tra xác nhận rằng việc đăng ký, thực thi công cụ không tham số, phân phối trình điều phối và trả về kết quả hoạt động cùng nhau trong các phiên bản đã cài đặt. Nó không xác nhận rằng một mô hình ngôn ngữ sẽ chọn công cụ giải quyết đúng hoặc rằng một biểu mẫu được bảo vệ cụ thể sẽ chấp nhận một mã.

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 — không giới hạn.
Nhận mã thưởng ngay bây giờ trong Bảng điều khiển CapSolver

Các đầu vào có kiểu được ánh xạ như thế nào đến một yêu cầu CAPTCHA?

Các đầu vào có kiểu ánh xạ cuộc gọi công cụ của agent vào từ điển tham số được trình điều phối chấp nhận. Bao giải quyết tối thiểu chấp nhận captcha_type, website_url và website_key.

Các tên này thuộc giao diện trình điều phối. Chúng không phải là yêu cầu REST nguyên bản chứa clientKey và đối tượng task. Tham khảo lược đồ công cụ đã cài đặt và tài liệu tham khảo thử thách reCAPTCHA v2 khi kết nối một trang thực tế.

Bao ba tham số được thiết kế tối thiểu chủ ý. Một số biến thể yêu cầu bối cảnh bổ sung. Không giả định rằng mọi thách thức được liệt kê bởi dịch vụ rộng hơn có thể được giải quyết chỉ với ba chuỗi này, hoặc rằng tên kiểu bao có thể được thay thế bằng tên nhiệm vụ REST.

Một ghi chú chuỗi không giới hạn URL đến tên miền được phê duyệt. Thực hiện kiểm soát tên miền được phép và thao tác trong ứng dụng cung cấp tham số công cụ. Nội dung trang không nên có thể cấp phép cho tên miền mới chỉ bằng cách yêu cầu mô hình sử dụng một trong số đó.

Agent nên xử lý kết quả giải quyết như thế nào?

Agent nên kiểm tra kết quả của trình thực thi và giữ kết quả CAPTCHA tách biệt khỏi kết quả nhiệm vụ kinh doanh. Trình điều phối agent được tài liệu hóa trả về một bao thành công chứa giải pháp, hoặc một bao thất bại mô tả lỗi.

Trong trường hợp thất bại, ứng dụng nên giữ thông tin lỗi liên quan và quyết định xem các đầu vào được sửa đổi, thử lại, hoặc xem xét bởi người vận hành là phù hợp. Không biến lỗi thành một phần tử giả mạo giống token chỉ để đáp ứng trường chuỗi đầu ra.

Trong trường hợp thành công, chuyển kết quả đến thành phần ứng dụng chịu trách nhiệm cho cùng thử nghiệm thách thức đó. Hàm trong hướng dẫn này không điều khiển trình duyệt, tìm trường phản hồi, gửi biểu mẫu hoặc xác nhận sự chấp nhận của ứng dụng.

Đối với kiểm tra biểu mẫu được sở hữu, tiêu chí hoàn thành phù hợp có thể là bản ghi xác nhận được kỳ vọng. Một sự thành công của người giải và sự từ chối của ứng dụng nên là hai quan sát riêng biệt. Sự tách biệt này làm cho khóa trang sai biệt với sự thất bại xác thực biểu mẫu không liên quan.

Tránh đặt thông tin xác thực hoặc token đầy đủ vào nhật ký thông thường. Nếu agent cần một bản tóm tắt đọc được, giữ trạng thái hoạt động và các trường chẩn đoán an toàn trong khi giữ giá trị kết quả trong thành phần thực sự tiêu thụ nó.

Làm thế nào để chuyển từ TestModel sang agent thực tế?

Chuyển sang agent thực tế bằng cách cấu hình nhà cung cấp mô hình mong muốn, cung cấp xác thực của nó và chỉ bật các thao tác sống mà ứng dụng cần. Giữ các lớp bao được kiểm tra và kiểm tra các cuộc gọi công cụ thực tế của mô hình mới.

TestModel trong màn trình diễn là cơ sở kiểm tra thủ công, không phải mô hình ngôn ngữ. Việc chọn danh mục thành công của nó không đo lường suy luận của mô hình. Một cuộc trò chuyện thực tế có thể tạo ra tham số bị thiếu, chọn công cụ sai hoặc yêu cầu thao tác khác, vì vậy ứng dụng vẫn phải kiểm tra đầu vào của nó.

Bắt đầu với một trang QA được sở hữu và một biến thể thách thức được tài liệu hóa. Cung cấp URL trang thực tế và khóa trang công khai từ ứng dụng, sau đó xác minh kết quả giải quyết và phản hồi cuối cùng của biểu mẫu. Ghi lại các thất bại theo giai đoạn thay vì giảm toàn bộ thí nghiệm xuống việc văn bản xuất hiện trong câu trả lời của agent.

Hướng dẫn giải quyết CAPTCHA doanh nghiệp rộng hơn https://www.capsolver.com/blog/ai/enterprise-captcha-solving-for-ai-agent-teams thảo luận về việc áp dụng đội ngũ. Ví dụ khung công tác này thiết lập nền tảng hẹp hơn: đăng ký hàm có kiểu và thực thi trình điều phối thực tế với thao tác được kiểm soát, không giải quyết.

Try CapSolver cho thách thức được hỗ trợ trong nhiệm vụ được phê duyệt của bạn một khi kết nối cục bộ được hiểu. Giữ phạm vi mỗi thử nghiệm rõ ràng: đăng ký công cụ, chọn mô hình, giải quyết có phí và chấp nhận trình duyệt là các kiểm tra khác nhau.

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

Câu hỏi: Có tồn tại một gói pydantic-ai-capsolver riêng biệt không?

Kho lưu trữ được tham khảo chứa các ví dụ sử dụng Pydantic AI và thư viện agent CapSolver chính thức. Hướng dẫn này cài đặt các thư viện đó trực tiếp thay vì giả định tên kho lưu trữ là một gói.

Câu hỏi: TestModel có gọi dịch vụ CAPTCHA thực tế không?

TestModel có thể thực thi các công cụ được đăng ký, vì vậy công cụ được chọn xác định điều gì xảy ra. Ví dụ này gọi rõ ràng chỉ danh mục kiểu được hỗ trợ và không gọi yêu cầu giải quyết.

Câu hỏi: Các đầu vào chuỗi có kiểu đủ để phê duyệt trang đích không?

Không. Ghi chú kiểu mô tả hình dạng đầu vào. Ứng dụng phải đảm bảo URL, nhiệm vụ và bối cảnh được phép riêng biệt.

Câu hỏi: Tại sao kết quả in lại chứa JSON được trốn?

Trình bao trả về JSON được serial hóa, và TestModel bao gồm chuỗi này trong tóm tắt kết quả của nó. Xử lý từng lớp serial hóa một cách chủ động thay vì giả định tóm tắt là đối tượng giải pháp nguyên bản.

Câu hỏi: Bao này có thể xử lý mọi biến thể CAPTCHA không?

Không có sự bao phủ nào được thiết lập ở đây. Hàm tối thiểu chấp nhận ba tham số; các biến thể cần bối cảnh bổ sung yêu cầu các trường được tài liệu hóa và kiểm tra tương ứng.

Câu hỏi: Một CAPTCHA thực tế đã được giải trong quá trình kiểm tra không?

Không. Khung và trình điều phối được cài đặt đã thực hiện thao tác danh mục thực tế sử dụng TestModel. Một giải quyết thực tế và chấp nhận bởi ứng dụng được sở hữu vẫn là các thử nghiệm riêng biệt yêu cầu các thông tin xác thực và trang phù hợp.