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 einen Agenten Aufgaben in einem von OpenAI gehosteten Browser erledigen.

Mit der Computernutzung kann ein Agent auf Websites navigieren und Benutzeroberflächen im Browser bedienen. So kann er eine Website testen, Informationen zusammentragen oder eine Anwendung über ihre Oberfläche nutzen.

Die Agents API führt den Browser in einer von OpenAI gehosteten Umgebung aus. Deine Anwendung startet die Sitzung und verfolgt die Sitzungsereignisse. Der Agent entscheidet anhand seiner Beobachtungen im Browser, was er als Nächstes tut.

So führst du eine Aufgabe im Browser aus:

  1. Erstelle eine Browsersitzung und speichere die Sitzungs-ID.
  2. Verfolge die Sitzungsereignisse und sende dem Agenten eine Aufgabe.
  3. Bearbeite jede Anfrage zum Zugriff auf eine Website. Wenn für die Aufgabe ein Konto nötig ist, kümmere dich um die Anmeldung.
  4. Warte, bis der Hauptagent seinen Durchlauf abgeschlossen hat, und prüfe das Ergebnis. Bricht die Verbindung ab, stelle die Verbindung zu derselben Sitzung wieder her, bevor du es erneut versuchst.
  5. Prüfe die gespeicherten Browseraktivitäten und lösche die Sitzung, wenn du fertig bist.

Browser konfigurieren

Folge den vorbereitenden Schritten im Schnellstart zur Agents API, um einen API-Schlüssel zu erstellen und OPENAI_API_KEY zu exportieren. Installiere anschließend das OpenAI SDK für deine Programmiersprache. Installiere für die TypeScript-Beispiele openai und prompt-sync. Für die cURL-Beispiele brauchst du Bash und jq.

So aktivierst du den Browserzugriff:

  • Füge { "type": "computer_use" } zu agent.tools hinzu.
  • Setze environment.type auf openai_hosted und environment.desktop.enabled auf true.

Die folgenden TypeScript-Beispiele bauen aufeinander auf. Du erstellst eine Sitzung, bearbeitest Genehmigungsanfragen für Websites, sendest eine Aufgabe und gibst die Antwort aus. Erstelle zuerst eine Browsersitzung mit aktivierten Screenshots. Damit startest du noch keine Aufgabe.

Browsersitzung erstellen
import OpenAI from "openai";
import { open } from "node:fs/promises";

const client = new OpenAI();
const session = await client.beta.agents.sessions.create({
  agent: {
    model: "gpt-6-astra",
    instructions:
      "Read public documentation in the browser. Do not sign in or change any website data. Report the page title and URL you find.",
    tools: [{ type: "computer_use", include_screenshots: true }],
  },
  environment: {
    type: "openai_hosted",
    desktop: { enabled: true },
    network: { access: "enabled" },
  },
});
console.log("Session ID:", session.id);

Zugriff auf eine Origin bearbeiten

Bevor der Browser auf eine neue Website-Origin zugreift, muss die Person, die deine Anwendung nutzt, den Zugriff genehmigen. Das gilt auch für öffentliche Websites. Wenn du den Netzwerkzugriff aktivierst, sind diese Anfragen weiterhin einzeln zu genehmigen.

Auch wenn du die automatische Überprüfung aktivierst, fordert der Browser weiterhin Genehmigungen für den Zugriff auf neue Origins an und stellt Anmeldeanfragen. Bearbeite beide Arten von Anfragen weiterhin in deiner Anwendung.

So bearbeitest du eine Genehmigungsanfrage für eine Origin:

  1. Rufe bei agent.session.requires_action die Sitzung ab und prüfe die aktuellen Einträge in required_actions.
  2. Suche nach ausstehenden Einträgen vom Typ computer_use_approval_request, deren verschachteltes Feld request.type den Wert browser_origin_access hat.
  3. Zeige die angefragte origin und, falls angegeben, die Begründung aus reason an. Lass die Person zwischen approve, deny und cancel wählen. Sende die Entscheidung wie unten gezeigt über den Endpunkt für Sitzungsereignisse. Verwende dieselbe request_id und ein verschachteltes response-Objekt mit type: "browser_origin_access" und decision.
Eine Genehmigung für eine Origin erzwingt keine Bestätigung vor einzelnen Aktionen

Wenn deine Anwendung vor Käufen, destruktiven Änderungen oder anderen folgenreichen Aktionen zwingend eine Bestätigung einholen muss, beschränke den gehosteten Browser auf Ressourcen, mit denen diese Aktionen nicht möglich sind. Alternativ kannst du eine Browser-Laufzeitumgebung verwenden, die du selbst kontrollierst. Holst du die Bestätigung über ein Funktionstool ein, bist du darauf angewiesen, dass der Agent die Funktion aufruft.

Behandle Website-Inhalte als nicht vertrauenswürdig. Sie können weder Berechtigungen erteilen noch die Anweisungen der Person außer Kraft setzen, die den Agenten beauftragt hat. Beachte die Hinweise zu Bestätigung und Einwilligung in einer selbst kontrollierten Laufzeitumgebung.

Definiere diese Hilfsfunktion vor dem Code für die Aufgabe. Sie bearbeitet Genehmigungsanfragen für Origins und bricht Anmeldeanfragen ab, da diese Aufgabe nur öffentliche Seiten liest.

Auf Zugriffsanfragen für Origins antworten
import { createInterface } from "node:readline";

