🎉MỚICapSolver cho AI agent-Tích hợp MCP, công cụ agent và SDK
Anh Tuan
Data Science Expert
Đã xuất bản Oct 30, 2026
Đã cập nhật Oct 30, 2026 · đọc tối thiểu
errorId trước khi diễn giải status hoặc solution.Một agent điều khiển trình duyệt có thể nhận được phản hồi hợp lệ từ công cụ nhưng vẫn không có bước hữu ích nào để thực hiện tiếp theo. Phản hồi có thể chứa một lỗi kiểm tra đầu vào, một tác vụ chưa hoàn thành, hoặc một lời giải mà trang chưa chấp nhận. Gộp cả ba thành cùng một thông điệp “xong” sẽ khiến agent tiếp tục quá sớm.
CapSolver cung cấp các thao tác CAPTCHA thông qua API trực tiếp và giao diện dành cho agent. Giao diện bạn chọn sẽ quyết định cấu trúc kết quả. Tài liệu này giải thích cách diễn giải các cấu trúc đó và thiết kế một bản tóm tắt nhỏ ở cấp ứng dụng mà không bịa thêm trường mới của nhà cung cấp.
Trường hợp sử dụng cụ thể là một agent vận hành một form thử nghiệm thuộc sở hữu của bạn. Trình duyệt gặp một CAPTCHA được hỗ trợ, trình giải được chọn chạy, và ứng dụng quyết định nên chờ, chỉnh sửa đầu vào, áp dụng kết quả, hay dừng lại. Câu hỏi ở đây là bằng chứng nào nên điều khiển quyết định đó.
Xác định lớp phản hồi trước khi đọc một trường tên là success hoặc status.
Có ba lớp hữu ích: lớp truyền tải công cụ (tool transport), thao tác CAPTCHA, và tác vụ trên trình duyệt. Một API định nghĩa một giao diện cụ thể; phản hồi của nó nên được diễn giải trong phạm vi hợp đồng đó. Một lớp bọc công cụ có thể thêm vỏ (envelope) khác, và ứng dụng có thể thêm trạng thái luồng công việc riêng.
| Lớp | Câu hỏi nó trả lời | Điều nó không thể tự xác lập |
|---|---|---|
| MCP/truyền tải công cụ | Lệnh gọi công cụ có trả về hay báo lỗi công cụ không? | Liệu có tồn tại lời giải CAPTCHA có thể sử dụng hay không |
| Dịch vụ CAPTCHA | Thao tác giải thất bại, vẫn đang chờ, hay đã tạo ra kết quả như tài liệu mô tả? | Form hay trang đích có chấp nhận kết quả đó hay không |
| Trình duyệt/ứng dụng | Thao tác dự định có đạt trạng thái mong đợi không? | Liệu mọi chẩn đoán trước đó có được ghi lại chính xác không |
Giữ nguyên kết quả gốc để phục vụ gỡ lỗi. Nếu ứng dụng của bạn chuẩn hoá kết quả, hãy gắn nhãn các trường đó là thuộc sở hữu của ứng dụng. Đừng trình bày một trường nội bộ tiện dụng như workflow_state như thể đó là trường API được CapSolver ghi nhận trong tài liệu.
Kiểm tra tín hiệu lỗi công cụ MCP, sau đó kiểm tra payload theo đúng hợp đồng của chính công cụ đó.
Đặc tả công cụ MCP mô tả nội dung kết quả công cụ và cờ isError. Thư viện client có thể phơi bày điều này bằng tên khác theo ngôn ngữ lập trình. Ví dụ, kết quả công cụ FastMCP cung cấp .is_error, .content, và dữ liệu đã phân tích.
Đừng cho rằng mọi phản hồi công cụ đều là một dictionary JSON thô. Một số server trả về nội dung dạng text chứa JSON đã được tuần tự hoá; một số khác còn cung cấp nội dung có cấu trúc. Hãy đọc thuộc tính client được ghi trong tài liệu, rồi chỉ phân tích lớp thực sự chứa JSON. Tìm từ “success” trong toàn bộ chuỗi phản hồi là cách làm không đáng tin cậy.
Trong một thử nghiệm kết nối cục bộ với FastMCP 3.4.11 và capsolver-mcp 0.1.3, một lệnh solve_captcha cố tình không đầy đủ đã trả về lỗi công cụ, chỉ ra thiếu đầu vào website_url và website_key. Một lệnh gọi registry riêng biệt lại trả về thành công. Những quan sát đó chỉ xác nhận đường đọc lỗi và việc thi hành registry, chứ không phải việc giải CAPTCHA có tính phí.
Một công cụ cũng có thể trả về một envelope MCP bình thường nhưng bên trong chứa lỗi ở cấp dịch vụ. Do đó, “không có ngoại lệ công cụ” chỉ là bước kiểm tra đầu tiên. Tiếp theo hãy xem kết quả nghiệp vụ (business result) được ghi trong tài liệu cho công cụ cụ thể đó. Đừng tự suy đoán để ánh xạ các trường từ API trực tiếp sang trường MCP.
Ví dụ đăng ký cụ thể tuỳ theo framework, hướng dẫn công cụ Pydantic AI trong tài liệu Pydantic AI tool guide trình bày input kiểu hoá và cách adapter chạy. Ở đây chúng ta tập trung vào quyết định sau khi phản hồi tới, bất kể framework nào đã đăng ký công cụ.
Với API trực tiếp, bắt đầu với errorId, rồi theo luồng trạng thái tác vụ như tài liệu.
Tài liệu createTask và getTaskResult định nghĩa luồng này. Một tác vụ tạo thành công có thể trả về định danh tác vụ cho lần truy xuất sau. Định danh đó là handle cho thao tác, không phải đáp án đã giải.
Với kết quả dạng thăm dò (polling), phản hồi lỗi phải được xử lý trước khi đọc lời giải. Hai trạng thái idle và processing được ghi trong tài liệu là trạng thái chưa hoàn tất. Tiếp tục luồng truy xuất hiện tại trong giới hạn thời gian đã cấu hình; tài liệu hướng dẫn bên gọi chờ ba giây trước khi thử lại sau kết quả processing. Một kết quả sẵn sàng vẫn phải chứa cấu trúc lời giải được ghi cho kiểu tác vụ đó.
| Quan sát phản hồi | Diễn giải | Hành động ứng dụng |
|---|---|---|
errorId khác 0 |
Dịch vụ báo lỗi | Lưu errorCode và errorDescription; chọn chỉnh sửa hoặc dừng |
| Tác vụ đã được chấp nhận nhưng kết quả vẫn đang xử lý | Chưa có lời giải cuối cùng | Tiếp tục thăm dò cùng tác vụ trong các giới hạn tài liệu |
| Kết quả sẵn sàng với trường solution như mong đợi | Có lời giải ứng cử viên | Chuyển nó cho thành phần chịu trách nhiệm với cùng thử thách |
| Thiếu hoặc xuất hiện trường kết quả không như mong đợi | Hợp đồng không được thiết lập | Ngừng diễn giải và kiểm tra phản hồi; đừng tự tạo token |
| Trình duyệt xác nhận tác vụ dự định | Kết quả ứng dụng đã được xác lập | Ghi lại hoàn tất luồng công việc tách biệt |
Một số kiểu tác vụ có thể hoàn tất đồng bộ. Hãy làm theo phản hồi được ghi cho kiểu đã chọn thay vì ép mọi tác vụ phải qua vòng lặp polling. Ngược lại, đừng gọi createTask nhiều lần chỉ vì kết quả bất đồng bộ chưa sẵn sàng.
Tài liệu reCAPTCHA v2 mô tả các trường trong lời giải. Các họ tác vụ khác có thể trả về dữ liệu khác nhau. Một lớp bọc mà giả định mọi kết quả đều có cùng một trường token có thể âm thầm loại bỏ một đáp án hợp lệ hoặc nhầm một trường không liên quan thành trường đó.
Nhận mã thưởng CapSolver của bạn
Tăng ngân sách tự động hoá ngay lập tức!
Hãy dùng mã thưởng CAP26 khi nạp tiền vào tài khoản CapSolver để nhận thêm 5% tiền thưởng cho mỗi lần nạp — không giới hạn.
Đổi mã ngay trong Bảng điều khiển CapSolver
Trả lại đủ thông tin cho bước kế tiếp được phép của agent, đồng thời giữ dữ liệu chi tiết của dịch vụ ở thành phần tiêu thụ nó.
Một bản tóm tắt nhỏ ở cấp ứng dụng có thể chứa giai đoạn thao tác, kết quả chuẩn hoá, giải thích an toàn, và hành động tiếp theo được phép. Đây là các trường thuộc ứng dụng của bạn, không phải bản thay thế cho phản hồi của nhà cung cấp.
Ví dụ, sau một phản hồi API trực tiếp cho biết tác vụ đang chờ, bản tóm tắt có thể là: “Tác vụ CAPTCHA đang được xử lý; tiếp tục chờ tác vụ hiện tại.” Sau một lỗi đầu vào, có thể là: “Yêu cầu chưa đầy đủ; hãy lấy các tham số trang còn thiếu trước khi thử lại.” Sau một kết quả từ trình giải, có thể là: “Đã có lời giải; đang chờ trình duyệt xác minh.”
Lưu ý điều các thông điệp này tránh: không thông điệp nào khẳng định form đã được gửi hay một yêu cầu dữ liệu đã hoàn thành. Trình duyệt phải cung cấp bằng chứng đó sau.
Một cách triển khai thực tế giữ hai loại bản ghi. Bản ghi vận hành lưu mã tham chiếu tác vụ, các trường chẩn đoán an toàn và các bước chuyển giai đoạn. Thành phần trình duyệt tạm thời giữ giá trị lời giải mà nó cần. Bản tóm tắt hiển thị cho mô hình chỉ trỏ đến hành động tiếp theo được phép và không sao chép toàn bộ token vào câu trả lời hội thoại.
Nếu ứng dụng chấp nhận đầu ra có cấu trúc từ mô hình, hãy kiểm tra chúng với schema riêng của ứng dụng. Một schema hợp lệ chỉ xác lập hình dạng, không xác lập sự thật. Mô hình không nên được phép biến một quan sát “trình giải còn đang chờ” thành “trình duyệt đã hoàn tất” chỉ bằng cách trả về một chuỗi trạng thái khác.
Chọn hành động tiếp theo dựa trên mô tả lỗi và trạng thái trang hiện tại, không dựa trên một quy tắc thử lại chung.
Tài liệu lỗi chính thức phân biệt đầu vào không hợp lệ, tác vụ không được hỗ trợ, thông tin xác thực, giới hạn và lỗi giải. Những nhóm này cần cách xử lý khác nhau. Thử lại với payload sai y như cũ sẽ không sửa trường của nó. Tạo một tác vụ tính phí mới sẽ không sửa lỗi thiếu thông tin xác thực.
Dùng một chuỗi quyết định gọn:
Một điểm dừng có giới hạn cũng là kết quả hữu ích. “Không thể hoàn tất bước này” cùng một lý do chính xác còn hữu ích hơn một chuỗi rỗng khiến agent hành xử như thể việc giải đã thành công.
Ứng dụng phải quan sát kết quả mong muốn của tác vụ ban đầu sau bước CAPTCHA.
Với một form thử nghiệm thuộc sở hữu của bạn, hãy định nghĩa điều kiện đó trước khi gọi trình giải: có thể là một phần tử xác nhận đã biết và bản ghi gửi form thử nghiệm tương ứng. Việc một iframe biến mất, một trường phản hồi được điền, hay một công cụ trả lại token có thể là bằng chứng trung gian hữu ích, nhưng mỗi thứ đều yếu hơn kết quả ứng dụng dự định.
Tài liệu xác minh reCAPTCHA của Google giải thích bước xác minh phía server. Đó là lý do token được trả về cho trình duyệt không nên bị nhầm với việc được ứng dụng nhận dữ liệu chấp nhận.
Khi một luồng công việc thất bại, hãy lưu lại giai đoạn cuối cùng đã được xác lập. “Trình giải đã trả về; ứng dụng từ chối” khác với “trình giải không bao giờ trả về.” Sự phân biệt này ngăn một phiên gỡ lỗi đi chỉnh yêu cầu gửi tới trình giải trong khi vấn đề thực sự lại là một trường bắt buộc khác trên form.
Kiểm thử từng nhánh kết quả độc lập, sau đó thực hiện một thử nghiệm end-to-end được phép với thông tin xác thực thật và một trang thuộc sở hữu của bạn.
Bao gồm một lỗi kiểm tra đầu vào, một fixture lỗi dịch vụ, một phản hồi đang xử lý, một phản hồi sẵn sàng, một payload bất ngờ, và một lần trình duyệt từ chối sau một lời giải ứng cử viên. Các fixture kiểm tra quyết định của ứng dụng; chúng không chứng minh hành vi API live hay khả năng chấp nhận CAPTCHA.
Cũng hãy kiểm thử một phản hồi tới sau khi ứng dụng đã ngừng chờ. Ứng dụng nên giữ nguyên trạng thái đã dừng thay vì cho phép một kết quả đến muộn làm tiếp tục một form đã bị bỏ. Giữ kết quả gắn với lần thử ban đầu của nó.
Các kiểm tra trong bài viết này thiết lập cách diễn giải phản hồi theo tài liệu và một đường xác thực/registry MCP thực. Chúng không cấu thành một bài đo benchmark giải CAPTCHA tính phí, một case study triển khai cho khách hàng, hay một phép đo tỉ lệ thành công của agent.
Hãy làm cho kết quả CAPTCHA có thể hành động được bằng cách giữ đúng trạng thái thực của nó và kiểm tra kết quả trên trình duyệt. CapSolver cung cấp giao diện trình giải được ghi nhận trong tài liệu cho bước đó. Dùng thử CapSolver với một luồng thử nghiệm được phép và giữ bước kiểm tra cuối cùng của ứng dụng tách biệt.
H: isError bằng false có nghĩa là CAPTCHA đã được giải xong không?
Không. Nó chỉ có nghĩa phản hồi công cụ không được đánh dấu là lỗi thực thi công cụ. Hãy kiểm tra kết quả nghiệp vụ được ghi trong payload rồi xác minh tác vụ trên trình duyệt một cách tách biệt.
H: Agent có nên nhận toàn bộ token CAPTCHA không?
Chỉ khi thành phần tiêu thụ token thực sự cần nó. Nhiều thiết kế có thể giữ giá trị trong trạng thái ứng dụng và chỉ đưa cho mô hình một trạng thái ngắn gọn.
H: Tôi có thể dùng cùng một bộ phân tích kết quả cho REST và MCP không?
Chỉ sau khi đã điều chỉnh rõ ràng các hợp đồng phản hồi khác nhau của chúng. Kết quả một tác vụ REST và một envelope công cụ MCP không phải là hai đối tượng có thể hoán đổi cho nhau.
H: Tôi nên trả về gì khi kết quả vẫn đang xử lý?
Hãy trả về trạng thái đang chờ theo định dạng riêng của ứng dụng và tiếp tục truy xuất tác vụ hiện có trong hạn chót. Đừng gắn nhãn là đã hoàn tất hay tạo tác vụ mới chỉ vì tác vụ đầu tiên chưa xong.
H: Nếu trình giải trả về kết quả nhưng form bị lỗi thì sao?
Hãy ghi nhận riêng việc trình giải đã hoàn tất và ứng dụng thất bại. Kiểm tra lý do từ chối của trang và bối cảnh tác vụ hiện tại trước khi quyết định liệu một lần thử CAPTCHA mới có phù hợp hay không.
Anh Tuan
Data Science Expert
Turning task outcomes into actionable insights.
GIỚI THIỆU TÁC GIẢ
Giữ cho các tác nhân trình duyệt chạy song song không trộn lẫn kết quả CAPTCHA. Ánh xạ ID tác vụ với chủ sở hữu trang, từ chối các phản hồi cũ và kiểm tra định tuyến trước khi áp dụng giải pháp.
Hãy chọn một API CAPTCHA hoặc MCP cho tác nhân AI của bạn bằng cách so sánh khả năng kiểm soát tác vụ, khám phá công cụ, xử lý kết quả và trách nhiệm của trình duyệt trước khi bạn tích hợp.
