OpenAI Agents API Computer Use-handledning: Bygg en QA-agent för webbläsare

Föreställ dig en checkout som visar 48 $ i varukorgen och 24 $ på granskningssidan. Kunden ser två totalsummor i samma checkout.

Team kör vanligtvis kvalitetssäkringstester (QA) på detta flöde med ett webbläsarskript: klicka på den här knappen, öppna den där sidan, kontrollera det här värdet. Ett skriptat test kontrollerar bara de tillstånd som dess författare skrev ner.

En AI‑agent är en modell som kan vidta åtgärder mot ett mål. OpenAIs Agents API hanterar agentloopen och behåller dess arbete i en session. I den här handledningen tillhandahåller Computer Use även den hostade webbläsaren.

Northstar Checkout är en fiktiv testbutik med en dold bugg i delsumma.

Agenten får rätt checkout‑resultat, men inte buggens plats eller en lista med knappar att trycka på. Ett litet Python‑program, kallat harnessen, jämför värdena agenten rapporterar och ber sedan samma session att testa den fixade butiken.

I den här handledningen går jag igenom hur du:

• Skapar en Agents API‑session med Computer Use som bara kan nå testsajten
• Godkänner webbläsarens begäran att öppna den sajten och nekar alla andra
• Låter din egen kod avgöra om testet blev godkänt
• Testar den fixade sajten igen i samma session och räknar ut vad experimentet kostade

Koden och mätningarna använder version 3.22.1 av Python‑paketet openai.

I korthet

Om du bara har en minut kommer här de viktigaste punkterna.

• Den buggiga builden misslyckades endast på granskningssidan för delsumma; kvantiteten förblev korrekt.
• Den fixade builden klarade testet i samma session utan ett andra ursprungsgodkännande.
• Tokenräknarna gav en standardprisuppskattning på 0,9469 $. Avgifter för cache‑skrivningar och hostad sandbox‑beräkning ingår inte, och Agents API‑användning är bästa möjliga uppskattning snarare än en slutlig faktura.
• I varje test returnerade API:et 2 skärmdumpar, från 7 respektive 5 computer_use_call-poster.

Det här är en testbutik med en planterad bugg, inte ett tillförlitlighetstest.

Vad är Computer Use i OpenAI Agents API?

Computer Use är ett verktyg i OpenAI Agents API som låter en agent styra en webbläsare som körs på OpenAIs servrar. Din kod följer sessionens händelser och besvarar dess förfrågningar. OpenAI listar webbplatstester som en användning.

OpenAI hanterar agentloopen, sessionen och återhämtning. Vår handledning för OpenAI Agents API täcker dessa grunder.

Äldre datoranvändningsupplägg, som i vår GPT‑5.4‑handledning för datoranvändning, låter i stället utvecklarkod köra loopen för skärmdumpar och åtgärder.

Varför använda Computer Use för QA‑testning i webbläsare?

Vid QA i webbläsare är sidan själv det som testas.

Att anropa ett checkout‑API direkt skulle hoppa över sidan där Northstars bugg finns, så agenten följer samma väg som en kund skulle göra, från produktsidan till varukorg, checkout och granskning.

Harness, session, hostad webbläsare, staging‑sajt. Bild av författaren.

OpenAI hanterar sessionen och webbläsaren i den grå zonen; harnessen och Northstar förblir utanför den.

Vad ska vi bygga med Agents API Computer Use?

Projektet är en fiktiv stagingbutik, en Python‑harness och en Agents API‑session.

Hela koden finns i detta GitHub‑repo.

Northstar Checkouts testfall

Northstar säljer en Trail Bottle för 24 $. Testet går från produkt till varukorg, checkout och granskning; det finns ingen frakt, skatt, inloggning eller fungerande köpknapp.

Northstars produktsida före testet. Bild av författaren.

Build ns-1041 innehåller buggen, medan ns-1042 innehåller fixen. Att lägga till ?reset=1 i en builds start‑URL tömmer varukorgen före båda testerna.

