Cách giải reCAPTCHA trong OpenAI Agents SDK

SDK Agents của OpenAI cung cấp khung làm việc sẵn sàng sản xuất để xây dựng các tác nhân AI với khả năng gọi công cụ. Khi các tác nhân này tương tác với các trang web được bảo vệ bởi reCAPTCHA, chúng cần một cách để xóa các thách thức xác minh một cách lập trình. Gói capsolver-agent của CapSolver tích hợp với SDK Agents của OpenAI thông qua bộ định danh @function_tool, cho phép tác nhân của bạn giải quyết các thách thức reCAPTCHA v2 và v3 như một phần của quy trình tự động.

Tóm tắt

• SDK Agents của OpenAI sử dụng @function_tool để đăng ký các công cụ có thể gọi — CapSolver phù hợp với mô hình này một cách tự nhiên
• Hàm execute_tool() của capsolver-agent bao bọc việc giải quyết thành một cuộc gọi bất đồng bộ duy nhất tương thích với SDK
• Hỗ trợ reCAPTCHA v2 (hộp kiểm và không hiển thị), reCAPTCHA v3 (dựa trên điểm số) và các phiên bản doanh nghiệp
• Chế độ token không cần trình duyệt — chỉ cần khóa trang web và URL
• Tác nhân tự động quyết định khi gọi giải CAPTCHA dựa trên ngữ cảnh nhiệm vụ

Tại sao các tác nhân OpenAI cần giải reCAPTCHA

SDK Agents của OpenAI cho phép các nhà phát triển xây dựng các tác nhân thực hiện các nhiệm vụ đa bước bằng cách sử dụng các công cụ. Khi nhiệm vụ của tác nhân liên quan đến tương tác web — truy cập dữ liệu sau khi đăng nhập, gửi biểu mẫu hoặc thu thập thông tin từ các trang được bảo vệ — các thách thức reCAPTCHA sẽ chặn tiến trình. Tác nhân có thể suy nghĩ về điều gì nên làm tiếp theo, nhưng nếu không có công cụ giải, nó không thể tạo ra token xác minh cần thiết để tiếp tục.

reCAPTCHA đặc biệt phổ biến trên các trang web mà các tác nhân cần truy cập: cổng đăng nhập, API dữ liệu có giới hạn tốc độ, cơ sở dữ liệu chính phủ và các nền tảng SaaS. Tài liệu reCAPTCHA của Google cho biết hơn 5 triệu trang web sử dụng reCAPTCHA trên toàn cầu, làm cho nó trở thành thách thức xác minh có khả năng cao nhất mà tác nhân của bạn sẽ gặp phải.

Kiến trúc của CapSolver phù hợp hoàn hảo với thiết kế của SDK Agents của OpenAI: tác nhân quyết định cái gì cần làm (bao gồm cả việc giải CAPTCHA), và CapSolver xử lý việc giải nó thông qua dịch vụ AI của họ. Sự phân chia trách nhiệm này giữ cho logic của tác nhân sạch sẽ đồng thời thêm khả năng xóa xác minh.

Những gì bạn cần trước khi bắt đầu

Cài đặt các gói cần thiết:

# Động cơ CapSolver
pip install git+https://github.com/capsolver-ai/capsolver-core.git

# Công cụ CapSolver cho tác nhân
pip install git+https://github.com/capsolver-ai/capsolver-agent.git

# SDK Agents của OpenAI
pip install openai-agents

Thiết lập biến môi trường:

export CAPSOLVER_API_KEY="mã API CapSolver của bạn"
export OPENAI_API_KEY="mã API OpenAI của bạn"

Bạn cần một tài khoản CapSolver với số dư. SDK hiện tại hỗ trợ reCAPTCHA v2, reCAPTCHA v3 (bao gồm cả phiên bản doanh nghiệp) và Cloudflare Turnstile — bao phủ các loại xác minh mà các tác nhân thường gặp nhất.

Bước 1 — Đăng ký Giải CAPTCHA như một Công cụ Hàm

Điều gì cần làm

SDK Agents của OpenAI sử dụng @function_tool để định nghĩa các công cụ mà tác nhân có thể gọi. Bao bọc trình thực thi của CapSolver theo mô hình này:

from agents import Agent, Runner, function_tool
from capsolver_agent.schema import execute_tool