const inputLines = createInterface({
  input: process.stdin,
  crlfDelay: Infinity,
});
const answers = inputLines[Symbol.asyncIterator]();

/** @param {OpenAI} client */
async function respondToOriginApproval(
  client: OpenAI,
  sessionId: string,
  approval: OpenAI.Beta.Agents.AgentSession.SessionRequiredActionResourceComputerUseApprovalRequest
) {
  const request = approval.request;
  if (request.type === "browser_origin_access") {
    console.log("Requested origin:", request.origin);
    console.log(request.reason ?? "The browser needs access to this origin.");
    let input;
    do {
      process.stdout.write(
        "Allow access? [approve/deny/cancel, default deny] "
      );
      const answer = await answers.next();
      input = (answer.done ? "" : answer.value).trim().toLowerCase() || "deny";
    } while (!["approve", "deny", "cancel"].includes(input));
    const decision =
      input === "approve" ? "approve" : input === "cancel" ? "cancel" : "deny";
    await client.beta.agents.sessions.events.create(sessionId, {
      events: [
        {
          type: "agent.session.input.computer_use_approval_request_result",
          request_id: approval.request_id,
          response: { type: "browser_origin_access", decision },
        },
      ],
    });
  } else if (request.type === "browser_authentication") {
    // This public-page task must not sign in.
    await client.beta.agents.sessions.events.create(sessionId, {
      events: [
        {
          type: "agent.session.input.computer_use_approval_request_result",
          request_id: approval.request_id,
          response: { type: "browser_authentication", action: "cancel" },
        },
      ],
    });
  } else {
    throw new Error("Unsupported approval request");
  }
}

Halte den Stream offen und bearbeite jede ausstehende Genehmigungsanfrage. Verfolge die Anfragen anhand ihrer request_id. Entferne die Bedienelemente für die Genehmigung, sobald die Anfrage nicht mehr unter required_actions in der Sitzung steht. Wenn du eine Genehmigungsanfrage abbrichst, läuft die Aufgabe weiter.

Eine Antwort mit 202 bedeutet, dass die API die Entscheidung angenommen hat. Die Navigation kann zu diesem Zeitpunkt noch laufen.

Aufgabe im Browser ausführen

Bitte den Agenten, auf der öffentlichen Entwicklerwebsite den Schnellstart zur Agents API zu suchen und dessen Titel und URL anzugeben.

Öffne den Ereignisstream, bevor du die Aufgabe sendest, damit deine Anwendung die ersten Fortschrittsmeldungen erhält. Bearbeite Genehmigungsanfragen für Origins, sobald sie eingehen, damit der Browser fortfahren kann.

Aufgabe senden und Ergebnis verfolgen
let screenshot;
const events = await client.beta.agents.sessions.events.stream(session.id);
const handledRequests = new Set();
let completed = false;
try {
  await client.beta.agents.sessions.events.create(session.id, {
    events: [
      {
        type: "agent.session.input.message",
        input: [
          {
            role: "user",
            content: [
              {
                type: "input_text",
                text: "Open https://developers.openai.com in the browser. Find the Agents API quickstart, then report its page title and URL.",
              },
            ],
          },
        ],
      },
    ],
  });
  for await (const event of events) {
    switch (event.type) {
      case "agent.session.requires_action": {
        const current = await client.beta.agents.sessions.retrieve(
          session.id
        );
        for (const approval of current.required_actions) {
          if (
            approval.type === "computer_use_approval_request" &&
            !handledRequests.has(approval.request_id)
          ) {
            await respondToOriginApproval(client, session.id, approval);
            handledRequests.add(approval.request_id);
          }
        }
        break;
      }
      case "agent.session.turn.item.done": {
        // Preserve streamed screenshots; retrieved history may omit image bytes.
        const item = event.item;
        if (item.type === "computer_use_call") {
          const output = item.output;
          if (
            output?.type === "computer_screenshot" &&
            output.image_url.startsWith("data:image/jpeg;base64,")
          ) {
            screenshot = Buffer.from(
              output.image_url.split(",", 2)[1],
              "base64"
            );
          }
        }
        break;
      }
      case "agent.session.turn.output_text.done":
        console.log(event.text);
        break;
      case "error":
        throw new Error(event.error.message);
      case "agent.session.failed":
      case "agent.session.environment.failed":
        throw new Error(`Agent lifecycle failure: ${event.type}`);
      case "agent.session.turn.failed":
        if (event.turn.subagent_id === null) {
          throw new Error(event.turn.error?.message ?? "Browser task failed");
        }
        break;
      case "agent.session.turn.cancelled":
        if (event.turn.subagent_id === null) {
          throw new Error("Browser task was cancelled");
        }
        break;
      case "agent.session.turn.completed":
        if (event.turn.subagent_id === null) completed = true;
        break;
    }
    if (completed) break;
  }
  if (!completed) {
    throw new Error("Stream closed before the browser task finished");
  }
  console.log();
} finally {
  events.controller.abort();
}

Das Beispiel gibt die Antwort des Agenten aus. Prüfe, ob sie den Titel und die URL des Schnellstarts enthält.

Wenn du den Ereignisstream schließt, läuft die Aufgabe weiter. Um sie zu stoppen, brich den Durchlauf ab. Bei Verbindungsfehlern oder unklarem Ergebnis folge den Hinweisen zur Wiederherstellung. Das ausführliche cURL-Beispiel zeigt auch, wie du Transportprobleme und andere Fehler diagnostizierst.

