Aqbeż għall-kontenut ewlieni
Malti— Agħżel lingwa
Menu

L-ewwel fluss tax-xogħol: navigazzjoni u interazzjoni

Lezzjoni 4 / 14 Aġġornat 3 ta’ Novembru 2026 Zviluppatur
F'din il-paġna
  1. Ingredar tal-biċċiet
  2. L-immaniġġjar tal-azzjonijiet
  3. Iċ-ċiklu sħiħ
  4. Tnedija tal-fluss tax-xogħol
  5. Funzjoni li tista’ terġa’ tuża għall-bqija tal-kors
  6. Tliet fallimenti li se tiltaqa’ magħhom
  7. Punti Ewlenin

Lezzjoni miktuba mill-ġdid fit-3 ta’ Novembru 2026 ibbażata fuq il-gwida Computer use ta’ OpenAI u r-riċetti ta’ integrazzjoni Computer use: l-aġent juża l-għodda computer mill-API tar-Risposti, immanigġjar tal-azzjonijiet mudellat fuq id-dokumentazzjoni (azzjonijiet raggruppati, keypress, scroll_x/scroll_y, mogħdijiet drag), u katina permezz ta’ previous_response_id, li jissostitwixxi l-kodiċi miktub għall-API ta’ Anthropic. Sorsi: Computer use · Integration recipes.

Ingredar tal-biċċiet

Għandek iċ-ċiklu f’moħħok u l-ambjent ikkonfigurat. Issa trid tiġborhom flimkien f’programm li jaħdem: aġent li jiftaħ enċiklopedija online, ifittex terminu, jiftaħ l-ewwel riżultat, u jirrapporta lura t-titlu tal-paġna li laħaq. Ix-xenarju jidher modest, iżda jinvolvi l-ġesti fundamentali—navigazzjoni, tipjar, ikklikkjar, qari ta’ informazzjoni—u kull ma tibni wara se jkun sempliċiment varjazzjoni itwal ta’ dan.

L-immaniġġjar tal-azzjonijiet

Il-mudell jiddeċiedi, iżda ma jesegwixxi xejn huwa stess: jirritorna lista ta’ azzjonijiet, u l-kodiċi tiegħek jittrasformahom f’ġesti ta’ Playwright, f’ordni. Din il-funzjoni ssegwi l-immaniġġjar ippubblikat minn OpenAI fir-riċetti ta’ integrazzjoni tiegħu, issimplifikat għal browser.

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

Żewġ għażliet jistħoqqilhom spjegazzjoni. L-ismijiet tat-tasti u tal-buttuni rritornati mill-mudell (ENTER, CTRL, wheel…) mhumiex dak li Playwright jistenna (Enter, Control, middle…): it-tabelli ta’ mmappjar, meħuda mid-dokumentazzjoni, jgħaqqdu d-differenza, u l-buttuni back u forward, li l-API tista’ titlob ukoll, jiġu miċħuda bħall-immaniġġjar ta’ OpenAI. U azzjoni mhux magħrufa tqajjem żball minflok ma tiġi injorata silenzjożament: waqfa iebsa hija aħjar minn aġent li jaħseb li ħa azzjoni meta ma għamilhiex.

Iċ-ċiklu sħiħ

L-aġent imbagħad jikkoordina ċ-ċiklu. L-ewwel sejħa tibgħat il-kompitu; jekk fiha biss talba għal screenshot, sempliċiment tirritorna l-iskrin. Kull screenshot jerġa’ lura għall-mudell bħala r-riżultat tas-sejħa li talbitha, irreferenzjata mill-call_id tagħha, u previous_response_id tgħaqqad id-dawriet flimkien.

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()

Tliet salvagwardji diġà huma fis-seħħ. MAX_TURNS jillimita ċ-ċiklu: mingħajr dan il-limitu, aġent diżorjentat jikkonsma l-baġit tiegħek sakemm jeżawrixxih. Sejħa b’verifiki tas-sigurtà pendenti (pending_safety_checks) twaqqaf kollox, bħall-eżempju uffiċjali ta’ OpenAI: il-lezzjoni 12 turi kif dawn jiġu vvalidati minn bniedem. U t-tlestija normali tiġi sinjalata bin-nuqqas ta’ computer_call: il-mudell waqqaf l-azzjoni u qed iwieġbek, u inti tirrikupra t-titlu tal-paġna minn output_text.

Tnedija tal-fluss tax-xogħol

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

B’headless=False, l-ispettaklu huwa edukattiv: it-tieqa tiftaħ, l-ikklikkar jinżel fil-kamp tat-tiftix, it-test jidher, l-ewwel link jiftaħ, u t-titlu jerġa’ lura fil-console tiegħek. Ara dan jaħdem darbtejn jew tliet darbiet qabel ma tgħaddi għal kompiti aktar ambizzjużi; se tara preċiżament fejn l-aġent jiddubita u x’għandhom jindirizzaw l-istruzzjonijiet tiegħek.

Funzjoni li tista’ terġa’ tuża għall-bqija tal-kors

Il-lezzjonijiet li ġejjin jaħdmu fuq paġna diġà miftuħa—wara login, f’nofs fluss tax-xogħol. Huma jiddependu fuq run_agent(task, page=page): l-istess ċiklu, estratt minn launch_agent, b’instructions fakultattivi rritornati f’kull dawra (il-lezzjoni 5 tispjega għaliex).

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

Tliet fallimenti li se tiltaqa’ magħhom

L-aġent jikklikkja sistematikament ħdejn il-mira tiegħu? Il-ħati kważi dejjem huwa diskrepanza fl-iskala bejn is-screenshot mibgħut u l-paġna li qed tikklikkja fuqha: screenshot ibiddel id-daqs, zoom tal-browser, skrin b’densità għolja. Il-koordinati tal-mudell jirreferu għall-immaġni li rċieva; jekk tiċċekkniha, ikkonverti l-koordinati tagħha fid-direzzjoni opposta.

L-aġent qed idur f’ċirku u jirrepeti l-istess ġest? Il-limitu tad-dawriet eventwalment iwaqqfu, iżda huwa aħjar li tiskopri ċ-ċiklu kmieni: jekk l-istess screenshot jerġa’ lura diversi drabi wara xulxin, l-aġent mhux qed jagħmel progress, u li twaqqfu jiffranka sejħiet mhux meħtieġa.

L-aġent qed jaġixxi fuq paġna li għadha vojta? Fuq sit tqil, page.goto() jerġa’ lura qabel ma jintemm ir-rendering, u l-ewwel screenshot juri biss sfond abjad. Stenna l-inattività tan-netwerk qabel ma tieħu l-istampa:

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

Punti Ewlenin

  • Aġent ta’ Computer Use jgħaqqad immaniġġjar tal-azzjonijiet, ċiklu ta’ kontroll, u katina ta’ risposti
  • L-ewwel sejħa tibgħat il-kompitu; kull screenshot jerġa’ lura f’computer_call_output bl-istess call_id
  • L-immaniġġjar jesegwixxi l-azzjonijiet f’ordni u jiċħad dak li ma jafx kif jagħmel
  • Dejjem illimita n-numru ta’ dawriet, waqqaf fuq pending_safety_checks, u uża headless=False waqt l-iżvilupp
  • run_agent(task, page=page) terġa’ tuża dan iċ-ċiklu għal paġna diġà miftuħa; dan huwa dak li jużaw il-lezzjonijiet li ġejjin