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.
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.
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, bleibenreasoning,service_tierundtexterhalten. - Ein übergebenes Objekt ersetzt den gesamten Feldinhalt. Übergibst du in
reasoningnureffort, wird auch der gespeicherte Wert vonsummarygelöscht. nullsetzt Felder zurück, die diesen Wert akzeptieren. Mitreasoning: nullstellst 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.
# 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
agentundreasoningwerden 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 nurmodel, behält die Sitzung ihren Reasoning-Aufwand und ihre Servicestufe bei. toolsersetzt 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. Lasstoolsweg, um die aktuellen Tools beizubehalten, oder übergibnulloder[], um die Liste zu leeren.reasoning.effort: nullsetzt den Reasoning-Aufwand auf den Standardwert des ausgewählten Modells zurück.service_tier: nullaktiviert wieder die automatische Auswahl der Servicestufe.- Es muss immer ein Modell festgelegt sein. Deshalb kannst du
model: nullnicht übergeben. Auch die Objekteagentundreasoningakzeptierennullnicht. metadataersetzt die gesamte Zuordnung von Schlüsseln und Werten. Lass das Feld weg, um die Metadaten beizubehalten, oder übergibnulloder{}, 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.