Mit der Agents API greift deine Anwendung über eine von OpenAI verwaltete API auf den Codex-Harness zu.
OpenAI verwaltet die Sitzungen und übernimmt die Orchestrierung, die Kontextverdichtung und die Wiederherstellung. Deine Anwendung stellt die Tools bereit und wählt die Ausführungsumgebung.
Agenten können in einer Sandbox Code ausführen, Dateien bearbeiten, Verbindungen zu MCP-Servern herstellen und Artefakte erstellen.
Die API-Referenz beschreibt die Endpunkte, Anfrageparameter und Antwortfelder.
Preise
Für die Modellnutzung gelten die API-Preise des gewählten Modells. Für OpenAI-Tools gelten die Standardpreise für Tools, für von OpenAI gehostete Sandboxen die regulären Containerpreise.
Beispiele ausprobieren
Probiere diese vollständigen Beispiele aus:
- Erstelle ein Skript zur Anzeige des Verzeichnisbaums und führe es aus. Verwende dafür eine von OpenAI gehostete Sandbox.
- Vergleiche Versionshinweise mithilfe von Subagenten und fasse ihre Ergebnisse in einer Antwort zusammen.
Sieh dir auch diese vollständigen Anwendungen an:
- Agent für die Reaktion auf Vorfälle: Untersuche Warnmeldungen und fordere eine Genehmigung für Wiederherstellungsmaßnahmen an.
- Slack-Bot: Gehe Anfragen mit den angebundenen Tools deines Unternehmens nach.
- Agent für Datenanalyse: Beantworte Fragen zu Daten im Data Warehouse mit SQL-Abfragen ohne Schreibzugriff.
- Mit dem Agenten zur Untersuchung von GitHub-Issues kannst du gemeldete Fehler reproduzieren und deine Ergebnisse auf GitHub teilen.
- Mit dem Agenten für die Dokumentenprüfung kannst du Dokumente mithilfe von Skills zur Richtlinienprüfung und spezialisierten Agenten prüfen.
Grundbegriffe
Die Agents API beruht auf vier zentralen Konzepten:
- Agent: Zum Agenten gehören das Modell sowie die Anweisungen, Tools und MCP-Server, die ihm zur Verfügung stehen.
- Umgebung: Optional kannst du eine Sandbox oder einen Computer als Umgebung verwenden. Dort greift der Agent auf Dateien zu, lädt Skills und führt Befehle aus.
- Sitzung: Eine persistente Instanz eines Agenten, die Aufgaben bearbeitet und auf Eingaben reagiert.
- Ereignisse und Elemente: Die Eingaben, die an einen Agenten gesendet werden, und die Ausgaben, die während einer Sitzung entstehen.
Ablauf einer Sitzung
Beginne wie im Schnellstart mit einer von OpenAI gehosteten Sandbox:
- Erstelle eine Sitzung. Konfiguriere den Agenten. OpenAI stellt seine Umgebung bereit.
- Gib dem Agenten eine Aufgabe. Sobald die Umgebung bereit ist, startet deine Eingabe einen Arbeitsdurchlauf.
- Verfolge den Fortschritt. Empfange die Ausgabe als Stream oder nutze Webhooks, um zu erfahren, wann der Agent fertig ist oder eine Eingabe benötigt.
- Setze die Arbeit fort oder greife steuernd ein. Sende eine weitere Aufgabe an dieselbe Sitzung oder gib dem Agenten während des laufenden Durchlaufs Anweisungen.
Bei einer von OpenAI gehosteten Sitzung sendet deine Anwendung Eingaben und empfängt Ereignisse. OpenAI führt den Agenten aus, stellt seine Sandbox bereit und verwaltet sie. Hinweise zum Setup und zu Einschränkungen findest du unter Umgebungsoptionen.

Funktionen des verwalteten Harness
Der verwaltete Codex-Harness unterstützt folgende Funktionen:
- Befehle und Code in einer Sandbox ausführen.
- Passende Skills und Anweisungen anwenden.
- Über Tools oder MCP auf externe Daten zugreifen.
- Den Agenten während der Arbeit steuern.
- Die bisherige Arbeit zusammenfassen, um Platz im Kontextfenster zu schaffen.
- Aufgaben in Teilaufgaben aufteilen und diese an Subagenten delegieren.
- Eine Sitzung dort fortsetzen, wo sie zuletzt aufgehört hat.
In den Voraussetzungen für den Schnellstart erfährst du, welche Berechtigungen dein API-Schlüssel benötigt und wie du das SDK einrichtest. Konfiguriere die Funktionen beim Erstellen einer Sitzung:
from openai import OpenAI
client = OpenAI()
session = client.beta.agents.sessions.create(
agent={
"model": "gpt-6-astra",
"instructions": "Use the OpenAI documentation MCP and web search to answer technical questions accurately. Delegate independent research tasks to subagents when useful.",
"tools": [
{"type": "programmatic_tool_calling"},
{
"type": "mcp",
"server_label": "openai_docs",
"transport": {
"type": "http",
"server_url": "https://developers.openai.com/mcp",
},
},
{"type": "web_search"},
],
"multi_agent": {"enabled": True, "max_concurrent_subagents": 4},
},
environment={
"type": "self_hosted",
"workspace_directory": "/workspace",
"capability_directories": ["/workspace/capabilities/skills"],
},
input=[
{
"role": "user",
"content": [
{
"type": "input_text",
"text": "Research how to connect an MCP server to an OpenAI agent, check for recent updates, and summarize the recommended setup.",
}
],
}
],
)
print(session.id)Einen Vergleich der Laufzeitumgebungen findest du in der Übersicht zu Agenten.
Informationen zum AWS-Dienst, der auf der Agents API basiert, findest du unter Bedrock Managed Agents.
Die Agents API speichert den Sitzungszustand. So kannst du die Arbeit über mehrere Durchläufe hinweg fortsetzen, ohne den Gesprächskontext neu aufzubauen. Sitzungen und veröffentlichte Artefakte kannst du löschen, sobald du sie nicht mehr benötigst. Die Agents API unterstützt Datenresidenz derzeit nur in den USA. Die Option „Keine Datenaufbewahrung“ (ZDR) unterstützt sie nicht. Auch mit einer selbst gehosteten Sandbox kannst du ZDR für die Agents API nicht nutzen. Weitere Informationen zu Datenresidenz und Datenaufbewahrung findest du unter Datenkontrollen auf der OpenAI-Plattform.