Wie verwendet man die OpenAI Agents API?

Die OpenAI Agents API führt OpenAI’s Open-Source-Codex-Harness für Sie aus. Sie senden POST https://api.openai.com/v1/agents/sessions mit dem Header OpenAI-Beta: agents=v1, einer Agent-Definition und einer Aufgabe; OpenAI führt das Modell und die Tool-Schleife aus, behält die Sitzung bei und kann eine Sandbox bereitstellen. Es gibt keine Gebühr für die Agents API: Sie bezahlen für Tokens, Tools und die Zeit der gehosteten Container (0,03 bis 0,48 US-Dollar pro 20-minütiger Sitzung für Sandbox-Größen von 1 GB bis 16 GB). Sie wurde am 10. September 2026 als öffentliche Beta eingeführt, und OpenAI fügte am 29. September auf dem DevDay die Computernutzung hinzu.

Unten: eine erste REST-Sitzung, Fortschrittsereignisse, MCP-Tools, Sub-Agents und der Genehmigungsablauf für die Computernutzung. Wie sie sich von anderen Agent-Schnittstellen von OpenAI unterscheidet, lesen Sie unter Agents API vs. Responses API vs. Agents SDK; für den Rest des Events, siehe den DevDay 2026 Rückblick. Jeder Aufruf ist reines HTTP, sodass Sie ihn von Apidog senden können, bevor Sie Anwendungscode schreiben.

Die OpenAI Agents API auf einen Blick

Quellen: Einführung der Agents API, die Agents API Übersicht und die Preisseite.

Die vier Konzepte

Die Dokumentation baut die API um vier Konzepte auf:

• Agent: das Modell, Anweisungen, Tools und MCP-Server. Übergeben Sie ihn inline, oder speichern Sie ihn und verwenden Sie seine agent_id wieder.
• Umgebung: eine optionale Sandbox oder ein Computer, auf dem der Agent Dateien liest und Befehle ausführt.
• Sitzung: eine dauerhafte Instanz des Agents, die Konfiguration, Konversation und gespeicherte Arbeit beibehält.
• Ereignisse und Elemente: Ereignisse berichten live über den Fortschritt; Elemente sind die gespeicherten Nachrichten und Tool-Aufrufe.

Eine an eine inaktive Sitzung gesendete Nachricht startet einen neuen Zug; eine während eines Zuges gesendete Nachricht steuert diesen. Das Harness (gemäß der Architekturseite, die gehostete Codex-Instanz, die das Modell und die Tool-Schleife ausführt) handhabt auch die Kontextkompaktierung, sodass Sie diese nicht konfigurieren müssen.

Wählen Sie eine Umgebung

environment.type entscheidet, wo Befehle ausgeführt werden:

• none: keine Berechnung. Remote MCP-Server und Ihre Funktions-Tools funktionieren weiterhin; integriertes Bash, Apply-Patch, Workspace-Dateien und Executor-MCPs nicht.
• openai_hosted: OpenAI verwaltet eine Linux-Sandbox mit Python und Node.js in /workspace. Setzen Sie container_size auf small (1 GB), medium (Standard, 4 GB) oder large (16 GB) und network.access auf enabled, disabled oder restricted mit allowed_domains. Dateien in /workspace/outputs werden zu Artefakten, wenn ein Zug abgeschlossen ist. Eine inaktive Sandbox ohne Keep-Alives kann nach einer Stunde gelöscht werden.
• self_hosted: Ihre Infrastruktur. Sie führen codex exec-server auf einem Laptop, in einem Container oder einer Remote-Sandbox aus, und dieser verbindet sich ausgehend mit einem separaten Umgebungsschlüssel.

Der Launch-Post listet die Sandbox-Partner Blaxel, Cloudflare, Daytona, DigitalOcean, E2B, Modal, Oracle, Runloop und Vercel auf; der Leitfaden für selbst gehostete Umgebungen fügt AWS Lambda MicroVMs hinzu.

