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.
# 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. |