Hướng dẫn Computer Use của OpenAI Agents API: Xây dựng Agent QA cho Trình duyệt

Hãy tưởng tượng một quy trình thanh toán hiển thị $48 trong giỏ và $24 trên trang xem lại. Khách hàng thấy hai tổng tiền khác nhau trong cùng một lần thanh toán.

Các nhóm thường chạy kiểm thử đảm bảo chất lượng (QA) cho luồng này bằng script trình duyệt: nhấp nút này, mở trang kia, kiểm tra giá trị này. Một bài kiểm thử có kịch bản chỉ kiểm tra những trạng thái mà tác giả đã ghi lại.

Một agent AI là một mô hình có thể thực hiện hành động để đạt mục tiêu. Agents API của OpenAI quản lý vòng lặp của agent và giữ công việc của nó trong một phiên. Trong hướng dẫn này, Computer Use cũng cung cấp trình duyệt được lưu trữ.

Northstar Checkout là một cửa hàng thử nghiệm hư cấu với một lỗi ẩn ở phần tạm tính.

Agent nhận được kết quả thanh toán đúng, nhưng không biết vị trí lỗi hay danh sách nút cần bấm. Một chương trình Python nhỏ, gọi là harness, so sánh các giá trị agent báo cáo rồi yêu cầu kiểm thử lại bản đã sửa trong cùng phiên.

Trong hướng dẫn này, tôi sẽ trình bày cách:

• Tạo một phiên Agents API với Computer Use chỉ có thể truy cập trang thử nghiệm
• Phê duyệt yêu cầu mở trang đó của trình duyệt, và từ chối mọi trang khác
• Để chính mã của bạn quyết định bài kiểm thử có đạt hay không
• Kiểm tra lại trang đã sửa trong cùng phiên và tính toán chi phí thử nghiệm

Mã và số đo sử dụng phiên bản 3.22.1 của gói Python openai.

Tóm tắt nhanh

Nếu bạn chỉ có một phút, đây là các điểm chính.

• Bản lỗi chỉ sai phần tạm tính trên trang xem lại; số lượng vẫn đúng.
• Bản đã sửa vượt qua trong cùng phiên mà không cần phê duyệt nguồn gốc lần hai.
• Bộ đếm token ước tính chi phí theo mức chuẩn là $0.9469. Không bao gồm phí ghi cache và tính toán trong sandbox lưu trữ, và mức sử dụng Agents API là nỗ lực tốt nhất chứ không phải hóa đơn cuối.
• Mỗi bài kiểm thử, API trả về 2 ảnh chụp màn hình, lần lượt từ 7 và 5 mục computer_use_call.

Đây là một cửa hàng thử nghiệm với một lỗi cài cắm, không phải thước đo độ tin cậy.

Computer Use trong OpenAI Agents API là gì?

Computer Use là một công cụ trong OpenAI Agents API cho phép agent vận hành một trình duyệt chạy trên máy chủ của OpenAI. Mã của bạn theo dõi các sự kiện của phiên và trả lời các yêu cầu của nó. OpenAI liệt kê kiểm thử website là một trường hợp sử dụng.

OpenAI quản lý vòng lặp agent, phiên và khôi phục. Hướng dẫn OpenAI Agents API của chúng tôi bao quát các kiến thức cơ bản đó.

Các thiết lập computer use cũ hơn, như trong hướng dẫn computer use GPT-5.4 của chúng tôi, khiến mã của nhà phát triển phải tự vận hành vòng lặp chụp ảnh và hành động.

Tại sao dùng Computer Use cho kiểm thử QA trên trình duyệt?

Trong QA trên trình duyệt, chính trang web là đối tượng được kiểm thử.

Gọi trực tiếp một API thanh toán sẽ bỏ qua trang nơi lỗi của Northstar tồn tại, vì vậy agent đi theo đúng lộ trình như khách hàng: từ trang sản phẩm đến giỏ hàng, thanh toán và trang xem lại.

Harness, phiên, trình duyệt lưu trữ, trang dàn dựng. Ảnh: Tác giả.

OpenAI quản lý phiên và trình duyệt trong vùng xám; harness và Northstar nằm ngoài nó.

Chúng ta sẽ xây dựng gì với Agents API Computer Use?

