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

Dateien und Artefakte

Rufe Dateien aus deiner Umgebung ab und sichere veröffentlichte Ausgaben.

Dateien und veröffentlichte Artefakte

Dateien liegen in der Umgebung des Agenten. Ein Artefakt ist eine veröffentlichte Kopie einer Datei aus einer von OpenAI gehosteten Umgebung. Du kannst diese Kopie auch nach Ablauf der Umgebung herunterladen.

Umgebung So rufst du Dateien ab
self_hosted Verwende die Datei-API deines Anbieters oder das eingebundene Dateisystem.
openai_hosted Rufe Dateien unter /workspace/outputs über die Artifacts API der Sitzung ab.
none Die Umgebung hat kein Dateisystem. Lies die Ausgabe aus den Sitzungselementen.

Dateien hochladen

Gib bei einer von OpenAI gehosteten Umgebung die Eingabedateien beim Erstellen der Sitzung in environment.files an. Wähle für jede Datei einen Zielpfad unter /workspace.

Verwende type: "file_id" mit einer file_id aus der Files API oder type: "inline" mit Base64-kodierten Daten in data. Beide Varianten erfordern einen path.

Sobald die Verbindung zur Umgebung steht, kannst du über die Files API der Umgebung weitere Dateien hinzufügen.

Fehler beim Hochladen beheben

Wenn die API beim Erstellen einer Sitzung oder beim Anhängen einer Datei die Dateien prüft, kann sie HTTP 429 mit files_api_rate_limit_exceeded zurückgeben. Im Abschnitt Ratenlimits der Files API findest du die Fehlerantwort und die Schritte zur Behebung.

Bei HTTP 400 zeigen dir error.param und error.message, welche Eingabe du korrigieren musst. Bei einem Zielpfad außerhalb von /workspace erhältst du beispielsweise folgende Antwort:

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_request_error",
    "message": "path must be an absolute POSIX path inside /workspace",
    "param": "path"
  }
}

Der Parameter entspricht der Struktur der Anfrage. Dabei ist i der Index der Datei. Die erste Datei hat den Index 0.

Anfrage Beispiel für error.param
Eine Datei zur Umgebung hinzufügen path, data oder file_id
Eine Sitzung erstellen oder eine Umgebung vorwärmen environment.files[i].data
Eine Umgebungsvorlage erstellen oder aktualisieren files[i].data

Verwende gültige Base64-Daten und Datei-IDs und wähle einen absoluten Pfad unter /workspace. Beachte die Grenzwerte für Dateien. Die API gibt HTTP 400 zurück, wenn der Zielpfad über einen symbolischen Link führt, das Ziel bereits existiert oder ein einzelner Pfadbestandteil zu lang ist.

Tritt beim Installieren einer Datei ein unerwarteter Fehler auf, gibt die API HTTP 500 zurück. Prüfe vor einem erneuten Versuch, ob die Zieldatei angelegt wurde. Befolge anschließend die Hinweise zum Wiederholen der Anfrage.

Dateien abrufen

Aus deiner eigenen Umgebung

Bitte den Agenten, seine Ausgabe unter einem bekannten Pfad zu speichern. Rufe die Datei nach Abschluss des Turns über deinen Anbieter oder deine Infrastruktur ab. Sichere die Datei im Speicher deiner Anwendung, bevor die Umgebung abläuft oder du die Umgebung löschst.

Dateien aus selbst gehosteten Umgebungen werden nicht über die Artifacts API veröffentlicht. Das gilt auch für Dateien unter /workspace/outputs. Im Abschnitt Sandbox-Anbieter erfährst du, wie du beim jeweiligen Anbieter auf Dateien zugreifst.

Aus einer von OpenAI gehosteten Umgebung

Bitte den Agenten, die Datei unter /workspace/outputs zu speichern, zum Beispiel unter /workspace/outputs/report.pdf. Sobald der Turn abgeschlossen ist, veröffentlicht OpenAI die Ausgaben als unveränderliche Artefakte.

Übergib dieser Funktion deinen API-Client, die Sitzungs-ID, die ID des abgeschlossenen Turns, den Artefaktpfad und den lokalen Zielpfad. Die Funktion listet die Artefakte auf und lädt die Datei herunter, die sowohl zur Turn-ID als auch zum Pfad passt.

Artefakt finden und herunterladen
# Pass the saved session ID, completed turn ID, artifact path, and local destination.
def download_artifact(client, session_id, turn_id, path, destination):
    for artifact in client.beta.agents.sessions.artifacts.list(session_id):
        if artifact.turn_id != turn_id or artifact.path != path:
            continue
        with client.beta.agents.sessions.artifacts.with_streaming_response.content(
            artifact.id, session_id=session_id
        ) as response:
            response.stream_to_file(destination)
        return
    raise FileNotFoundError(f"No artifact for {path!r} in turn {turn_id}")

Die Felder für Anfragen und Antworten findest du in der API-Referenz unter Artefakte auflisten, Metadaten abrufen und Inhalt herunterladen.

Mehrere Dateien herunterladen

Die API liefert pro Download-Anfrage ein Artefakt. Einen Endpunkt für Sammeldownloads gibt es nicht. Um mehrere Dateien herunterzuladen, liste die Artefakte auf und rufe für jede Datei content ab. Wenn du alles auf einmal herunterladen möchtest, bitte den Agenten, die Ergebnisse in einer ZIP-Datei unter /workspace/outputs zu bündeln. Lade das Archiv anschließend als einzelnes Artefakt herunter.

Lebensdauer von Dateien

Veröffentlichte Artefakte bleiben nach Ablauf der Umgebung verfügbar. Lade alles, was du behalten möchtest, herunter, bevor du die Sitzung löschst.

Über diese API kannst du Artefakte weder hochladen noch bearbeiten. Um eine neue Version zu veröffentlichen, bitte den Agenten, die Datei zu aktualisieren und einen weiteren Turn abzuschließen. Anhand der Turn-ID und des Pfads kannst du die Versionen unterscheiden.

Lösche ein Artefakt, wenn du die veröffentlichte Kopie nicht mehr benötigst. Die Datei in der Umgebung bleibt dabei erhalten.

Grenzwerte für Dateien

Dateivorgang Grenzwert
Dateien beim Erstellen einer Sitzung mitgeben 50 Dateien pro Anfrage.
Einzelne Datei inline hochladen 5 MiB pro Datei, gemessen vor der Base64-Kodierung.
Dateien in einer Erstellungsanfrage inline hochladen Insgesamt 10 MiB, gemessen vor der Base64-Kodierung.
Datei aus der Files API kopieren 50 MiB pro Datei.
Artefakt veröffentlichen 200 MiB pro Datei.
Ausgaben gemeinsam veröffentlichen Insgesamt 500 MiB.