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

Schnellstart mit der Agents API

Erstelle einen Agenten, der in einer von OpenAI gehosteten Sandbox ein Skript schreibt und ausführt.

Entwickle einen Programmierassistenten, der tree.py schreibt, das Skript ausführt und einen Verzeichnisbaum anzeigt. OpenAI verwaltet den Agenten, den Gesprächsverlauf und die Sandbox, in der der Agent arbeitet.

Voraussetzungen

Erstelle in deinem Projekt auf der OpenAI Platform einen API-Schlüssel für deine Anwendung. Weise dem Schlüssel die Berechtigungen api.agents.read und api.agents.write für Sitzungsoperationen sowie api.responses.write für die Modellinferenz zu. Exportiere ihn anschließend als Umgebungsvariable.

export OPENAI_API_KEY="your-api-key"

Bewahre den Schlüssel außerhalb der Sandbox des Agenten auf. Angaben zur Konfiguration und zu den Einschränkungen findest du im Leitfaden zu von OpenAI gehosteten Sandboxen.

Anfragen benötigen den Header OpenAI-Beta: agents=v1. Die OpenAI-SDKs fügen ihn automatisch hinzu. Wenn du cURL verwendest, gib ihn ausdrücklich an.

1. Aufgabe ausführen

Wähle eine Programmiersprache, installiere das OpenAI-SDK und führe das Beispiel aus. Die SDK-Beispiele verwenden den Namensraum beta.agents. Die Anfrage erstellt eine Sitzung, übermittelt eine Aufgabe und liefert fortlaufend Ereignisse zum Fortschritt.

Installiere oder aktualisiere das Python-SDK.

pip install --upgrade openai

Speichere das Beispiel als quickstart.py.

tree.py erstellen und ausführen
from openai import OpenAI

with OpenAI() as client:
    with client.beta.agents.sessions.create(
        agent={
            "model": "gpt-6-astra",
            "instructions": "Write clean code, run it, and report the actual output.",
        },
        environment={"type": "openai_hosted"},
        input="Create tree.py, a Python script that prints a readable tree of the files in the current directory. Run it and show me the output.",
        stream=True,
    ).with_result_collection() as stream:
        for event in stream:
            print(event.to_json(indent=None), flush=True)
        result = stream.get_final_result()
    print(result.output_text)
    session_id = result.session_id

Führe das Beispiel im Terminal aus.

python quickstart.py

Du brauchst keine Sandbox? Setze environment.type auf none, wenn dein Agent Fragen beantwortet oder externe Tools aufruft, ohne Befehle auszuführen oder mit lokalen Dateien zu arbeiten. Mehr erfahren.

2. Fortschritt verfolgen

Im Terminal siehst du die Ereignisse, sobald sie eintreffen. Die SDK-Beispiele geben sie als JSON aus. cURL zeigt den unverarbeiteten Ereignisstream an. Bei erfolgreicher Ausführung erstellt der Agent tree.py, führt das Skript aus und gibt einen Verzeichnisbaum aus, der diese Datei enthält. Welche weiteren Dateien und Ausgaben du siehst, hängt von der Sandbox ab.

Achte auf agent.session.turn.completed und prüfe anschließend, welches Ergebnis der Agent für die Ausführung meldet. Auch bei einem abgeschlossenen Durchlauf können einzelne Toolaufrufe fehlgeschlagen sein. Ereignisse, deren Namen auf turn.failed, turn.cancelled oder session.failed enden, weisen auf einen Fehler oder Abbruch hin. Das Ereignis agent.session.idle allein bestätigt keinen Erfolg. Wenn die Verbindung zum Stream vorzeitig abbricht, rufe die Sitzung und die darin gespeicherten Elemente ab, bevor du es erneut versuchst.

3. Sitzung fortsetzen

Speichere die session_id aus den Ereignissen. Damit kannst du eine weitere Nachricht senden, zum Beispiel „Ergänze tree.py um eine Option für die maximale Verzeichnistiefe, führe das Skript aus und zeige mir die Ausgabe.“ Öffne den Ereignisstream, bevor du die nächste Nachricht sendest, damit du die ersten Ereignisse nicht verpasst.

4. Aufräumen

Behalte die Sitzung für weitere Aufgaben oder lösche sie, wenn du fertig bist. Sichere vorher alle Dateien, die du noch brauchst.

Ersetze den Beispielwert sess_123 durch die Sitzungs-ID, die du gespeichert hast.

Sitzung löschen
# Replace the illustrative IDs and URLs below with your own resource values.

from openai import OpenAI


def delete_session(client: OpenAI, session_id: str):
    return client.beta.agents.sessions.delete(session_id)


if __name__ == "__main__":
    result = delete_session(OpenAI(), "sess_123")
    print(result.to_json())

Nächste Schritte