Den vollständigen Index der Dokumentation findest du in llms.txt. Die Markdown-Version einer Dokumentationsseite erhältst du, indem du .md an die URL der Seite anhängst.
Hauptnavigation
Design

Computernutzung

Lass ein Modell Browser- und Desktopoberflächen bedienen.

Mit der Computernutzung kann ein Modell eine Browser- oder Desktopoberfläche bedienen. So kannst du Formulare ausfüllen, Bedienabläufe testen oder Aufgaben in einer Anwendung erledigen lassen.

Welche Integration du wählst, hängt davon ab, was das Modell sehen muss und wer die Umgebung betreibt.

Aufgabe Einstieg
Screenshots und Maus- oder Tastaturaktionen in deinem Browser oder auf deinem Desktop nutzen Verwende ComputerToolset mit dem Computer-Tool der Responses API.
Seitentext lesen oder Bedienelemente und Tabs in deinem Browser nutzen Verwende BrowserToolset. Dein Treiber stellt ausgewählte Operationen als Funktions-Tools bereit.
Einen von OpenAI gehosteten Browser verwenden Folge dem separaten Leitfaden zur Computernutzung mit der Agents API.

Für öffentliche Informationen, die sich ohne Interaktion abrufen lassen, nutze die Websuche.

Das SDK verwenden

Das SDK führt die Tool-Schleife der Responses API in Python oder Node aus. Deine Anwendung stellt einen Treiber bereit. Dieser Code liest den Zustand der Umgebung aus oder führt eine erlaubte Aktion aus. Deine Anwendung verwaltet die Sitzung und die Berechtigungen und gibt die Ressourcen nach dem Lauf frei.

Eine gehostete Umgebung anbinden

Du kannst den Browser oder Desktop eines Partnerunternehmens nutzen, ohne selbst einen zu betreiben. Einige Integrationen liefern einen Treiber mit. Andere stellen Bedienelemente bereit, die deine Anwendung an das SDK anbindet. In der Anleitung des jeweiligen Partnerunternehmens erfährst du, wie du die Integration einrichtest und welche Paketversionen sie unterstützt.

Umgebung Integration
Browserbase Verwende den Browsertreiber von Stagehand mit einer gehosteten Browserbase-Sitzung. Folge der Integrationsanleitung für Stagehand oder sieh dir die Beispiele für Python und TypeScript an.
Browser Use Nutze den Treiber der Bibliothek Browser Use oder binde vorhandenen Playwright-Code über die Integration für Browser Use Cloud an. Beide Anleitungen verwenden Python.
Daytona Verwende ComputerToolset mit einer Desktop-Sandbox von Daytona. Folge der Daytona-Anleitung zu Hilfsfunktionen für die Computernutzung (Python). Ein Beispiel mit dem Agents SDK findest du in der Anleitung zur Computernutzung mit Daytona.
E2B Desktop Führe Computeraktionen oder Code in einer Desktop-Sandbox aus. Folge der E2B-Anleitung zur Computernutzung oder sieh dir die Beispiele für Python und TypeScript an.

Lege ein Zeitlimit für die Sitzung fest. Schließe die Sitzung oder gib sie frei, auch wenn der Lauf fehlschlägt. Falls die Ressourcenfreigabe fehlschlägt, prüfe das Dashboard des Anbieters. Beschränke über dessen Netzwerkregeln, welche Websites und Ressourcen die Sitzung erreichen kann.

Deine erste Aufgabe ausführen

Verwende Python ab Version 3.11 oder Node.js ab Version 22.6. Erstelle und exportiere einen API-Schlüssel. Beide Beispiele starten vorübergehend einen lokalen Browser und rufen die Responses API auf. Dafür können Kosten anfallen.

Installiere die Pakete und Chromium in einem neuen Ordner:

# Python
python3 -m venv .venv
.venv/bin/python -m pip install openai==3.31.0 playwright==1.61.0
.venv/bin/python -m playwright install chromium

# Node
npm install openai@7.33.0 playwright@1.61.1
npx playwright install chromium

Verwende unter Windows py -3 anstelle von python3 und .venv\Scripts\python.exe anstelle von .venv/bin/python.

