Tutorial Computer Use OpenAI Agents API: Bangun Agen QA Browser

Bayangkan sebuah checkout yang menampilkan $48 di keranjang dan $24 di halaman ulasan. Pelanggan melihat dua total dalam satu checkout.

Tim biasanya menjalankan pengujian quality assurance (QA) pada alur ini dengan skrip browser: klik tombol ini, buka halaman itu, periksa nilai ini. Uji berbasis skrip hanya memeriksa keadaan yang ditulis pembuatnya.

Sebuah agen AI adalah model yang dapat mengambil tindakan menuju suatu tujuan. Agents API dari OpenAI mengelola loop agen dan menyimpan pekerjaannya dalam sebuah sesi. Dalam tutorial ini, Computer Use juga menyediakan browser ter-host.

Northstar Checkout adalah toko uji fiksi dengan bug subtotal tersembunyi.

Agen menerima hasil checkout yang benar, tetapi tidak lokasi bug atau daftar tombol yang harus ditekan. Program Python kecil, disebut harness, membandingkan nilai yang dilaporkan agen dan kemudian meminta sesi yang sama untuk menguji toko yang telah diperbaiki.

Dalam tutorial ini, saya akan membahas cara:

• Membuat sesi Agents API dengan Computer Use yang hanya dapat menjangkau situs uji
• Menyetujui permintaan browser untuk membuka situs tersebut, dan menolak yang lainnya
• Membiarkan kode Anda sendiri yang memutuskan apakah uji lulus
• Menguji ulang situs yang telah diperbaiki dalam sesi yang sama dan menghitung biaya eksperimen

Kode dan pengukuran menggunakan versi 3.22.1 dari paket Python openai.

Intinya

Jika Anda hanya punya satu menit, berikut poin-poin utamanya.

• Build bermasalah hanya gagal pada subtotal ulasan; kuantitas tetap benar.
• Build yang diperbaiki lulus dalam sesi yang sama tanpa persetujuan origin kedua.
• Penghitung token menghasilkan estimasi tarif standar $0,9469. Biaya penulisan cache dan komputasi sandbox ter-host tidak termasuk, dan penggunaan Agents API bersifat best-effort, bukan tagihan final.
• Pada setiap uji, API mengembalikan 2 tangkapan layar, masing-masing dari 7 dan 5 item computer_use_call.

Ini adalah satu toko uji dengan satu bug yang ditanam, bukan tolok ukur reliabilitas.

Apa Itu Computer Use di OpenAI Agents API?

Computer Use adalah alat di OpenAI Agents API yang memungkinkan agen mengoperasikan browser yang berjalan di server OpenAI. Kode Anda mengikuti peristiwa sesi dan menjawab permintaannya. OpenAI mencantumkan pengujian situs web sebagai salah satu kegunaannya.

OpenAI mengelola loop agen, sesi, dan pemulihan. Tutorial OpenAI Agents API kami membahas dasar-dasar tersebut.

Setup computer use yang lebih lama, seperti dalam tutorial computer use GPT-5.4 kami, membuat kode pengembang yang menjalankan loop tangkapan layar dan aksi sebagai gantinya.

Mengapa menggunakan Computer Use untuk pengujian QA browser?

Dalam QA browser, halaman itu sendiri adalah objek yang diuji.

Memanggil API checkout secara langsung akan melewati halaman tempat bug Northstar berada, sehingga agen mengikuti jalur yang sama seperti pelanggan, dari halaman produk ke keranjang, checkout, dan ulasan.

Harness, sesi, browser ter-host, situs staging. Gambar oleh Penulis.

OpenAI mengelola sesi dan browser di dalam area abu-abu; harness dan Northstar tetap di luarnya.

Apa yang Akan Kita Bangun dengan Agents API Computer Use?

Proyek ini adalah toko staging fiksi, sebuah harness Python, dan satu sesi Agents API.

Seluruh kode ada di repositori GitHub ini.

Kasus uji Northstar Checkout

Northstar menjual satu Trail Bottle seharga $24. Uji bergerak dari produk ke keranjang, checkout, dan ulasan; tidak ada pengiriman, pajak, login, atau tombol pembelian yang berfungsi.

Halaman produk Northstar sebelum pengujian. Gambar oleh Penulis.

Build ns-1041 berisi bug, sedangkan ns-1042 berisi perbaikannya. Menambahkan ?reset=1 ke URL awal build mengosongkan keranjang sebelum kedua uji.

Permintaan QA ditulis sebagai sebuah tujuan. Kriteria penerimaannya meminta agen untuk:

• Temukan Trail Bottle dan masukkan 2 ke keranjang
• Periksa bahwa subtotal keranjang adalah $48,00
• Lanjut ke halaman ulasan pesanan dan periksa bahwa kuantitas dan subtotal masih cocok
• Laporkan hanya nilai yang terlihat di browser

Kendala keamanan terpisah menyatakan untuk tidak pernah melakukan, mengirim, atau membayar pesanan. Permintaan mendefinisikan hasil, bukan kliknya.

Bug checkout yang ditanam

Build bermasalah menjumlahkan harga satuan di halaman ulasan dan melupakan kuantitas. Kedua halaman menampilkan kuantitas 2, tetapi subtotal keranjang $48,00 dan subtotal ulasan $24,00.

Kunci jawaban berada di kode aplikasi. Instruksi maupun pesan tugas tidak menyebutkan bug tersebut.

Cara kode aplikasi memutuskan lulus atau gagal

Agen melaporkan ID build dan 4 nilai yang diamati melalui satu alat fungsi, record_qa_result.

Harness pertama-tama memeriksa bahwa build yang dilaporkan adalah yang diuji, karena kedua build berbagi hostname, lalu membandingkan nilai dengan kunci jawaban.

Alat fungsi hanya berjalan jika agen memanggilnya. Catatan hilang, nilai hilang, atau build yang salah membuat hasil incomplete, yang tidak pernah dihitung sebagai lulus.

Dari tujuan QA ke putusan aplikasi. Gambar oleh Penulis.

Cara Menyiapkan Pengujian Browser OpenAI Agents API

Anda memerlukan Python, kunci API dengan cakupan, akses GPT-6 Astra, dan satu sesi dengan Computer Use.

Prasyarat untuk Computer Use Agents API

• Python 3.10 atau lebih baru dan openai==3.22.1 (SDK mengirim header OpenAI-Beta: agents=v1 untuk Anda)
• Kunci API dengan cakupan api.agents.read, api.agents.write, dan api.responses.write, pada proyek yang dapat menggunakan gpt-6-astra

Agents API berada dalam public beta, jadi nama bidang dan perilaku dapat berubah antar rilis SDK. Repositori mem-pin versi 3.22.1 di requirements.txt.

Browser ter-host memerlukan URL yang dapat dijangkau, jadi kode menggunakan deployment Vercel dari Northstar.

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

Untuk selengkapnya tentang dependensi terisolasi, lihat panduan virtual environment kami. Di macOS atau Linux, aktifkan dengan source .venv/bin/activate dan salin berkas dengan cp. Simpan kunci di .env, jangan pernah di dalam kode.

Eksperimen ini menggunakan GPT-6 Astra, model dalam contoh Computer Use OpenAI. Tinjauan GPT-6 Astra kami membahas modelnya.

Kode menggunakan Agents API (client.beta.agents), bukan Agents SDK atau alat computer Responses API yang digunakan dalam tutorial GPT-6 Astra API kami.

Konfigurasikan sesi Computer Use

Buat satu sesi dengan alat computer_use dan desktop ter-host OpenAI, lalu gunakan kembali untuk kedua uji:

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 menampilkan tangkapan layar apa pun yang dikembalikan API, sementara akses jaringan terbatas membatasi browser ke Northstar.

Lingkungan menggunakan ukuran default medium (2 vCPU, 4 GB RAM).

Tambahkan alat fungsi untuk hasil QA

Fungsi mencatat apa yang diamati agen. Jika agen tidak dapat membaca salah satu dari 4 nilai kuantitas atau subtotal yang diperiksa, ia harus melaporkan bidang tersebut sebagai null.

Mencantumkan setiap properti di bawah required memberi tahu model untuk menjawab semuanya, menggunakan null untuk apa pun yang tidak dilihatnya. Harness tetap memperlakukan bidang yang hilang sebagai 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 mengonversi setiap harga yang ditampilkan ke sen, memverifikasi ID build, dan membandingkan nilai dengan kunci jawaban:

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}

Nilai yang tidak terbaca atau hilang menghasilkan putusan incomplete, tidak pernah lulus.

Laporan dari build yang salah mengembalikan incomplete sebelum nilainya dapat memengaruhi putusan.

Tulis instruksi QA

Instruksi yang sama mengatur kedua uji:

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."
)

Hanya build situs web yang berubah di antara uji.

Cara Menjalankan Uji QA Browser dengan Computer Use