@function_tool
async def solve_recaptcha(
    website_url: str, 
    website_key: str, 
    captcha_type: str = "reCaptchaV2"
) -> str:
    """Giải quyết thử thách reCAPTCHA trên trang web và trả về token xác minh.
    
    Sử dụng công cụ này khi bạn cần vượt qua xác minh reCAPTCHA trên trang web.
    
    Args:
        website_url: URL đầy đủ của trang chứa reCAPTCHA
        website_key: Khóa trang web reCAPTCHA (được tìm thấy trong thuộc tính data-sitekey)
        captcha_type: Hoặc 'reCaptchaV2' hoặc 'reCaptchaV3' (mặc định: reCaptchaV2)
    
    Returns:
        Token reCAPTCHA đã giải để gửi dưới dạng g-recaptcha-response
    """
    result = await execute_tool("solve_captcha", {
        "captcha_type": captcha_type,
        "website_url": website_url,
        "website_key": website_key
    }, api_key="YOUR_CAPSOLVER_API_KEY")
    
    if result["success"]:
        return f"reCAPTCHA đã được giải. Token: {result['solution']['token']}"
    return f"Giải thất bại: {result['error']}"

Hàm execute_tool() từ capsolver-agent là một cuộc gọi bất đồng bộ duy nhất xử lý toàn bộ quy trình giải — tạo nhiệm vụ, kiểm tra kết quả và trả về đầu ra có cấu trúc. Nó được thiết kế đặc biệt cho các tình huống bạn muốn giải một lần mà không cần xây dựng vòng lặp thực thi đầy đủ.

Tại sao điều này quan trọng

Bộ định danh @function_tool của SDK Agents của OpenAI tự động tạo lược đồ JSON mà mô hình cần để hiểu tham số của công cụ. Tác nhân nhìn thấy mô tả công cụ, hiểu khi nào nên sử dụng nó và gọi nó với các tham số đúng — tất cả thông qua cơ chế gọi hàm tích hợp của SDK.

Những sai lầm phổ biến cần tránh

• Thực thi đồng bộ: SDK Agents của OpenAI là bất đồng bộ. Luôn sử dụng async def cho các hàm công cụ và await cho các cuộc gọi CapSolver.
• Thiếu chú thích kiểu: SDK tạo lược đồ từ chú thích kiểu. Hãy bao gồm chú thích kiểu chính xác cho tất cả các tham số.

Bước 2 — Tạo một Tác nhân với Khả năng Giải CAPTCHA

Điều gì cần làm

Xây dựng một tác nhân OpenAI bao gồm công cụ giải CAPTCHA:

from agents import Agent, Runner

# Tạo tác nhân với khả năng giải CAPTCHA
captcha_agent = Agent(
    name="Tác nhân Truy cập Web",
    instructions="""Bạn là một tác nhân truy cập web giúp người dùng tương tác với 
    các trang web. Khi một nhiệm vụ yêu cầu truy cập trang được bảo vệ bởi reCAPTCHA, sử dụng 
    công cụ solve_recaptcha để lấy token xác minh. 
    
    Đối với reCAPTCHA v2: sử dụng captcha_type='reCaptchaV2'
    Đối với reCAPTCHA v3: sử dụng captcha_type='reCaptchaV3'
    
    Luôn cung cấp chính xác website_url và website_key từ yêu cầu của người dùng.""",
    tools=[solve_recaptcha]
)

# Chạy tác nhân
async def main():
    result = await Runner.run(
        captcha_agent,
        "Tôi cần truy cập https://example.com/login có reCAPTCHA v2. "
        "Khóa trang web là 6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI. "
        "Vui lòng giải nó và cung cấp token cho tôi."
    )
    print(result.final_output)

import asyncio
asyncio.run(main())

Tác nhân xử lý yêu cầu, nhận ra rằng giải CAPTCHA là cần thiết, gọi công cụ với các tham số được cung cấp và trả lại token cho người dùng.

Tại sao điều này quan trọng

SDK Agents của OpenAI xử lý vòng lặp hội thoại, phân phối công cụ và tích hợp kết quả tự động. Bạn định nghĩa công cụ một lần, và runtime của SDK quản lý khi và cách nó được gọi. Điều này đơn giản hơn việc xây dựng thủ công vòng lặp gọi hàm.

Bước 3 — Xử lý reCAPTCHA v3 với Yêu cầu Điểm Số

Điều gì cần làm

reCAPTCHA v3 là dựa trên điểm số và không hiển thị — nó yêu cầu tham số page_action và trả về token có điểm số liên quan. Tạo một công cụ chuyên dụng:

@function_tool
async def solve_recaptcha_v3(
    website_url: str,
    website_key: str,
    page_action: str = "verify",
    min_score: float = 0.7
) -> str:
    """Giải quyết thử thách reCAPTCHA v3 (không hiển thị, dựa trên điểm số).
    
    Sử dụng khi trang sử dụng reCAPTCHA v3 — không có hộp kiểm hiển thị,
    nhưng trang xác minh token dựa trên điểm số ở nền.
    
    Args:
        website_url: URL đầy đủ của trang
        website_key: Khóa trang web reCAPTCHA v3
        page_action: Tên hành động cho điểm số (ví dụ: 'đăng nhập', 'gửi', 'xác minh')
        min_score: Điểm số chấp nhận được tối thiểu (0.0-1.0, mặc định 0.7)
    """
    result = await execute_tool("solve_captcha", {
        "captcha_type": "reCaptchaV3",
        "website_url": website_url,
        "website_key": website_key,
        "page_action": page_action,
        "min_score": min_score
    }, api_key="YOUR_CAPSOLVER_API_KEY")
    
    if result["success"]:
        return f"reCAPTCHA v3 đã được giải với điểm số cao. Token: {result['solution']['token']}"
    return f"Giải thất bại: {result['error']}"

Hướng dẫn giải reCAPTCHA v3 giải thích cách xác định tham số page_action chính xác cho các trang khác nhau. Các hành động phổ biến bao gồm đăng nhập, gửi, trang chủ và xác minh.

Bước 4 — Xây dựng Tác nhân Đa Công cụ cho Quy Trình Web Hoàn chỉnh

Điều gì cần làm

Kết hợp giải CAPTCHA với các công cụ khác cho các tác nhân thực hiện các nhiệm vụ web hoàn chỉnh:

from agents import Agent, Runner, function_tool

@function_tool
async def solve_recaptcha(website_url: str, website_key: str, captcha_type: str = "reCaptchaV2") -> str:
    """Giải CAPTCHA và trả về token."""
    result = await execute_tool("solve_captcha", {
        "captcha_type": captcha_type,
        "website_url": website_url,
        "website_key": website_key
    }, api_key="YOUR_CAPSOLVER_API_KEY")
    if result["success"]:
        return f"Token: {result['solution']['token']}"
    return f"Thất bại: {result['error']}"

@function_tool
async def check_solver_balance() -> str:
    """Kiểm tra số dư giải CAPTCHA còn lại."""
    result = await execute_tool("get_balance", {}, api_key="YOUR_CAPSOLVER_API_KEY")
    if result["success"]:
        return f"Số dư: ${result['balance']:.2f}"
    return "Không thể kiểm tra số dư"

# Tác nhân đa khả năng
web_agent = Agent(
    name="Tác nhân Web Tự động",
    instructions="""Bạn giúp người dùng truy cập các tài nguyên web có thể bị bảo vệ bởi 
    reCAPTCHA. Bạn có thể giải cả reCAPTCHA v2 (hộp kiểm hiển thị) và v3 (không hiển thị 
    dựa trên điểm số). Luôn kiểm tra số dư trước khi giải nếu người dùng hỏi về chi phí.
    
    Khi giải CAPTCHA:
    - v2: Sử dụng captcha_type='reCaptchaV2' 
    - v3: Sử dụng captcha_type='reCaptchaV3' và bao gồm page_action nếu biết
    
    Trả lại token rõ ràng để người dùng có thể gửi cùng biểu mẫu của họ.""",
    tools=[solve_recaptcha, check_solver_balance]
)

async def run_web_agent(task: str):
    result = await Runner.run(web_agent, task)
    return result.final_output

Mô hình này hoạt động cho các tác nhân cần xử lý nhiều phiên bản reCAPTCHA trên các trang khác nhau trong cùng một phiên.

Nhận Mã Ưu Đãi: Sử dụng mã WEBS tại Bảng điều khiển CapSolver để nhận thêm 5% ưu đãi cho mỗi lần nạp tiền. Lý tưởng cho các nhà phát triển xây dựng các tác nhân OpenAI với khả năng truy cập web.

Bước 5 — Xem xét Triển khai Sản phẩm

Đối với các tác nhân OpenAI sản phẩm có giải CAPTCHA:

import os
from agents import Agent, Runner, function_tool
from capsolver_agent.schema import create_executor

# Executor sản phẩm với cài đặt tùy chỉnh
executor = create_executor(
    api_key=os.environ["CAPSOLVER_API_KEY"],
    default_timeout=90,      # 90 giây
    polling_interval=3       # Kiểm tra mỗi 3 giây
)

