AI-Entwicklung

OpenAI Agents API + JSON Schema in der Praxis: Stabiles, prüfbares, ausführbares JSON (2026)

Ca. 16 Min.

Der allgemeine Schema-Text hat schon gefragt, warum ein Vertrag nötig ist. Dieser landet nur auf der Agents API: jedes JSON, das das Modell füllt, muss ein Tor passieren, bevor etwas läuft. Tool-Parameter, MCP-Eingabe und Ihr Hauptbuch sind drei Türen — nicht der Satz „bitte JSON ausgeben“.

Bevor Sie lesen

Tür Was sie schließt Wer ausführt
Function parameters order_id, Booleans, Enums additionalProperties: false
Host-Prüfung arguments in required_actions Kein Pass, keine Funktion
Endkarte Das Objekt für den Nutzer Zweites Schema; nicht text.format
MCP inputSchema einer weiteren Tool-Tabelle Subagents können erben

Schema ist ein Tor, keine Höflichkeit. Ein weites object ist eine weitere offene Tür.

Stabil, prüfbar, ausführbar: drei Verfahren, kein Schalter

Auf der Agents API füllt das Modell weiter nur JSON. Eine offizielle Funktion braucht ein parameters-Schema: required, additionalProperties: false und wo nötig pattern / enum. Das stabilisiert die Füllung. Prüfbar heißt: Sie laufen dasselbe Schema auf arguments, bevor Sie ausführen. Ausführbar heißt: der Host erzeugt Nebenwirkungen erst nach dem Tor.

  • Stabil: ein enges Tool-Schema. Ein weites object lädt erfundene Schlüssel ein.
  • Prüfbar: den Aufruf in required_actions lokal prüfen. Ein function_call in der Historie reicht nicht.
  • Ausführbar: lookup_order nicht laufen lassen, wenn das Tor fällt. success: false und einen Grund zurückschreiben. Den Store nicht still anfassen.

Wie Tools gerufen werden: OpenAI-Agents-API-Rundgang. Wie vier Objekte auf IDs sitzen: JSON-Strukturen der Agents API. Die allgemeine Teilung Schema / Function Calling / Structured Output: Warum AI JSON Schema braucht. Dieser Text definiert die Wörter nicht neu. Er landet sie nur auf einer Agents-Session.

Erste Tür: parameters auf agent.tools

Ein offizieller Function-Eintrag ist Name, Beschreibung und ein JSON Schema. Beim Anlegen in agent.tools schreiben. Fiktive Bestellung — keine echten Geheimnisse:

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

Nur wenige Hebel zählen: jedes Feld in required; Objekte schließen Extra-Schlüssel; IDs nutzen pattern, kein nacktes string. Funktionen laden standardmäßig eifrig. Zum Aufschieben defer_loading: true und tool_search auf die Tabelle. Das Tor selbst ändert sich nicht.

Argumente, die das Tor verfehlen, dürfen nicht laufen

Hält die Session auf agent.session.requires_action, steht in required_actions ein function_call. Dieses Beispiel sieht nach Lookup aus und ist schon über den Zaun: die ID bricht das Pattern, ein refund taucht auf:

{
  "type": "function_call",
  "turn_id": "turn_2",
  "call_id": "call_3c91",
  "name": "lookup_order",
  "arguments": {
    "order_id": "1042",
    "include_lines": true,
    "refund": true
  }
}

Dasselbe turn_id / call_id-Paar — eine passende Form sieht so aus. Extra-Schlüssel, fehlendes required, driftendes Pattern: keines davon ausführen:

{
  "type": "function_call",
  "turn_id": "turn_2",
  "call_id": "call_3c91",
  "name": "lookup_order",
  "arguments": {
    "order_id": "A-1042",
    "include_lines": true
  }
}

Zweite Tür: der Host läuft dasselbe Schema noch einmal

Das offizielle Schema verbessert Füllungen. Es übernimmt Ihre Nebenwirkungen nicht. Vor dem Lauf lokal prüfen. Einen Fehlschlag als Objekt festhalten:

{
  "check": "lookup_order",
  "schema": "parameters",
  "pass": ["order_id", "include_lines"],
  "fail": [
    { "path": "/order_id", "reason": "pattern" },
    { "path": "/refund", "reason": "additionalProperties" }
  ],
  "execute": false
}

Bei Fehler agent.session.input.tool_result mit success: false und lesbarem error senden. Bei Erfolg output als String serialisieren. Keine neue Session als „Retry“.

{
  "type": "agent.session.input.tool_result",
  "turn_id": "turn_2",
  "call_id": "call_3c91",
  "success": false,
  "error": "order_id failed schema: expected ^[A-Z]-\\d{4}$"
}

Die Endkarte ist eine dritte Tür, nicht Responses text.format