Das Modell sieht einen Screenshot einer fiktiven Seite zur Paketabholung und ruft per Klick die Abholdaten auf. Der Treiber erlaubt nur Screenshots und einen Linksklick auf das entsprechende Bedienelement. Er blockiert Anfragen der Seite und schließt den Browser, sobald der Lauf endet. Das Skript sendet höchstens sechs Anfragen an die Responses API und prüft die Seite, bevor es Erfolg meldet. Dein Projekt benötigt Zugriff auf ein Modell, das das Computer-Tool unterstützt.

Speichere das Beispiel für deine Programmiersprache als pickup.py oder pickup.mts:

Abholdaten mit Computeraktionen anzeigen
import asyncio
import base64

from openai import AsyncComputerToolset, AsyncOpenAI
from playwright.async_api import async_playwright


class PickupDriver:
    def __init__(self, page):
        self.page = page

    async def screenshot(self):
        image = await self.page.screenshot(type="png")
        return {
            "type": "computer_screenshot",
            "image_url": "data:image/png;base64," + base64.b64encode(image).decode(),
        }

    async def allowed(self, action):
        if action.type == "screenshot":
            return True
        if action.type != "click" or action.button != "left" or action.keys:
            return False
        box = await self.page.locator("summary").bounding_box()
        return bool(
            box
            and box["x"] <= action.x < box["x"] + box["width"]
            and box["y"] <= action.y < box["y"] + box["height"]
        )

    async def click(self, action):
        # The page may have changed after approval, so bind the click again.
        if not await self.allowed(action):
            raise RuntimeError("Pickup details moved or the click is not allowed.")
        await self.page.mouse.click(action.x, action.y)

    async def refuse(self, action):
        raise RuntimeError(f"This exercise does not allow {action.type}.")

    double_click = drag = keypress = move = scroll = type = wait = refuse


async def main():
    async with (
        async_playwright() as playwright,
        AsyncOpenAI(timeout=30, max_retries=0) as client,
    ):
        browser = await playwright.chromium.launch(env={}, chromium_sandbox=True)
        try:
            page = await browser.new_page(viewport={"width": 1024, "height": 768})
            await page.route("**/*", lambda route: route.abort())
            await page.set_content(
                "<title>Parcel pickup</title><main>"
                "<h1>Parcel pickup</h1><p>Order #1042 is ready.</p>"
                "<details><summary>Show pickup details</summary>"
                "<p>Locker 18. Pickup code: 6249.</p></details></main>"
            )
            driver = PickupDriver(page)
            tools = AsyncComputerToolset(driver)
            try:
                response = await tools.run(
                    client,
                    {
                        "model": "gpt-6.1-sol",
                        "store": False,
                        "input": "Take a screenshot. Open 'Show pickup details' and report the locker and pickup code. Use only screenshots and left clicks.",
                    },
                    before_action=driver.allowed,
                    max_steps=6,
                )
                if await page.locator("details").get_attribute("open") is None:
                    raise RuntimeError("Pickup details are still closed.")
                print(
                    "Verified pickup details:",
                    await page.locator("details p").inner_text(),
                )
                print("Answer:", response.output_text)
            finally:
                tools.close()
        finally:
            await browser.close()


if __name__ == "__main__":
    asyncio.run(main())

Führe .venv/bin/python pickup.py oder node --experimental-strip-types pickup.mts aus. Bei Erfolg gibt das Skript Verified pickup details: Locker 18. Pickup code: 6249. und anschließend die Antwort des Modells aus. Stehen noch Sicherheitsprüfungen der API aus, stoppt das Beispiel. Füge einen Callback für die Genehmigung durch eine Person erst hinzu, wenn deine Anwendung diese Prüfungen verarbeiten kann.

Wenn die API das Tool ablehnt oder Chromium nicht startet, folge der Anleitung zur Fehlerbehebung. Wenn Klicks ihr Ziel verfehlen, prüfe den Screenshot und die Koordinaten.

