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.idMit 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:
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.
Das Modell trägt einen Namen in ein Formular für Besucherausweise ein und klickt auf „Create badge“. Der Treiber erlaubt nur das Lesen der Seite, Texteingaben und Klicks. Sein Bestätigungs-Callback lässt ausschließlich die Bedienelemente dieses Formulars und den Namen Mira zu. Das Skript prüft das Ergebnis auf der Seite, bevor es Erfolg meldet.
Speichere das Beispiel für deine Programmiersprache als badge.py oder badge.mts:
import asyncio
from openai import AsyncOpenAI
from openai.lib.browser import AsyncBrowserToolset
from openai.lib.responses_tool_runner import AsyncResponsesToolRunner
from playwright.async_api import async_playwright
class BadgeForm:
def __init__(self, page):
self.page = page
async def state(self):
return {
"tabs": [
{
"id": "badge",
"title": await self.page.title(),
"url": self.page.url,
"active": True,
}
]
}
async def read_page(self, args):
return {
"version": 1,
"text": await self.page.locator("body").inner_text(),
"elements": [
{"ref": "name", "role": "textbox", "label": "Name"},
{"ref": "save", "role": "button", "label": "Create badge"},
],
"omitted": [],
}
async def type(self, args):
await self.page.locator("#name").fill(args["text"])
async def click(self, args):
await self.page.locator("#save").click()
async def confirm(self, context):
args = context["arguments"]
if self.page.url != "about:blank" or args["tab_id"] not in (None, "badge"):
return False
return (
context["member"] == "type"
and args["target"] == "name"
and args["text"] == "Mira"
) or (context["member"] == "click" and args["target"] == "save")
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()
await page.route("**/*", lambda route: route.abort())
await page.set_content("""
<title>Visitor badge</title>
<label>Name <input id="name"></label>
<button id="save" onclick="document.querySelector('output').innerText =
'Badge ready: ' + document.querySelector('#name').value">Create badge</button>
<output></output>
""")
driver = BadgeForm(page)
tools = AsyncBrowserToolset(
driver, members=["read_page", "type", "click"], confirm=driver.confirm
)
response = await AsyncResponsesToolRunner(browser=tools).run(
client,
{
"model": "gpt-6-astra",
"store": False,
"input": "Create a visitor badge for Mira.",
},
max_steps=6,
)
result = await page.locator("output").inner_text()
if result != "Badge ready: Mira":
raise RuntimeError(f"The badge was not created: {result!r}")
print(result)
print("Answer:", response.output_text)
finally:
await browser.close()
if __name__ == "__main__":
asyncio.run(main())Führe .venv/bin/python badge.py oder node --experimental-strip-types badge.mts aus. Bei Erfolg gibt das Skript Badge ready: Mira und anschließend die Antwort des Modells aus.
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
storeauffalse. 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.
- Folge in einer isolierten Umgebung der Setup-Anleitung für die gewählte Implementierung.
- Wähle eines der mitgelieferten Szenarien und starte einen Lauf.
- 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.
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.idimport { randomUUID } from "node:crypto";
import OpenAI from "openai";
async function runComputerUse(
endpoint: string,
prompt: string,
model = "gpt-6-astra"
) {
const client = new OpenAI();
const sessionId = randomUUID();
const tools: OpenAI.Responses.Tool[] = [
{
type: "function",
name: "exec_js",
description: `Run JavaScript in a persistent browser. Available: Playwright's
browser, context, and page objects; console.log(value); and display(base64Image).
Save reusable variables on globalThis. Inspect a screenshot before acting and
check the screen after a short group of actions. Keep screenshots in memory.
Use top-level await for async operations. Return images with display() and concise
text with console.log(). The context viewport is 1440x900.`,
parameters: {
type: "object",
properties: { code: { type: "string" } },
required: ["code"],
additionalProperties: false,
},
strict: true,
},
];
let nextInput: OpenAI.Responses.ResponseInput = [
{ role: "user", content: prompt },
];
let previousResponseId: string | undefined;
for (let turn = 0; turn < 20; turn++) {
const response: OpenAI.Responses.Response = await client.responses.create({
model,
tools,
input: nextInput,
previous_response_id: previousResponseId,
reasoning: { effort: "low" },
});
if (response.status !== "completed") {
throw new Error(`Response stopped with status: ${response.status}`);
}
const calls = response.output.filter(
(item) => item.type === "function_call"
);
if (
calls.length === 0 &&
response.output.some(
(item) => item.type === "message" && item.phase !== "commentary"
)
) {
console.log(response.output_text);
return;
}
if (turn === 19) {
throw new Error(
"The task reached the 20-response limit. Inspect the last result."
);
}
nextInput = [];
for (const call of calls) {
if (call.name !== "exec_js")
throw new Error(`Unexpected tool: ${call.name}`);
const { code } = JSON.parse(call.arguments);
const output = await executeInSandbox(code, sessionId, endpoint);
nextInput.push({
type: "function_call_output",
call_id: call.call_id,
output,
});
}
previousResponseId = response.id;
}
}require "json"
require "openai"
require "securerandom"
def run_computer_use(endpoint, prompt)
client = OpenAI::Client.new
session_id = SecureRandom.uuid
tools = [
{
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 = []
next_input << {
role: :user,
content: prompt
}
history = {}
20.times do |turn|
response = client.responses.create(
model: "gpt-6-astra", tools: tools, input: next_input, previous_response_id: history[:id]
)
raise "Response stopped with status: #{response.status}" unless response.status == OpenAI::Responses::ResponseStatus::COMPLETED
calls = response.output.grep(OpenAI::Responses::ResponseFunctionToolCall)
if calls.empty? && response.output.any? { |item| item.is_a?(OpenAI::Responses::ResponseOutputMessage) && item.phase != :commentary }
puts(response.output_text)
return response
end
raise "The task reached the 20-response limit" if turn == 19
next_input.clear
calls.each do |call|
raise "Unexpected tool: #{call.name}" unless call.name == "exec_py"
code = JSON.parse(call.arguments).fetch("code")
raise "Expected Python source text" unless code.is_a?(String)
output = execute_in_sandbox(code, session_id, endpoint)
next_input << {
type: :function_call_output,
call_id: call.call_id,
output: output
}
end
history[:id] = response.id
end
endfunc runComputerUse(ctx context.Context, client openai.Client, endpoint, prompt string, terminal *bufio.Scanner, output io.Writer) error {
session := make([]byte, 16)
if _, err := rand.Read(session); err != nil {
return err
}
sessionID := hex.EncodeToString(session)
tool := responses.ToolParamOfFunction("exec_py", map[string]any{
"type": "object", "properties": map[string]any{"code": map[string]any{"type": "string"}},
"required": []string{"code"}, "additionalProperties": false,
}, true)
tool.OfFunction.Description = openai.String("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.")
params := responses.ResponseNewParams{
Model: "gpt-6-astra", Tools: []responses.ToolUnionParam{tool},
Input: responses.ResponseNewParamsInputUnion{OfString: openai.String(prompt)},
}
for turn := 0; turn < 20; turn++ {
response, err := client.Responses.New(ctx, params)
if err != nil {
return err
}
if response.Status != "completed" {
return fmt.Errorf("response stopped with status: %s", response.Status)
}
var calls []responses.ResponseFunctionToolCall
finalMessage := false
for _, item := range response.Output {
if item.Type == "function_call" {
calls = append(calls, item.AsFunctionCall())
}
if item.Type == "message" && item.AsMessage().Phase != "commentary" {
finalMessage = true
}
}
if len(calls) == 0 && finalMessage {
fmt.Fprintln(output, response.OutputText())
return nil
}
if turn == 19 {
return fmt.Errorf("task reached the 20-response limit; inspect the last result")
}
nextInput := responses.ResponseInputParam{}
for _, call := range calls {
if call.Name != "exec_py" {
return fmt.Errorf("unexpected tool: %s", call.Name)
}
var arguments struct {
Code *string `json:"code"`
}
if err := json.Unmarshal([]byte(call.Arguments), &arguments); err != nil {
return err
}
if arguments.Code == nil {
return fmt.Errorf("exec_py requires code")
}
observations, err := executeInSandbox(ctx, endpoint, sessionID, *arguments.Code, terminal, output)
if err != nil {
return err
}
nextInput = append(nextInput, responses.ResponseInputItemUnionParam{
OfFunctionCallOutput: &responses.ResponseInputItemFunctionCallOutputParam{
CallID: openai.String(call.CallID),
Output: responses.ResponseInputItemFunctionCallOutputOutputUnionParam{OfResponseFunctionCallOutputItemArray: observations},
},
})
}
params.Input = responses.ResponseNewParamsInputUnion{OfInputItemList: nextInput}
params.PreviousResponseID = openai.String(response.ID)
}
return nil
}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:
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.
{
"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:
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
- In den Integrationsbeispielen erfährst du, wie du die Umgebung einrichtest, Aktionen verarbeitest, Screenshots aufnimmst und Adapter für deinen Ausführungsdienst implementierst.
- Folge der Anleitung zur Migration von computer-use-preview, wenn du eine ältere Integration aktualisierst.
- In der CUA-Beispiel-App findest du vollständige Abläufe für Browser und Desktop.