Browseraktivitäten verfolgen

Browseroperationen erscheinen in der Sitzungsausgabe als Einträge vom Typ computer_use_call. Diese Einträge haben im Stream und im gespeicherten Sitzungsverlauf dieselbe Struktur.

Feld Bedeutung
id ID des Aktivitätseintrags.
turn_id Durchlauf, in dem die Aktivität stattgefunden hat.
title Beschreibung der Browseraktivität oder null.
status in_progress, completed, failed oder incomplete.
output Screenshot, sofern verfügbar.

Zeige mit dem Titel und dem Status den Fortschritt in deiner Anwendung an. Ein Eintrag zur Browseraktivität beschreibt eine einzelne Tooloperation. Die abschließende Antwort des Agenten und der Status des gesamten Durchlaufs lassen sich daraus nicht ablesen. Weitere Informationen zum Ereignismodell für Sitzungen findest du unter Ereignisse und Einträge.

Screenshots einbeziehen

Um den Fortschritt im Browser in deiner Anwendung anzuzeigen, setze include_screenshots auf true, wenn du das Tool computer_use konfigurierst. Standardmäßig enthält die API-Ausgabe keine Screenshots. Der Agent kann sie trotzdem sehen.

Das Ereignis zum Abschluss einer Browseraktivität enthält in item.output den zuletzt ausgegebenen Screenshot, sofern einer verfügbar ist:

{
  "type": "computer_screenshot",
  "image_url": "data:image/jpeg;base64,..."
}

Verwende image_url, um den Screenshot anzuzeigen. Manche Operationen geben auch bei aktivierten Screenshots output: null zurück. Deine Anwendung sollte daher Aktivitätseinträge ohne Bild verarbeiten können.

Screenshots können sensible Seiteninhalte oder Kontodaten enthalten. Zeige sie nur berechtigten Personen an und speichere sie nicht in den Anwendungslogs.

Erfasse beim Lesen des Streams die verfügbaren Screenshots aus den Ereignissen vom Typ agent.session.turn.item.done. Beim späteren Abruf des Verlaufs können die Bilddaten fehlen. Bewahre das Bild deshalb in deiner Anwendung auf, statt dich auf einen späteren Abruf der Eintragsliste zu verlassen. Nach Abschluss des Durchlaufs listen die SDK-Beispiele die Browseraktivitäten auf und speichern den zuletzt erfassten Screenshot. Die meisten verwenden browser-screenshot.jpg. Das Java-Beispiel verwendet eine temporäre Datei.

Browseraktivitäten auslesen
for await (const item of client.beta.agents.sessions.items.list(session.id, {
  order: "asc",
  limit: 100,
})) {
  if (item.type !== "computer_use_call") continue;
  console.log(item.title ?? "Browser activity", item.status);
}
if (screenshot) {
  const file = await open("browser-screenshot.jpg", "wx", 0o600);
  try {
    await file.writeFile(screenshot);
  } finally {
    await file.close();
  }
  console.log("Saved browser-screenshot.jpg");
} else {
  console.log("No browser screenshot was returned.");
}

Die SDK-Beispiele überschreiben keine vorhandenen Dateien. Verschiebe oder entferne browser-screenshot.jpg, bevor du sie erneut ausführst.

Anmeldung verarbeiten

Für Aufgaben wie das Lesen von Issues in einem privaten GitHub-Repository ist eine Anmeldung im Browser erforderlich. Deine Anwendung übernimmt die Anmeldung, damit die Personen, die sie nutzen, außerhalb des Chats eine Anmeldemethode wählen und ihre Zugangsdaten eingeben können.

Eine Anmeldung kann mehrere Anfragen umfassen. Eine Website kann beispielsweise zuerst die Anmeldung per E-Mail zur Auswahl stellen, dann nach der E-Mail-Adresse fragen und anschließend einen Bestätigungscode anfordern. Richte deine Benutzeroberfläche nach den Anmeldemethoden und Feldern der jeweiligen Anfrage aus.

Nur der Hauptagent kann die Authentifizierung im Browser anfordern. Subagenten können das nicht. Dieser Ablauf unterstützt E-Mail-Adressen, Passwörter und Bestätigungscodes. Passkeys und die Anmeldung per QR-Code werden nicht unterstützt. Verlangt eine Website eine nicht unterstützte Methode, lässt sich die Anmeldung über diesen Ablauf nicht abschließen.

Halte den Ereignisstream für die Aufgabe offen und bearbeite Genehmigungsanfragen für Origins, sobald sie eingehen. Rufe bei agent.session.requires_action die Sitzung ab. Suche unter den aktuellen required_actions nach Einträgen vom Typ computer_use_approval_request, deren verschachteltes Feld request.type den Wert browser_authentication hat.

Verwende das verschachtelte request-Objekt, um die Anmeldeoberfläche anzuzeigen:

Feld Verwendung
reason Zeige die Begründung für die benötigte Eingabe an, sofern sie vorliegt. Der Wert kann null sein.
credential_origin Zeige an, für welches Ziel die Zugangsdaten bestimmt sind. Der Wert kann null sein.
fields Erstelle die Eingabefelder anhand der Werte id, label, type und required jedes Felds. Die Liste kann leer sein.
options Zeige die verfügbaren Anmeldemethoden an. Jede Option enthält eine id, ein label und die field_ids der zugehörigen Eingabefelder.

