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

Agenten konfigurieren

Definiere einen Agenten, verwende seine Konfiguration wieder und passe jede Sitzung individuell an.

Mit der Konfiguration legst du fest, wie sich der Agent verhält. Du kannst sie beim Erstellen einer Sitzung übergeben oder zur späteren Verwendung speichern. Die Sitzung enthält die Unterhaltung und die Arbeit des Agenten. Der gespeicherte Agent enthält die wiederverwendbaren Einstellungen.

Verhalten des Agenten festlegen

Wähle zuerst das Modell und formuliere die Anweisungen. Ergänze dann die Tools und Einstellungen, die du für deine Aufgabe brauchst.

  • Modell: Welches Modell die Aufgabe übernimmt.
  • Anweisungen: Was der Agent tun soll und wie er sich dabei verhalten soll.
  • Tools: Welche Aktionen der Agent ausführen kann, etwa das Web durchsuchen oder deine Funktionen aufrufen.
  • Reasoning und Ausgabe: Wie hoch der Reasoning-Aufwand des Modells ist, in welchem Format es antwortet und wie ausführlich seine Antworten sind.

Übergib diese Einstellungen beim Erstellen einer Sitzung in agent. Das folgende Beispiel übergibt ein Modell, Anweisungen und die erste Nutzernachricht.

Einen Agenten für eine Sitzung konfigurieren
from openai import OpenAI

client = OpenAI()

session = client.beta.agents.sessions.create(
    agent={
        "model": "gpt-6-astra",
        "instructions": "Answer the user clearly and concisely.",
    },
    environment={"type": "none"},
    input=[
        {
            "role": "user",
            "content": [{"type": "input_text", "text": "What can you help with?"}],
        }
    ],
)
print(session.to_json())

Die Konfigurationsfelder und ihre Werte findest du in der Referenz zur Agents API. Anleitungen zum Setup findest du in den Abschnitten Funktionen, Computernutzung, MCP-Verbindungen und Aufgaben an mehrere Agenten delegieren.

Größe der Konfiguration

Anweisungen und Tool-Konfiguration müssen zusammen unter 4 MiB (4.194.304 Byte) bleiben. Lass dabei etwas Platz für die Metadaten der Agents API. Wenn eine Sitzung wegen einer zu großen Konfiguration nicht startet, erstelle eine neue Sitzung mit kürzeren Anweisungen und einer kleineren Tool-Konfiguration.

Für Dateien, die du in die Umgebung hochlädst, gelten separate Dateilimits.

Einen Agenten in mehreren Sitzungen verwenden

Speichere einen Agenten, um seine Konfiguration in mehreren Sitzungen zu verwenden. Erstelle ihn einmal und übergib dann beim Start jeder Sitzung seine ID als agent_id.

Einen Agenten wiederverwenden
from openai import OpenAI

client = OpenAI()
agent = client.beta.agents.create(
    model="gpt-6-astra",
    instructions="Answer technical questions accurately.",
    reasoning={"summary": "auto"},
    timeout=360,
)
session = client.beta.agents.sessions.create(
    agent_id=agent.id,
    environment={"type": "none"},
    input="Explain how an agent connects to an MCP server.",
)
print(session.to_json())

Jede Sitzung enthält ihre eigene Unterhaltung und die darin erledigte Arbeit. In der Referenz zur Agents API erfährst du, wie du gespeicherte Agenten auflistest, abrufst, aktualisierst oder löschst. Zugangsdaten bleiben getrennt von der gespeicherten Konfiguration in Tresoren.

Einen gespeicherten Agenten aktualisieren

Änderungen an einem gespeicherten Agenten gelten nur für neue Sitzungen. Jede Sitzung übernimmt beim Erstellen eine Kopie der gespeicherten Konfiguration und behält diese Einstellungen für spätere Gesprächsrunden bei. Um eine bestehende Sitzung zu ändern, aktualisiere ihre Einstellungen.

