OpenAI Agents API 2026: Wie ruft ein AI Agent Werkzeuge auf? JSON Schema, Tool Calling und Workflow-Daten

Auf einen Blick

Begriff	Ein Satz	Landet auf
Agents API	Von OpenAI betriebenes Codex-Harness	sessions.create / agent
Tool Calling	Das Modell schlägt Namen und Argumente vor	function_call / arguments
JSON Schema	Die Argumentform, die in die Schleife darf	parameters / additionalProperties
Workflow	Sitzung, Runde, Einträge, Übergabe	session / turn / items

Die Teilung merken: Sie deklarieren Agent, Tools, Environment; OpenAI dreht die Schleife. Nebenwirkungen bleiben im Host oder in der Sandbox, nicht in den Gewichten.

Es kann Tools rufen. Das Modell ist nicht der Rufer

Nach der Public Beta startet ein POST /v1/agents/sessions einen langlebigen Agenten: Bestellung nachschlagen, Repo lesen, Subagent schicken. Die Nebenwirkungen sind echt.

„Direkt aufrufen“ setzt das Subjekt falsch. Das Modell hält die MCP-Verbindung nicht, startet die Sandbox nicht und trifft Ihre Billing-API nicht. Es sendet ein prüfbares Objekt. Ausgeführt wird vom verwalteten Harness und der Environment, die Sie wählen.

• Deklarieren: Functions, MCP und web_search auf agent.tools.
• Vorschlagen: das Modell sendet einen function_call — Name plus Argumentobjekt.
• Ausführen: das Harness trifft ein Service-Tool, Ihren Handler oder einen Befehl in der Sandbox.

Wenn Agent, Tool Calling und Function Calling noch ein Wort sind, zuerst AI-Agent-Leitfaden. Dieser Text behandelt eine Tatsache: wie die Agents API diese JSON-Kette hostet.

Was die Beta am 10. September wirklich lieferte

OpenAI sagte es klar: dasselbe Harness hinter Codex und ChatGPT for Work, als API. Auf der Modellseite sehen Sie oft GPT-6-Astra-Leitfaden. Sie zahlen Tokens und Tool-Nutzung; die API selbst kostet nichts extra.

• Verwaltete Schleife: Session, Orchestrierung, Recovery — ohne eigenen LangChain-Kleber.
• Kontextkompaktierung: Auto-Compact nahe am Fensterlimit, Arbeit über mehrere Fenster.
• Tool search + programmatic tool calling: Definitionen bei Bedarf laden, parallel rufen, nur relevante Ergebnisse zurückschreiben.
• MCP / function / web_search: eine Tool-Tabelle kann sie mischen.
• Subagents: multi_agent.enabled, mit Concurrency-Deckel (Doku oft 6).

OpenAI DevDay 2026-Prognosen hat Structured Outputs und Function Calling vorhergesagt. Gelandet ist eine Session-Ressource: Agent, Environment, Session, Events / Items — nicht noch ein Chat-Completion-Wrapper.

JSON Tool Calling bleibt das Skelett

Der API-Name wechselte. Die vier Sprünge nicht:

1. Deklarieren: agent.tools[] bietet Function-Schema, MCP-Server, eingebaute Tools.
2. Vorschlagen: das Modell füllt Name und Argumente. Es führt nicht aus.
3. Tor: Harness oder Handler prüft, allowlistet, wartet vielleicht auf einen Menschen.
4. Zurückschreiben: ein Tool-Result wird das nächste sichtbare Item.

Ein Session-Create sieht ungefähr so aus. Die Bestellung ist fiktiv — keine echten Geheimnisse oder Intranet-URLs auf eine öffentliche Seite:

{
  "agent": {
    "model": "gpt-6-astra",
    "instructions": "Look up orders. Confirm before any refund.",
    "tools": [
      { "type": "programmatic_tool_calling" },
      {
        "type": "function",
        "name": "lookup_order",
        "parameters": {
          "type": "object",
          "properties": {
            "order_id": { "type": "string", "pattern": "^[A-Z]-\\d{4}$" }
          },
          "required": ["order_id"],
          "additionalProperties": false
        }
      },
      {
        "type": "mcp",
        "server_label": "orders",
        "transport": {
          "type": "http",
          "server_url": "https://orders.example.com/mcp"
        }
      }
    ],
    "multi_agent": {
      "enabled": true,
      "max_concurrent_subagents": 3
    }
  },
  "environment": {
    "type": "hosted",
    "workspace_directory": "/workspace"
  },
  "input": [
    {
      "role": "user",
      "content": [
        { "type": "input_text", "text": "Look up order A-1042." }
      ]
    }
  ]
}