Bietet die Anfrage Anmeldemethoden an, lass die Person eine davon auswählen und zeige die zugehörigen Felder an. Andernfalls zeigst du direkt die Felder der Anfrage an.

Fordere Personen nur dann zur Eingabe ihrer Zugangsdaten auf, wenn sie das Ziel überprüfen können. Fehlt die Origin für die Zugangsdaten oder ist sie der Person unbekannt, brich die Authentifizierungsanfrage ab, sofern die Person das Ziel nicht unabhängig überprüfen kann.

Übermittle die Eingabe mit der request_id der äußeren Aktion oder brich die Authentifizierungsanfrage ab, wenn die Person die Anmeldung ablehnt. Bearbeite weitere Anfragen, sobald sie eingehen. Aus dem Absenden einer Antwort lässt sich noch nicht schließen, dass die Anmeldung erfolgreich war. Verfolge die Aufgabe bis zum Abschluss und prüfe ihr Ergebnis.

Beispiel: Methode auswählen und anschließend einen Code eingeben

Eine Website, die eine Anmeldung per E-Mail-Code oder Passwort anbietet, kann zunächst zur Auswahl einer Methode auffordern, ohne Eingabefelder anzufordern:

Anmeldemethode auswählen
{
  "type": "computer_use_approval_request",
  "turn_id": "turn_example",
  "request_id": "request_choose_method",
  "request": {
    "type": "browser_authentication",
    "reason": "Choose how to sign in to the issue tracker",
    "credential_origin": "https://issues.example.com",
    "fields": [],
    "options": [
      { "id": "email_code", "label": "Email me a code", "field_ids": [] },
      { "id": "password", "label": "Use a password", "field_ids": [] }
    ]
  }
}

Wählt die Person die Anmeldung per E-Mail-Code, sende selected_option: "email_code" zusammen mit fields: [] und der request_id dieser Anfrage. Die Website kann dann die E-Mail-Adresse und den Bestätigungscode in separaten Anfragen anfordern. Zeige jede neue Anfrage mit ihren eigenen Feldern und IDs an. Sende selected_option nur mit, wenn die jeweilige Anfrage Optionen anbietet.

Eingabe zurückgeben

Sobald die Person die Anmeldeanfrage ausgefüllt hat, sende ihre Antwort über den Endpunkt für Sitzungsereignisse. Setze action auf submit und verwende die Anfrage-ID und die Feld-IDs aus der ausstehenden Genehmigungsanfrage. Eine Antwort auf die Frage nach einer E-Mail-Adresse sieht beispielsweise so aus:

{
  "events": [
    {
      "type": "agent.session.input.computer_use_approval_request_result",
      "request_id": "REQUEST_ID",
      "response": {
        "type": "browser_authentication",
        "action": "submit",
        "fields": [{ "field_id": "email", "value": "USER_ENTERED_VALUE" }]
      }
    }
  ]
}

Wenn die Anfrage Anmeldemethoden anbietet, gib die ID der gewählten Methode in response.selected_option an. Sende nur die Felder, die für diese Methode unter field_ids aufgeführt sind. Jedes Pflichtfeld muss einen nicht leeren Wert enthalten. Hat die Methode keine Felder, sende fields: [].

Wenn keine Anmeldemethoden angeboten werden, lass selected_option weg und sende die Felder der Anfrage direkt. Führt die Anfrage Felder auf, sende mindestens eines davon mit, selbst wenn alle optional sind.

Sende Anmeldedaten ausschließlich über dieses dafür vorgesehene Ereignis. Die übermittelten Werte gelangen nicht in die Modelleingabe des Agenten. Auch die Einträge zu Authentifizierungsantworten im Sitzungsverlauf enthalten diese Werte nicht.

Behandle alle Werte als sensibel, auch E-Mail-Adressen. Verdecke die Werte bei der Eingabe. Speichere sie weder in Logs noch in Analysedaten oder im gespeicherten Zustand der Benutzeroberfläche. Leere das Formular nach dem Absenden. Sende Zugangsdaten weder in gewöhnlichen Nachrichten noch in Ergebnissen von Funktionstools.

Lass turn_id in dem Ereignis weg, mit dem du die Eingabe übermittelst. Die Vorgaben für Felder und Nutzdaten findest du unter Grenzwerte für die Übermittlung von Anmeldedaten.

Eine Antwort mit 202 und leerem Antworttext bestätigt, dass die API die Eingabe angenommen hat. Ob die Anmeldung erfolgreich war, geht daraus noch nicht hervor. Verfolge die weiteren Sitzungsereignisse, um zu sehen, ob neue Anfragen eingehen oder der Agent die Aufgabe fortsetzt. Deaktiviere automatische Wiederholungsversuche auf HTTP- oder SDK-Ebene für die Übermittlung von Zugangsdaten. Wenn unklar ist, ob die API eine Eingabe angenommen hat, rufe vor dem Fortfahren den aktuellen Sitzungsstand ab.

Abbruch der Anmeldung ermöglichen

Lehnt die Person die Anmeldung ab, antworte auf die ausstehende Anfrage mit action: "cancel". Verwende die zugehörige request_id und lass fields und selected_option weg:

{
  "events": [
    {
      "type": "agent.session.input.computer_use_approval_request_result",
      "request_id": "REQUEST_ID",
      "response": { "type": "browser_authentication", "action": "cancel" }
    }
  ]
}