QA‑förfrågan är skriven som ett mål. Dess acceptanskriterier ber agenten att:

• Hitta Trail Bottle och lägga 2 i varukorgen
• Kontrollera att varukorgens delsumma är 48,00 $
• Fortsätta till beställningsgranskningssidan och kontrollera att kvantitet och delsumma fortfarande matchar
• Rapportera endast värden som är synliga i webbläsaren

En separat säkerhetsbegränsning säger att aldrig lägga, skicka in eller betala en beställning. Förfrågan definierar utfallet, inte klicken.

Den planterade checkout‑buggen

Den buggiga builden summerar styckepriser på granskningssidan och glömmer kvantiteten. Båda sidor visar kvantitet 2, men varukorgens delsumma är 48,00 $ och granskningssidans delsumma är 24,00 $.

Facit finns i applikationskoden. Varken instruktionerna eller uppgiftsmeddelandet nämner buggen.

Hur applikationskoden avgör godkänd eller underkänd

Agenten rapporterar build‑ID och 4 observerade värden via ett funktionstool, record_qa_result.

Harnessen kontrollerar först att den rapporterade builden är den som testas, eftersom båda byggerna delar ett värdnamn, och jämför sedan värdena med facit.

Ett funktionstool körs bara om agenten anropar det. En saknad post, ett saknat värde eller fel build gör resultatet incomplete, vilket aldrig räknas som godkänt.

Från QA‑mål till applikationsdom. Bild av författaren.

Hur du sätter upp webbläsartestning med OpenAI Agents API

Du behöver Python, en avgränsad API‑nyckel, GPT‑6 Astra‑åtkomst och en session med Computer Use.

Förutsättningar för Agents API Computer Use

• Python 3.10 eller senare och openai==3.22.1 (SDK:n skickar headern OpenAI-Beta: agents=v1 åt dig)
• En API‑nyckel med rättigheterna api.agents.read, api.agents.write och api.responses.write, på ett projekt som kan använda gpt-6-astra

Agents API är i öppen beta, så fältnamn och beteende kan ändras mellan SDK‑releaser. Repot låser version 3.22.1 i requirements.txt.

Den hostade webbläsaren behöver en nåbar URL, så koden använder en Vercel‑deployment av 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

För mer om isolerade beroenden, se vår guide om virtuella miljöer. På macOS eller Linux aktiverar du med source .venv/bin/activate och kopierar filen med cp. Håll nyckeln i .env, aldrig i kod.

Experimentet använder GPT‑6 Astra, modellen i OpenAIs Computer Use‑exempel. Vår översikt av GPT‑6 Astra täcker själva modellen.

Koden använder Agents API (client.beta.agents), inte Agents SDK eller Responses API:s computer-verktyg som används i vår GPT‑6 Astra API‑handledning.

Konfigurera en Computer Use‑session

Skapa en session med verktyget computer_use och en OpenAI‑hostad desktop, återanvänd den sedan för båda testerna:

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 exponerar eventuella skärmdumpar som API:et returnerar, medan begränsad nätverksåtkomst begränsar webbläsaren till Northstar.

Miljön använder standardstorleken medium (2 vCPU, 4 GB RAM).

Lägg till ett funktionstool för QA‑resultat

Funktionen registrerar vad agenten observerade. Om agenten inte kan läsa ett av de 4 kontrollerade värdena för kvantitet eller delsumma måste den rapportera det fältet som null.

Att lista varje egenskap under required säger åt modellen att besvara alla, med null för allt den inte såg. Harnessen behandlar ändå ett saknat fält som 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,

Harnessen konverterar varje visat pris till cent, verifierar build‑ID:t och jämför värdena med facit:

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}

Ett oläsbart eller saknat värde ger domen incomplete, aldrig godkänt.

En rapport från fel build returnerar incomplete innan dess värden kan påverka domen.

Skriv QA‑instruktionerna

Samma instruktioner styr båda testerna:

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

Endast webbplatsbuilden ändras mellan testerna.

Hur du kör ett QA‑test i webbläsare med Computer Use