Modellzugriff, Kosten und Daten prüfen

  • Modell: Prüfe bei Funktions-Tools für den Browser, ob das Modell die Responses API und Funktionsaufrufe unterstützt. Wenn dein Treiber Bilder zurückgibt, prüfe auch, ob das Modell Bildeingaben unterstützt. Für Computeraktionen anhand von Screenshots prüfst du im Abschnitt „Tools“ des Modells, ob es die Computernutzung unterstützt. Sieh im Modellkatalog nach und prüfe, auf welche Modelle dein Projekt zugreifen kann.
  • Kosten: Bei jeder Anfrage an die Responses API können Kosten für Eingabe- und Ausgabetoken anfallen. Screenshots zählen als Bildeingaben. Informiere dich über die API-Preise, schätze die Kosten für Bildeingaben oder prüfe den Verbrauch pro Anfrage. Für eine gehostete Umgebung können zusätzliche Kosten anfallen.
  • Daten: Das SDK sendet den zurückgegebenen Seitentext oder die Screenshots an OpenAI. Die Beispiele setzen store auf false. Trotzdem können Daten in bestimmten Fällen aufbewahrt werden. Informiere dich über die Optionen zur Datenkontrolle und die Ausnahmen für Bildeingaben. Der Anbieter deiner Umgebung hat eigene Datenrichtlinien.

Änderungen verfolgen und genehmigen

Probiere als Nächstes die Buchungsdemo in Python oder Node aus. Sie füllt ein Formular für eine fiktive Reservierung aus, fordert vor dem Absenden deine Genehmigung an und prüft anschließend die gespeicherten Felder und die Bestätigung. Du kannst den Ablauf im Browser verfolgen, die Steuerung übernehmen und wieder zurückgeben oder den Lauf stoppen. Beide Versionen bieten einen lokalen Probelauf mit einem echten Browser ohne API-Aufruf.

Um die SDK-Aktionen auf einem Desktop zu verfolgen, probiere die visuelle Desktop-Demo aus.

Den Treiber anpassen

Ersetze die Beispielseite durch eine Umgebung, die deine Anwendung kontrolliert. Stelle bei einem Browsertreiber über members nur die Operationen bereit, die für die Aufgabe erforderlich sind. Implementiere bei einem Computertreiber die erforderlichen Methoden und weise nicht unterstützte Aktionen zurück. Halte die Sitzung bis zum Ende des Laufs offen und gib dann die Ressourcen frei, die deine Anwendung angelegt hat.

Seiteninhalte können das Modell beeinflussen. Verwende ein neues Browserprofil oder einen isolierten Desktop. Beschränke den Netzwerkzugriff und stelle sicher, dass weder Seitentext noch Screenshots Zugangsdaten enthalten. Fordere eine Genehmigung an, bevor du Änderungen vornimmst, und prüfe das gespeicherte Ergebnis, bevor du Erfolg meldest. Die Treiberreferenz beschreibt die Anforderungen an die Methoden, das Genehmigungsverfahren, die URL-Richtlinien und die Wiederherstellung.

Bei fest vorgegebenen Optionen zu Decisions wechseln

Verwende die Responses API, wenn das Modell Aktionen auswählen und die zugehörigen Argumente erzeugen muss. Nutze Decisions nur, wenn deine Anwendung bereits alle zulässigen Aktionen samt ihren vollständigen Argumenten kennt. Eine App könnte beispielsweise route_billing, route_technical und review anbieten. Decisions wählt eine Option aus. Deine Anwendung muss die Aktion weiterhin genehmigen und ausführen und anschließend das Ergebnis prüfen. Verwirf die Auswahl, wenn sich die Seite ändert. Weitere Informationen findest du im Leitfaden zu Decisions.

Um Decisions in der Buchungsdemo auszuprobieren, verwende einen Schlüssel mit Zugriff auf Decisions, setze OPENAI_DECISIONS_MODEL und starte den Server neu. Starte einen neuen Lauf und wähle „Decisions“ aus.

Die API direkt verwenden

Verwende die Responses API direkt, wenn du die Tool-Schleife selbst steuern musst. Du stellst die Umgebung bereit und führst die vom Modell angeforderten Aktionen aus. Wähle, wie du die Umgebung an deine Anwendung anbindest:

  • Codeausführung: Das Modell schreibt Code, der die Oberfläche über eine Bibliothek wie PyAutoGUI oder Playwright bedient. Ein einzelner Aufruf kann Aktionen, Schleifen oder Bedingungen kombinieren.
  • Computer-Tool: Das Modell gibt strukturierte Maus- und Tastaturaktionen zurück, die deine Anwendung in Browser- oder Desktopeingaben umsetzt.