Damit brichst du die Authentifizierungsanfrage ab. Um die Aufgabe selbst zu stoppen, brich den Durchlauf ab.

Browseraufgabe mit Anmeldung ausführen

Deine Anwendung verfolgt die Sitzungsereignisse und bearbeitet dabei Genehmigungsanfragen für Origins sowie Anmeldeanfragen. Definiere die folgende Hilfsfunktion, bevor du die Aufgabe ausführst. Sie zeigt das Ziel an, verdeckt die Werte bei der Eingabe und sendet die Antwort. Lehnt die Person die Anmeldung ab, bricht die Funktion die Anmeldeanfrage ab.

Genehmigungen und Anmeldungen im Browser bearbeiten
import promptSync from "prompt-sync";

const prompt = promptSync({ sigint: true });

/** @param {OpenAI} client */
async function respondToComputerUseApproval(
  client: OpenAI,
  sessionId: string,
  approval: OpenAI.Beta.Agents.AgentSession.SessionRequiredActionResourceComputerUseApprovalRequest
) {
  const request = approval.request;
  if (request.type === "browser_origin_access") {
    console.log("Requested origin:", request.origin);
    console.log(request.reason ?? "The browser needs access to this origin.");
    let input;
    do {
      input =
        prompt("Allow access? [approve/deny/cancel, default deny] ")
          .trim()
          .toLowerCase() || "deny";
    } while (!["approve", "deny", "cancel"].includes(input));
    const decision =
      input === "approve" ? "approve" : input === "cancel" ? "cancel" : "deny";
    await client.beta.agents.sessions.events.create(sessionId, {
      events: [
        {
          type: "agent.session.input.computer_use_approval_request_result",
          request_id: approval.request_id,
          response: { type: "browser_origin_access", decision },
        },
      ],
    });
    return;
  }
  if (request.type !== "browser_authentication") {
    throw new Error("Unsupported approval request");
  }
  async function cancelSignIn() {
    await client.beta.agents.sessions.events.create(
      sessionId,
      {
        events: [
          {
            type: "agent.session.input.computer_use_approval_request_result",
            request_id: approval.request_id,
            response: { type: "browser_authentication", action: "cancel" },
          },
        ],
      },
      { maxRetries: 0 }
    );
  }
  console.log(request.reason ?? "Sign in to continue");
  console.log(
    "Credential origin:",
    request.credential_origin ?? "Not supplied"
  );
  const consent = prompt("Have you verified the sign-in destination? [y/N] ")
    .trim()
    .toLowerCase();
  if (!["y", "yes"].includes(consent)) {
    await cancelSignIn();
    return;
  }

  let selectedOption: (typeof request.options)[number] | undefined;
  let activeFields = request.fields;
  if (request.options.length > 0) {
    request.options.forEach((option, index) => {
      console.log(`${index + 1}. ${option.label}`);
    });
    let choice;
    do {
      const input = prompt("Choose a sign-in method, or enter cancel: ")
        .trim()
        .toLowerCase();
      if (input === "cancel") {
        await cancelSignIn();
        return;
      }
      choice = Number(input);
    } while (
      !Number.isInteger(choice) ||
      choice < 1 ||
      choice > request.options.length
    );
    const option = request.options[choice - 1];
    selectedOption = option;
    activeFields = request.fields.filter((field) =>
      option.field_ids.includes(field.id)
    );
  }

  const fields = [];
  do {
    for (const field of activeFields) {
      while (true) {
        const value = prompt.hide(
          `${field.label}${field.required ? "" : " (optional)"} (leave blank for options): `
        );
        if (value.length > 0) {
          fields.push({ field_id: field.id, value });
          break;
        }
        let action;
        do {
          action = prompt(
            field.required
              ? "Enter a value or cancel sign-in? [enter/cancel, default enter] "
              : "Skip this field, enter a value, or cancel sign-in? [skip/enter/cancel, default skip] "
          )
            .trim()
            .toLowerCase();
        } while (
          ![
            "",
            "enter",
            "cancel",
            ...(field.required ? [] : ["skip"]),
          ].includes(action)
        );
        if (action === "cancel") {
          await cancelSignIn();
          return;
        }
        if (!field.required && (action === "" || action === "skip")) break;
      }
    }
    if (!selectedOption && activeFields.length > 0 && fields.length === 0) {
      console.log(
        "This form requires at least one field. Enter a value or cancel sign-in."
      );
    }
  } while (!selectedOption && activeFields.length > 0 && fields.length === 0);
  await client.beta.agents.sessions.events.create(
    sessionId,
    {
      events: [
        {
          type: "agent.session.input.computer_use_approval_request_result",
          request_id: approval.request_id,
          response: {
            type: "browser_authentication",
            action: "submit",
            fields,
            ...(selectedOption ? { selected_option: selectedOption.id } : {}),
          },
        },
      ],
    },
    { maxRetries: 0 }
  );
}

Das folgende Beispiel fordert den Agenten auf, Issues in einem privaten GitHub-Repository zu lesen. Ersetze https://github.com/acme/private-repo/issues durch eine Issues-Seite, auf die du zugreifen kannst.

Öffne den Ereignisstream, bevor du die Aufgabe sendest. Rufe die Hilfsfunktion jedes Mal auf, wenn die Sitzung eine Eingabe erfordert.

Issues in einem privaten Repository lesen
import OpenAI from "openai";

