Emre Demir

Posted on Oct 2 Originally published at apidog.com

Wie verwendet man die OpenAI Agents API?

#openai #ai #api #agents

Die OpenAI Agents API führt das Open-Source-Codex-Harness von OpenAI 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 Modell und Tool-Schleife aus, behält die Sitzung bei und kann eine Sandbox bereitstellen. Für die Agents API selbst fällt keine Gebühr an: Sie bezahlen für Tokens, Tools und die Zeit gehosteter 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; am 29. September fügte OpenAI auf dem DevDay die Computernutzung hinzu.

Teste Apidog noch heute

In diesem Beitrag erstellen Sie eine erste REST-Sitzung, verarbeiten Fortschrittsereignisse, binden MCP-Tools und Sub-Agents ein und implementieren den Genehmigungsablauf für die Computernutzung. Die Unterschiede zu anderen OpenAI-Agent-Schnittstellen beschreibt Agents API vs. Responses API vs. Agents SDK; den restlichen Event-Kontext finden Sie im DevDay-2026-Rückblick. Da jeder Aufruf reines HTTP ist, können Sie ihn vor dem Anwendungscode direkt mit Apidog testen.

Die OpenAI Agents API auf einen Blick

Element	Wert
Status	Öffentliche Beta seit 10. September 2026; Computernutzung hinzugefügt am 29. September
Sitzung erstellen	`POST /v1/agents/sessions`
Beta-Header	`OpenAI-Beta: agents=v1` — die OpenAI SDKs setzen ihn automatisch
Schlüsselberechtigungen	`api.agents.read`, `api.agents.write`, `api.responses.write`
Preise	Keine Agents-API-Gebühr; Modell-Tokens zu API-Preisen, Tools zu Standardpreisen, Websuche: 10 $ pro 1.000 Aufrufe
Gehostete Container	0,03 $ (`small`, 1 GB), 0,12 $ (`medium`, 4 GB), 0,48 $ (`large`, 16 GB) pro 20-minütiger Sitzung
Umgebungen	`none`, `openai_hosted`, `self_hosted`
Modell in den Dokumentationsbeispielen	`gpt-6-astra`
Datenkontrollen	Nur Datenresidenz in den USA; keine Zero Data Retention (ZDR)
Maximale Anforderungsgröße	4 MiB

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

Die vier Konzepte

Die API basiert auf vier Bausteinen:

Agent: Modell, Anweisungen, Tools und MCP-Server. Sie können den Agent inline senden oder speichern und über seine agent_id wiederverwenden.
Umgebung: Optionale Sandbox oder Computer, auf dem der Agent Dateien liest und Befehle ausführt.
Sitzung: Dauerhafte Agent-Instanz, die Konfiguration, Konversation und gespeicherte Arbeit behält.
Ereignisse und Elemente: Ereignisse liefern Live-Fortschritt; Elemente speichern Nachrichten und Tool-Aufrufe.

Eine Nachricht an eine inaktive Sitzung startet einen neuen Zug. Eine Nachricht während eines laufenden Zuges steuert diesen. Das Harness — die gehostete Codex-Instanz, die Modell und Tool-Schleife ausführt — übernimmt außerdem die Kontextkompaktierung. Details dazu finden Sie auf der Architekturseite.

Wählen Sie eine Umgebung

Mit environment.type legen Sie fest, 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 jedoch 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). Konfigurieren Sie network.access als enabled, disabled oder restricted mit allowed_domains. Dateien unter /workspace/outputs werden beim Abschluss eines Zuges zu Artefakten. 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 in einer Remote-Sandbox aus. Der Server verbindet sich ausgehend mit einem separaten Umgebungsschlüssel.

Der Launch-Post nennt Blaxel, Cloudflare, Daytona, DigitalOcean, E2B, Modal, Oracle, Runloop und Vercel als Sandbox-Partner. Der Leitfaden für selbst gehostete Umgebungen ergänzt AWS Lambda MicroVMs.

Ihre erste Sitzung über REST

Exportieren Sie einen API-Schlüssel mit den erforderlichen Berechtigungen als OPENAI_API_KEY. Erstellen Sie dann eine gestreamte Sitzung mit einer kleinen Sandbox:

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 erhalten Sie den Ereignisstrom des ersten Zuges. Speichern Sie die Sitzungs-ID aus der Antwort, denn der restliche Lebenszyklus verwendet dieselbe Ressource:

Aktion	Anfrage
Nachfassen oder steuern	`POST /v1/agents/sessions/{id}/events` mit einem `agent.session.input.message`-Ereignis
Aktuellen Zug abbrechen	Gleicher Endpunkt mit Ereignistyp `agent.session.input.cancel`
Gespeicherte Arbeit lesen	`GET /v1/agents/sessions/{id}/items?order=asc&limit=100`
Aufräumen	`DELETE /v1/agents/sessions/{id}`

Das JavaScript SDK folgt derselben Struktur. Dieses Beispiel fügt Websuche, 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 den Stream vor dem Senden einer Eingabe, damit keine frühen Ereignisse verloren gehen:

GET /v1/agents/sessions/{id}/events?stream=true
Accept: text/event-stream

Verarbeiten Sie mindestens diese Ereignisse:

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

Beachten Sie drei wichtige Details:

agent.session.idle bedeutet nicht automatisch, dass der Zug erfolgreich war.
Ein abgeschlossener Zug kann fehlgeschlagene Tool-Aufrufe enthalten.
Das Schließen des Streams beendet die Aufgabe nicht.

Streams spielen verpasste Ereignisse nicht erneut ab. Öffnen Sie nach einer Unterbrechung daher einen neuen Stream und lesen Sie zusätzlich Sitzung und Elemente ab.

Webhooks

Abonnieren Sie diese Webhook-Ereignisse:

agent.session.created
agent.session.action_required
agent.session.in_progress
agent.session.idle
agent.session.failed

Achten Sie auf die unterschiedliche Benennung: Im Stream heißt das Ereignis requires_action, beim Webhook action_required. Webhook-Payloads enthalten keine vollständigen Aufrufdetails. Ihr Handler muss deshalb die Sitzung abrufen und required_actions auswerten.

Verifizieren Sie jede Signatur. Der Beitrag zur Webhook-Signaturverifizierung zeigt den Ablauf. Für Aufgaben mit mehreren Minuten Laufzeit sind Webhooks besonders geeignet; siehe auch langlaufende API-Operationen.

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

MCP-Server verbinden

Fügen Sie einen MCP-Server in agent.tools ein:

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

Standardmäßig baut OpenAI die Verbindung auf (connection_origin: "service"). Der MCP-Server muss dann aus der OpenAI-Infrastruktur erreichbar sein.

Verwenden Sie alternativ:

connection_origin: "environment" für einen Server in Ihrem privaten Netzwerk
stdio, um einen Server innerhalb der Sandbox zu starten
transport.authorization für sitzungsbezogene Zugangsdaten
vault_ids für Vault-Anmeldeinformationen wie static_bearer oder mcp_oauth

Tool-Suche aktivieren

MCP-Tools werden automatisch erkannt, wenn das Modell Tool-Suche unterstützt. Bei vielen Funktions-Tools fügen Sie das Tool tool_search hinzu und markieren Funktionen mit defer_loading: true:

{
  "type": "tool_search"
}

Programmatische Tool-Aufrufe

Standardmäßig erhält der Agent ein exec-Tool. Es führt JavaScript in einer isolierten V8-Laufzeit aus. Damit kann der Agent Tool-Aufrufe durchlaufen und große Ergebnisse kürzen, bevor sie in den Modellkontext gelangen.

Deaktivieren Sie dieses Verhalten bei Bedarf:

{
  "type": "programmatic_tool_calling",
  "enabled": false
}

Sub-Agents konfigurieren

Aktivieren Sie Sub-Agents über multi_agent:

{
  "multi_agent": {
    "enabled": true,
    "max_concurrent_subagents": 3
  }
}

Das Standardlimit beträgt 6 parallele Sub-Agents. Sie teilen sich das Dateisystem der Umgebung und erben MCP-Tools sowie Websuche. Funktions-Tools können sie jedoch nicht verwenden. Für den Haupt-Agenten ist subagent_id eines Zuges null.

Computernutzung: die DevDay-Ergänzung

Die Computernutzung stellt dem Agenten einen gehosteten Browser bereit. Fügen Sie dazu 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 eine Nutzergenehmigung, bevor er jede neue Website-Herkunft besucht — auch öffentliche Seiten. Bei agent.session.requires_action rufen Sie die Sitzung ab und suchen nach computer_use_approval_request.

Der verschachtelte request.type ist einer von zwei Typen:

browser_origin_access: Zeigen Sie origin und reason an. Senden Sie anschließend approve, deny oder cancel.
browser_authentication: Das Formular enthält fields, optionale Anmelde-options und eine credential_origin. Senden Sie action: "submit" mit den Nutzerwerten oder action: "cancel".

Senden Sie Genehmigungsantworten ü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. Wenn include_screenshots aktiviert ist und ein Screenshot verfügbar ist, enthält output einen base64-codierten JPEG-Screenshot.