Öppna händelseströmmen, skicka QA‑målet en gång, hantera sedan godkännanden och funktionsanrop tills vändan är klar.

Skicka en QA‑uppgift till Agents API‑sessionen

Öppna först händelseströmmen och skicka sedan uppgiften exakt en gång:

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)

Strömmar spelar inte upp missade händelser. Om strömmen bryts, öppna en ny, hämta sedan sessionen och dess sparade poster medan den förblir ansluten.

Uppgiftsmeddelandet namnger builden, acceptanskriterierna och säkerhetsbegränsningen, men ingenting om buggen:

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.

Spara sessions‑ID:t för omtestet.

Hantera godkännande av webbläsarursprung

Den hostade webbläsaren ber om godkännande innan varje nytt webbplatsursprung öppnas.

Strömmen emitterar agent.session.requires_action; hämta sessionen och läs required_actions för begäran.

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

Spåra webbläsaraktivitet med sessionshändelser

Arbete i webbläsaren visas som computer_use_call-poster, var och en med en kort titel och en status. Händelseströmmen för det första testet visade:

   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

Cirka 47 sekunder gick innan den första webbläsaraktiviteten.

Alla 7 computer_use_call-poster slutfördes, men en posts status är inte QA‑domen; det är funktionsresultatet.

Upptäckte agenten checkout‑buggen?

Ja. Ännu viktigare: funktionsanropet isolerade felet till ett fält: granskningssidans delsumma.

Vad GPT‑6 Astra rapporterade

Anropet record_qa_result innehöll:

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

Varje värde matchar den buggiga sidan. Kvantiteten förblev 2 på granskningssidan, vilket utesluter en synlig kvantitetsavvikelse.

Hur harnessen gjorde rapporten till ett underkännande

judge() bekräftade build ns-1041, jämförde de 4 värdena med de förväntade och fann att endast granskningssidans delsumma var fel.

Detta är den enda domen experimentet använder:

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

Testa en fix igen i samma Agents API‑session

När fixen är live skickar du ett meddelande till samma session.

Det här lilla regressionstestet använder samma instruktioner och domsfunktion.

Leverera fixen utan att ändra testet

Fixen i build ns-1042 är en rad i Northstars JavaScript:

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

Skicka uppföljningen i samma session

Startlänken innehåller ?reset=1, så omtestet börjar med en tom varukorg. Sedan går uppföljningen till samma session:

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.

Omtestet behöll den hostade miljön och krävde inget nytt ursprungsgodkännande. Beroende inte av webbläsartillstånd, eftersom cookies kan löpa ut och återvinning av miljön rensar den.

En session bar båda QA‑testen. Bild av författaren.

En hostad sandbox kan raderas om aktivitet och keep‑alives upphör i 1 timme. Håll utkik efter agent.session.environment.reset och starta varje omtest från ett känt tillstånd.

Klarade omtestet?

Ja. Omtestet rapporterade varukorgskvantitet 2 och 48,00 $, sedan granskningskvantitet 2 och 48,00 $, och judge() returnerade godkänt utan misslyckade kontroller.

Det tog 38,9 sekunder med 5 webbläsaraktiviteter, jämfört med 96,5 sekunder och 7 poster för det första testet, som inkluderade 47 sekunders väntan innan webbläsaraktivitet började.

Omtestet godkändes utan ett nytt godkännande.

Returnerar Computer Use en skärmdump för varje aktivitet?

Inte nödvändigtvis. Även med include_screenshots aktiverat returnerade första testet 2 skärmdumpar från 7 webbläsaraktiviteter, och omtestet returnerade 2 från 5.

Vissa poster returnerar output: null, så rapporter kan inte förutsätta en bild för varje aktivitet.

Händelseströmmen är inte en kontinuerlig videoström av den hostade webbläsaren; den returnerar webbläsaraktiviteter och skärmdumpar när de finns tillgängliga.

Northstar använder rrweb för att fånga ändringar i Document Object Model (DOM) och interaktioner, skicka dem till samma värd och återspela båda resorna nedan.