AI-Entwicklung

Wie hält die OpenAI Agents API lang laufende AI-Agenten am Leben? Context, Tools, Subagents und JSON-Zustand (2026)

Ca. 16 Min.

Die öffentliche Beta am 10. September war kein „weiterer Chat“. OpenAI lieferte das Harness, das Codex schon Tage laufen ließ: die Session bleibt, der Kontext wird verdichtet, jeder Subagent hat sein eigenes Fenster. Dieser Text gilt nur dem Überleben eines langen Auftrags: welches JSON Sie speichern, was OpenAI komprimiert, welche Items Sie nach einem Abbruch lesen.

Bevor Sie lesen

Objekt Was es tut Was Sie halten
Session Dauerhafte Instanz über Stunden und Fenster session_id
Turn Asynchrone Arbeit nach einem Input turn_id / Endereignisse
Items Gespeicherte Nachrichten und Tool-Aufrufe Wiedergabe nach Abbruch
Compact Automatische Kompression nahe dem Limit Schlüsselfelder selbst halten
Subagent Eigener Kontext, parallele Arbeit Nebenläufigkeitsgrenze

Eine idle Session ist kein Erfolg. Lesen Sie Turn-Ereignisse und Items, nicht den letzten Satz.

Ein langer Auftrag lebt in einer Session, nicht in einem längeren Prompt

Die Antwort der Agents API ist konkret: eine dauerhafte Session anlegen und spätere Eingaben an dieselbe session_id schicken. Nahe dem Kontextlimit verdichtet das Harness frühere Arbeit. Unabhängige Teilaufgaben können an einen Subagent. Sie bauen das Chat-Protokoll nicht neu.

  • Fortsetzen: session_id an Ihr Gespräch binden. Keine zweite Session für denselben Fall.
  • Abbruch: Streams wiederholen nichts. Session und Items holen. Nicht annehmen, der Client kenne den letzten Sprung.
  • Geld und IDs: Compact verwirft Details. Bestellnummern, Beträge, Freigaben ins eigene JSON.

Wie Session auf Tool-JSON trifft: OpenAI-Agents-API-Rundgang. Wer die Schleife besitzen soll: Agents API vs. Responses API. Sind Agent und Function Calling noch ein Wort, zuerst AI-Agent, vollständiger Leitfaden.

Die Session bleibt; ein Turn läuft asynchron

Einmal anlegen: Modell, Tools, Umgebung, multi_agent. Offiziell: POST /v1/agents/sessions mit OpenAI-Beta: agents=v1. Gehostete Sandbox: openai_hosted:

{
  "agent": {
    "model": "gpt-6-astra",
    "instructions": "Look up orders. Confirm before any refund. Delegate independent lookups to subagents.",
    "tools": [
      {
        "type": "function",
        "name": "lookup_order",
        "parameters": {
          "type": "object",
          "properties": {
            "order_id": { "type": "string", "pattern": "^[A-Z]-\\d{4}$" }
          },
          "required": ["order_id"],
          "additionalProperties": false
        }
      },
      { "type": "web_search" }
    ],
    "multi_agent": { "enabled": true, "max_concurrent_subagents": 3 }
  },
  "environment": { "type": "openai_hosted", "workspace_directory": "/workspace" },
  "input": [
    {
      "role": "user",
      "content": [{ "type": "input_text", "text": "Look up A-1042 and keep the case open." }]
    }
  ]
}

Ein weiteres agent.session.input.message an dieselbe Session. Idle startet einen neuen Turn; aktiv lenkt den laufenden. Abbrechen mit agent.session.input.cancel — Session und gespeicherte Arbeit bleiben:

{
  "events": [
    {
      "type": "agent.session.input.message",
      "input": [
        {
          "role": "user",
          "content": [
            { "type": "input_text", "text": "Warehouse marked A-1042 packed. Continue." }
          ]
        }
      ]
    }
  ]
}

Das Ergebnis lesen, nicht „ist sie idle“. Offizielle Ereignisse: agent.session.turn.completed, failed, cancelled. Ein abgeschlossener Turn heißt nicht, jedes Tool sei gelungen. Braucht es ein Funktionsergebnis, required_actions prüfen.