Buka event stream, kirim tujuan QA sekali, lalu tangani persetujuan dan panggilan fungsi hingga giliran selesai.

Kirim tugas QA ke sesi Agents API

Buka event stream terlebih dahulu, lalu kirim tugas tepat satu kali:

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)

Stream tidak memutar ulang peristiwa yang terlewat. Jika stream terputus, buka yang baru, lalu ambil sesi dan item yang tersimpan selama tetap tersambung.

Pesan tugas menyebutkan build, kriteria penerimaan, dan kendala keamanan, tetapi tidak ada tentang bug:

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.

Simpan ID sesi untuk uji ulang.

Tangani persetujuan origin browser

Browser ter-host meminta persetujuan sebelum membuka setiap origin situs web baru.

Stream memancarkan agent.session.requires_action; ambil sesi dan baca required_actions untuk permintaannya.

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}])

Lacak aktivitas browser dengan event sesi

Pekerjaan browser muncul sebagai item computer_use_call, masing-masing dengan judul singkat dan status. Event stream untuk uji pertama menunjukkan:

   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

Sekitar 47 detik berlalu sebelum aktivitas browser pertama.

Semua 7 item computer_use_call selesai, tetapi status item bukanlah putusan QA; hasil fungsi yang menentukan.

Apakah Agen Menemukan Bug Checkout?

Ya. Lebih penting lagi, panggilan fungsi mengisolasi kegagalan pada satu bidang: subtotal ulasan.

Apa yang dilaporkan GPT-6 Astra

Panggilan record_qa_result berisi:

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

Setiap nilai cocok dengan halaman bermasalah. Kuantitas tetap 2 di halaman ulasan, yang menyingkirkan ketidakcocokan kuantitas yang terlihat.

Bagaimana harness mengubah laporan menjadi gagal

judge() mengonfirmasi build ns-1041, membandingkan 4 nilai dengan nilai yang diharapkan, dan menemukan hanya subtotal ulasan yang salah.

Ini satu-satunya putusan yang digunakan eksperimen:

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

Uji Ulang Perbaikan dalam Sesi Agents API yang Sama

Setelah perbaikan tayang, kirim satu pesan lagi ke sesi yang sama.

Uji regresi kecil ini menggunakan instruksi dan fungsi putusan yang sama.

Kirim perbaikan tanpa mengubah uji

Perbaikan pada build ns-1042 adalah satu baris JavaScript milik 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);

Kirim tindak lanjut dalam sesi yang sama

Tautan awal menyertakan ?reset=1, jadi uji ulang dimulai dengan keranjang kosong. Lalu tindak lanjutnya dikirim ke sesi yang sama:

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.

Uji ulang mempertahankan lingkungan ter-host dan tidak memerlukan persetujuan origin baru. Jangan bergantung pada status browser, karena cookie dapat kedaluwarsa dan daur ulang lingkungan akan menghapusnya.

Satu sesi menjalankan kedua uji QA. Gambar oleh Penulis.

Sandbox ter-host dapat dihapus jika aktivitas dan keep-alives berhenti selama 1 jam. Perhatikan agent.session.environment.reset dan mulai setiap uji ulang dari keadaan yang diketahui.

Apakah uji ulang lulus?

Ya. Uji ulang melaporkan kuantitas keranjang 2 dan $48,00, lalu kuantitas ulasan 2 dan $48,00, dan judge() mengembalikan lulus tanpa pemeriksaan gagal.

Waktunya 38,9 detik dengan 5 item aktivitas browser, dibanding 96,5 detik dan 7 item untuk uji pertama, yang mencakup waktu tunggu 47 detik sebelum aktivitas browser dimulai.

Uji ulang lulus tanpa persetujuan baru. Gambar oleh Penulis.

Apakah Computer Use Mengembalikan Tangkapan Layar untuk Setiap Aktivitas?

Tidak selalu. Bahkan dengan include_screenshots diaktifkan, uji pertama mengembalikan 2 tangkapan layar dari 7 item aktivitas browser, dan uji ulang mengembalikan 2 dari 5.

Beberapa item mengembalikan output: null, jadi laporan tidak bisa berasumsi ada gambar untuk setiap aktivitas.

Event stream bukan umpan video kontinu dari browser ter-host; ia mengembalikan item aktivitas browser dan tangkapan layar saat tersedia.

Northstar menggunakan rrweb untuk merekam perubahan Document Object Model (DOM) dan interaksi, mengirimkannya ke host yang sama, dan memutar ulang kedua perjalanan di bawah ini.