Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

Ensimmäinen työnkulku: navigointi ja vuorovaikutus

Oppitunti 4 / 14 Päivitetty 3. marraskuuta 2026 Kehittäjä
Tällä sivulla
  1. Palasten kokoaminen
  2. Toimintokäsittelijä
  3. Täydellinen silmukka
  4. Työnkulun käynnistäminen
  5. Uudelleenkäytettävä funktio kurssin loppuosaa varten
  6. Kolme epäonnistumista, jotka kohtaat
  7. Keskeiset asiat

Oppitunti kirjoitettu uudelleen 3. marraskuuta 2026 OpenAI:n Computer use -oppaan ja Computer use integration recipes -dokumentaation pohjalta: agentti käyttää Responses API:n computer-työkalua, dokumentaation mukaista toimintokäsittelijää (ryhmitetyt toiminnot, keypress, scroll_x/scroll_y, drag-polut) ja ketjutusta previous_response_id:n kautta, korvaten Anthropicin API:lle kirjoitetun koodin. Lähteet: Computer use · Integration recipes.

Palasten kokoaminen

Sinulla on silmukkarakenne mielessäsi ja ympäristö konfiguroituna. Nyt sinun täytyy yhdistää ne toimivaksi ohjelmaksi: agentiksi, joka avaa verkkotietosanakirjan, etsii termin, avaa ensimmäisen tuloksen ja raportoi saavuttamansa sivun otsikon. Skenaario vaikuttaa vaatimattomalta, mutta se hyödyntää perusliikkeitä – navigointia, kirjoittamista, klikkaamista, tiedon lukemista – ja kaikki myöhemmin rakentamasi on vain tämän pidempi muunnos.

Toimintokäsittelijä

Malli tekee päätökset, mutta se ei suorita mitään itse: se palauttaa listan toimintoja, ja koodisi muuntaa ne Playwright-liikkeiksi järjestyksessä. Tämä funktio noudattaa OpenAI:n integraatio-ohjeissa julkaisemaa käsittelijää, yksinkertaistettuna selainta varten.

import time

KEYS = {
    "ENTER": "Enter", "RETURN": "Enter", "ESC": "Escape", "ESCAPE": "Escape",
    "TAB": "Tab", "SPACE": "Space", "BACKSPACE": "Backspace", "DELETE": "Delete",
    "UP": "ArrowUp", "DOWN": "ArrowDown", "LEFT": "ArrowLeft", "RIGHT": "ArrowRight",
    "CTRL": "Control", "CONTROL": "Control", "SHIFT": "Shift", "ALT": "Alt",
    "CMD": "Meta", "META": "Meta",
}
BUTTONS = {"left": "left", "right": "right", "wheel": "middle"}

def execute_actions(page, actions):
    """Executes the actions from a computer_call in order."""
    for action in actions:
        if action.type in ("click", "double_click", "drag", "move", "scroll") and getattr(action, "keys", None):
            raise ValueError("Mouse action with modifier key: not handled here")
        match action.type:
            case "click":
                button = getattr(action, "button", "left")
                if button not in BUTTONS:  # back and forward don't exist in Playwright
                    raise ValueError(f"Unsupported button: {button}")
                page.mouse.click(action.x, action.y, button=BUTTONS[button])
            case "double_click":
                page.mouse.dblclick(action.x, action.y)
            case "drag":
                points = [(p.x, p.y) for p in action.path]
                page.mouse.move(*points[0])
                page.mouse.down()
                for x, y in points[1:]:
                    page.mouse.move(x, y)
                page.mouse.up()
            case "move":
                page.mouse.move(action.x, action.y)
            case "scroll":
                page.mouse.move(action.x, action.y)
                page.mouse.wheel(action.scroll_x, action.scroll_y)
            case "keypress":
                page.keyboard.press("+".join(KEYS.get(k, k) for k in action.keys))
            case "type":
                page.keyboard.type(action.text)
            case "wait":
                time.sleep(2)
            case "screenshot":
                continue  # screenshot is taken after each batch of actions
            case _:
                raise ValueError(f"Unsupported action: {action.type}")