Für GPT-6 Astra empfehlen wir die Codeausführung. Das Tool computer wird als Alternative weiterhin unterstützt.

Wenn du Bedienaktionen bereits über Funktionsaufrufe oder Remote-MCP-Tools bereitstellst, kannst du diese Schnittstelle beibehalten. Im Abschnitt Eigene UI-Tools verwenden erfährst du, wie sich diese Integrationen bei der Ausführung von Tools und der Rückgabe von Ergebnissen unterscheiden.

Code ausführen

Bei einer Integration mit Codeausführung erhält das Modell ein Funktions-Tool, das ein Skript entgegennimmt. Deine Anwendung führt das Skript in einer isolierten Browser- oder Desktopumgebung aus und gibt dessen Ausgabe einschließlich der Screenshots zurück. Halte die Umgebung zwischen den Aufrufen verfügbar, damit das Modell seine bisherige Arbeit fortsetzen kann.

Die Beispiel-App ausführen

Die CUA-Beispiel-App enthält Implementierungen mit JavaScript und Playwright sowie mit Python und PyAutoGUI. Beide bieten lokale Aufgaben und nutzen eine gemeinsame Konsole.

  1. Folge in einer isolierten Umgebung der Setup-Anleitung für die gewählte Implementierung.
  2. Wähle eines der mitgelieferten Szenarien und starte einen Lauf.
  3. Prüfe anhand der Aktionen, der Screenshots und des Endzustands, ob die Aufgabe erfolgreich abgeschlossen wurde.

In der README der App findest du Hinweise zur Installation, zu den Desktopberechtigungen und zu den unterstützten Umgebungen. Lies den Abschnitt Sichere Ausführung, bevor du die App für echte Websites oder Konten anpasst.

Deine eigene Laufzeitumgebung anbinden

Das folgende Beispiel zeigt die API-Schleife für eine Laufzeitumgebung, die du selbst bereitstellst. Die Clients für Python, Ruby und Go senden Python-Code an eine Desktop-Laufzeitumgebung mit PyAutoGUI. Der JavaScript-Client bedient einen Browser mit Playwright. Jeder Client stellt ein reguläres Funktions-Tool bereit und gibt Text oder Bilder mit der ursprünglichen call_id zurück.

Die Hilfsfunktion execute_in_sandbox oder executeInSandbox sendet Code an deine Ausführungsumgebung und gibt die dort erfassten Beobachtungen zurück. Sie muss die Browser- oder Desktopsitzung aufrechterhalten, Ausführungsgrenzen durchsetzen und deine Berechtigungsregeln anwenden. Diese Integrationsbeispiele sind unabhängig vom Start der Beispiel-App.

Computernutzung mit Codeausführung
import json
import uuid

from openai import OpenAI
from openai.types.responses import (
    FunctionToolParam,
    ResponseInputParam,
)

def run_computer_use(endpoint, prompt, model="gpt-6-astra"):
    client = OpenAI()
    session_id = str(uuid.uuid4())
    tools: list[FunctionToolParam] = [
        {
            "type": "function",
            "name": "exec_py",
            "description": (
                "Run Python in a persistent desktop. Variables persist across calls. "
                "PyAutoGUI operations are synchronous. Available: pyautogui, time, "
                "log(value), and display(PIL_image). Inspect the screen with "
                "display(pyautogui.screenshot()) before acting. Use screenshot "
                "coordinates and check the screen after a short group of actions. "
                "Keep screenshots in memory and PyAutoGUI's fail-safe enabled."
            ),
            "parameters": {
                "type": "object",
                "properties": {"code": {"type": "string"}},
                "required": ["code"],
                "additionalProperties": False,
            },
            "strict": True,
        }
    ]
    next_input: ResponseInputParam = [{"role": "user", "content": prompt}]
    previous_response_id = None

    for turn in range(20):
        response = client.responses.create(
            model=model,
            tools=tools,
            input=next_input,
            previous_response_id=previous_response_id,
        )
        if response.status != "completed":
            raise RuntimeError(f"Response stopped with status: {response.status}")

        calls = [item for item in response.output if item.type == "function_call"]
        if not calls and any(
            item.type == "message" and item.phase != "commentary"
            for item in response.output
        ):
            print(response.output_text)
            return
        if turn == 19:
            raise RuntimeError(
                "The task reached the 20-response limit. Inspect the last result."
            )

        next_input = []
        for call in calls:
            if call.name != "exec_py":
                raise ValueError(f"Unexpected tool: {call.name}")
            code = json.loads(call.arguments)["code"]
            output = execute_in_sandbox(code, session_id, endpoint)
            next_input.append(
                {
                    "type": "function_call_output",
                    "call_id": call.call_id,
                    "output": output,
                }
            )
        previous_response_id = response.id