const client = new OpenAI();
const session = await client.beta.agents.sessions.create({
  agent: {
    model: "gpt-6-astra",
    instructions:
      "Read the requested GitHub issue list in the browser. Request sign-in when needed. Do not create, edit, comment on, or close issues.",
    tools: [{ type: "computer_use", include_screenshots: false }],
  },
  environment: {
    type: "openai_hosted",
    desktop: { enabled: true },
    network: { access: "enabled" },
  },
});
console.log("Session ID:", session.id);

let completed = false;
let readyToDelete = false;
try {
  const events = await client.beta.agents.sessions.events.stream(session.id);
  const handledRequests = new Set();
  try {
    await client.beta.agents.sessions.events.create(session.id, {
      events: [
        {
          type: "agent.session.input.message",
          input: [
            {
              role: "user",
              content: [
                {
                  type: "input_text",
                  // Replace this illustrative URL with your private repository.
                  text: "Open https://github.com/acme/private-repo/issues in the browser. Sign in if needed, then report the title and URL of the most recently updated open issue. Do not make changes.",
                },
              ],
            },
          ],
        },
      ],
    });
    for await (const event of events) {
      switch (event.type) {
        case "agent.session.requires_action": {
          const current = await client.beta.agents.sessions.retrieve(
            session.id
          );
          for (const approval of current.required_actions) {
            if (
              approval.type === "computer_use_approval_request" &&
              !handledRequests.has(approval.request_id)
            ) {
              await respondToComputerUseApproval(client, session.id, approval);
              handledRequests.add(approval.request_id);
            }
          }
          break;
        }
        case "agent.session.turn.output_text.done":
          console.log(event.text);
          break;
        case "error":
          throw new Error(event.error.message);
        case "agent.session.failed":
        case "agent.session.environment.failed":
          throw new Error(`Agent lifecycle failure: ${event.type}`);
        case "agent.session.turn.failed":
          if (event.turn.subagent_id === null) {
            throw new Error(event.turn.error?.message ?? "Browser task failed");
          }
          break;
        case "agent.session.turn.cancelled":
          if (event.turn.subagent_id === null) {
            throw new Error("Browser task was cancelled");
          }
          break;
        case "agent.session.turn.completed":
          if (event.turn.subagent_id === null) completed = true;
          break;
      }
      if (completed) break;
    }
    if (!completed) {
      throw new Error("Stream closed before the browser task finished");
    }
    console.log();
  } finally {
    events.controller.abort();
  }
  readyToDelete = completed;
} catch (error) {
  console.error(
    `Session ${session.id} was kept. Use the same ID to check its status before trying again.`
  );
  throw error;
} finally {
  if (readyToDelete) await client.beta.agents.sessions.delete(session.id);
}

Für die Anmeldung können mehrere Anfragen nötig sein. Bearbeite Genehmigungsanfragen daher so lange, bis die Aufgabe abgeschlossen ist. Prüfe, ob das Ergebnis des Agenten zur Aufgabe passt. Überprüfe in diesem Beispiel den angegebenen Titel und die URL des Issues.

Anmeldeverlauf auslesen

Authentifizierungsanfragen und angenommene Antworten erscheinen im Sitzungsverlauf und in Ereignissen vom Typ agent.session.turn.item.added. Die Anfrageeinträge enthalten die Metadaten des Anmeldeformulars. Die Antworteinträge halten die angenommene Aktion fest, enthalten aber keine übermittelten Zugangsdaten.

Im Verlauf kannst du frühere Interaktionen nachvollziehen. Um festzustellen, ob ein Anmeldeformular noch eine Eingabe erfordert, rufe die aktuellen required_actions der Sitzung ab. Eine protokollierte Antwort belegt noch keine erfolgreiche Anmeldung.

Für Genehmigungen zum Zugriff auf eine Origin gibt es im Verlauf keine eigenen Anfrage- oder Antworteinträge. Bearbeite sie über required_actions.

Während einer Aufgabe eine Frage stellen

Um während einer Aufgabe etwas zu klären oder eine Auswahl anzubieten, definiere ein Funktionstool in agent.tools. Beispielsweise kannst du request_user_response definieren, um eine Frage anzuzeigen und eine Antwort zu erfassen. Deine Anwendung stellt den Namen des Tools, das Schema für die Argumente und die Benutzeroberfläche bereit.

Wenn du agent.session.requires_action empfängst, suche den ausstehenden function_call für dein Tool und zeige die Frage anhand der zugehörigen arguments an. Gib die Antwort über agent.session.input.tool_result zurück und verwende dabei die turn_id und call_id der Aktion. Setze success: true und schreibe die Antwort in output. Serialisiere strukturierte Antworten als JSON-String. Lehnt die Person eine Antwort ab, gib success: false mit einer Meldung in error zurück.

Verfolge die Sitzungsereignisse weiter, nachdem du die Antwort zurückgegeben hast. Die zuvor gezeigten Hilfsfunktionen für Browsergenehmigungen verarbeiten Origin-Zugriffe und Anmeldungen. Erweitere deinen Ereignishandler so, dass er auch das Tool für Rückfragen verarbeitet.

Das Modell kann die Ergebnisse von Funktionstools sehen. Die Ergebnisse werden außerdem im Sitzungsverlauf gespeichert. Erfasse Passwörter und Bestätigungscodes über die Authentifizierung im Browser.

Bearbeitung von Genehmigungsanfragen wieder aufnehmen