Kaksi valintaa ansaitsee selityksen. Mallin palauttamat näppäin- ja painikenimet (ENTER, CTRL, wheel…) eivät ole niitä, joita Playwright odottaa (Enter, Control, middle…): dokumentaatiosta otetut kartoitustaulukot kuromvat kuilun umpeen, ja back- sekä forward-painikkeet, joita API voi myös pyytää, hylätään kuten OpenAI:n käsittelijässäkin. Tuntematon toiminto nostaa virheen sen sijaan, että se ohitettaisiin hiljaa: kova pysäytys on parempi kuin agentti, joka luulee toimineensa, vaikka ei ole.

Täydellinen silmukka

Agentti orkestroi sitten syklin. Ensimmäinen kutsu lähettää tehtävän; jos se sisältää vain kuvankaappauspyynnön, palautat yksinkertaisesti näytön. Jokainen kuvankaappaus palaa mallille sen kutsun tuloksena, joka sen pyysi, viitaten sen call_id:hen, ja previous_response_id linkittää vuorot toisiinsa.

import base64

from openai import OpenAI
from playwright.sync_api import sync_playwright

client = OpenAI()
MODEL = "gpt-6.1-sol"
MAX_TURNS = 15

def launch_agent(task: str, start_url: str = "https://en.wikipedia.org"):
    """Launches a Computer Use agent on a given task."""
    pw = sync_playwright().start()
    browser = pw.chromium.launch(headless=False)  # False to observe
    page = browser.new_page(viewport={"width": 1280, "height": 720})
    page.goto(start_url)
    page.wait_for_load_state("networkidle")

    try:
        response = client.responses.create(
            model=MODEL, tools=[{"type": "computer"}], input=task,
        )
        for turn in range(MAX_TURNS):
            call = next((i for i in response.output if i.type == "computer_call"), None)
            if call is None:
                print(f"Task complete: {response.output_text}")
                return response.output_text

            if call.pending_safety_checks:  # see lesson 12
                raise RuntimeError("Pending safety checks: human intervention required")
            for action in call.actions:
                print(f"  Action: {action.type}")
            execute_actions(page, call.actions)
            screenshot = base64.b64encode(page.screenshot()).decode("utf-8")

            response = client.responses.create(
                model=MODEL,
                tools=[{"type": "computer"}],
                previous_response_id=response.id,
                input=[{
                    "type": "computer_call_output",
                    "call_id": call.call_id,
                    "output": {
                        "type": "computer_screenshot",
                        "image_url": f"data:image/png;base64,{screenshot}",
                        "detail": "original",
                    },
                }],
            )
        raise RuntimeError("Maximum number of turns reached: check the page state")
    finally:
        browser.close()
        pw.stop()

Kolme suojamekanismia on jo paikallaan. MAX_TURNS rajoittaa silmukkaa: ilman tätä rajaa eksynyt agentti kuluttaisi budjettisi loppuun. Kutsu, jossa on odottavia turvallisuustarkistuksia (pending_safety_checks), pysäyttää kaiken, kuten OpenAI:n virallisessa esimerkissä: oppitunti 12 näyttää, kuinka ne validoidaan ihmisen toimesta. Normaali valmistuminen signaloidaan computer_call:in puuttumisella: malli on lopettanut toimimisen ja vastaa sinulle, ja haet sivun otsikon kohdasta output_text.

Työnkulun käynnistäminen

if __name__ == "__main__":
    launch_agent(
        "Search for 'Computer Use' in Wikipedia's search engine, "
        "open the first result, and give me the title of the page. "
        "Use the computer tool to act on the interface."
    )