Einen vollständigen Client-Adapter und das erwartete Format für Text- und Bildausgaben findest du im Abschnitt Deinen Ausführungsdienst anbinden. Die Dienstschnittstelle in diesen Beispielen gehört zu deiner Anwendung. OpenAI hostet diesen Endpunkt nicht.

Zustand erhalten und Beobachtungen zurückgeben

Halte die Browser- oder Desktopsitzung zwischen den Aufrufen offen. Ein persistenter Python- oder JavaScript-Namensraum kann auch Variablen erhalten. Beschreibe die verfügbaren Objekte und Hilfsfunktionen in der Tool-Definition, damit das Modell weiß, was es verwenden kann.

Gib dem Modell einen aktuellen Screenshot, wenn der Zustand der Oberfläche unbekannt ist. Gib nach einigen Aktionen einen weiteren Screenshot zurück, damit das Modell das Ergebnis prüfen kann. Halte die Bilder im Arbeitsspeicher und verwende detail: "original", um die Auflösung beizubehalten. Wenn du einen Screenshot verkleinerst, rechne die Koordinaten des Modells vor der Ausführung der Aktionen in das Koordinatensystem der Umgebung zurück. Weitere Informationen findest du im Abschnitt Screenshots aufnehmen und die Auflösung wählen.

Die API-Unterhaltung und die Ausführungsumgebung haben jeweils einen eigenen Zustand. Bewahre die Tool-Aufrufe und ihre Ausgaben in der Unterhaltung auf und halte die zugehörige Umgebung in deiner Anwendung verfügbar. Wenn du eine Antwort fortsetzt, werden dadurch weder die Browsersitzung noch der Anmeldestatus noch die Variablen der Laufzeitumgebung wiederhergestellt.

Das Computer-Tool verwenden

Verwende diese Alternative, wenn deine Integration strukturierte Aktionen anstelle von generiertem Code erwartet.

Folge dazu derselben Setup-Anleitung für die Beispiel-App, wähle den Modus „Native“ und führe eines der mitgelieferten Szenarien aus. Verwende ein Modell, das das Computer-Tool unterstützt.

Der Austausch mit der API läuft in drei Schritten ab. Du sendest eine Aufgabe, führst die zurückgegebenen Aktionen aus und gibst einen Screenshot zurück. Die folgenden Codebeispiele verwenden eine Seite mit dem Bedienelement „Show filters“ und einem Suchfeld. Passe die Aufgabe bei der Integration des Tools an deine eigene Oberfläche an.

Wie du die Umgebung einrichtest und Aktionen verarbeitest, erfährst du in den Integrationsbeispielen.

Die Aufgabe senden

Aktiviere computer im Array tools und beschreibe das gewünschte Ergebnis:

Eine Anfrage an das Computer-Tool senden
from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-6.1-sol",
    tools=[{"type": "computer"}],
    input="Check whether the Filters panel is open. If it is not open, click Show filters. Then type penguin in the search box. Use the computer tool for UI interaction.",
)

print(response.output)

Die angeforderten Aktionen ausführen

Ein computer_call enthält ein Array namens actions, das die Reihenfolge der Aktionen vorgibt. Im folgenden Beispiel fordert der Aufruf zwei Aktionen an: das Suchfeld auswählen und penguin eingeben.

Mehrere Aktionen in einem Schritt bündeln
{
  "output": [
    {
      "type": "computer_call",
      "call_id": "call_002",
      "actions": [
        { "type": "click", "button": "left", "x": 405, "y": 157 },
        { "type": "type", "text": "penguin" }
      ],
      "status": "completed"
    }
  ]
}