Wenn deine Anwendung die Verbindung verliert oder eine Antwort auf eine Genehmigungsanfrage fehlschlägt, rufe dieselbe Sitzung ab und prüfe die aktuellen required_actions, bevor du fortfährst. Stelle nur die Formulare für noch ausstehende Anfragen wieder her. Entferne die Bedienelemente für Anfragen, die nicht mehr vorliegen.

Bricht die Verbindung zum Ereignisstream ab, folge der Anleitung zur Wiederherstellung des Streams, um wieder Ereignisse zu empfangen. Beim Wiederverbinden darf deine Anwendung weder die Aufgabe noch eine Antwort auf eine Genehmigungsanfrage automatisch erneut senden.

Entscheide anhand des Antwortstatus, wie deine Anwendung fortfährt:

Ergebnis Vorgehen in deiner Anwendung
202 Lösche die übermittelten Werte aus dem Formular und verfolge die Sitzungsereignisse, um das Ergebnis zu erfahren.
400 Gleiche Antworttyp, ausgewählte Option, Feld-IDs und Pflichtwerte mit der ausstehenden Anfrage ab. Lass bei einem Abbruch und bei Antworten auf Origin-Zugriffsanfragen die Felder weg.
404 Prüfe Sitzungs-ID, Anfrage-ID und Antworttyp. Rufe die Sitzung erneut ab. Möglicherweise liegt die Anfrage nicht mehr vor.
409 Rufe den aktuellen Sitzungsstand ab. Möglicherweise ist die Anfrage abgelaufen, der zugehörige Durchlauf beendet oder bereits eine andere Antwort angenommen worden.
Verbindungsabbruch vor der Bestätigung Ob die API die Antwort angenommen hat, ist unklar. Stelle die Verbindung wieder her und rufe die Sitzung ab, bevor du über einen erneuten Versuch entscheidest.

Authentifizierungsanfragen laufen nach fünf Minuten ab. Der zugehörige Durchlauf kann enden, während die Person ihre Daten eingibt. Rufe den aktuellen Sitzungsstand ab, bevor du ein Anmeldeformular wiederherstellst.

Wenn du Anmeldedaten erneut übermittelst, verwende dieselbe request_id, dieselbe ausgewählte Option und dieselbe Zuordnung von Feldern und Werten. Bei einer identischen Wiederholung wird das Formular im Browser nicht erneut ausgefüllt. Änderst du Werte, nachdem die API eine Eingabe angenommen hat, erhältst du 409. Für einen neuen Anmeldeversuch ist eine neue Anfrage des Agenten erforderlich.

Schlägt die Übermittlung einer Entscheidung zum Origin-Zugriff fehl, sende dieselbe Entscheidung erneut. Änderst du eine bereits angenommene Entscheidung, erhältst du 409. Offene Origin-Anfragen bleiben für die Dauer des zugehörigen Durchlaufs bestehen. Die Fünf-Minuten-Frist für Authentifizierungsanfragen gilt für sie nicht.

Netzwerkzugriff steuern

Mit der network-Konfiguration der gehosteten Umgebung steuerst du ausgehende Verbindungen sowohl für den Browser als auch für Code, der in der Umgebung läuft. Erlaube den Zugriff auf die Zielwebsite und alle Domains, die für Seitenressourcen oder Weiterleitungen benötigt werden.

Über den Zugriff auf eine Origin entscheidet die Person, die deine Anwendung nutzt, separat. Ihre Genehmigung setzt die Netzwerkrichtlinie nicht außer Kraft. Wie du die Umgebung konfigurierst, erfährst du in den Einstellungen für den Netzwerkzugriff.

Sitzung weiterverwenden und aufräumen

Verwende dieselbe Sitzung für Folgeaufgaben, die auf den aktuellen Browserzustand angewiesen sind. Anmelde-Cookies können ablaufen. Wenn die Umgebung neu bereitgestellt wird, geht der Browserzustand verloren.

Wenn du fertig bist, rufe alle benötigten Ergebnisse ab und lösche die Sitzung, um die Bereinigung der Umgebung anzufordern:

Browsersitzung löschen
await client.beta.agents.sessions.delete(session.id);

Unter Von OpenAI gehostete Sandboxes erfährst du, wie lange eine Umgebung besteht und was beim Löschen passiert.

Referenz zur Verarbeitung von Anfragen

Grenzwerte für die Übermittlung von Anmeldedaten

Pro Übermittlung kannst du bis zu sechs Feldwerte senden. Jedes Feld darf nur einmal vorkommen. Jeder Wert darf bis zu 16.384 Zeichen enthalten. Die serialisierten Feldwerte und die ausgewählte Option dürfen zusammen höchstens 120 KiB belegen.

Verwende die Anfrage-ID und die Feld-IDs aus der ausstehenden Genehmigungsanfrage und gib für jedes Pflichtfeld einen nicht leeren Wert an. Das Anfrageschema findest du in der API-Referenz für Sitzungsereignisse.

Ausführliches cURL-Beispiel zur Verarbeitung von Anfragen und Streams

Verwende diese Variante, wenn du Transportfehler, HTTP-Fehler und ungültige Antworten beim Erstellen einer Sitzung unterscheiden musst. Sie filtert außerdem die Ausgabe des Streams und gibt Fehlertypen und Fehlercodes aus. Wie im ersten Beispiel arbeitest du mit zwei Terminals. Bearbeite Genehmigungsanfragen im zweiten Terminal, sobald sie eingehen.

