OpenAI Agents API Computer Use Eğitimi: Bir Tarayıcı QA Aracısı Oluşturun

Sepette $48, inceleme sayfasında ise $24 gösteren bir ödeme düşünün. Müşteri, aynı ödeme akışında iki farklı toplam görüyor.

Ekipler genellikle bu akış üzerinde kalite güvencesi (QA) testlerini bir tarayıcı betiğiyle yürütür: şu düğmeye tıkla, şu sayfayı aç, şu değeri kontrol et. Betiklenmiş bir test, yalnızca yazarının yazdığı durumları kontrol eder.

Bir Yapay zeka aracısı, bir amaca yönelik eylemler gerçekleştirebilen bir modeldir. OpenAI'nin Agents API'si aracı döngüsünü yönetir ve çalışmalarını bir oturumda tutar. Bu eğitimde, Computer Use ayrıca barındırılan tarayıcıyı sağlar.

Northstar Checkout, gizli bir ara toplam hatası olan kurgusal bir test mağazasıdır.

Aracı, doğru ödeme sonucunu alır; ancak hatanın yerini veya basılacak düğmelerin bir listesini almaz. Harness adı verilen küçük bir Python programı, aracının bildirdiği değerleri karşılaştırır ve ardından aynı oturumdan düzeltilmiş mağazayı test etmesini ister.

Bu eğitimde şunları ele alacağım:

• Yalnızca test sitesine erişebilen Computer Use ile bir Agents API oturumu oluşturma
• Tarayıcının o siteyi açma isteğini onaylama ve diğer tüm istekleri reddetme
• Testin geçip geçmediğine kendi kodunuzun karar vermesi
• Aynı oturumda düzeltilmiş siteyi yeniden test etme ve deneyin maliyetini çıkarma

Kod ve ölçümler openai Python paketinin 3.22.1 sürümünü kullanır.

Kısaca

Yalnızca bir dakikanız varsa, temel çıkarımlar burada.

• Hatalı sürümde yalnızca inceleme ara toplamı başarısız oldu; adet doğru kaldı.
• Düzeltilmiş sürüm, aynı oturumda ikinci bir origin onayı olmadan geçti.
• Jeton sayaçları $0.9469 standart oran tahmini üretti. Önbelleğe yazma ücretleri ve barındırılan sandbox hesaplaması dahil değildir ve Agents API kullanımı, nihai faturadan ziyade en iyi çabadır.
• Her testte, API sırasıyla 7 ve 5 computer_use_call öğesinden 2 ekran görüntüsü döndürdü.

Bu, kasıtlı olarak yerleştirilmiş tek bir hataya sahip tek bir test mağazasıdır; bir güvenilirlik kıyaslaması değildir.

OpenAI Agents API'de Computer Use Nedir?

Computer Use, OpenAI Agents API içinde, bir aracının OpenAI sunucularında çalışan bir tarayıcıyı kullanmasına olanak tanıyan bir araçtır. Kodunuz oturumun olaylarını izler ve isteklerine yanıt verir. OpenAI, web sitesi testini kullanım alanlarından biri olarak listeler.

OpenAI, aracı döngüsünü, oturumu ve kurtarmayı yönetir. OpenAI Agents API eğitimimiz bu temelleri kapsar.

Daha eski computer use kurulumları, örneğin GPT-5.4 computer use eğitimindeki gibi, ekran görüntüsü-ve-eylem döngüsünü geliştirici koduna yaptırır.

Neden tarayıcı QA testleri için Computer Use kullanmalı?

Tarayıcı QA'de, test edilen şey bizzat sayfanın kendisidir.

Bir ödeme API'sini doğrudan çağırmak, Northstar'ın hatasının bulunduğu sayfayı atlar; bu nedenle aracı, bir müşterinin izleyeceği aynı yolu izler: ürün sayfasından sepete, ödemeye ve incelemeye.

Harness, oturum, barındırılan tarayıcı, staging sitesi. Görsel: Yazar.

OpenAI, gri bölgenin içindeki oturumu ve tarayıcıyı yönetir; harness ve Northstar onun dışında kalır.

Agents API Computer Use ile Ne İnşa Edeceğiz?

Proje; kurgusal bir staging mağazası, bir Python harness ve tek bir Agents API oturumundan oluşur.

Tüm kod bu GitHub deposunda.

Northstar Checkout test senaryosu

Northstar, $24'lık tek bir Trail Bottle satar. Test; ürün sayfasından sepete, ödemeye ve incelemeye ilerler; kargo, vergi, giriş veya çalışan bir satın alma düğmesi yoktur.

Testten önce Northstar ürün sayfası. Görsel: Yazar.

ns-1041 sürümü hatayı içerirken, ns-1042 sürümü düzeltmeyi içerir. Bir sürümün başlangıç URL'sine ?reset=1 eklemek, her iki testten önce sepeti boşaltır.