Beim Aktualisieren eines gespeicherten Agenten gelten folgende Regeln.

  • Felder, die du weglässt, behalten ihre gespeicherten Werte. Wenn du nur model änderst, bleiben reasoning, service_tier und text erhalten.
  • Ein übergebenes Objekt ersetzt den gesamten Feldinhalt. Übergibst du in reasoning nur effort, wird auch der gespeicherte Wert von summary gelöscht.
  • null setzt Felder zurück, die diesen Wert akzeptieren. Mit reasoning: null stellst du beispielsweise den Standardwert des Modells für den Reasoning-Aufwand wieder her.

Ändere alle Einstellungen, die das neue Modell nicht unterstützt, in derselben Anfrage oder setze sie darin zurück.

Einstellungen für eine einzelne Sitzung überschreiben

Übergib beim Erstellen einer Sitzung sowohl agent_id als auch agent, um die Konfiguration eines gespeicherten Agenten für diese Sitzung anzupassen. Alle Einstellungen, die du weglässt, übernimmt die Sitzung beim Erstellen vom gespeicherten Agenten. Das gilt auch für das Modell.

Ersetze den Beispielwert agent_123 durch die ID des gespeicherten Agenten, bevor du das Beispiel ausführst.

Agenteneinstellungen für eine Sitzung überschreiben
# Replace the illustrative IDs and URLs below with your own resource values.
from openai import OpenAI

client = OpenAI()

agent_id = "agent_123"
session = client.beta.agents.sessions.create(
    agent_id=agent_id,
    agent={"instructions": "Answer this question in one concise paragraph."},
    environment={"type": "none"},
    input=[
        {
            "role": "user",
            "content": [
                {
                    "type": "input_text",
                    "text": "Explain how an agent connects to an MCP server.",
                }
            ],
        }
    ],
)
print(session.to_json())

Die abweichenden Einstellungen gelten nur für diese Sitzung. Der gespeicherte Agent und andere Sitzungen bleiben unverändert. Übergebene Objekte und Arrays ersetzen den gesamten Feldinhalt. Sie werden nicht mit dem gespeicherten Wert zusammengeführt. Übergibst du beispielsweise tools, ersetzt du damit die gespeicherte Tool-Liste.

Die Felder der Anfrage findest du in der API-Referenz zum Erstellen einer Sitzung.

Einstellungen einer bestehenden Sitzung aktualisieren

Sende POST /v1/agents/sessions/{session_id} mit einem agent-Objekt, um tools, model, reasoning.effort oder service_tier für eine einzelne Sitzung zu ändern. Diese Einstellungen stehen sowohl in der Betaversion als auch in der allgemein verfügbaren Version der API zur Verfügung. In derselben Anfrage kannst du auch metadata aktualisieren.

Änderungen am Modell, am Reasoning-Aufwand und an der Servicestufe gelten für neue Gesprächsrunden, die du mit einer nach Abschluss der Aktualisierung gesendeten Nachricht startest. Für bereits gesendete Nachrichten, deren Verarbeitung noch läuft, können noch die vorherigen Einstellungen gelten. Eine laufende Gesprächsrunde behält für Modell, Reasoning-Aufwand und Servicestufe die bisherigen Einstellungen bei, auch wenn du eine Nachricht sendest, um den weiteren Verlauf zu steuern. Der Gesprächsverlauf der Sitzung bleibt erhalten. Das ausgewählte Modell muss die resultierenden Einstellungen unterstützen, sonst schlägt die Aktualisierung fehl.

  • Bei den Objekten agent und reasoning werden die übergebenen Felder mit den aktuellen Einstellungen zusammengeführt. Felder, die du weglässt, bleiben unverändert. Das gilt auch für die Reasoning-Zusammenfassung. Änderst du nur model, behält die Sitzung ihren Reasoning-Aufwand und ihre Servicestufe bei.
  • tools ersetzt die gesamte Tool-Liste. Änderungen an Funktionen und MCP-Servern gelten ab dem nächsten Modellaufruf. Änderungen an integrierten Tools werden spätestens mit der nächsten Gesprächsrunde wirksam. Lass tools weg, um die aktuellen Tools beizubehalten, oder übergib null oder [], um die Liste zu leeren.
  • reasoning.effort: null setzt den Reasoning-Aufwand auf den Standardwert des ausgewählten Modells zurück.
  • service_tier: null aktiviert wieder die automatische Auswahl der Servicestufe.
  • Es muss immer ein Modell festgelegt sein. Deshalb kannst du model: null nicht übergeben. Auch die Objekte agent und reasoning akzeptieren null nicht.
  • metadata ersetzt die gesamte Zuordnung von Schlüsseln und Werten. Lass das Feld weg, um die Metadaten beizubehalten, oder übergib null oder {}, um sie zu löschen.