Ihre erste Sitzung über REST

Exportieren Sie einen Schlüssel mit den oben genannten Berechtigungen als OPENAI_API_KEY, dann senden Sie die Quickstart-Aufgabe mit einem kleinen Container:

curl --no-buffer https://api.openai.com/v1/agents/sessions \
  -H "OpenAI-Beta: agents=v1" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": {
      "model": "gpt-6-astra",
      "instructions": "Write clean code, run it, and report the actual output."
    },
    "environment": { "type": "openai_hosted", "container_size": "small" },
    "input": "Create tree.py, a script that prints a tree of the files in the current directory. Run it and show the output.",
    "stream": true
  }'

Mit stream: true ist die Antwort der Ereignisstrom des ersten Zuges. Speichern Sie die Sitzungs-ID daraus; der Rest des Lebenszyklus verwendet dieselbe Ressource:

Das JavaScript SDK hat die gleiche Form. Diese Version, angepasst vom Launch-Post, fügt ein Tool, Sub-Agents und einen Vault hinzu:

import OpenAI from "openai";

const client = new OpenAI();
const session = await client.beta.agents.sessions.create({
  agent: {
    model: "gpt-6-astra",
    tools: [{ type: "web_search" }],
    multi_agent: { enabled: true, max_concurrent_subagents: 3 },
  },
  vault_ids: [process.env.VAULT_ID],
  environment: { type: "openai_hosted" },
  input: "Summarize breaking changes in the latest release notes.",
});
console.log(session.id);

Fortschritt verfolgen: Stream oder Webhooks

Streaming. Öffnen Sie GET /v1/agents/sessions/{id}/events?stream=true mit Accept: text/event-stream, bevor Sie Eingaben senden, um keine frühen Ereignisse zu verpassen. Achten Sie auf:

• agent.session.turn.output_text.delta und agent.session.turn.output_text.done für Text
• agent.session.turn.completed, agent.session.turn.failed oder agent.session.turn.cancelled für das Ergebnis
• agent.session.requires_action, wenn der Agent ein Funktionsergebnis, eine Umgebungskonnektion oder eine Genehmigung zur Computernutzung benötigt

Drei Fallstricke: agent.session.idle bedeutet nicht, dass der Zug erfolgreich war, ein abgeschlossener Zug kann fehlgeschlagene Tool-Aufrufe enthalten, und das Schließen des Streams stoppt die Aufgabe nicht. Streams spielen verpasste Ereignisse nicht erneut ab, daher öffnen Sie nach einer Trennung einen neuen Stream und rufen die Sitzung und ihre Elemente ab.

Webhooks. Abonnieren Sie agent.session.created, agent.session.action_required, agent.session.in_progress, agent.session.idle und agent.session.failed. Beachten Sie die Benennung: der Stream sagt requires_action, der Webhook sagt action_required. Payloads lassen Aufrufdetails weg, daher ruft Ihr Handler die Sitzung ab und liest required_actions. Verifizieren Sie jede Signatur (Webhooks-Signaturverifizierung); langlaufende API-Operationen erklärt, warum Webhooks für Aufgaben von mehreren Minuten geeignet sind.

MCP-Tools, Tool-Suche, programmatische Tool-Aufrufe und Sub-Agents

MCP. Fügen Sie einen Server zu agent.tools hinzu:

{
  "type": "mcp",
  "server_label": "openai_docs",
  "transport": { "type": "http", "server_url": "https://developers.openai.com/mcp" },
  "required": true
}

Standardmäßig stellt OpenAI die Verbindung her (connection_origin: "service"), daher muss der Server von OpenAI aus erreichbar sein. Verwenden Sie connection_origin: "environment" für einen Server im privaten Netzwerk oder stdio, um einen in der Sandbox zu starten. Für Anmeldeinformationen übergeben Sie transport.authorization für eine Sitzung oder hängen Sie eine Vault-Anmeldeinformation (static_bearer oder mcp_oauth) mit vault_ids an.

