For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.
Hauptnavigation

Schnellstart für die Agents API

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

Entwickle einen Programmierassistenten, der tree.py schreibt, ausführt und einen Verzeichnisbaum anzeigt. OpenAI verwaltet den Agenten, seine Unterhaltung und die Sandbox, in der er arbeitet.

Voraussetzungen

Erstelle einen API-Schlüssel für Anwendungen in deinem Projekt auf der OpenAI Platform. Erteile ihm die Berechtigungen api.agents.read und api.agents.write für Sitzungsoperationen sowie api.responses.write für Modellinferenz. Exportiere ihn anschließend:

export OPENAI_API_KEY="your-api-key"

Bewahre diesen Schlüssel außerhalb der Sandbox des Agenten auf. Informationen zur Konfiguration und zu den Grenzen der Sandbox findest du unter Von OpenAI gehostete Sandboxen.

Anfragen benötigen den Header OpenAI-Beta: agents=v1. Die OpenAI SDKs fügen ihn automatisch hinzu. Bei cURL musst du ihn ausdrücklich angeben.

1. Eine Aufgabe ausführen

Wähle eine Sprache aus, 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 überträgt den Fortschritt als Stream.

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,
    ) as events:
        for event in events:
            print(event.to_json(indent=None), flush=True)

Führe es in deinem Terminal aus:

python quickstart.py

Du brauchst keine Sandbox? Setze environment.type auf none, wenn die Agenten Fragen beantworten oder externe Werkzeuge aufrufen, ohne Befehle auszuführen oder mit lokalen Dateien zu arbeiten. Mehr erfahren.

2. Den Fortschritt verfolgen

Das Terminal zeigt die gestreamten Ereignisse an. Die SDK-Beispiele geben JSON aus; cURL zeigt den unverarbeiteten Ereignisstream. Bei erfolgreicher Ausführung erstellt der Agent tree.py, führt die Datei aus und gibt einen Verzeichnisbaum aus, der diese Datei enthält. Weitere Dateien und Ausgaben hängen von der Sandbox ab.

Achte auf agent.session.turn.completed und prüfe anschließend das vom Agenten gemeldete Ausführungsergebnis. Ein abgeschlossener Gesprächsschritt garantiert nicht, dass jedes Tool erfolgreich ausgeführt wurde. Ereignisse, die auf turn.failed, turn.cancelled oder session.failed enden, zeigen einen Fehler oder Abbruch an. agent.session.idle allein bedeutet keinen Erfolg. Wenn der Stream vorzeitig abbricht, rufe die Sitzung und ihre gespeicherten Elemente ab, bevor du es erneut versuchst.

3. Die Sitzung fortsetzen

Speichere die session_id aus den Ereignissen. Verwende sie, um eine Folgeanfrage zu senden, zum Beispiel: “Add a maximum-depth option to tree.py, run it, and show me the output.” Öffne den Ereignisstream, bevor du weitere Eingaben sendest, damit du keine frühen Ereignisse verpasst.

4. Aufräumen

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

Ersetze im Beispiel den Platzhalterwert 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