Dự án gồm một cửa hàng dàn dựng hư cấu, một harness bằng Python và một phiên Agents API.

Mã hoàn chỉnh nằm trong kho GitHub này.

Tình huống kiểm thử Northstar Checkout

Northstar bán một chai Trail Bottle giá $24. Bài kiểm thử đi từ sản phẩm đến giỏ, thanh toán và xem lại; không có vận chuyển, thuế, đăng nhập hay nút mua hoạt động.

Trang sản phẩm Northstar trước khi kiểm thử. Ảnh: Tác giả.

Bản ns-1041 chứa lỗi, còn ns-1042 chứa bản sửa. Thêm ?reset=1 vào URL bắt đầu của bản dựng sẽ làm trống giỏ trước mỗi lần kiểm thử.

Yêu cầu QA được viết dưới dạng mục tiêu. Tiêu chí chấp nhận yêu cầu agent:

• Tìm Trail Bottle và cho 2 cái vào giỏ
• Kiểm tra giỏ có tạm tính $48.00
• Tiếp tục đến trang xem lại đơn hàng và kiểm tra số lượng và tạm tính vẫn khớp
• Chỉ báo cáo các giá trị hiển thị trong trình duyệt

Một ràng buộc an toàn riêng yêu cầu không bao giờ đặt, gửi hoặc thanh toán đơn hàng. Yêu cầu định nghĩa kết quả, không phải các cú nhấp.

Lỗi thanh toán được cài cắm

Bản lỗi cộng các đơn giá trên trang xem lại và quên số lượng. Cả hai trang đều hiển thị số lượng 2, nhưng tạm tính giỏ là $48.00 còn tạm tính xem lại là $24.00.

Đáp án ở trong mã ứng dụng. Cả hướng dẫn lẫn thông điệp tác vụ đều không nhắc đến lỗi.

Cách mã ứng dụng quyết định đạt hay trượt

Agent báo cáo ID bản dựng và 4 giá trị quan sát được thông qua một công cụ hàm, record_qa_result.

Harness trước tiên kiểm tra bản dựng được báo có đúng bản đang kiểm thử không, vì cả hai bản dùng chung hostname, sau đó so sánh các giá trị với đáp án.

Một công cụ hàm chỉ chạy nếu agent gọi nó. Một bản ghi thiếu, giá trị thiếu, hoặc sai bản dựng khiến kết quả là incomplete, và không bao giờ được tính là đạt.

Từ mục tiêu QA đến phán quyết của ứng dụng. Ảnh: Tác giả.

Cách thiết lập kiểm thử trình duyệt với OpenAI Agents API

Bạn cần Python, một khóa API có phạm vi, quyền truy cập GPT-6 Astra và một phiên có Computer Use.

Điều kiện tiên quyết cho Agents API Computer Use

• Python 3.10 trở lên và openai==3.22.1 (SDK sẽ gửi sẵn header OpenAI-Beta: agents=v1)
• Một khóa API có phạm vi api.agents.read, api.agents.write và api.responses.write, trên một dự án có thể dùng gpt-6-astra

Agents API đang ở giai đoạn public beta, nên tên trường và hành vi có thể thay đổi giữa các bản phát hành SDK. Kho đã cố định phiên bản 3.22.1 trong requirements.txt.

Trình duyệt lưu trữ cần URL có thể truy cập, nên mã dùng một triển khai Northstar trên Vercel.

git clone https://github.com/KhalidAbdelaty/OpenAI-Agents-API.git
cd OpenAI-Agents-API
python -m venv .venv
.venv\Scripts\Activate.ps1
pip install -r requirements.txt
Copy-Item .env.example .env   # then add your OPENAI_API_KEY
python run_qa.py

Để biết thêm về phụ thuộc cách ly, xem hướng dẫn môi trường ảo của chúng tôi. Trên macOS hoặc Linux, kích hoạt bằng source .venv/bin/activate và sao chép tệp bằng cp. Giữ khóa trong .env, không để trong mã.

Thử nghiệm dùng GPT-6 Astra, mô hình trong các ví dụ Computer Use của OpenAI. Tổng quan GPT-6 Astra của chúng tôi trình bày về chính mô hình.