QA talebi bir hedef olarak yazılmıştır. Kabul kriterleri, aracının şunları yapmasını ister:

• Trail Bottle'ı bulup sepete 2 tane eklemek
• Sepet ara toplamının $48.00 olduğunu kontrol etmek
• Sipariş inceleme sayfasına devam edip, adet ve ara toplamın hâlâ eşleştiğini kontrol etmek
• Yalnızca tarayıcıda görünen değerleri raporlamak

Ayrı bir güvenlik kısıtı, asla bir sipariş vermemeyi, göndermemeyi veya ödeme yapmamayı söyler. İstek, tıklamaları değil sonucu tanımlar.

Yerleştirilmiş ödeme hatası

Hatalı sürüm, inceleme sayfasında birim fiyatları toplar ve adedi unutur. Her iki sayfa da adet 2 gösterir; ancak sepette ara toplam $48.00 iken inceleme ara toplamı $24.00'dır.

Cevap anahtarı uygulama kodunda bulunur. Ne talimatlarda ne de görev mesajında hatadan bahsedilir.

Uygulama kodu geçme veya kalmayı nasıl belirler

Aracı, derleme kimliğini ve 4 gözlemlenen değeri tek bir fonksiyon aracı olan record_qa_result ile bildirir.

Harness önce, bildirilen sürümün test edilen sürüm olduğundan emin olur; çünkü her iki sürüm de bir ana bilgisayar adını paylaşır, ardından değerleri cevap anahtarıyla karşılaştırır.

Bir fonksiyon aracı yalnızca aracı onu çağırırsa çalışır. Eksik kayıt, eksik değer veya yanlış sürüm sonucu incomplete yapar ve bu asla geçer sayılmaz.

QA hedefinden uygulama hükmüne. Görsel: Yazar.

OpenAI Agents API Tarayıcı Testini Nasıl Kurarsınız

Python, kapsamlandırılmış bir API anahtarı, GPT-6 Astra erişimi ve Computer Use'lu bir oturuma ihtiyacınız var.

Agents API Computer Use için önkoşullar

• Python 3.10 veya daha yeni ve openai==3.22.1 (SDK sizin için OpenAI-Beta: agents=v1 başlığını gönderir)
• api.agents.read, api.agents.write ve api.responses.write kapsamlarına sahip ve gpt-6-astra kullanabilen bir projede tanımlı bir API anahtarı

Agents API genel betadadır; bu nedenle alan adları ve davranışlar SDK sürümleri arasında değişebilir. Depo, requirements.txt içinde 3.22.1 sürümünü sabitler.

Barındırılan tarayıcının erişilebilir bir URL'ye ihtiyacı vardır; bu nedenle kod, Northstar'ın bir Vercel dağıtımını kullanır.

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

Yalıtılmış bağımlılıklar hakkında daha fazla bilgi için sanal ortam rehberimize bakın. macOS veya Linux'ta source .venv/bin/activate ile etkinleştirin ve dosyayı cp ile kopyalayın. Anahtarı .env içinde tutun, koda asla koymayın.

Deney, OpenAI'nin Computer Use örneklerindeki model olan GPT-6 Astra'yı kullanır. GPT-6 Astra genel bakışımız modelin kendisini kapsar.

Kod, Agents SDK'yı veya GPT-6 Astra API eğitiminde kullanılan Responses API computer aracını değil, Agents API'yi (client.beta.agents) kullanır.

Bir Computer Use oturumu yapılandırın

computer_use aracı ve OpenAI barındırmalı bir masaüstüyle tek bir oturum oluşturun ve her iki test için de yeniden kullanın:

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, API'nin döndürdüğü ekran görüntülerini sağlar; kısıtlı ağ erişimi ise tarayıcıyı Northstar ile sınırlar.

Ortam varsayılan medium boyutunu kullanır (2 vCPU, 4 GB RAM).

QA sonuçları için bir fonksiyon aracı ekleyin

Fonksiyon, aracının gözlemlediklerini kaydeder. Aracı, kontrol edilen 4 adet veya ara toplam değerinden birini okuyamazsa, o alanı null olarak bildirmelidir.

required altında her özelliğin listelenmesi, modele hepsini yanıtlamasını söyler ve göremediklerine null kullanır. Harness yine de eksik bir alanı incomplete olarak değerlendirir:

"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, her görüntülenen fiyatı sente çevirir, sürüm kimliğini doğrular ve değerleri cevap anahtarıyla karşılaştırır:

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}

Okunamayan veya eksik bir değer, asla geçmeyen bir incomplete hükmü üretir.

Yanlış sürümden gelen bir rapor, değerleri hükmü etkilemeden önce incomplete döndürür.

QA talimatlarını yazın

Aynı talimatlar her iki testi de yönetir:

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

Testler arasında yalnızca web sitesi sürümü değişir.

Computer Use ile Bir Tarayıcı QA Testi Nasıl Çalıştırılır

