Ein Treiber setzt zulässige Tool-Aufrufe in Aktionen um, die in einem Browser oder auf einem Desktop unter deiner Kontrolle stattfinden. Verwende einen Browser-Treiber, wenn deine Anwendung Seitentext, Bedienelemente und Tabs auslesen und melden kann. Verwende einen Computer-Treiber, wenn das Modell mit Screenshots und Koordinaten arbeiten muss. Das SDK sendet Anfragen und leitet Aufrufe weiter. Deine Anwendung verwaltet die Sitzung, vergibt Berechtigungen und gibt Ressourcen wieder frei.
Gemeinsame Einstellungen konfigurieren
Beginne mit dem Browser-Beispiel in Python oder Node. Es zeigt einen vollständigen Treiber, eine Bestätigungsrichtlinie und einen Responses-Lauf mit begrenzter Anzahl von Anfragen. Halte die Sitzung bis zum Ende des Laufs offen. Python bietet für synchrone Treiber auch die synchronen Klassen BrowserToolset und ResponsesToolRunner.
| Ziel | Einstellung | Verhalten |
|---|---|---|
| Browser-Methoden einschränken | Setze members beim Erstellen von BrowserToolset oder AsyncBrowserToolset. |
Nur ausgewählte, implementierte Methoden sind verfügbar. Soll der Beispieltreiber ohne Schreibzugriff arbeiten, wähle ausschließlich read_page. Methoden auswählen. |
| Änderungen im Browser genehmigen | Übergib confirm an den Konstruktor von BrowserToolset oder AsyncBrowserToolset. |
Nur der exakte Rückgabewert true oder True erlaubt die vorgeschlagene Aktion. Prüfe Methode, Ziel und Argumente. Aktionen genehmigen. |
| Navigation im Browser einschränken | Übergib urlPolicy in Node oder url_policy in Python an den Konstruktor von BrowserToolset oder AsyncBrowserToolset. |
Das ist erforderlich, wenn du navigate oder new_tab aktivierst. Das SDK prüft die angeforderte URL, bevor es um Bestätigung bittet. URLs einschränken. |
| Native Computeraktionen genehmigen | Setze bei ResponsesToolRunner in Node computerOptions in den Laufoptionen. In Python übergibst du approve_safety_checks und before_action an run. |
Ausstehende Sicherheitsprüfungen erfordern eine ausdrückliche Genehmigung. Der optionale Callback vor der Ausführung kann jede einzelne Aktion ablehnen. Genehmigung von Computeraktionen. |
| Lauf begrenzen | Setze maxSteps in Node oder max_steps in Python in den Laufoptionen des Responses-Runners. |
Standardmäßig sind 20 Anfragen zulässig. Die letzte zulässige Anfrage kann keine weiteren Aktionen mit Außenwirkung anstoßen. |
| Verbrauch messen | Übergib einen synchronen Callback onDiagnostic in Node oder on_diagnostic in Python an ResponsesToolRunner.run. |
Addiere die Token-Verbrauchswerte aus den Datensätzen abgeschlossener Anfragen. Fehlt bei einer abgeschlossenen Anfrage der Verbrauch, kennzeichne die Summe als unvollständig. Verbrauch und Laufzeiten prüfen. |
Aktionen genehmigen und die Sitzung verwalten
Erstelle Treiber und Genehmigungs-Callbacks in vertrauenswürdigem Anwendungscode. Trenne ausführbare Konfiguration von nicht vertrauenswürdigen Seitendaten. Gib Seitendaten über die dafür vorgesehenen Berichtsfelder des Treibers zurück.
Eine ausgewählte Browser-Methode, die den Zustand ändert oder Diagnosedaten liest, erfordert confirm. Nur der exakte Rückgabewert true in Node oder True in Python genehmigt die Aktion. navigate und new_tab erfordern zusätzlich urlPolicy (Node) oder url_policy (Python). Beide Callbacks erhalten ein unabhängiges Objekt mit member, den validierten arguments, dem zuvor erfassten state und call_id. Der Callback für die URL-Richtlinie erhält zusätzlich die angeforderte URL. Änderungen an diesem Objekt haben keinen Einfluss auf die validierte Aktion.
confirm genehmigt die Aktion mit ihren festgelegten Argumenten. Der Wert von state beschreibt eine frühere Beobachtung und sperrt weder das Dokument noch das fokussierte Bedienelement. Während eine Person entscheidet, kann die Seite navigieren oder den Fokus wechseln. Gilt die Zustimmung für eine bestimmte Seite oder ein bestimmtes Bedienelement, muss der Treiber das ursprüngliche Ziel bei der Ausführung prüfen. Deaktiviere in diesem Fall key und lehne type mit dem Zielwert null ab. Beide verwenden den aktuellen Fokus. Binde auch andere Aktionen, die vom aktuellen Browserzustand abhängen, auf entsprechende Weise an ihr Ziel.
Wenn du vor dem Lesen einer privaten Seite eine Bestätigung einholen möchtest, führe die Lesemethoden unter confirmReads (Node) oder confirm_reads (Python) auf. Derselbe confirm-Callback läuft, bevor der Treiber Zustand oder Inhalt liest. Sein Kontext enthält phase: "before_read" und state: null in Node bzw. None als Zustandswert in Python. Behandle diesen Fall, ohne Seitenmetadaten auszulesen. Bei einer Ablehnung werden weder Seiteninhalt noch Zustand zurückgegeben. Ohne diese Option verhalten sich bestehende Lesezugriffe wie bisher. Obligatorische Aktionsgenehmigungen gelten weiterhin.
Bestätige bei Computeraufrufen alle ausstehenden Sicherheitsprüfungen, bevor die Hilfsklasse Aktionen ausführt. approveSafetyChecks in Node und approve_safety_checks in Python müssen exakt den booleschen Wert true zurückgeben. Fehlt der Callback oder verweigert er die Genehmigung, endet der Lauf. Optional prüft beforeAction oder before_action jede Aktion unmittelbar vor der Ausführung, einschließlich des abschließenden Screenshots. Wenn du diesen Callback angibst, muss auch er ausdrücklich zustimmen. Weder eine Entscheidung des Modells noch eine Abschlussnachricht kann eine Genehmigung erteilen. Siehe die Sicherheitshinweise zur Computernutzung.
Node übergibt { signal } als letztes Argument an beide Genehmigungs-Callbacks für Computeraktionen. Python übergibt das optionale Schlüsselwortargument cancelled, wenn der Callback es akzeptiert. Bestehende Callbacks mit weniger Argumenten werden weiterhin unterstützt. Nutze diesen Kontext, um eine offene Genehmigungsabfrage zu schließen, wenn der Lauf endet. Die Hilfsklasse wartet, bis der Callback beendet ist, bevor sie die Sitzung freigibt.
Die Genehmigung einer Computeraktion gilt für deren festgelegte Argumente. Bildschirm und Fokus können sich ändern, während eine Person entscheidet. Soll die Zustimmung nur für ein bestimmtes Ziel gelten, muss der Treiber die Aktion an dieses Ziel binden oder sie nach einer Zustandsänderung ablehnen. Führe Computeraktionen in einer isolierten Umgebung mit eingeschränktem Netzwerkzugriff aus.
URLs einschränken
Aktiviere navigate oder new_tab nur, wenn die Aufgabe diese Methoden erfordert. Gib in Node sowohl confirm als auch urlPolicy an, in Python confirm und url_policy. Der URL-Callback erhält (context, url) sowie optional einen Ausführungskontext in Node oder das Schlüsselwortargument cancelled in Python. Er muss exakt true zurückgeben, damit das SDK anschließend confirm aufruft. Ein neuer leerer Tab mit der URL null erfordert ebenfalls eine Bestätigung, hat aber keine URL, die geprüft werden könnte.
Zerlege die angeforderte URL und vergleiche Protokoll, Hostnamen und Port mit den für deine Aufgabe zulässigen Zielen. Ein Vergleich des Zeichenkettenanfangs reicht nicht aus. https://example.com.evil.test darf nicht als https://example.com gelten. Ein Browser-Treiber ohne Navigationsfunktionen benötigt keinen URL-Callback. Im Browser-Beispiel bleiben diese Methoden deaktiviert.
Setze zusätzlich eine Netzwerkrichtlinie im Browser oder in der Umgebung durch. Der Callback prüft die angeforderte Navigation, kann aber weder Weiterleitungen noch Pop-ups, Seitenskripte oder eingebettete Ressourcen einschränken. Verwende über mehrere Anfragen hinweg dieselbe isolierte Sitzung und schließe Ressourcen, die deine Anwendung erstellt hat. Überlasse ausgeliehene Ressourcen der Stelle, die sie bereitgestellt hat.
Verbrauch und Laufzeiten prüfen
Wenn du ResponsesToolRunner verwendest, übergib onDiagnostic in Node oder on_diagnostic in Python an run. Für jede abgeschlossene Responses-Anfrage erhält der Callback einen Datensatz mit api: "responses", stage: "request", reason: "completed" und usage. Die Verbrauchsdaten enthalten input_tokens, output_tokens und total_tokens, sofern die API diese Angaben liefert. Andernfalls ist der Verbrauchswert in Node null und in Python None. Addiere die Werte jedes Token-Felds über alle abgeschlossenen Anfragen hinweg, um den Verbrauch des Laufs zu messen. Fehlen die Verbrauchsdaten bei einer Anfrage, sind die Summen unvollständig.
ComputerToolset.run meldet den Verbrauch einzelner Anfragen nicht über seinen Diagnose-Callback. Die zurückgegebene Antwort kann nur Verbrauchsdaten für die letzte Anfrage enthalten. Verwende ResponsesToolRunner mit ComputerToolset, wenn du den Verbrauch pro Anfrage benötigst.
Diagnosedatensätze geben außerdem API, Phase, Grund, Aufruf-ID, Methode und gemessene Dauer an. Sie enthalten weder unbearbeitete Fehlerdaten noch Seitentext, Argumente oder Bilder. Ein Fehler im Beobachter kann keine Aktion genehmigen oder deren Ergebnis ändern. Halte Aufruf-IDs und Methodennamen aus öffentlichen Protokollen heraus, wenn deine Anwendung darin private Daten ablegt.
Verwende einen synchronen Beobachter. Der Runner wartet nicht auf die Verarbeitung der Diagnosedaten. Plane eine asynchrone Speicherung in deiner Anwendung ein.
Bei vorzeitiger Ausführung können sich die gemessenen Phasen überschneiden, weil die Empfangszeit des Streams auch die Ausführungszeit einer Aktion enthalten kann. Addiere die Phasendauern deshalb nicht, um die Gesamtdauer des Laufs zu berechnen.
Aufrufe beenden und abbrechen
Die Hilfsklasse weist überlappende Aufrufe mit einer Fehlermeldung zurück, die auf den laufenden Aufruf hinweist. Auch der Runner weist einen zweiten gleichzeitigen Lauf auf derselben Instanz zurück. Lege für jede Browser- oder Desktop-Sitzung genau eine zuständige Instanz fest.
Rufe close() auf der Hilfsklasse auf, damit sie keine neuen Aufträge mehr annimmt. Ihr status lautet closed, wenn kein Aufruf mehr aktiv ist, oder draining, wenn ein früherer Aufruf noch Auswirkungen haben kann. Warte bei draining, bis der ursprüngliche Ausführungsaufruf beendet ist, bevor du den Treiber schließt oder die Sitzung einer anderen Instanz übergibst. Die Hilfsklasse schließt deinen Browser oder Desktop nicht. Rufst du close() innerhalb eines Treiber-Callbacks auf, wartet die Methode nicht auf diesen Callback.
Node-Treibermethoden und reguläre Funktionen, die einen kooperativen Abbruch unterstützen, können als zweites Argument einen Kontext mit signal annehmen. Python-Methoden können das Schlüsselwortargument cancelled annehmen. Prüfe das Abbruchsignal bei länger dauernden Vorgängen, auch bei der Navigation und beim Erstellen von Screenshots. Bestehende Callbacks mit einem Argument bleiben gültig. Das SDK kann ihren Abbruch jedoch nicht erzwingen oder ihre Auswirkungen rückgängig machen.
Schnittstelle des Browser-Treibers
Implementiere state() und nur die Operationen, die du bereitstellen möchtest. Node-Methoden können einen Wert oder ein Promise zurückgeben. Python stellt separate synchrone und asynchrone Klassen bereit. Jede Operation erhält ein validiertes Argumentobjekt oder Dictionary. Für Tab-IDs und Ziele, bei denen ein fehlender Wert zulässig ist, gib in Node ausdrücklich null und in Python None an.
Python weist erkennbare Konflikte zwischen synchronen und asynchronen Methoden bereits beim Erstellen der Hilfsklasse zurück. Verwende async def-Methoden mit AsyncBrowserToolset. Behalte bei Wrappern die Decorator-Metadaten oder die Typannotationen für Rückgabewerte bei. Wrapper, deren Verhalten sich nicht vorab erkennen lässt, werden beim Aufruf geprüft. Mit optionalen Protokollen wie BrowserReadDriver und AsyncBrowserReadDriver kannst du einen teilweise implementierten Treiber typisieren, ohne jede Operation implementieren zu müssen. Node exportiert BrowserArguments<Member> und BrowserResult<Member> für die jeweiligen Ein- und Ausgaben.
state() liefert tabs, ein Array von Objekten mit id, title, url und active. Verwende stabile IDs und kennzeichne den tatsächlich aktiven Tab. Halte Zugangsdaten und private Informationen aus Titeln und URLs heraus. Das SDK gibt nach regulären Operationen den aktuellen Zustand zurück, auch bei Fehlern. Ein abgelehnter geschützter Lesezugriff liefert eine festgelegte Ablehnung, ohne den Zustand zu lesen oder offenzulegen. Schlägt ein erforderlicher Zustandsabruf fehl, endet der Lauf. In Node erhalten Methoden zum Lesen des Zustands { signal }. In Python können sie das Schlüsselwortargument cancelled annehmen. Nutze diesen Kontext, um ausstehende Zustandsabrufe zu beenden, wenn der aufrufende Code den Lauf stoppt. Bestehende Lesemethoden ohne Argumente werden weiterhin unterstützt.
Der Tab-Zustand enthält für HTTP und HTTPS nur den Ursprung, etwa https://example.com:8443, ohne Zugangsdaten, Pfade, Abfrageparameter oder Fragmente. Das ältere Zustandsformat ohne Beobachtungsmetadaten behält about:blank bei und gibt für andere URLs nur das Schema an, etwa data: oder file:. Die Grenze von 2.048 UTF-8-Bytes gilt für den gemeldeten Wert. Ein langer Seitenpfad verhindert daher keinen Zustandsabruf. Bei Zuständen mit V1-Beobachtungsmetadaten werden Titel bei Bedarf an einer Zeichengrenze auf höchstens 1.024 UTF-8-Bytes gekürzt und mit title_truncated gekennzeichnet. Für Titel und Seiteninhalte musst du weiterhin die Datenschutzregeln deiner Anwendung anwenden.
Methoden auswählen
Standardmäßig stellt das SDK die folgenden 18 Methoden bereit, sofern sie implementiert sind, und leitet list_tabs aus state() ab. Implementiere list_tabs nicht selbst. Mit einer members-Liste kannst du weniger Methoden bereitstellen oder die Methoden für Seitenbereiche und Zeigeraktionen oder die Diagnose-, Skript- und Dateimethoden ausdrücklich aktivieren. Jeder Name darf nur einmal vorkommen und muss eine der festgelegten, vom Treiber implementierten Methoden bezeichnen. Nur list_tabs benötigt außer state() keine eigene Methode. Eine leere Liste stellt keine Methoden bereit. Das SDK kopiert die Auswahl beim Erstellen der Instanz, behält seine eigene Tool-Reihenfolge bei und weist deaktivierte Aufrufe zurück, bevor es den Zustand liest oder eine Zustimmung einholt.
Um eine optionale Methode hinzuzufügen und die implementierten Standardmethoden beizubehalten, verwende additionalMembers in Node oder additional_members in Python. Kombiniere diese Option nicht mit members. Jede zusätzlich angeforderte Methode muss im Treiber vorhanden sein. BROWSER_MEMBERS und DEFAULT_BROWSER_MEMBERS listen die festgelegten Namen auf, ohne einen Treiber zu untersuchen.
Wenn du list_tabs deaktivierst, bleibt der Zustand sichtbar, den andere erfolgreiche Operationen zurückgeben. In Python und Node beschränkt members die Methoden der Browser-Hilfsklasse. Namen regulärer Funktionen dürfen mit browser_ beginnen, aber nicht mit dem Namen eines aktivierten Browser-Tools übereinstimmen.
| Methode | Argumente | Ergebnis | Bestätigung |
|---|---|---|---|
navigate |
url, tab_id |
Text oder kein Ergebnis | Ja, mit URL-Prüfung |
read_page |
filter (“all” oder “interactive”), tab_id |
Text oder strukturierte Lesedaten | Nein |
get_page_text |
tab_id |
Text oder strukturierte Lesedaten ohne Elemente | Nein |
find |
query, tab_id |
Text oder strukturierte Lesedaten | Nein |
click |
target, tab_id |
Text oder kein Ergebnis | Ja |
type |
text, target (darf null sein), tab_id |
Text oder kein Ergebnis | Ja |
key |
keys (Zeichenketten), tab_id |
Text oder kein Ergebnis | Ja |
scroll |
direction, nicht negativer Wert für amount, tab_id |
Text oder kein Ergebnis | Ja |
scroll_to |
target, tab_id |
Text oder kein Ergebnis | Ja |
wait_for |
text, timeout_ms, tab_id |
Text oder kein Ergebnis | Nein |
select_option |
target, values (Zeichenketten), tab_id |
Text oder kein Ergebnis | Ja |
hover |
target, tab_id |
Text oder kein Ergebnis | Ja |
screenshot |
tab_id |
Natives Eingabebild | Nein |
zoom |
region, tab_id |
Natives Eingabebild | Nein |
new_tab |
url (darf null sein) |
Text oder kein Ergebnis | Ja, mit URL-Prüfung |
list_tabs |
Keine | Abgeleiteter aktueller Zustand | Nein |
switch_tab |
Pflichtargument tab_id |
Text oder kein Ergebnis | Ja |
close_tab |
Pflichtargument tab_id |
Text oder kein Ergebnis | Ja |
Außer bei switch_tab und close_tab darf die angegebene tab_id null sein. Zulässige Richtungen sind up, down, left und right. In Node beschreibt BrowserArguments<Member> das jeweilige Argumentobjekt. Python stellt benannte Eingabetypen wie TabInput, ReadPageInput und ClickInput bereit.
Gib für read_page, find und get_page_text in Node null oder keinen Wert und in Python None zurück, wenn du nur den aktualisierten Browserzustand liefern möchtest. Gib eine leere Zeichenkette zurück, wenn der Lesevorgang abgeschlossen ist und keinen Text ergeben hat.
Jede Node-Operation in dieser Tabelle außer list_tabs erhält { signal } als zweites Argument. list_tabs verwendet die oben beschriebene Methode zum Lesen des Zustands. Python übergibt cancelled als Schlüsselwortargument, wenn die Methode es akzeptiert. Nutze diesen Kontext, um laufende Vorgänge wie Navigation und Eingabe abzubrechen. Bestehende Methoden mit einem Argument werden weiterhin unterstützt.
Verwende für wait_for nicht leeren Text, der nach der Normalisierung von Leerraum höchstens 256 UTF-8-Bytes umfasst. Das Zeitlimit muss zwischen 1 und 30.000 Millisekunden liegen. Lies die aktuelle Seite nach scroll_to erneut, bevor du mit einem Bedienelement interagierst.
Strukturierte Lesedaten zurückgeben
read_page, find und get_page_text können BrowserReadV1 zurückgeben. Das Format enthält version: 1, den sichtbaren text, ein elements-Array und ein omitted-Array. Jedes Element hat eine eindeutige ref, ein nicht leeres label und eine von sieben Rollen: button, textbox, combobox, checkbox, radio, slider oder listbox.
Gib den Feldwert value oder die options eines Felds (Paare aus label und value) nur zurück, wenn deine Anwendung dem Modell Einblick in diese Daten erlaubt. Kontrollkästchen und Optionsfelder können den booleschen Wert checked melden. Optionen einer listbox können den booleschen Wert selected melden. Bei anderen Rollen lässt das SDK diese Felder weg. Node lässt optionale Felder mit dem Wert undefined weg und weist null für diese Felder zurück. get_page_text muss ein leeres elements-Array zurückgeben. Das SDK wandelt reguläre Zeichenketten nicht in strukturierte Lesedaten um.
Das SDK begrenzt weder die Anzahl der Elemente oder Optionen noch die Größe des Seitentexts oder des vollständigen Berichts. Referenzen und Beschriftungen dürfen höchstens 256 Bytes umfassen, Werte höchstens 512 Bytes. Verwende gültige Unicode-Skalarwerte. Treiber können mit eindeutigen omitted-Codes angeben, warum Teile fehlen: report_limit, text_limit, target_limit, work_limit, frame_limit, unsupported_root, unsupported_control, remote_action, private, value oder name_limit.
Der Treiber ist dafür verantwortlich, die Sichtbarkeit zu prüfen, private Felddaten zu schützen und Referenzen gültig zu halten. Prüfe eine Referenz nach der Genehmigung anhand der aktuellen Seite erneut, bevor du die Aktion ausführst. Die Beschriftung eines Bedienelements erteilt keine Berechtigung, seinen Wert zu lesen. Größenbeschränkungen allein machen Seiteninhalte nicht sicher.
Browserbilder zurückgeben
screenshot und zoom geben ein natives input_image zurück, für das mindestens eine nicht leere image_url oder file_id vorliegen muss. Beide Quellfelder dürfen vorhanden sein. Jede Quelle, deren Wert nicht null ist, muss eine nicht leere Zeichenkette sein. Unterstützt werden die Felder type, image_url, file_id, detail und prompt_cache_breakpoint. Ein Cache-Breakpoint muss { mode: "explicit" } sein. Auch null ist zulässig, wenn der native Inhaltstyp diesen Wert erlaubt. Das SDK validiert und kopiert die Felder, bevor es das Bild zurückgibt. Beide Node-Methoden geben ResponseInputImageContent zurück. Darin darf detail fehlen oder null sein. Wenn du einen Wert setzt, verwende auto, low, high oder original.
Für zoom hat region das Format [left, top, right, bottom]. Die Koordinaten müssen nicht negative, sicher darstellbare Ganzzahlen sein und eine positive Breite und Höhe ergeben. Der Treiber schneidet das Bild zu und prüft die Grenzen. Alle nachfolgenden Koordinaten beziehen sich weiterhin auf den gesamten sichtbaren Bereich.
Methoden für Seitenbereiche und Zeigeraktionen aktivieren
Diese sechs Browser-Methoden sind standardmäßig deaktiviert, auch wenn der Treiber sie implementiert. Wähle sie mit members aus oder füge sie mit additionalMembers in Node bzw. additional_members in Python hinzu. Namen, Argumente und Ergebnistypen der ursprünglichen 18 Standardmethoden bleiben gleich. Wenn du members verwendest, nimm alle weiterhin benötigten Standardmethoden wie screenshot oder read_page in die Liste auf.
| Methode | Pflichtfelder | Ergebnis | Bestätigung |
|---|---|---|---|
read_page_scoped |
tab_id, root, depth, filter |
BrowserScopedReadV1 |
Nein |
click_at |
tab_id, x, y, button, click_count, keys |
Text oder kein Ergebnis | Ja |
drag_path |
tab_id, path, keys |
Text oder kein Ergebnis | Ja |
hold_keys |
tab_id, keys, duration_ms |
Text oder kein Ergebnis | Ja |
hover_at |
tab_id, x, y |
Text oder kein Ergebnis | Ja |
set_checked |
tab_id, target, checked |
Text oder kein Ergebnis | Ja |
Node verwendet BrowserArguments<Member>. Python exportiert ReadPageScopedInput, ClickAtInput, DragPathInput, HoldKeysInput, HoverAtInput und SetCheckedInput. Alle Felder sind erforderlich. Für den aktiven Tab darf tab_id den Wert null oder None haben. Unbekannte Felder werden zurückgewiesen, auch zusätzliche Felder in einem Pfadpunkt. Zahlen müssen endliche, sicher darstellbare Ganzzahlen sein. Python weist True und False zurück, wenn Zahlen erforderlich sind.
click_at akzeptiert nicht negative Werte für x und y. Für button sind left, right und middle zulässig, für click_count die Werte 1, 2 und 3. drag_path akzeptiert 2 bis 100 Punkte im exakten Format {x, y} mit nicht negativen Koordinaten. Beide Methoden beziehen sich auch nach dem Zoomen auf den gesamten sichtbaren Seitenbereich in CSS-Pixeln. Der Treiber muss die aktuellen Grenzen prüfen. Die keys-Felder enthalten eine Liste der Modifikatortasten Control, Alt, Meta oder Shift, jeweils ohne Wiederholungen. Die Liste darf leer sein.
hover_at bewegt den Zeiger zu den aktuellen CSS-Koordinaten, ohne eine Maustaste gedrückt zu halten. set_checked setzt ein Kontrollkästchen auf den angeforderten booleschen Zustand. Wird es zweimal auf true gesetzt, muss es aktiviert bleiben. Auch eine Aktion ohne Zustandsänderung muss das ursprüngliche, weiterhin gültige Ziel verwenden und bestätigt werden. Ein veraltetes oder ersetztes Bedienelement darf der Treiber nicht akzeptieren.
hold_keys akzeptiert 1 bis 8 eindeutige, nicht leere Tastennamen mit gültigen Unicode-Skalarwerten und jeweils höchstens 64 UTF-8-Bytes. duration_ms muss zwischen 1 und 3.000 liegen. Bei Methoden, die den Zustand ändern, muss confirm exakt true zurückgeben. Methoden mit kooperativem Abbruch erhalten einen Abbruchkontext für den jeweiligen Aufruf. Node übergibt { signal } als zweites Argument. Python übergibt das Schlüsselwortargument cancelled, wenn die Methode es akzeptiert. Bestehende Methoden mit einem Argument bleiben gültig.
Einen Seitenbereich lesen
Bei read_page_scoped werden mit einem root-Wert von null die sichtbaren Seitenbereiche ermittelt. Für andere Werte ist eine vom Treiber ausgegebene Bereichsreferenz erforderlich. Ein Selektor ist unzulässig. Die Referenz darf nicht leer sein. Sie muss gültiges Unicode enthalten und darf höchstens 256 UTF-8-Bytes umfassen. Setze depth auf einen Wert zwischen 1 und 32 und filter auf all oder interactive. Die Tiefe zählt die durchlaufenen DOM-Ebenen innerhalb dieses Bereichs unabhängig von den Grenzen für Frames und Shadow DOM.
Gib BrowserScopedReadV1 zurück. Dieses Format erweitert die bestehenden Lesedaten um scopes: [{ref, label}]. Referenzen und Beschriftungen dürfen nicht leer sein, müssen gültiges Unicode enthalten und dürfen jeweils höchstens 256 UTF-8-Bytes umfassen. Bereichsreferenzen müssen eindeutig sein und dürfen mit keiner Elementreferenz übereinstimmen. Die Methode weist Zeichenketten und null als Ergebnisse zurück. Das SDK kopiert die bekannten Felder, bevor es den abschließenden Zustand abfragt.
Verwende Bereichsreferenzen ausschließlich, um den Ausgangspunkt für einen weiteren Lesezugriff auszuwählen. Operationen, die Elemente verändern, müssen sie zurückweisen. Erkläre Bereichs- und Elementreferenzen gemeinsam für ungültig, wenn sich der zugehörige Tab, das Dokument, die Generation oder die Sichtbarkeit ändert. Behalte die bestehenden Regeln zum Schutz von Felddaten sowie die Grenzen für Gesamtaufwand und Lesezugriffe bei.
Diagnose-, Skript- und Dateiübertragungsmethoden aktivieren
Auch diese vier Methoden sind standardmäßig deaktiviert. Wähle jede gewünschte Methode in members aus oder füge sie mit additionalMembers oder additional_members hinzu. Gib außerdem confirm an, auch für das Lesen von Diagnosedaten. Die Implementierung im Treiber allein macht die Methoden für das Modell noch nicht verfügbar.
| Methode | Pflichtargumente | Ergebnis |
|---|---|---|
read_diagnostics |
tab_id, source, limit |
Strukturierte Lesedaten nur mit Text |
run_script |
tab_id, source, timeout_ms |
Text |
upload_file |
grant_id |
BrowserFileOutcome |
download_file |
grant_id |
BrowserFileOutcome |
Wähle für read_diagnostics als Quelle console oder network und eine Obergrenze zwischen 1 und 100. Gib strukturierte Lesedaten mit einem leeren elements-Array zurück. Verwende in Node den Ergebnistyp BrowserTextReadV1. Der Treiber muss private Daten herausfiltern und den Umfang des Verlaufs begrenzen. Gib keine unbearbeiteten Header, Cookies, Zugangsdaten oder ungefilterten Konsolenmeldungen zurück.
run_script erwartet nicht leeren Quelltext mit gültigem Unicode und ein Zeitlimit zwischen 1 und 30.000 Millisekunden. Das SDK behält den vollständigen Quelltext bei. Gib Text mit gültigem Unicode zurück. Eine leere Zeichenkette ist zulässig, der Rückgabewert null ist unzulässig. Das SDK behält auch große Ergebnisse vollständig bei. Skripte laufen mit den Berechtigungen der Seite. Verwende eine neue Sitzung ohne Zugangsdaten, beschränke ihren Netzwerkzugriff und verwende sie nicht weiter, wenn der Ausführungszustand unklar ist. Wenn du lokal nicht mehr auf das Ergebnis wartest, kann das Seitenskript dennoch weiterlaufen.
Dateimethoden akzeptieren ausschließlich eine vom aufrufenden Code ausgegebene grant_id. Sie darf nicht leer sein. Sie muss gültiges Unicode enthalten und darf höchstens 256 UTF-8-Bytes umfassen. Die Freigabe bezeichnet genau eine für die Aufgabe genehmigte Datei. Sie ist weder ein Pfad noch eine URL. Die für die Datei zuständige Instanz muss eine separate Genehmigung für die Datei einholen. Sie muss erneut prüfen, ob die Freigabe noch gültig ist und wem die Datei gehört, Größenbeschränkungen durchsetzen und die Freigabe nur einmal zulassen. Die Browser-Bestätigung ersetzt diese Dateigenehmigung nicht.
Gib genau version, status, effect und cleanup zurück. Setze version auf 1. Für cleanup sind not_started, pending und completed zulässig. Für Status und Auswirkung gelten folgende Kombinationen:
status |
effect |
|---|---|
completed |
completed |
refused |
none |
unknown |
unknown |
interrupted |
none oder unknown |
Das SDK kopiert und validiert das Ergebnis, bevor es den abschließenden Browserzustand abfragt. Nur bei completed wird ok in der Tool-Ausgabe auf true gesetzt. Bei anderen Ergebnissen bleibt das strukturierte Ergebnis mit ok gleich false erhalten. Der Runner überspringt dann die davon abhängigen Browseraufrufe in dieser Antwort. Prüfe die tatsächliche Datei und den Anwendungszustand, bevor du eine Übertragung mit unbekanntem Ausgang wiederholst. Ein Dateiergebnis belegt nicht, dass ein Formular später erfolgreich übermittelt oder ein nachgelagerter Geschäftsvorgang erfolgreich ausgeführt wurde.
run_script, upload_file und download_file erhalten ein Abbruchsignal für den jeweiligen Aufruf. Node übergibt { signal } als zweites Argument, Python das Schlüsselwortargument cancelled. Python exportiert ReadDiagnosticsInput, RunScriptInput und BrowserFileInput.
Schnittstelle des Computer-Treibers
Ein Computer-Treiber empfängt native Computeraktionen und gibt Screenshots zurück. Er muss die folgenden Methoden implementieren. Importiere in Node ComputerDriver aus openai. Importiere in Python ComputerDriver oder AsyncComputerDriver aus openai. Importiere auch das passende ComputerToolset oder in Python AsyncComputerToolset aus openai.
| Methode | Aktion, die der Treiber empfängt |
|---|---|
click |
Koordinaten, Maustaste und ggf. gedrückt gehaltene Tasten |
double_click |
Koordinaten und ggf. gedrückt gehaltene Tasten |
drag |
Pfad und ggf. gedrückt gehaltene Tasten |
keypress |
Tastenkombination |
move |
Zeigerkoordinaten |
scroll |
Koordinaten, scroll_x und scroll_y |
type |
Text für das fokussierte Bedienelement |
wait |
Aufforderung zu warten, bis sich die Umgebung stabilisiert hat |
screenshot |
Kein Argument. Gib den aktuellen Bildschirminhalt zurück. |
Aktionsmethoden erhalten das bereits generierte Computeraktionsobjekt mit seinen Feldern in snake_case und geben keinen Wert zurück. Können sie die Aktion nicht ausführen, müssen sie einen Fehler auslösen. Ignoriere nicht unterstützte Eingaben nicht stillschweigend. Node unterstützt synchrone Ergebnisse und Promises. Warte in Python mit await auf asynchrone Methoden.
Verwende in Python synchrone Methoden mit ComputerToolset und async def-Methoden mit AsyncComputerToolset. Die Hilfsklasse weist erkennbare Konflikte schon beim Erstellen zurück. Behalte beim Einbinden von Methoden in Wrapper die Decorator-Metadaten oder die Typannotationen für Rückgabewerte bei. Wrapper, deren Verhalten sich nicht vorab erkennen lässt, werden beim Aufruf geprüft. Ihr eigener Code kann daher laufen, bevor die Hilfsklasse einen Konflikt erkennt.
Verwende in Node ComputerCallInput für Aufrufe, die du an ComputerToolset.execute() übergibst. Der Typ akzeptiert native Aufrufe sowie moderne Aufrufe mit einem actions-Array, bei denen pending_safety_checks fehlt. Wenn das Feld zulässigerweise fehlt, erhalten die Genehmigungs-Callbacks eine unabhängige Kopie des Aufrufs mit leerer Prüfliste. Bei der erneuten Übergabe behält der Aufruf seine ursprünglichen Felder.
screenshot() gibt ein computer_screenshot mit einer image_url (auch eine Daten-URL ist zulässig) oder einer file_id zurück. Computer-Hilfsklassen benötigen mindestens eine Bildquelle und akzeptieren beide Quellfelder zusammen. Die Hilfsklasse liest keine lokalen Dateien. Die Aktionen werden einmal in der vorgegebenen Reihenfolge ausgeführt. Anschließend nimmt die Hilfsklasse den abschließenden Screenshot auf. Sie wiederholt keine Treiberaktionen.
Verwende für eine Responses-Schleife ausschließlich mit Computeraktionen ComputerToolset.run oder in Python AsyncComputerToolset.run. Wähle ein für dein Projekt verfügbares Modell, das das Computer-Tool unterstützt. Übergib die Computer-Hilfsinstanz bei gemischten Läufen als Option computer an den Responses-Runner. Node erwartet Computer-Callbacks in der Laufoption computerOptions. Python akzeptiert approve_safety_checks und before_action direkt als Schlüsselwortargumente des Laufs. Das Browser-Beispiel steuert ausschließlich einen Browser. Es implementiert oder überprüft keinen nativen Desktop.
Sowohl die Computer-Hilfsklasse als auch ResponsesToolRunner unterstützen die Kontextverdichtung von Responses über context_management. Sie prüfen die erforderlichen Felder der Einträge und übergeben den verschlüsselten Inhalt erneut unverändert. Wähle für ResponsesToolRunner entweder diese native Option oder die lokale Option contextBudget bzw. context_budget. Kombiniere sie nicht.
Eine Aufgabe anhand von Screenshots ausführen
Deine erste Aufgabe ausführen enthält ein vollständiges Beispiel für Python oder Node. Es verwendet das Computer-Tool der Responses API, um in einem lokalen Browser Abholdetails einzublenden.
Einen isolierten Desktop verwenden
Wie du den Desktop eines Betriebssystems steuerst, zeigt das vollständige Desktop-Beispiel für Python oder Node. Beide verwenden ein isoliertes Linux-Gastsystem. Auf Macs mit Apple-Chip läuft das Gastsystem in einer virtuellen Maschine, unter x86-64-Linux in Docker. Jedes Beispiel enthält eine lokale Übung ohne API-Schlüssel. Die Live-Aufgabe prüft sowohl den Datensatz im Browser als auch die gespeicherte Datei. Beginne für deine eigene Umgebung mit der Docker-Anleitung und passe die oben beschriebene Treiberschnittstelle an.
Browseraktionen mit anderen Tools kombinieren
Der Responses-Runner kann Browser- und Computer-Hilfsklassen mit regulären Funktionen, Websuche, Dateisuche, Code Interpreter, Bildgenerierung und entfernten MCP-Tools kombinieren. Wenn die nächste Anfrage die Antwort erneut übergibt, behalten Ergebnisse serverseitiger Tools ihren nativen Inhalt und ihre Container-IDs. Fehlgeschlagene, unvollständige oder noch nicht abgeschlossene Serverergebnisse beenden den aktuellen Durchgang, bevor lokale Aktionen ausgeführt werden.
Wenn ein Lauf serverseitige Tools deklariert, warten lokale Aufrufe auf die vollständige Antwort, auch wenn eager aktiviert ist. Der Runner muss zunächst spätere Serverergebnisse und Genehmigungsanfragen prüfen, bevor er Aktionen sicher ausführen kann.
Am Ende dieses Durchgangs kann supplyOutputs in Node oder supply_outputs in Python das Ergebnis einer regulären Funktion ersetzen, deren Ausführung noch nicht versucht wurde, sofern ihre Registrierung das Überschreiben erlaubt. Das funktioniert auch ohne ausdrückliche Richtlinie für die vorzeitige Ausführung. Ein Ersatzergebnis kann weder einen Browser- oder Computeraufruf noch eine MCP-Genehmigungsanfrage beantworten.
Dieser Runner benötigt gespeicherte Antworten, um nach einer Bildgenerierung fortzufahren. Er weist store: false in Node oder store=False in Python zurück, wenn du image_generation deklarierst. Aktiviere die Speicherung, sofern angemessen, oder verwende client.responses.create für eine einzelne zustandslose Anfrage. Der Runner aktiviert die Speicherung niemals von sich aus.
Verwende typisierte Funktionstools wieder, damit du ihre Validierung nicht duplizieren musst. Binde in Node eine zodResponsesFunction oder standardResponsesFunction mit runnerFunction aus openai/helpers/responses-tool-runner ein. Das Tool muss seinen Callback enthalten. Verwende in Python RegisteredFunction.from_tool oder AsyncRegisteredFunction.from_tool mit einem vorhandenen pydantic_responses_function_tool und einer ausdrücklich angegebenen, typisierten Ausführungsfunktion. Bei ungültigen Argumenten endet die Verarbeitung, bevor diese Funktion läuft. Eine ungültige Callback-Ausgabe beendet den Lauf, ohne die Aktion zu wiederholen. Direkte Registrierungen mit RunnerFunction und RegisteredFunction behalten ihr bisheriges Verhalten bei der Argumentverarbeitung bei.
Gib für MCP approveMcp in Node oder approve_mcp in Python an. Der Callback erhält eine unabhängige Kopie der tatsächlichen Genehmigungsanfrage und gibt true oder false zurück. Der Runner bindet die Antwort an die ID und den deklarierten Server dieser Anfrage. Er kann weder selbst eine Genehmigung erteilen noch eine Abschlussnachricht als Zustimmung werten.
Bei Anfragen mit deklarierten MCP-Tools sind automatische Wiederholungsversuche des SDK deaktiviert, unabhängig davon, ob ein Ledger verwendet wird. Prüfe bei einem Fehler, was der MCP-Server ausgeführt hat, bevor du einen neuen Lauf startest.
Fehler behandeln
Löse BrowserError nur bei behebbaren Problemen wie einer veralteten Referenz aus und verwende dafür ausschließlich Text, den das Modell sehen darf. Andere Fehler, die eine Browseroperation auslöst, führen zu einer allgemeinen Fehlermeldung. Bei solchen Fehlern liefert der Runner für jeden Browseraufruf eine Ausgabe, überspringt die verbleibenden Browseroperationen dieser Antwort und lässt das Modell im nächsten Durchgang erneut entscheiden. Ungültige Rückgabewerte oder ein ungültiger Zustand beenden den Lauf. Der Lauf endet auch, wenn der Zustand nicht gemeldet werden kann, eine reguläre Funktion fehlschlägt oder eine native Sicherheitsprüfung für eine Computeraktion nicht genehmigt wird.
Begrenze die Anzahl der API-Anfragen mit maxSteps oder max_steps. Der Standardwert ist 20. Die letzte zulässige Anfrage kann keine weiteren Aktionen mit Außenwirkung anstoßen. Bei einem erneuten HTTP-Versuch des SDK wird keine Treiberaktion wiederholt. Verwende signal in Node oder cancelled in Python, um zwischen Operationen abzubrechen. Bereits laufende Treiberaufrufe lassen sich nicht in jedem Fall rückgängig machen.
ResponsesToolRunner behält tool_choice bei jeder Anfrage bei. Eine Auswahl, die immer ein lokales Tool erzwingt, lässt keinen Abschluss zu. Der Runner weist sie daher zurück, bevor er mit der Arbeit beginnt. Verwende auto für eine Schleife oder responses.create für eine einzelne Anfrage mit erzwungener Auswahl. Eine verpflichtende Auswahl bleibt gültig, wenn sie auch ein deklariertes serverseitiges Tool zulässt.
Probleme bei einem Lauf beheben
| Symptom | Prüfung und Abhilfe |
|---|---|
ComputerToolset oder eine Browser-Hilfsklasse lässt sich nicht importieren |
Prüfe das installierte Paket in der Umgebung, in der das Skript läuft. Verwende für Python openai==3.31.0 oder für Node openai@7.33.0 oder eine neuere Version, die die Hilfsklassen enthält. |
| Chromium startet nicht | Führe den Playwright-Installationsbefehl in derselben Umgebung wie das Skript aus. Installiere in einem Linux-Container die erforderlichen Systembibliotheken und führe das Skript ohne Root-Rechte aus. Deaktiviere die Sandbox nicht, um den Fehler zu umgehen. |
| Die API weist das Modell oder Tool zurück | Prüfe den Modellzugriff deines Projekts und den Abschnitt Tools des Modells im Modellkatalog. Das native Tool computer und die Browser-Funktionstools stellen unterschiedliche Anforderungen an das Modell. |
| Eine Aktion oder ausstehende Sicherheitsprüfung wird abgelehnt | Prüfe die Genehmigungsrichtlinie deiner Anwendung. Gleiche die festgelegten Aktionsargumente mit dem aktuellen Zustand ab. Hole bei Bedarf eine Genehmigung ein. Genehmige nicht pauschal jede Anfrage, nur damit der Lauf erfolgreich endet. |
| Das Modell erreicht die Schrittgrenze | Prüfe zuerst die tatsächliche Seite oder Datei. Stelle fest, ob die Aufgabe Funktionen erfordert, die dein Treiber verweigert. Vereinfache die Aufgabe, bevor du maxSteps oder max_steps erhöhst. |
| Das Browser-Modell antwortet, ohne die Seite zu lesen | Aktiviere eine vom Treiber implementierte Lesemethode, etwa read_page im Beispiel. Fordere das Modell auf, die aktuelle Seite zu lesen, und führe die Aufgabe erneut aus. Prüfe das Ergebnis auf der Seite oder in der Datei, bevor du die Antwort akzeptierst. |
| Klicks verfehlen das sichtbare Ziel | Screenshot und Koordinaten prüfen. |
Klicks korrigieren, die ihr Ziel verfehlen
Erstelle einen neuen Screenshot und prüfe, ob er das gewünschte Fenster zeigt. Verwende für Screenshot und Aktion dasselbe Koordinatensystem. Sendest du einen Screenshot mit 800 × 600 Pixeln von einem Bildschirm mit 1.600 × 1.200 Pixeln, verdopple vor dem Klick beide zurückgegebenen Koordinaten. Sendet ein Computer-Treiber einen zugeschnittenen Screenshot, addiere nach der Skalierung den Versatz des Ausschnitts. Die Zeigermethoden des Browser-Treibers verwenden auch nach dem Zoomen CSS-Pixel im gesamten sichtbaren Seitenbereich. Verwechsle sie nicht mit Bildschirmpixeln.
Die Screenshot-Größe beeinflusst die Anzahl der Eingabetoken und die Kosten. Informationen zu Bildgrößen und Modellgrenzen findest du im Abschnitt Screenshots erstellen.
Streaming und Wiederaufnahme
Responses-Läufe verwenden standardmäßig kein Streaming. Mit stream und onEvent (Node) oder on_event (Python) liefert der Runner unabhängige Kopien der Stream-Ereignisse und wartet vor der Ausführung auf die vollständige Antwort. Mit eager kann er abgeschlossene Ausgabeeinträge vorzeitig in ihrer Reihenfolge ausführen. Inkrementelle Änderungen an Argumenten führt er niemals aus.
Aktiviere die vorzeitige Ausführung nur, wenn sich ein abgeschlossener Eintrag sicher ausführen lässt, bevor der Runner die gesamte Antwort validiert hat. Wenn ein späteres Ereignis den Eintrag ändert oder entfernt, stoppt der Runner und behält den Ausführungsnachweis bei. Die Aktion kann er nicht rückgängig machen. Wenn alle Aktionen auf die erfolgreiche Validierung der vollständigen Antwort warten müssen, lass die vorzeitige Ausführung deaktiviert oder verwende dafür eine leere Richtlinie.
Treffen abgeschlossene Einträge in der falschen Reihenfolge ein oder weisen ihre Indizes Lücken auf, wartet der Runner auf die vollständige Antwort, bevor er diesen Teil der Sequenz ausführt. Bereits abgeschlossene Aktionen bleiben protokolliert, wenn der Stream fehlschlägt.
Mit earlyExecution oder early_execution kannst du die vorzeitige Ausführung auf ausgewählte Funktionsnamen im Übertragungsprotokoll beschränken und den Dispatcher für native Computeraktionen über einen separaten booleschen Wert steuern. Ein leeres Objekt stellt alle lokalen Tools zurück. Ohne diese Option gilt das übliche Verhalten für die vorzeitige Ausführung aller Tools. Ab dem ersten zurückgestellten Tool werden auch alle nachfolgenden Tools zurückgestellt, damit die Reihenfolge erhalten bleibt. Prüfe bei iterate() den abgeschlossenen Durchgang, bevor du fortfährst. Beendest du den Lauf an dieser Stelle, wird keines der zurückgestellten Tools ausgeführt. Diese Optionen ändern den Ausführungszeitpunkt. Die Genehmigungsanforderungen gelten weiterhin.
Für einen einzelnen abgeschlossenen Aufruf kann beforeEarlyCall oder before_early_call vor der Weiterleitung defer zurückgeben. Der Callback kann keine vorzeitige Ausführung für Aufrufe erlauben, die außerhalb der dafür zugelassenen Liste liegen. Kennzeichne eine reguläre Funktion nur dann mit independent: true, wenn sie unabhängig von anderen Aktionen laufen kann. Ohne Ledger können unabhängige Funktionen laufen, während der Stream weitere Daten liefert. Dauerhaft protokollierte Läufe, Browseraktionen und Computeraktionen behalten ihre Reihenfolge bei. Für bereits gestartete Vorgänge bleibt der Ausführungsnachweis erhalten, auch wenn ein anderer Aufruf fehlschlägt.
Standardmäßig laufen höchstens zwei unabhängige vorzeitig ausgeführte Aufrufe gleichzeitig. Setze maxConcurrentCalls in Node oder max_concurrent_calls in Python auf eine positive Ganzzahl, um diese Grenze zu ändern. Der Runner wartet auf den Abschluss der aktuellen Gruppe, bevor er weitere Aufrufe aus dem Stream liest. Diese Option gilt nur für unabhängige vorzeitige Ausführungen ohne Ledger. Jede Funktion muss Vorgänge, die sie selbst startet, eigenständig begrenzen.
Prüfe nach einem unterbrochenen Lauf mit vorzeitiger Ausführung in Node ResponsesToolRunnerError.attemptedCallIds und completedCallIds, in Python attempted_call_ids und completed_call_ids. Sie enthalten ausschließlich Aufruf-IDs, keine Ergebnisse, Argumente oder Treibermeldungen. Aktionen können bereits Auswirkungen gehabt haben. Lies den maßgeblichen Anwendungszustand, bevor du eine bereits versuchte Aktion oder eine Aktion mit ungewissem Ausgang wiederholst.
Mit contextBudget oder context_budget begrenzt du die Anzahl der Eingabebytes und Bilder für die nächste Anfrage, unabhängig davon, ob du dauerhaften Speicher verwendest. Die daraus abgeleitete Eingabe enthält weiterhin die aktuellen Beobachtungen und erforderlichen Beziehungen zwischen Tools. Eine Begrenzung im Arbeitsspeicher ermöglicht keine Wiederherstellung des Laufs nach Prozessende.
Am Ende eines abgeschlossenen Durchgangs kannst du mit appendUserText oder append_user_text Hinweise einer Person für den weiteren Lauf vormerken. Der Runner fügt sie an, nachdem er die ausstehenden Ausgaben protokolliert hat. Die Methode akzeptiert Text, aber keine beliebigen Tool-Ausgaben oder Genehmigungsobjekte. Das Anfragebudget wird nicht zurückgesetzt.
Nutze diese Methode, um die aktuelle Aufgabe zu präzisieren, etwa um den Agenten zu bitten, ein anderes Datum zu prüfen. Ersetzt die Person die Aufgabe durch eine neue, stoppe den aktuellen Lauf und warte auf sein Ende, bevor du einen neuen startest. Lies den Anwendungszustand erneut und hole für neue Aktionen eine neue Genehmigung ein. Bewahre das Protokoll des alten Laufs auf. Geänderte Anweisungen machen seine Auswirkungen nicht rückgängig.
Damit du einen Lauf dauerhaft sichern und wiederherstellen kannst, gib ein ledger an, das jeden Prüfpunkt speichert, während ausschließlich eine Instanz den Lauf verwaltet. Nimm den Lauf nur am Ende eines abgeschlossenen Durchgangs wieder auf. Bei einer ausstehenden Aktion oder ungewissem Ausgang musst du zuerst das Protokoll mit dem tatsächlichen Zustand abgleichen. Das verbleibende Anfragebudget und der bisher abgeschlossene Verlauf bleiben bei der Wiederaufnahme erhalten. Bei der lokalen Kontextverdichtung für das Kontextbudget bleiben alle Nachweise im Ledger erhalten. Aktuelle Beobachtungen, Sicherheitsprüfungen, Nachrichten und Reasoning bleiben im Kontext. Die Verdichtung erteilt niemals eine Genehmigung.
Bei jedem Speichervorgang wird eine unabhängige, vollständige Kopie des Prüfpunkts übergeben, auch vor und nach lokalen Aktionen mit Außenwirkung. Der Prüfpunkt enthält den gesamten aktuellen Stapel und den bisher angesammelten Verlauf. Bei großen Stapeln kann der Gesamtaufwand für das Kopieren und Speichern dieser Datensätze quadratisch wachsen. Wähle einen Speicher, der für dieses Volumen geeignet ist. contextBudget und context_budget begrenzen die Anfrageeingabe, nicht den Speicherbedarf des Ledgers.
Bei einer Unterbrechung enthält ein als ausstehend markierter Prüfpunkt den zuletzt gespeicherten Anfang der Sequenz. Späterer Text und Vorschläge, deren Ausführung noch nicht versucht wurde, können fehlen. Der Prüfpunkt berechtigt niemals zur erneuten Ausführung. Vor und nach einer Aktion mit Außenwirkung enthält der gespeicherte Prüfpunkt die gesamte bis dahin beobachtete Sequenz und die Ausführungsnachweise.
Ein Lauf mit MCP-Tools speichert vor jeder Anfrage einen als ausstehend markierten Prüfpunkt. Prüfe bei einem Verbindungsfehler, was der MCP-Server ausgeführt hat, bevor du einen neuen Lauf startest. An einem ausstehenden Prüfpunkt kann der Lauf nicht automatisch wieder aufgenommen werden.
Beim Speichern von MCP-Deklarationen werden Autorisierungsdaten und benutzerdefinierte Header weggelassen und Server-URLs durch SHA-256-Fingerabdrücke ersetzt. Native Anfragen verwenden weiterhin die ursprüngliche URL. Hinterlege Zugangsdaten, die regelmäßig gewechselt werden müssen, in den Autorisierungsdaten oder Headern. Eine Änderung am URL-Pfad oder an einem nicht erkannten Abfragewert ändert die Identität der URL und erfordert einen neuen Lauf. Prüfpunkte mit MCP-URLs im Klartext lassen sich nicht zur Wiederaufnahme verwenden. Node benötigt crypto.subtle.digest, um eine MCP-URL zu speichern. Andere Ein- und Ausgaben des Prüfpunkts bleiben private Anwendungsdaten.
Gib bei der Wiederaufnahme aktuelle Zugangsdaten an und prüfe, ob sie für den vorgesehenen Server und das richtige Konto gelten.
Gespeicherte Deklarationen für Code Interpreter behalten die Namen der Zugangsdaten und die Domains bei, entfernen aber die geheimen Werte. Gib bei der Wiederaufnahme die aktuellen Werte in der Tool-Konfiguration an. Bei MCP-Genehmigungen gilt ein leerer Filter always: {} oder never: {} für jedes Tool.
Gib approveMcp in Node oder approve_mcp in Python an, wenn die anfängliche Eingabe oder ein gespeichertes Ledger genehmigte MCP-Anfragen enthält. Vor dem ersten Speichervorgang oder der ersten API-Anfrage holt der Runner jede Genehmigung erneut ein, für die kein passender abgeschlossener MCP-Aufruf vorliegt. Das gilt mit und ohne Ledger oder Kontextbudget. Abgeschlossene Aufrufe und frühere Ablehnungen bleiben unverändert. Ist eine neue Genehmigung erforderlich und fehlt der Callback, endet der Lauf.
Einen eigenen Treiber lokal prüfen
Führe die lokale Übung aus der Buchungsdemo oder dem Beispiel für einen isolierten Desktop aus, bevor du sie anpasst. Ergänze Prüfungen für den tatsächlichen Seitenzustand deines Treibers, die Auswirkungen von Eingaben und die Freigabe von Ressourcen. Die SDK-Validierung belegt nicht, dass die Umgebung eine Aktion korrekt ausgeführt hat.
Einen funktionsfähigen SDK-Workflow findest du im Abschnitt Deine erste Aufgabe ausführen. Die Integrationsanleitungen zeigen, wie du die Umgebung einrichtest. Prüfe nach jeder Änderung das gespeicherte Formular, die Datei oder den jeweiligen Anwendungsdatensatz, bevor du Erfolg meldest.