Mã dùng Agents API (client.beta.agents), không dùng Agents SDK hay công cụ computer của Responses API trong hướng dẫn GPT-6 Astra API của chúng tôi.

Cấu hình một phiên Computer Use

Tạo một phiên với công cụ computer_use và desktop do OpenAI lưu trữ, sau đó tái sử dụng cho cả hai bài kiểm thử:

session = client.beta.agents.sessions.create(
    agent={"model": MODEL, "instructions": INSTRUCTIONS,
           "reasoning": {"effort": REASONING_EFFORT},  # "medium", set explicitly
           "tools": [{"type": "computer_use", "include_screenshots": True}, RECORD_QA_RESULT]},
    environment={"type": "openai_hosted", "desktop": {"enabled": True},
                 "network": {"access": "restricted", "allowed_domains": [host]}},
    metadata={"experiment": "northstar-browser-qa"},
)

include_screenshots: True cho phép truy xuất mọi ảnh chụp màn hình API trả về, trong khi truy cập mạng bị hạn chế giới hạn trình duyệt vào Northstar.

Môi trường dùng kích thước mặc định medium (2 vCPU, 4 GB RAM).

Thêm một công cụ hàm cho kết quả QA

Hàm ghi lại những gì agent quan sát được. Nếu agent không thể đọc một trong 4 giá trị số lượng hoặc tạm tính được kiểm tra, nó phải báo cáo trường đó là null.

Liệt kê mọi thuộc tính dưới required yêu cầu mô hình trả lời tất cả, dùng null cho bất cứ thứ gì nó không thấy. Harness vẫn coi trường thiếu là incomplete:

"properties": {
    "build_id": {"type": "string", "description": "Build id shown on the page."},
    "stage_reached": {"type": "string", "enum": ["product", "cart", "checkout_details", "review"]},
    "cart_quantity": {"type": ["integer", "null"]},
    "cart_subtotal": {"type": ["string", "null"], "description": "Exactly as displayed, e.g. $10.00"},
    "review_quantity": {"type": ["integer", "null"]},
    "review_subtotal": {"type": ["string", "null"], "description": "Exactly as displayed"},
    "purchase_control": {"type": "string", "enum": ["disabled", "absent", "enabled", "not_seen"]},
    "evidence_note": {"type": "string", "description": "One or two sentences on what you saw."},
},
"required": ["build_id", "stage_reached", "cart_quantity", "cart_subtotal",
             "review_quantity", "review_subtotal", "purchase_control", "evidence_note"],
"additionalProperties": False,

Harness chuyển đổi mỗi giá hiển thị sang số cent, xác minh ID bản dựng và so sánh các giá trị với đáp án:

EXPECTED = {"cart_quantity": 2, "cart_subtotal_cents": 4800,
            "review_quantity": 2, "review_subtotal_cents": 4800}

def judge(record, expected_build):
    observed = {
        "cart_quantity": record.get("cart_quantity"),
        "cart_subtotal_cents": to_cents(record.get("cart_subtotal")),
        "review_quantity": record.get("review_quantity"),
        "review_subtotal_cents": to_cents(record.get("review_subtotal")),
    }
    missing = [field for field, value in observed.items() if value is None]
    if record.get("build_id") != expected_build:
        return {"verdict": "incomplete", "observed": observed, "failed_checks": [],
                "missing": [f"build_id={expected_build}", *missing]}
    if record.get("stage_reached") != "review":
        missing.append("stage_reached=review")
    failed = [{"field": field, "expected": EXPECTED[field], "observed": value}
              for field, value in observed.items()
              if value is not None and value != EXPECTED[field]]
    verdict = "fail" if failed else "incomplete" if missing else "pass"
    return {"verdict": verdict, "observed": observed, "failed_checks": failed, "missing": missing}

Một giá trị không đọc được hoặc thiếu sẽ cho ra phán quyết incomplete, không bao giờ là đạt.

Báo cáo từ sai bản dựng trả về incomplete trước khi các giá trị của nó có thể ảnh hưởng phán quyết.

Viết hướng dẫn QA

Cùng một bộ hướng dẫn áp dụng cho cả hai kiểm thử:

INSTRUCTIONS = (
    "You are a QA tester for the Northstar Checkout staging site. "
    "Use the browser to run the test you are given. "
    "Stay on the approved staging origin and do not visit any other website. "
    "Inspect what is visible on a page before you make any claim about it. "
    "Stop before any purchase: never place, submit, or pay for an order. "
    "Never invent an observed value. If you could not see a value, report null. "
    "Call record_qa_result once, only after the browser test is finished, then give a short summary."
)

Chỉ bản dựng website thay đổi giữa các lần kiểm thử.

Cách chạy kiểm thử QA trên trình duyệt với Computer Use

Mở luồng sự kiện, gửi mục tiêu QA một lần, rồi xử lý phê duyệt và lời gọi hàm cho đến khi lượt hoàn tất.

Gửi một tác vụ QA đến phiên Agents API

Mở luồng sự kiện trước, rồi gửi tác vụ đúng một lần:

with self.client.beta.agents.sessions.events.stream(self.session_id) as events:
    if not sent:  # open the stream first, then send the task exactly once
        self.client.beta.agents.sessions.events.create(self.session_id, events=[message(text)])
        sent = True
    else:  # reconnected: act on what is still pending, never resend the task
        yield from self.handle_required_actions()
    for event in events:
        yield from self.handle(event)

Luồng sẽ không phát lại các sự kiện bị bỏ lỡ. Nếu luồng rơi, hãy mở luồng mới, rồi truy xuất phiên và các mục đã lưu trong khi kết nối vẫn còn.

Thông điệp tác vụ nêu tên bản dựng, tiêu chí chấp nhận và ràng buộc an toàn, nhưng không nói gì về lỗi:

QA objective for Northstar Checkout staging build ns-1041. Start at https://northstar-checkout-staging.vercel.app/b/ns-1041/?reset=1
Scenario: a customer adds 2 Trail Bottles to the cart and continues through checkout to the order review page.
Acceptance criteria:
- The cart shows quantity 2 and a subtotal of $48.00 (unit price $24.00, no shipping or taxes).
- The order review page shows the same quantity and subtotal as the cart.
Safety constraint: never place, submit, or pay for an order.
Record the cart values and the review values as separate fields.

Giữ lại ID phiên để kiểm tra lại.

Xử lý phê duyệt nguồn gốc trình duyệt

Trình duyệt lưu trữ sẽ yêu cầu phê duyệt trước khi mở mỗi nguồn gốc trang web mới.

Luồng phát ra agent.session.requires_action; truy xuất phiên và đọc required_actions để lấy yêu cầu.

def answer_approval(self, action):
    request = action.request
    if request.type == "browser_origin_access":
        decision = "approve" if request.origin.rstrip("/") == self.origin else "deny"
        response = {"type": "browser_origin_access", "decision": decision}
    else:  # browser_authentication: Northstar has no login, so sign-in is refused
        response = {"type": "browser_authentication", "action": "cancel"}
    self.client.beta.agents.sessions.events.create(self.session_id, events=[{
        "type": "agent.session.input.computer_use_approval_request_result",
        "request_id": action.request_id, "response": response}])

Theo dõi hoạt động trình duyệt bằng sự kiện phiên

Công việc của trình duyệt xuất hiện dưới dạng các mục computer_use_call, mỗi mục có tiêu đề ngắn và trạng thái. Luồng sự kiện của bài kiểm thử đầu tiên cho thấy:

   12.4s  turn     sent       build=ns-1041
   59.4s  browser  completed  Connecting to the staging test browser
   63.6s  browser  completed  Connecting to the staging test browser
   68.6s  approval approve    https://northstar-checkout-staging.vercel.app
   70.8s  browser  completed  Inspecting the Trail Bottle product
   73.5s  browser  completed  Adding the first Trail Bottle
   78.2s  browser  completed  Checking cart quantity and subtotal
   85.7s  browser  completed  Continuing to checkout details
   89.2s  browser  completed  Checking order review values
   95.9s  record              cart 2 $48.00, review 2 $24.00, purchase disabled

Mất khoảng 47 giây trước hoạt động trình duyệt đầu tiên.

Cả 7 mục computer_use_call đều hoàn tất, nhưng trạng thái mục không phải là phán quyết QA; kết quả của lời gọi hàm mới là phán quyết.