Diese Beispielanfrage ändert den Reasoning-Aufwand und lässt die API die Servicestufe automatisch auswählen.

{
  "agent": {
    "reasoning": { "effort": "low" },
    "service_tier": null
  }
}

Wenn du eine Sitzung aktualisierst, bleiben der gespeicherte Agent und andere Sitzungen unverändert. Spätere Änderungen am gespeicherten Agenten wirken sich ebenfalls nicht auf diese Sitzung aus.

Über diesen Endpunkt kannst du reasoning.summary, text, instructions oder multi_agent nicht aktualisieren. Erstelle eine neue Sitzung, um diese Einstellungen zu ändern. Die Felder der Anfrage findest du in der API-Referenz zum Aktualisieren einer Sitzung.

Aktionen automatisch überprüfen

Setze das Feld review auf Sitzungsebene auf "auto_review", um unterstützte Genehmigungsanfragen automatisch überprüfen zu lassen. Gib das Feld außerhalb der Agentenkonfiguration auf derselben Ebene wie agent oder agent_id an. Wenn du review beim Erstellen einer Sitzung weglässt, gilt der Standardwert "none".

Die automatische Überprüfung ändert auch die Ausführungsberechtigungen. Prüfe die Voraussetzungen für die Ausführungsumgebung, bevor du die automatische Überprüfung aktivierst.

Du kannst review aktualisieren, wenn die Hauptaufgabe ruht und die Übermittlung aller ausstehenden Eingaben abgeschlossen ist. Für die anschließende Ausführung und Wiederherstellung gilt die neue Einstellung. Wenn du vorher einen Moduswechsel anforderst, gibt die API 409 Conflict zurück und übernimmt keine Änderungen. Verwende ein Projekt, in dem die automatische Überprüfung aktiviert ist, und eine Sitzung, die sie unterstützt. Im Abschnitt Automatische Überprüfung erfährst du, wie du die Überprüfung konfigurierst und Genehmigungsanfragen bearbeitest.

Umgebungseinstellungen

Gib beim Erstellen einer Sitzung environment zusammen mit agent an. Damit legst du fest, wo der Agent Befehle ausführt und mit Dateien arbeitet.

Wähle none, openai_hosted oder self_hosted. Im Abschnitt Architektur erfährst du, wann du welche Option verwenden solltest und wer die jeweilige Umgebung verwaltet.

Für eine von OpenAI gehostete Umgebung wählst du eine Containergröße und konfigurierst die Pakete, die anfänglich bereitgestellten Dateien und den Netzwerkzugriff passend zur Aufgabe. Du kannst dieselbe Umgebungsvorlage für mehrere Sitzungen verwenden. Für eine selbst gehostete Umgebung stellst du die Rechenressourcen bereit und bindest einen Executor an.

Die Felder für die Umgebung findest du in der API-Referenz zum Erstellen einer Sitzung. Der Abschnitt Plug-ins beschreibt Skills, Plug-ins und Vorlagen. Wie du Dateien nach der Ausführung aufbewahrst, erfährst du im Abschnitt Sitzungsartefakte.