Asetuksella headless=False esitys on opettavainen: ikkuna aukeaa, klikkaus osuu hakukenttään, teksti ilmestyy, ensimmäinen linkki avautuu ja otsikko palaa konsoliisi. Seuraa sen suorittamista kaksi tai kolme kertaa ennen siirtymistäsi kunnianhimoisempiin tehtäviin; näet tarkasti, missä agentti epäröi ja mitä ohjeistuksesi pitäisi korjata.

Uudelleenkäytettävä funktio kurssin loppuosaa varten

Seuraavat oppitunnit työskentelevät jo auki olevalla sivulla – kirjautumisen jälkeen tai työnkulun keskellä. Ne luottavat funktioon run_agent(task, page=page): sama silmukka, erotettuna launch_agent:ista, valinnaisilla instructions:illa, jotka palautetaan jokaisella vuorolla (oppitunti 5 selittää miksi).

def run_agent(task: str, page, instructions: str | None = None, max_turns: int = MAX_TURNS) -> str:
    """Computer Use loop on an already-open page; returns the final message."""
    request = {"model": MODEL, "tools": [{"type": "computer"}]}
    if instructions:
        request["instructions"] = instructions  # to be returned on each request

    response = client.responses.create(**request, input=task)
    for turn in range(max_turns):
        call = next((i for i in response.output if i.type == "computer_call"), None)
        if call is None:
            return response.output_text
        if call.pending_safety_checks:
            raise RuntimeError("Pending safety checks: human intervention required")

        execute_actions(page, call.actions)
        screenshot = base64.b64encode(page.screenshot()).decode("utf-8")
        response = client.responses.create(
            **request,
            previous_response_id=response.id,
            input=[{
                "type": "computer_call_output",
                "call_id": call.call_id,
                "output": {
                    "type": "computer_screenshot",
                    "image_url": f"data:image/png;base64,{screenshot}",
                    "detail": "original",
                },
            }],
        )
    raise RuntimeError("Maximum number of turns reached: check the page state")

Kolme epäonnistumista, jotka kohtaat

Klikkaako agentti järjestelmällisesti kohteensa viereen? Syyllinen on lähes aina mittakaavaero lähetetyn kuvankaappauksen ja sivun välillä, jolle klikkaat: kokoa muutettu kuvankaappaus, selaimen zoomaus, suurella tiheydellä varustettu näyttö. Mallin koordinaatit viittaavat vastaanottamaansa kuvaan; jos pienennät sitä, muunna sen koordinaatit vastakkaiseen suuntaan.

Kiertääkö agentti kehää ja toistaako samaa liikettä? Vuororaja pysäyttää sen lopulta, mutta silmukka on parempi havaita aiemmin: jos sama kuvankaappaus palaa useita kertoja peräkkäin, agentti ei etene, ja sen keskeyttäminen säästää turhilta kutsuilta.

Toimiiko agentti sivulla, joka on vielä tyhjä? Raskaalla sivustolla page.goto() palaa ennen renderöinnin valmistumista, ja ensimmäinen kuvankaappaus näyttää vain valkoisen taustan. Odota verkon toimettomuutta ennen kuvan ottamista:

page.goto(url)
page.wait_for_load_state("networkidle")

Keskeiset asiat

  • Computer Use -agentti yhdistää toimintokäsittelijän, ohjaussilmukan ja vastausketjutuksen
  • Ensimmäinen kutsu lähettää tehtävän; jokainen kuvankaappaus palaa computer_call_output:issa samalla call_id:llä
  • Käsittelijä suorittaa toiminnot järjestyksessä ja hylkää ne, joita se ei osaa tehdä
  • Rajoita aina vuorojen määrää, pysähdy kohtaan pending_safety_checks ja käytä asetusta headless=False kehitysvaiheessa
  • run_agent(task, page=page) käyttää tätä silmukkaa uudelleen jo auki olevalle sivulle; tätä seuraavat oppitunnit käyttävät