Dateien und Artefakte

Dateien und veröffentlichte Artefakte

Dateien befinden sich 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.

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-kodiertem data. Beide Varianten erfordern einen path.

Verwende die Files API der Umgebung, um nach dem Verbindungsaufbau der Umgebung Dateien hinzuzufügen.

Deine 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. Speichere sie im Speicher deiner Anwendung, bevor die Umgebung abläuft oder du sie löschst.

Dateien aus selbst gehosteten Umgebungen werden nicht über die Artifacts API veröffentlicht. Das gilt auch für Dateien unter /workspace/outputs. Informationen zum anbieterspezifischen Dateizugriff findest du unter Sandbox-Anbieter.

Aus einer von OpenAI gehosteten Umgebung

Bitte den Agenten, die Datei unter /workspace/outputs zu speichern, zum Beispiel unter /workspace/outputs/report.pdf. OpenAI veröffentlicht Ausgaben nach Abschluss des Turns als unveränderliche Artefakte.

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

1
2
3
4
5
6
7
8
9
10
11# 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}")

Informationen zu den Anfrage- und Antwortfeldern findest du in den Referenzen Artefakte auflisten, Metadaten abrufen und Inhalt herunterladen.

Mehrere Dateien herunterladen

Die API lädt pro Anfrage ein Artefakt herunter. Sie bietet keinen Endpunkt zum gleichzeitigen Herunterladen mehrerer Artefakte. Um mehrere Dateien herunterzuladen, liste die Artefakte auf und fordere für jede Datei content an. Wenn du nur einen Download möchtest, bitte den Agenten, die Ergebnisse in einer ZIP-Datei unter /workspace/outputs zu bündeln. Lade dieses Archiv anschließend als ein Artefakt herunter.

Lebensdauer von Dateien

Veröffentlichte Artefakte bleiben auch nach Ablauf der Umgebung erhalten. Lade alles herunter, was du aufbewahren möchtest, bevor du die Sitzung löschst.

Artefakte können über diese API weder hochgeladen noch bearbeitet werden. Um eine neue Version zu veröffentlichen, bitte den Agenten, die Datei zu aktualisieren und einen weiteren Turn abzuschließen. Unterscheide die Versionen anhand der Turn-ID und des Pfads.

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

Grenzwerte für Dateien