Dein Aktionshandler setzt diese Anfragen in Eingaben für den Browser oder das Betriebssystem um. Führe die erlaubten Aktionen in der vorgegebenen Reihenfolge aus und nimm anschließend einen Screenshot des aktualisierten Bildschirms auf. Das Modell kann click, double_click, drag, move, scroll, keypress, type, wait oder screenshot anfordern.

Der erste Aufruf kann als einzige Aktion screenshot enthalten. Nimm in diesem Fall den aktuellen Bildschirm auf und gib den Screenshot zurück, ohne die Oberfläche zu verändern. Der Wert status: "completed" bedeutet, dass das Modell den Aufruf vollständig generiert hat. Deine Anwendung muss ihn noch ausführen.

Die Beispiele für Aktionshandler zeigen, wie du Tastenzuordnungen, Mausbewegungen beim Ziehen und Modifikatortasten handhabst.

Den Screenshot zurückgeben

Gib ein computer_call_output zurück, dessen call_id mit der ID des verarbeiteten Aufrufs übereinstimmt. Verwende previous_response_id, um die Unterhaltung mit dem Modell fortzusetzen:

Den aktualisierten Screenshot senden
from openai import OpenAI

client = OpenAI()


def send_computer_screenshot(response, call_id, screenshot_base64):
    return client.responses.create(
        model="gpt-6.1-sol",
        tools=[{"type": "computer"}],
        previous_response_id=response.id,
        input=[
            {
                "type": "computer_call_output",
                "call_id": call_id,
                "output": {
                    "type": "computer_screenshot",
                    "image_url": f"data:image/png;base64,{screenshot_base64}",
                    "detail": "original",
                },
            }
        ],
    )

Für diese Schleife gelten dieselben Hinweise zu Screenshots und zum Erhalt des Zustands. Halte die Umgebung verfügbar, während du mit previous_response_id die Unterhaltung mit dem Modell fortsetzt.

Wiederhole die Schritte, bis das Modell keine computer_call-Elemente mehr zurückgibt. Prüfe, ob die übrige Ausgabe eine Antwort, eine Bitte um Hilfe oder einen weiteren Tool-Aufruf enthält, und überprüfe das Ergebnis in der Anwendung. In diesem Beispiel sollte der Bereich „Filters“ geöffnet sein und im Suchfeld sollte penguin stehen.

Im Abschnitt Die Schleife für die Computernutzung wiederholen findest du das Grundgerüst der Schleife samt den erforderlichen Hilfsfunktionen für Aktionen und Screenshots.

Sichere Ausführung

Die Computernutzung kann sich auf echte Konten und Daten auswirken. Setze die folgenden Schutzmaßnahmen in deiner Anwendung und deiner Ausführungsumgebung um und nimm sie auch in die Anweisungen für das Modell auf.

  • Beschränke die Umgebung. Nutze einen isolierten Browser oder eine virtuelle Maschine und lege eine Liste erlaubter Websites und Aktionen fest. Erlaube nur die Zugriffe, die für die Aufgabe nötig sind.
  • Behandle Bildschirminhalte als nicht vertrauenswürdig. Text auf einer Seite, in einem Dokument oder in einem Tool-Ergebnis kann weder Berechtigungen erteilen noch Anweisungen der Person außer Kraft setzen, die den Auftrag gegeben hat.
  • Lass folgenreiche Aktionen bestätigen. Stelle sicher, dass die Personen, die deine Anwendung nutzen, die Kontrolle über Käufe, Datenübermittlungen, destruktive Änderungen und andere schwer rückgängig zu machende Aktionen behalten. Schon die Eingabe sensibler Informationen in ein Formular gilt als Datenübermittlung.
  • Setze dem Lauf Grenzen und prüfe das Ergebnis. Begrenze die Anzahl der Schritte, die Laufzeit oder die Kosten. Ermögliche einen Abbruch und prüfe das tatsächliche Ergebnis, statt dich allein auf die abschließende Antwort des Modells zu verlassen.

Die Hinweise zu Bestätigung und Einwilligung erläutern, wann eine Genehmigung erforderlich ist und wann eine Person die Steuerung übernehmen muss. Dort findest du auch Beispiel-Prompts.

Nächste Schritte