Agent có phát hiện lỗi thanh toán không?

Có. Quan trọng hơn, lời gọi hàm đã cô lập lỗi vào một trường: tạm tính trên trang xem lại.

GPT-6 Astra đã báo cáo gì

Lời gọi record_qa_result chứa:

{
  "build_id": "ns-1041",
  "cart_quantity": 2,
  "cart_subtotal": "$48.00",
  "review_quantity": 2,
  "review_subtotal": "$24.00",
  "stage_reached": "review",
  "purchase_control": "disabled"
}

Mọi giá trị đều khớp với trang lỗi. Số lượng vẫn là 2 trên trang xem lại, loại trừ khả năng lệch số lượng nhìn thấy được.

Harness đã biến báo cáo thành kết quả trượt như thế nào

judge() xác nhận bản dựng ns-1041, so sánh 4 giá trị với giá trị kỳ vọng và chỉ thấy sai ở tạm tính trang xem lại.

Đây là phán quyết duy nhất thử nghiệm sử dụng:

{
  "verdict": "fail",
  "failed_checks": [{"field": "review_subtotal_cents", "expected": 4800, "observed": 2400}],
  "missing": []
}

Kiểm tra lại bản sửa trong cùng một phiên Agents API

Sau khi bản sửa hoạt động, gửi thêm một thông điệp vào cùng phiên.

Bài kiểm thử hồi quy nhỏ này dùng cùng hướng dẫn và hàm phán quyết.

Triển khai bản sửa mà không đổi bài kiểm thử

Bản sửa trong bản dựng ns-1042 là một dòng JavaScript của Northstar:

-const reviewSubtotal = (cart) => cart.reduce((sum, line) => sum + line.unitCents, 0);
+const reviewSubtotal = (cart) => cart.reduce((sum, line) => sum + line.unitCents * line.qty, 0);

Gửi bài theo dõi trong cùng phiên

Liên kết bắt đầu bao gồm ?reset=1, nên lần kiểm tra lại bắt đầu với giỏ trống. Sau đó thông điệp theo dõi được gửi vào cùng phiên:

A fix is deployed as staging build ns-1042 at https://northstar-checkout-staging.vercel.app/b/ns-1042/?reset=1
That link starts from an empty cart. Run the same QA objective and acceptance criteria against this build from the start of the journey, and record a new result.

Lần kiểm tra lại giữ nguyên môi trường lưu trữ và không cần phê duyệt nguồn gốc mới. Đừng phụ thuộc vào trạng thái trình duyệt, vì cookie có thể hết hạn và việc tái chế môi trường sẽ xóa sạch.

Một phiên bao trọn cả hai kiểm thử QA. Ảnh: Tác giả.

Một sandbox lưu trữ có thể bị xóa nếu hoạt động và keep-alive ngừng trong 1 giờ. Theo dõi agent.session.environment.reset và bắt đầu mỗi lần kiểm tra lại từ trạng thái đã biết.

Lần kiểm tra lại có đạt không?

Có. Lần kiểm tra lại báo số lượng giỏ là 2 và $48.00, rồi số lượng xem lại là 2 và $48.00, và judge() trả về đạt mà không có kiểm tra nào trượt.

Mất 38,9 giây với 5 mục hoạt động trình duyệt, so với 96,5 giây và 7 mục cho bài đầu, trong đó có 47 giây chờ trước khi bắt đầu hoạt động trình duyệt.

Lần kiểm tra lại đạt mà không cần phê duyệt mới. Ảnh: Tác giả.

Computer Use có trả về ảnh chụp màn hình cho mọi hoạt động không?

Không nhất thiết. Ngay cả khi bật include_screenshots, bài kiểm thử đầu trả về 2 ảnh chụp từ 7 mục hoạt động, và lần kiểm tra lại trả về 2 từ 5.

Một số mục trả output: null, nên báo cáo không thể giả định có ảnh cho mọi hoạt động.

Luồng sự kiện không phải video liên tục của trình duyệt lưu trữ; nó trả về các mục hoạt động trình duyệt và ảnh chụp khi có.

Northstar dùng rrweb để ghi lại thay đổi DOM và tương tác, gửi về cùng máy chủ và phát lại cả hai hành trình bên dưới.