Olay akışını açın, QA hedefini bir kez gönderin, ardından tur tamamlanana kadar onayları ve fonksiyon çağrılarını yönetin.

Agents API oturumuna bir QA görevi gönderin

Önce olay akışını açın, ardından görevi tam olarak bir kez gönderin:

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)

Akışlar kaçırılan olayları yeniden yürütmez. Akış düşerse, yeni bir tane açın; ardından bağlı kalırken oturumu ve kaydedilmiş öğelerini alın.

Görev mesajı sürümü, kabul kriterlerini ve güvenlik kısıtını belirtir; hatayla ilgili hiçbir şey söylemez:

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.

Yeniden test için oturum kimliğini saklayın.

Tarayıcı origin onayını yönetin

Barındırılan tarayıcı, her yeni web sitesi origin'ini açmadan önce onay ister.

Akış agent.session.requires_action yayar; isteği okumak için oturumu alın ve required_actions'ı kontrol edin.

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

Oturum olaylarıyla tarayıcı etkinliğini izleyin

Tarayıcı çalışmaları, her biri kısa bir başlığa ve duruma sahip computer_use_call öğeleri olarak görünür. İlk testin olay akışı şunu gösterdi:

   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

İlk tarayıcı etkinliğinden önce yaklaşık 47 saniye geçti.

Tüm 7 computer_use_call öğesi tamamlandı; ancak bir öğe durumu QA hükmü değildir; hüküm fonksiyon sonucudur.

Aracı ödeme hatasını yakaladı mı?

Evet. Daha da önemlisi, fonksiyon çağrısı hatayı tek bir alana izole etti: inceleme ara toplamı.

GPT-6 Astra ne raporladı

record_qa_result çağrısı şunları içeriyordu:

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

Her değer hatalı sayfayla eşleşiyor. İnceleme sayfasında adet 2 olarak kaldı; bu da görünür bir adet uyumsuzluğunu dışlar.

Harness raporu nasıl başarısızlığa çevirdi

judge(), ns-1041 sürümünü doğruladı, 4 değeri beklenenlerle karşılaştırdı ve yalnızca inceleme ara toplamının hatalı olduğunu buldu.

Deneyin kullandığı tek hüküm budur:

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

Aynı Agents API Oturumunda Düzeltmeyi Yeniden Test Edin

Düzeltme yayına alındıktan sonra, aynı oturuma bir mesaj daha gönderin.

Bu küçük regresyon testi aynı talimatları ve hüküm fonksiyonunu kullanır.

Testi değiştirmeden düzeltmeyi gönderin

ns-1042 sürümündeki düzeltme, Northstar'ın JavaScript'inde tek satırlı bir değişikliktir:

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

Takip mesajını aynı oturumda gönderin

Başlangıç bağlantısı ?reset=1 içerir, bu nedenle yeniden test boş bir sepetle başlar. Ardından takip mesajı aynı oturuma gider:

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.

Yeniden test, barındırılan ortamı korudu ve yeni bir origin onayı gerektirmedi. Çerezler süresi dolabileceği ve ortamın geri dönüştürülmesi durumu temizleyeceği için tarayıcı durumuna bağımlı olmayın.

Tek bir oturum her iki QA testini taşıdı. Görsel: Yazar.

Bir saat boyunca etkinlik ve keep-alive yoksa barındırılan sandbox silinebilir. agent.session.environment.reset'e dikkat edin ve her yeniden teste bilinen bir durumdan başlayın.

Yeniden test geçti mi?

Evet. Yeniden test, sepette adet 2 ve $48.00; ardından incelemede adet 2 ve $48.00 raporladı ve judge() başarısız kontrol olmadan geçer döndürdü.

Tarayıcı etkinliği öğeleri 5 iken 38.9 saniye sürdü; ilk testte 7 öğe ve 96.5 saniye sürmüştü ve bunun içinde tarayıcı etkinliği başlamadan önce 47 saniyelik bir bekleme vardı.

Yeniden test yeni bir onay olmadan geçti. Görsel: Yazar.

Computer Use Her Etkinlik İçin Bir Ekran Görüntüsü Döndürür mü?

Gerekli değil. include_screenshots ayarlı olsa bile, ilk test 7 tarayıcı etkinliği öğesinden 2 ekran görüntüsü; yeniden test ise 5 öğeden 2 ekran görüntüsü döndürdü.

Bazı öğeler output: null döndürür; bu nedenle raporlar her etkinlik için bir görsel varsayamaz.

Olay akışı, barındırılan tarayıcının sürekli bir video yayını değildir; mevcut olduğunda tarayıcı etkinlik öğeleri ve ekran görüntüleri döndürür.

Northstar, Belge Nesne Modeli (DOM) değişikliklerini ve etkileşimlerini yakalamak, aynı ana bilgisayara göndermek ve aşağıdaki her iki yolculuğu yeniden oynatmak için rrweb kullanır.