Tool-Suche. MCP-Tools werden automatisch erkannt, wenn das Modell die Tool-Suche unterstützt. Für viele Funktions-Tools fügen Sie {"type": "tool_search"} hinzu und markieren Funktionen mit defer_loading: true.

Programmatische Tool-Aufrufe. Standardmäßig aktiviert: Der Agent erhält ein exec-Tool, das JavaScript in einer isolierten V8-Laufzeitumgebung ausführt, sodass es Tool-Aufrufe durchlaufen und große Ergebnisse kürzen kann, bevor sie den Kontext erreichen. Deaktivieren Sie es mit {"type": "programmatic_tool_calling", "enabled": false}.

Sub-Agents. Setzen Sie multi_agent: {"enabled": true, "max_concurrent_subagents": 3} (das Standardlimit ist 6). Sub-Agents teilen sich das Dateisystem der Umgebung und erben MCP-Tools und Web-Suche, können aber keine Funktions-Tools verwenden. Die subagent_id eines Zuges ist null für den Haupt-Agenten.

Computernutzung: die DevDay-Ergänzung

Die Computernutzung gibt dem Agenten einen gehosteten Browser. Fügen Sie das Tool und einen Desktop zu einer gehosteten Umgebung hinzu:

{
  "agent": {
    "model": "gpt-6-astra",
    "tools": [{ "type": "computer_use", "include_screenshots": true }]
  },
  "environment": {
    "type": "openai_hosted",
    "desktop": { "enabled": true },
    "network": { "access": "enabled" }
  }
}

Der Browser benötigt die Genehmigung des Benutzers, bevor er jede neue Website-Herkunft besucht, einschließlich öffentlicher Seiten. Bei agent.session.requires_action rufen Sie die Sitzung ab und finden Einträge für computer_use_approval_request. Der verschachtelte request.type ist einer von zwei Typen:

• browser_origin_access: Zeigen Sie origin und reason an und senden Sie dann approve, deny oder cancel.
• browser_authentication: ein Anmeldeformular mit fields, optionalen Anmelde-options und einer credential_origin. Senden Sie action: "submit" mit den Werten des Benutzers oder action: "cancel".

Beide Antworten gehen über den Events-Endpunkt zurück:

curl "https://api.openai.com/v1/agents/sessions/$SESSION_ID/events" \
  -H "OpenAI-Beta: agents=v1" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"events": [{
    "type": "agent.session.input.computer_use_approval_request_result",
    "request_id": "REQUEST_ID",
    "response": { "type": "browser_origin_access", "decision": "approve" }
  }]}'

Browser-Arbeit erscheint als computer_use_call-Elemente mit id, turn_id, title, status und output, das einen base64 JPEG-Screenshot enthält, wenn include_screenshots aktiviert ist und einer verfügbar ist. Halten Sie Screenshots aus Protokollen fern; sie können Kontodaten anzeigen.

Der Leitfaden zur Computernutzung weist auf folgende Vorbehalte hin:

• Die Ursprungsfreigabe ist keine Handlungsbestätigung. Die Genehmigung einer Website bewirkt nicht, dass der Agent vor jedem Kauf oder jeder Löschung nachfragt. Wenn Sie dies benötigen, beschränken Sie den Browser auf Ressourcen, die solche Aktionen nicht ausführen können, oder verwenden Sie eine von Ihnen kontrollierte Browser-Laufzeitumgebung.
• Die Anmeldung umfasst E-Mail, Passwörter und Verifizierungscodes. Passkeys und QR-Code-Anmeldungen werden nicht unterstützt.
• Nur der Haupt-Agent kann eine Authentifizierung anfordern. Sub-Agents können dies nicht.
• Deaktivieren Sie automatische Wiederholungsversuche bei der Übermittlung von Anmeldeinformationen (maxRetries: 0 im SDK, --retry 0 in curl).
• Ein 202 bedeutet akzeptiert, nicht dass die Navigation oder Anmeldung erfolgreich war. Authentifizierungsanfragen verfallen nach fünf Minuten.
• Die Ursprungsfreigabe überschreibt die Netzwerkrichtlinie nicht. Erlauben Sie die Website und ihre Weiterleitungsdomänen auch im network.