Die Bestellkarte für den Nutzer ist nicht das Tool-Parameter-Schema. Eine Agents-Session legt Responses text.format.json_schema nicht automatisch an. Drei Jobs getrennt halten:

  • Tool-Parameter: die Tür zu Nebenwirkungen schließen. Lookups und Schreibvorgänge hier.
  • Endkarte: Objekt aus Items ziehen, auf einem zweiten Schema prüfen, dann zeigen.
  • Soll die Endform Structured Outputs sperren: das ist die Responses-Schicht. Nicht in dieselbe Session-Ressource mischen.

Wer die Schleife besitzen soll: Agents API vs. Responses API. Eine MCP-Zeile ist eine weitere Tool-Tabelle; ihr inputSchema will ebenfalls additionalProperties: false. Grenze: MCP Tool Schema vs. Function Calling. Subagents erben MCP-Schema, nicht Ihre Funktion.

Fünf Schritte zu ausführbarem JSON

Nicht bei „bitte JSON ausgeben“ starten. Die Türen gehen:

  1. Zuerst das Tool-Schema schreiben. Pattern, Enum, required, additionalProperties: false einmal festziehen.
  2. Dasselbe Schema in den Host-Validator laden. Keine zweite, driftende Kopie.
  3. Bei required_actions prüfen, dann ausführen. Tor verfehlt → success: false.
  4. Der Endkarte ein eigenes Schema geben. Nach dem Extrahieren aus Items prüfen. Prosa ist keine Karte.
  5. Hauptbuchfelder selbst halten. Compact streicht Details. Beträge und Freigaben leben nicht nur im Chat.

Wie ein Workflow Schema wird: JSON Schema und Agent-Workflows. Dieser Text verlangt nur, dass jede Tür auf einer Agents-Session ein Objekt ist.

Stabile Ausgabe prüfen: zwei JSON-Spuren ausbreiten

Drift ist meist eine schief stehende Tür, kein dümmeres Modell.

  • parameters neben arguments formatieren. Extra-Schlüssel und fehlende Felder suchen.
  • Mit JSONPath extrahieren order_id und $.parameters.required ziehen.
  • Einen fallenden und einen passenden Aufruf JSON Diff. Driftet das Pattern, zuerst das Schema.
  • Karten-Schema und Tool-Schema getrennt prüfen. Nur die Karte zu sperren ist Fassade.
  • Keine Bestellungen, Sessions oder Intranet-MCP in einen öffentlichen Formatter. JSONSort läuft lokal im Browser.

Lassen sich beide Spuren gegen Schema neu aufbauen, haben Sie JSON gesammelt. Sonst Prosa.

Häufige Fallen

  • Nur in instructions „bitte JSON ausgeben“ schreiben. Das ist kein Tor. Das Tor ist parameters plus Host-Validator.
  • Nur einen Teil der Felder in required listen. Ausgelassene Schlüssel bleiben leer. Der nächste Sprung hat Löcher.
  • additionalProperties offen lassen oder true setzen. Offizielle Beispiele schließen Extra-Schlüssel. Ein extra refund und die Nebenwirkung kippt.
  • Responses text.format in eine Agents-Session kopieren. Zwei Ressourcen. Die Endkarte selbst prüfen.
  • Die Funktion nach einem Fehlschlag trotzdem laufen lassen. Ausführbar heißt: das Tor ist durch. Zuerst den Fehler schreiben.
  • Ihre Funktion an einen Subagent schicken. Subagents haben keine Function-Tools. Das enge Schema bleibt beim Hauptagenten.

FAQ

Hat die Agents API Structured Outputs?

Tool-Parameter werden mit JSON Schema angezogen. Das Objekt für den Nutzer bekommt nicht automatisch Responses text.format. Die Endform selbst sperren oder diesen Sprung auf Responses legen.

Wenn es ein offizielles Schema gibt, prüfe ich trotzdem?

Ja. Das offizielle Tor verbessert Füllungen. Nebenwirkungen geschehen in Ihrem Prozess. arguments in required_actions durch dasselbe Schema; Fehlschlag mit success: false.

Brauche ich pattern und enum?

Ja. Ein nacktes string lässt 1042 statt A-1042 zu. Beträge und Status wollen ein Enum oder ein klares Format. Weite Typen sind der übliche Weg über den Zaun.

Brauchen MCP-Tools dieselbe Disziplin?

Ja. inputSchema soll Extra-Schlüssel schließen und jedes required listen. Subagents erben MCP, nicht Funktionen. Die Tür zu Ihren Bestellungen bleibt beim Hauptagenten.

Lässt ein Fehlschlag die Session stehen?

Ein tool_result auf demselben turn_id / call_id-Paar reicht. Ein klarer error lässt das Modell mit neuen Argumenten erneut rufen. Keine neue Session als Retry.

Schluss

Stabiles JSON auf der Agents API ist kein längerer Prompt. Es sind drei Türen: Tool-Parameter, eine Host-Prüfung und ein eigenes Schema für die Endkarte. Ausführung erst nach dem Tor.

Schreiben Sie fest, an welcher Regel A-1042 fallen würde. Können Sie auf einen Pfad zeigen, ist die Date prüfbar. Modelle wechseln; die Türen sollten zuerst stehen.

Weiterlesen

Änderungsprotokoll: Erstveröffentlichung