Sitzung erstellen und Streamfehler untersuchen
create_browser_session() {
  unset session_id
  local result http_status body curl_status
  if result=$(curl --silent --fail-with-body --write-out '\n%{http_code}' \
    https://api.openai.com/v1/agents/sessions \
    -H "OpenAI-Beta: agents=v1" \
    -H "Authorization: Bearer $OPENAI_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "agent": {
        "model": "gpt-6-astra",
        "instructions": "Read public documentation in the browser. Do not sign in or change any website data. Report the page title and URL you find.",
        "tools": [{ "type": "computer_use", "include_screenshots": true }]
      },
      "environment": {
        "type": "openai_hosted",
        "desktop": { "enabled": true },
        "network": { "access": "enabled" }
      }
    }'); then curl_status=0; else curl_status=$?; fi
  http_status=$(printf '%s\n' "$result" | tail -n 1)
  body=$(printf '%s\n' "$result" | sed '$d')
  [[ "$http_status" =~ ^[0-9]{3}$ ]] || http_status=000

  if [ "$curl_status" -ne 0 ] || [[ ! "$http_status" =~ ^2[0-9][0-9]$ ]]; then
    printf '%s' "$body" | jq --raw-input --slurp --compact-output \
      --arg status "$http_status" --arg curl_status "$curl_status" '
        def identifier:
          if type == "string" and test("^[A-Za-z][A-Za-z0-9_]{0,79}$") then . else null end;
        (try fromjson catch {}) as $response
        | (if ($response | type) == "object" then $response.error // $response else {} end) as $error
        | if $curl_status != "0" and $curl_status != "22" then
            {status: $status, type: "transport_error", code: ("curl_" + $curl_status)}
          else
            {status: $status, type: ((try ($error.type | identifier) catch null) // "http_error"),
             code: (try ($error.code | identifier) catch null)}
          end' >&2
    return 1
  fi
  if ! session_id=$(printf '%s' "$body" | jq --exit-status --raw-output \
    'select(type == "object") | .id | select(type == "string" and length > 0)' 2>/dev/null); then
    unset session_id
    printf '{"status":"%s","type":"invalid_response","code":"missing_session_id"}\n' "$http_status" >&2
    return 1
  fi
  printf 'Session ID: %s\n' "$session_id"
}
create_browser_session

# Terminal 1: use session_id from the creation request.
# Keep this stream open. Wait for HTTP 200 before sending input.
set -o pipefail
curl --silent --show-error --dump-header - --suppress-connect-headers \
  --no-buffer --fail-with-body \
  "https://api.openai.com/v1/agents/sessions/$session_id/events" \
  -H "OpenAI-Beta: agents=v1" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Accept: text/event-stream" \
  | jq --null-input --raw-input --compact-output --unbuffered '
      def identifier:
        if type == "string" and test("^[A-Za-z][A-Za-z0-9_]{0,79}$") then . else null end;
      def safe_error:
        if type == "object" then {type: (.type | identifier), code: (.code | identifier)} else null end;
      def public_event:
        if .type == "agent.session.turn.output_text.done" then {type, text}
        elif .type == "agent.session.turn.completed" or .type == "agent.session.turn.failed" or .type == "agent.session.turn.cancelled" then
          {type, turn_id: .turn.id, subagent_id: .turn.subagent_id, error: (.turn.error | safe_error)}
        elif .type == "error" or .type == "agent.session.failed" or .type == "agent.session.environment.failed" then
          {type, error: ((.error // .session.error // .environment.error) | safe_error)}
        elif .type == "agent.session.requires_action" then {type}
        else empty end;
      foreach inputs as $raw (
        {body: "", headers: false, failed: false, output: []};
        .output = []
        | ($raw | rtrimstr([13] | implode)) as $line
        | if ($line | startswith("HTTP/")) then
            (try ($line | capture("^(?<protocol>HTTP/[0-9.]+) (?<status>[0-9]{3})(?: |$)")) catch null) as $http
            | if $http == null then . else
                .body = "" | .headers = true | .status = $http.status
                | .failed = (($http.status | tonumber) >= 300)
                | .output = [$http.protocol + " " + $http.status]
              end
          elif .headers then
            if $line == "" then .headers = false else . end
          elif ($line | startswith("data:")) then
            (try ($line | ltrimstr("data:") | fromjson) catch null) as $event
            | .output = [$event | select(type == "object") | public_event]
          elif .failed and .body != null then
            .body += ($line + "\n")
            | (try (.body | fromjson) catch null) as $body
            | if ($body | type) == "object" then
                (($body.error // $body) | safe_error) as $error
                | .output = [{status: .status, type: ($error.type // "http_error"), code: $error.code}]
                | .body = null
              else . end
          else . end;
        .output[])'

# Terminal 2: replace sess_123 with the ID printed in terminal 1.
# Export OPENAI_API_KEY in this terminal too.
session_id="sess_123"
curl --fail-with-body "https://api.openai.com/v1/agents/sessions/$session_id/events" \
  -H "OpenAI-Beta: agents=v1" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [{
      "type": "agent.session.input.message",
      "input": [{
        "role": "user",
        "content": [{
          "type": "input_text",
          "text": "Open https://developers.openai.com in the browser. Find the Agents API quickstart, then report its page title and URL."
        }]
      }]
    }]
  }'