Die Tool-Kette dauert Stunden; der Rückschreib bleibt JSON

Beim langen Auftrag füllt das Modell weiter nur Argumente. Ist Ihre Funktion fällig, hält das Harness an; Sie liefern das Ergebnis mit turn_id / call_id. Vier Stunden später dieselbe Form:

{
  "type": "tool_result",
  "turn_id": "turn_4",
  "call_id": "call_3c91",
  "success": true,
  "output": "{\"order_id\":\"A-1042\",\"status\":\"packed\"}"
}

Funktionen brauchen Sie. MCP und web_search kann das Harness selbst. Subagents erben MCP und Websuche; sie erben keine Function-Tools. Nebenwirkungen an Ihren Bestellungen bleiben beim Hauptagenten.

Das Tor bleibt Schema. Ein weites object ist auf langen Läufen gefährlicher: nach Compact erfindet das Modell eher eine ID. MCP ist eine weitere Tool-Tabelle; die Grenze steht bei MCP Tool Schema vs. Function Calling.

Compact verkleinert das Fenster, nicht Ihr Hauptbuch

Offiziell: nähert sich eine Session dem Limit, verdichtet die Agents API früheren Kontext, damit Arbeit Fenster überspannt. Sie schreiben diesen Verdichter nicht. Das ist nicht die Schicht context_management / /responses/compact von Responses.

  • Agents API: die Session verdichtet sich selbst. Items holen und prüfen, ob die Bestellnummer noch da ist.
  • Responses: Compact selbst einschalten oder den Compact-Endpunkt rufen. Das verschlüsselte Compaction-Item weiterreichen, nicht von Hand kürzen.
  • Beide: Kompression streicht Details. Beträge, Bestätigungen, Freigaben schreibt der Host.

Lebt order_id nur im Chat, haben Sie das Hauptbuch einer Zusammenfassung übergeben. Schema als Tor: Warum AI JSON Schema braucht.

Subagents: parallel, mit getrenntem Kontext

Mit multi_agent.enabled liefert das Harness Create, Message, Wait und Interrupt. Diese Tools deklarieren Sie nicht. Koordination erscheint als Items:

{
  "data": [
    {
      "type": "function_call",
      "turn_id": "turn_4",
      "call_id": "call_3c91",
      "name": "lookup_order",
      "arguments": "{\"order_id\":\"A-1042\"}"
    },
    {
      "type": "create_subagent_call",
      "agent_id": "agent_main",
      "task": "Compare A-1042 packing notes with the invoice."
    }
  ]
}
  • Eigener Kontext: jeder Subagent hat einen. Der Hauptagent schließt mit create / message / wait / interrupt.
  • Nebenläufigkeit deckeln: Standard ist 6, ohne Koordinator. In Produktion eine kleinere Zahl festschreiben.
  • Ein fertiges Item ≠ fertige Teilaufgabe: ein abgeschlossenes create_subagent_call heißt nur: gesendet. agent.session.subagent.created und die Items dieses Subagenten lesen.

Ein Handoff soll prüfbares JSON sein, kein „bitte an die Buchhaltung“. Als Schema einfangen: JSON Schema und Agent-Workflows.

Halten Sie Ihren Zustand; Compact soll ihn nicht merken

OpenAI behält Session-Konfiguration, Gespräch und gespeicherte Arbeit. Sie brauchen trotzdem ein Geschäftsobjekt, das nach einem Abbruch wiedersteht:

{
  "session_id": "sess_8f21",
  "order_id": "A-1042",
  "last_turn_id": "turn_4",
  "last_call_id": "call_3c91",
  "awaiting": "tool_result",
  "compact_checkpoint": "after_turn_3"
}

Dieses Objekt ist keine Session, keine SDK-Session, keine Responses-Conversation und keine Sandbox. Eines löschen räumt die anderen nicht. Datenresidenz ist vorerst nur die USA; eine selbst gehostete Sandbox macht die API nicht ZDR-fähig.

Fünf Schritte für einen Auftrag über Fenster hinweg