@function_tool
async def solve_recaptcha_production(
    website_url: str,
    website_key: str,
    captcha_type: str = "reCaptchaV2"
) -> str:
    """Giải CAPTCHA cấp sản phẩm với logic thử lại."""
    for attempt in range(3):
        result = await executor.execute("solve_captcha", {
            "captcha_type": captcha_type,
            "website_url": website_url,
            "website_key": website_key
        })
        if result["success"]:
            return f"Đã giải (lần thử {attempt+1}). Token: {result['solution']['token']}"
        if attempt < 2:
            await asyncio.sleep(2)
    return f"Thất bại sau 3 lần thử: {result.get('error')}"

Các yếu tố quan trọng cho sản phẩm:

• Cấu hình thời gian chờ: Thiết lập default_timeout dựa trên yêu cầu thời gian phản hồi của tác nhân
• Logic thử lại: Lỗi mạng và thất bại tạm thời nên kích hoạt thử lại, không phải thất bại ngay lập tức
• Theo dõi số dư: Kiểm tra số dư định kỳ để tránh thất bại trong nhiệm vụ do thiếu tín dụng
• Báo lỗi: Trả về thông báo lỗi rõ ràng để tác nhân có thể suy nghĩ về các phương pháp thay thế

Tài liệu API của CapSolver cung cấp các tùy chọn cấu hình bổ sung để tối ưu hóa thời gian giải trong môi trường sản phẩm. Để xác định các tham số reCAPTCHA trên các trang mục tiêu, phần mở rộng trình duyệt CapSolver cung cấp phát hiện tự động.

Kết luận

Việc tích hợp giải CAPTCHA vào SDK Agents của OpenAI yêu cầu định nghĩa một @function_tool bao bọc hàm execute_tool() của CapSolver, sau đó gán nó cho tác nhân của bạn. Runtime của SDK tự động xử lý phân phối công cụ — tác nhân quyết định khi nào cần giải CAPTCHA và gọi công cụ với các tham số phù hợp. CapSolver cung cấp cơ sở hạ tầng giải CAPTCHA dựa trên AI tạo ra các token hợp lệ cho các phiên bản reCAPTCHA v2, v3 và doanh nghiệp.

Bắt đầu với công cụ solve_recaptcha, kiểm tra nó với tác nhân của bạn trên mục tiêu đã biết, sau đó thêm hỗ trợ v3 và logic thử lại cho sản phẩm. Kiến trúc bất đồng bộ của SDK Agents của OpenAI phù hợp tự nhiên với API bất đồng bộ của CapSolver, làm cho tích hợp trở nên sạch sẽ và hiệu quả.

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

SDK Agents của OpenAI có hỗ trợ giải CAPTCHA bất đồng bộ không?

Có. SDK hoàn toàn bất đồng bộ, và hàm execute_tool() của CapSolver là bất đồng bộ. Bộ định danh @function_tool hỗ trợ các hàm async def natively, vì vậy giải CAPTCHA chạy mà không làm gián đoạn vòng lặp sự kiện của tác nhân.

Tác nhân có thể giải reCAPTCHA doanh nghiệp với tích hợp này không?

Có. Gửi enterprise: true trong tham số. reCAPTCHA doanh nghiệp sử dụng cùng loại nhiệm vụ v2/v3 nhưng có thể yêu cầu tham số s. CapSolver xử lý các phiên bản doanh nghiệp một cách tự động qua cùng API.

Tác nhân biết trang web sử dụng phiên bản reCAPTCHA nào như thế nào?

Bao gồm hướng dẫn trong chỉ dẫn của tác nhân về việc xác định v2 vs v3. Hoặc cung cấp loại CAPTCHA trong lời nhắc nhiệm vụ. Hướng dẫn xác định loại reCAPTCHA giải thích sự khác biệt: v2 hiển thị widget, trong khi v3 tải qua thẻ script.

Chi phí mỗi lần giải reCAPTCHA là bao nhiêu?

reCAPTCHA v2 chi phí khoảng $2-3 cho 1.000 lần giải, và reCAPTCHA v3 chi phí $1-2 cho 1.000 lần. Đối với tác nhân giải 10 reCAPTCHA mỗi phiên, chi phí khoảng $0.02-0.03 mỗi phiên — nhỏ so với giá trị của việc hoàn thành nhiệm vụ tự động.

Bạn có thể sử dụng điều này với tính năng chuyển giao của SDK Agents của OpenAI không?

Có. Bạn có thể tạo một "tác nhân giải CAPTCHA" chuyên dụng và chuyển giao cho nó khi tác nhân chính gặp thách thức xác minh. Tác nhân giải CAPTCHA giải quyết CAPTCHA và chuyển lại cho tác nhân chính với token. Điều này giữ cho trách nhiệm của tác nhân được tách biệt rõ ràng.