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

Agents API

Entwickle Cloud-Agenten, die mit einem verwalteten Codex-Harness ihre Arbeit fortsetzen können.

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:

Sieh dir auch diese vollständigen Anwendungen an:

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:

  1. Erstelle eine Sitzung. Konfiguriere den Agenten. OpenAI stellt seine Umgebung bereit.
  2. Gib dem Agenten eine Aufgabe. Sobald die Umgebung bereit ist, startet deine Eingabe einen Arbeitsdurchlauf.
  3. Verfolge den Fortschritt. Empfange die Ausgabe als Stream oder nutze Webhooks, um zu erfahren, wann der Agent fertig ist oder eine Eingabe benötigt.
  4. 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.

Deine Anwendung startet Sitzungen und empfängt Ereignisse und Ausgaben von der Agents API. OpenAI betreibt den verwalteten Codex-Harness, stellt seine Sandbox bereit und verwaltet sie.

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:

Funktionen des verwalteten Harness konfigurieren
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.