Speichern Sie Screenshots nicht ungeschützt in Logs: Sie können Kontodaten enthalten.

Der Leitfaden zur Computernutzung nennt folgende Einschränkungen:

Die Ursprungsfreigabe ist keine Handlungsbestätigung. Das Genehmigen einer Website bedeutet nicht, dass der Agent vor jedem Kauf oder jeder Löschung nachfragt. Begrenzen Sie den Browser auf sichere Ressourcen oder verwenden Sie eine selbst kontrollierte Browser-Laufzeit.
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 Anmeldeinformationen: maxRetries: 0 im SDK oder --retry 0 mit curl.
Ein 202 bedeutet nur „akzeptiert“. Es bestätigt nicht, dass Navigation oder Anmeldung erfolgreich waren. Authentifizierungsanfragen laufen nach fünf Minuten ab.
Ursprungsfreigabe überschreibt keine Netzwerkrichtlinie. Erlauben Sie die Zielseite und Weiterleitungsdomänen zusätzlich in network.

Die Computernutzung wird laut Zusammenfassung „über die API sowie in Codex und ChatGPT Work auf Pro 500 und Enterprise“ bereitgestellt. Für UI-gesteuerte Tests 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 ein Fallback für Software ohne API. Wenn Sie das Zielsystem kontrollieren, kapseln Sie es stattdessen als MCP-Server:

Definieren Sie typisierte Tools.
Vermeiden Sie Ursprungsfreigaben.
Liefern Sie überprüfbare Ergebnisse.
Begrenzen Sie Berechtigungen auf die tatsächlich nötigen Aktionen.

Der Beitrag Computernutzung vs. strukturierte APIs erläutert diesen Kompromiss. Der Apidog MCP Server kann Ihre API-Spezifikation an einen Code-Assistenten liefern, der den Wrapper erstellt.

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

Da die API noch in der Beta-Phase ist, sollten Sie die Form jedes Requests zunächst manuell in Apidog prüfen:

Erstellen Sie eine Apidog-Umgebung mit OPENAI_API_KEY, VAULT_ID und SESSION_ID. Senden Sie bei jeder Anfrage Bearer {{OPENAI_API_KEY}} und OpenAI-Beta: agents=v1.
Senden Sie die Create-Session-Anfrage zunächst ohne stream. Prüfen Sie auf einen 2xx-Status und eine nicht leere id. Speichern Sie die id in SESSION_ID.
Öffnen Sie den Ereignisstrom als SSE-Anfrage. Senden Sie die Eingabe über eine zweite Anfrage und beobachten Sie die eintreffenden Ereignisse.
Speichern Sie Genehmigungs- und Abbruch-Payloads als wiederverwendbare Anfragen, damit Sie jeden required_actions-Fall reproduzieren können.
Verketten Sie die Requests 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 loszulegen.

FAQ

Ist die OpenAI Agents API kostenlos?

Es gibt keine Plattformgebühr. Sie zahlen jedoch für Modell-Tokens, Tool-Aufrufe und die Laufzeit gehosteter Container.

Welche Modelle funktionieren mit der Agents API?

Die Dokumentationsbeispiele, einschließlich aller Beispiele zur Computernutzung, verwenden gpt-6-astra. Die Seiten nennen keine weiteren unterstützten Modelle. Testen Sie daher Ihr Zielmodell vor dem produktiven Einsatz.

Unterstützt die Agents API Zero Data Retention?

Nein. Sie unterstützt nur Datenresidenz in den USA und ist nicht ZDR-berechtigt — auch nicht mit einer selbst gehosteten Sandbox.

Wie unterscheidet sie sich vom Agents SDK oder der Responses API?

Das SDK führt die Schleife in Ihrer Anwendung aus. Die Responses API ist der Modellaufruf, um den Sie selbst eine Schleife bauen. Details finden Sie im vollständigen Vergleich.

Beginnen Sie mit einer schreibgeschützten Sitzung

Starten Sie mit einem sicheren Minimal-Setup:

Erstellen Sie eine Sitzung mit ausschließlich lesenden Aufgaben.
Binden Sie einen MCP-Server mit minimalen Berechtigungen ein.
Ergänzen Sie Computernutzung erst danach.
Implementieren Sie einen Genehmigungs-Handler, der standardmäßig ablehnt.
Aktivieren Sie Schreibzugriffe nur für klar abgegrenzte und überprüfbare Workflows.

Wenn ChatGPT stattdessen auf Ereignisse Ihres eigenen Servers reagieren soll, ist MCP Events der passende Baustein.

DEV Community