Läuft die Schleife, sendet das Modell weiter ein Objekt, keinen Absatz „bitte die Bestellung nachschlagen“:

{
  "type": "function_call",
  "id": "call_3c91",
  "name": "lookup_order",
  "arguments": "{\"order_id\":\"A-1042\"}"
}

Die MCP-Zeile ist eine andere Schreibweise derselben Tabelle; Grenze in MCP Tool Schema vs. Function Calling. Ein Coding-Agent in der Sandbox ist weiter JSON — siehe AI Coding Agents und die JSON-Aufrufkette.

JSON Schema ist das Tor, nicht „bitte JSON zurück“

Die Schleife zu hosten macht ein weites object nicht sicher. Vertrag in Warum KI JSON Schema braucht: der Prompt beeinflusst, was es füllt; Schema entscheidet, was ausführen darf.

{
  "name": "lookup_order",
  "description": "Look up an order by ID",
  "parameters": {
    "type": "object",
    "properties": {
      "order_id": {
        "type": "string",
        "pattern": "^[A-Z]-\\d{4}$"
      }
    },
    "required": ["order_id"],
    "additionalProperties": false
  }
}

Ein Function-Schema, das einen schlechten Sprung stoppt, braucht vier Dinge:

• Typen eng: order_id bekommt ein Pattern, keinen nackten string.
• Beträge und Aktionen als Enum: Erstattungen und Statuswechsel brauchen enum.
• Zusatzschlüssel zu: additionalProperties: false. Ein weites Objekt ist eine weitere Tür.
• Der Host schreibt die Bestätigung: das Modell darf create_refund vorschlagen; es darf allowed: true nicht in den State schreiben.

Tools und Workflows als Schema im Repo halten, nicht als Chat-Abmachung. Tore ketten: JSON Schema und AI-Agent-Workflows.

Der Workflow sind vier Objekte, keine Prompt-Kette

OpenAI faltet die Agents API in vier Begriffe. Ingenieurisch sind sie alle JSON:

• Agent: Modell, Instructions, Tools, MCP. Die Fähigkeitstabelle.
• Environment: gehostete oder self-hosted Sandbox. Dateien, Befehle, Skills wohnen hier.
• Session: eine dauerhafte Instanz. State bleibt beim Dienst; Sie bauen History nicht neu.
• Events / Items: Input, Tool-Calls, Ergebnisse, Subagent-Koordination.

Ein auditierbarer Workflow sieht nach Objekten aus, nicht nach einem letzten Satz „erledigt“:

{
  "session_id": "sess_9f2a",
  "turn": 2,
  "items": [
    { "type": "function_call", "name": "lookup_order", "id": "call_3c91" },
    { "type": "function_call_result", "call_id": "call_3c91", "status": "paid" }
  ],
  "state": {
    "order_id": "A-1042",
    "status": "paid"
  },
  "next": {
    "tool": "create_refund",
    "allowed": false,
    "reason": "missing_confirmation"
  }
}

Jeder Subagent behält eigenen Kontext. Der Hauptagent koordiniert mit Create / Message / Wait / Interrupt-Items. Concurrency deckeln. Ohne Deckel fächern Tokens und Nebenwirkungen auf.

Wer dreht die Schleife

Die Frage ist nicht, wer klüger ist. Wo die Orchestrierung wohnt:

Wählen Sie das Subjekt, bevor Sie die API wählen: wollen Sie die Schleife besitzen? Der volle Vergleich kommt als nächstes. Dieser Text verlangt nur: Eingang tauschen, die JSON-Aufrufkette bleibt.

Objekte prüfen, nicht „der Agent ist fertig“

Nach einer Session prüfen Sie nicht den letzten Satz. Sie prüfen die Spur.