Die Zusammenfassung besagt, dass die Computernutzung „über die API sowie in Codex und ChatGPT Work auf Pro 500 und Enterprise“ bereitgestellt wird. Für UI-gesteuertes Testen mit demselben Modell, siehe GPT-6 Astra Computernutzung für API-Tests.

Geben Sie dem Agenten Ihre API, nicht Ihre Benutzeroberfläche

Ein Browser ist der Fallback für Software ohne API. Wenn das System Ihnen gehört, verpacken Sie es in einem MCP-Server: typisierte Tools, keine Ursprungsaufforderungen, überprüfbare Ergebnisse. Computernutzung vs. strukturierte APIs behandelt den Kompromiss, und der Apidog MCP Server speist Ihre API-Spezifikation an den Code-Assistenten, der den Wrapper schreibt.

Testen Sie die Agents API in Apidog, bevor Sie Code schreiben

Die API ist in der Beta-Phase, daher bestätigen Sie die Form jedes Aufrufs zuerst manuell in Apidog:

1. Erstellen Sie eine Apidog-Umgebung mit OPENAI_API_KEY, VAULT_ID und SESSION_ID. Senden Sie Bearer {{OPENAI_API_KEY}} und OpenAI-Beta: agents=v1 bei jeder Anfrage.
2. Senden Sie die create-session-Anfrage ohne stream, bestätigen Sie einen 2xx-Status und eine nicht leere id, und extrahieren Sie id in SESSION_ID.
3. Öffnen Sie den Ereignisstrom als SSE-Anfrage, senden Sie die Eingabe von einer zweiten Anfrage und beobachten Sie, wie Ereignisse eintreffen.
4. Speichern Sie die Genehmigungs- und Abbruch-Payloads als Anfragen, um jeden required_actions-Fall wiederzugeben.
5. Verketten Sie sie zu einem Testszenario und führen Sie es in CI mit der Apidog CLI aus.

Der Leitfaden zum Testen der KI-Agenten-API enthält Assertionsmuster für nicht-deterministische Ausgaben. Laden Sie Apidog herunter, um mitzumachen.

FAQ

Ist die OpenAI Agents API kostenlos? Es gibt keine Plattformgebühr, aber Sie zahlen für Modell-Tokens, Tool-Aufrufe und gehostete Container-Zeit.

Welche Modelle funktionieren mit der Agents API? Die Beispiele der Dokumentation, einschließlich jedes Beispiels zur Computernutzung, verwenden gpt-6-astra. Die Seiten listen keine anderen unterstützten Modelle auf, daher testen Sie Ihre zuerst.

Unterstützt die Agents API Zero Data Retention? Nein. Sie unterstützt nur die Datenresidenz in den USA und ist nicht ZDR-berechtigt, selbst mit einer selbst gehosteten Sandbox.

Wie unterscheidet sie sich vom Agents SDK oder der Responses API? Das SDK führt die Schleife innerhalb Ihrer App aus; die Responses API ist der Modellaufruf, um den Sie eine Schleife bauen. Siehe den vollständigen Vergleich.

Beginnen Sie mit einer schreibgeschützten Sitzung

Beginnen Sie mit einer Sitzung, die nur liest, fügen Sie einen MCP-Server hinzu, und fügen Sie dann die Computernutzung hinter einem Genehmigungs-Handler hinzu, der standardmäßig ablehnt. Wenn ChatGPT stattdessen auf Ereignisse von Ihrem eigenen Server reagieren soll, ist MCP Events das passende Stück.