Kein Demovideo rückwärts lesen. Die Objekte gehen:

  1. Eine Session anlegen und session_id ins Gespräch schreiben. Tool-Tabelle und Schema einmal festziehen.
  2. Abonnieren, dann später senden. Den Stream öffnen, bevor agent.session.input.message kommt, sonst fehlen frühe Ereignisse.
  3. Bei required_actions zurückschreiben. Dieselbe turn_id / call_id. Keine neue Session zum Wiederholen.
  4. Nach Abbruch Items listen. Streams wiederholen nichts. order=asc und Bestellnummer sowie offene Calls abgleichen.
  5. Nach Compact das Hauptbuch erneut prüfen. Fehlt A-1042 in der Zusammenfassung, erfindet der nächste Sprung eine Nummer.

Alle fünf sitzen auf Objekten. Einen auslassen heißt, gegen ein noch leeres Fenster wetten.

Einen langen Auftrag prüfen: zwei JSON-Spuren ausbreiten

Die meisten Fehler sind falsch zugeordnete Objekte, kein dümmeres Modell.

  • Session-Items und lokalen Zustand formatieren. Prüfen, ob session_id / call_id zusammenpassen.
  • Mit JSONPath extrahieren order_id, turn_id und eine Subagent-agent_id ziehen.
  • Items vor und nach Compact JSON Diff. Driftet die ID, zuerst die Kompression ansehen.
  • Items des Hauptagenten und eines Subagenten getrennt listen. Auf einer Seite gemischt hängt Koordination am falschen Akteur.
  • Keine Bestellungen, Sessions oder Intranet-MCP in einen öffentlichen Formatter. JSONSort läuft lokal im Browser.

Lassen sich beide Spuren neu aufbauen, haben Sie fortgesetzt. Sonst neu geraten.

Häufige Fallen

  • Idle als Erfolg lesen. Erst turn.completed / failed / cancelled, dann die Tool-Ergebnisse.
  • Nach dem Abbruch auf Stream-Wiedergabe warten. Offiziell: keine. Session und Items holen.
  • Die Bestellnummer nur im Chat lassen. Nach Compact kann die Zusammenfassung A-1042 verlieren.
  • multi_agent ohne Deckel. Die Vorgabe 6 fächert weiter Tokens und Nebenwirkungen auf.
  • Ihre Funktion an einen Subagent schicken. Subagents unterstützen keine Function-Tools. Lookups bleiben beim Hauptagenten.
  • Session und Conversation als eine Ressource behandeln. Eine löschen räumt die andere nicht.

FAQ

Ist ein langer Lauf nur ein längerer Prompt?

Nein. Es ist eine dauerhafte Session, automatisches Compact und das Geschäfts-JSON, das Sie halten. Ein längerer Systemprompt hebt das Fensterlimit nicht.

Darf ich Agents-Compact mit Responses-Compact mischen?

Nicht. Eine Agents-Session verdichtet sich selbst. Responses nutzt context_management oder /responses/compact. Zwei Ressourcen, zwei nächste Fenstereingaben.

Wie stelle ich nach einem Abbruch wieder her?

Session und Items mit der gespeicherten session_id laden. Der Stream wiederholt verpasste Ereignisse nicht. last_turn_id und offene call_id ausrichten, dann zurückschreiben oder die nächste Nachricht senden.

Kann ein Subagent mein lookup_order aufrufen?

Nein. Offiziell: keine Function-Tools. Sie erben MCP, Websuche und Dateien / Befehle der Umgebung. Bestellabfragen bleiben beim Hauptagenten.

Macht eine selbst gehostete Sandbox Zero Data Retention?

Nein. Offiziell: Agents API unterstützt derzeit nur US-Residenz und kein ZDR. Eine self-hosted Sandbox ändert das nicht.

Schluss

Ein langer Lauf ist kein klügeres Modell. Es ist eine dauerhafte Session, ein automatisches Compact und JSON-Zustand, den Sie halten. Tool-Argumente, Turn-Ereignisse und Subagent-Items sind Objekte auf dieser Kette.

Schreiben Sie fest, ob Sie A-1042 nach einem Abbruch neu aufbauen können. Wenn ja, lebt der Auftrag. Modelle wechseln; session_id und Schema sollten zuerst stehen.

Weiterlesen

Änderungsprotokoll: Erstveröffentlichung