• formatieren agent.tools, function_call und function_call_result. Name und Argumente müssen der gedachte Sprung sein.
• Mit JSONPath extrahieren name, arguments und server_url ziehen. Prosa nicht mit dem Auge scannen.
• JSON Diff gegen eine Session-Spur, die letzte Woche durchging. Driftete die Schleife, zuerst Tool-Tabelle und Argumentform, dann das Modell.
• Compact-Zusammenfassungen müssen Schlüsselfelder tragen. order_id verlieren, und der nächste Sprung füllt falsch.
• Keine Bestellungen, Sessions oder Intranet-MCP-URLs in einen öffentlichen Formatter. JSONSort läuft lokal im Browser; dort gehören diese Objekte hin.

Lässt sich die Spur neu bauen, lässt sich die Session prüfen. Das ist die Eintrittskarte in Produktion, kein Extra.

Fallstricke

• Glauben, die Agents API lasse das Modell Tools ausführen. Ausführung sitzt auf Harness und Environment.
• Ein weites object der verwalteten Schleife geben. Gehostet ist kein Tor.
• multi_agent ohne Concurrency-Deckel. Subagents fächern Tokens und Nebenwirkungen.
• Eine Session wie eine weitere Chat Completion behandeln. State, Recovery und Compact sind First-Class-Objekte.
• Schema durch einen Prompt ersetzen. Der Vertrag muss prüfbar sein.
• Eine gehostete Sandbox als Zero Data Retention lesen. OpenAI ist klar: self-hosted macht Agents API nicht ZDR-fähig.

FAQ

Lässt die Agents API das Modell Tools direkt rufen?

Sie lässt das Modell Tool-JSON direkt senden. Ausführung bleibt im verwalteten Harness, Ihrem Handler oder der Sandbox. Ohne tools[] ruft es nichts.

Agents API oder Responses API — wo anfangen?

Soll OpenAI eine lange Schleife drehen, Kontext verdichten und Subagents schicken? Agents API. Wollen Sie jeden Modellaufruf besitzen? Responses API. Soll die Schleife in Ihrem Prozess bleiben? Agents SDK.

Brauche ich auf der Agents API noch JSON Schema?

Ja. Die verwaltete Schleife orchestriert nur. Function-Parameter, MCP-inputSchema und State-Objekte müssen eng bleiben. Ein weites Schema plus automatische Schleife öffnet die Tür weiter.

Unterschied zwischen Session, Turn und Item?

Eine Session ist die dauerhafte Instanz. Ein Turn ist Arbeit aus einem User-Input. Items sind Inputs, Tool-Calls, Ergebnisse oder Subagent-Koordination in diesem Abschnitt. Audits sehen Items, nicht den letzten Satz.

Darf ein Agent die Produktionsdatenbank oder eine Produktionserstattung anfassen?

Keine Produktionsnebenwirkung auf den ersten Sprung. Im isolierten Environment hinter einem engen Schema entwerfen lassen. Der Host schreibt die Bestätigung. Geheimnisse und Freigabe bleiben ein menschliches Tor.

Fazit

Die Agents API lässt einen Agenten „Tools direkt rufen“ — der Satz ist nur halb wahr. Die wahre Hälfte: Sie schreiben die Schleife nicht mehr. Die falsche Hälfte ist das Subjekt. Subjekt ist das Harness; Verb ist ausführen; Objekt ist JSON, das das Modell füllte.

Ab heute weniger streiten, ob es „selbst arbeitet“. Zuerst Agent, Tools, Session-Items und Schema ins Repo. Modelle wechseln. Diese JSON-Tool-Calling-Kette sollte zuerst stehen.

Weiterlesen

• Was ist ein AI Agent? Kompletter Leitfaden Runtime, Tool Calling und der JSON-Vertrag
• JSON Schema und AI-Agent-Workflows Tools und State als Schema halten
• MCP Tool Schema vs. Function Calling Protokollgrenze für Tool-JSON
• Warum KI JSON Schema braucht Schema / Function Calling / Structured Output
• OpenAI DevDay 2026-Prognosen Die ältere Structured-Outputs- / Agent-Rahmung
• JSONSort lokaler Werkzeugkasten Formatieren, prüfen, Diff
• Alle Beiträge Weitere JSON- und KI-Notizen

Änderungsprotokoll: 2026-09-20 Erstveröffentlichung