Output-Schema definieren

Das Output-Schema ist das maschinenlesbare Ergebnis-Format eines Features: die feste Struktur, in der ein Feature seine Antwort liefert. Es ist das Interface, an dem sich aufrufender Code orientiert. Das SDK leitet daraus den Ergebnistyp ab, gegen den ein Entwickler programmiert. Solange das Schema stabil bleibt, bleibt auch der aufrufende Code stabil. Deshalb ist das Output-Schema einer der wichtigsten Bestandteile des Agent Contracts (der zentralen, versionierten Definition eines Features); mehr dazu unter Agent Contract.

Diese Anleitung beschreibt den Tab Schema im Feature-Detail.

Zum Schema-Tab gelangen

Öffne Features in der Sidebar, klicke die gewünschte Feature-Karte an und wähle in der Tab-Leiste den Tab Schema. Direkt daneben liegen weitere Tabs des Agent Contracts: Prompt (Prompt), Models (Modelle) und Tools.

Ein Output-Schema anlegen

Hat ein Feature noch keinen Contract, zeigt der Schema-Tab den Hinweis „Noch kein Output-Schema”. Klicke auf die Schaltfläche Output Schema anlegen. Damit entsteht der erste Entwurf (Draft) des Agent Contracts samt einem leeren Schema, das anschließend gefüllt wird.

Hinweis

Die Schaltfläche Output Schema anlegen erscheint nur für Rollen, die den Contract bearbeiten dürfen. Ohne diese Berechtigung ist der Tab nur lesbar.

Die zwei Ansichten: Form und JSON

Der Schema-Editor bietet zwei Ansichten auf dieselbe Definition. Sie sind als zwei innere Tabs umschaltbar:

• Form — die klickbare Feld-Liste für Fachexperten. Jedes Feld wird über Eingabefelder und Auswahlmenüs gepflegt, ohne JSON zu schreiben.
• JSON — der Code-Editor für Entwickler, in dem das Schema direkt als JSON bearbeitet wird.

Beide Ansichten arbeiten auf demselben Stand. Eine Änderung in der einen Ansicht ist in der anderen sofort sichtbar.

Achtung

Enthält die JSON-Ansicht ungültiges JSON, ist der Wechsel zurück in die Form-Ansicht gesperrt, bis der Fehler behoben ist. Eine Fehlermeldung zeigt an, was nicht geparst werden kann. Korrigiere das JSON, danach steht die Form-Ansicht wieder offen.

Hinweis

In der Form-Ansicht sind die obersten Felder direkt editierbar. Verschachtelte Strukturen innerhalb eines Objekts oder Arrays werden über die JSON-Ansicht gepflegt. Ist der oberste Typ kein Objekt, verweist die Form-Ansicht ebenfalls auf die JSON-Ansicht.

Felder in der Form-Ansicht

Klicke auf Feld hinzufügen, um ein neues Feld anzulegen. Je Feld stehen zur Verfügung:

• Feld-Name — der Schlüssel, unter dem der Wert im Ergebnis steht.
• Type — der Datentyp.
• optional — Häkchen setzen, wenn das Feld im Ergebnis fehlen darf. Ohne Häkchen ist es ein Pflichtfeld.
• Beschreibung — ein erklärender Text zum Feld.

Über das Papierkorb-Symbol wird ein Feld entfernt.

Feldtypen

Type	Bedeutung	Besonderheit
string	Text	—
number	Zahl	—
boolean	Wahrheitswert (wahr/falsch)	—
enum	feste Auswahl aus erlaubten Werten	Werte unter Enum-Werte (komma-separiert) eintragen
array	Liste gleichartiger Werte	Elementtyp wird in der JSON-Ansicht festgelegt
object	verschachteltes Objekt mit eigenen Feldern	innere Felder über die JSON-Ansicht

Bei enum erscheint zusätzlich das Feld Enum-Werte (komma-separiert); trage dort die erlaubten Werte durch Komma getrennt ein.

Speichern und der abgeleitete SDK-Typ

Der Editor speichert automatisch. Wenige Sekunden nach der letzten Änderung läuft das Speichern an; der Stand wird über dem Editor angezeigt — von „Speichern in … s …” über „Speichern …” bis „Gespeichert …”. Tritt ein Fehler auf, erscheint „Fehler beim Speichern” mit einer Schaltfläche zum erneuten Versuch.

Das Output-Schema bestimmt den Ergebnistyp, den das SDK aus dem Contract ableitet. Ein Objekt mit Feldern wird zu einem entsprechenden Typ mit denselben Schlüsseln; ein als optional markiertes Feld wird im abgeleiteten Typ als optional gekennzeichnet. So bildet das Schema unmittelbar ab, womit aufrufender Code rechnen kann. Beim Veröffentlichen liefert die Plattform ein passendes SDK-Code-Snippet; Details dazu unter SDK-Überblick.

Beispiel

Ein Objekt mit den Feldern kategorie (enum) und vertraulich (boolean, optional) ergibt im abgeleiteten Typ eine feste Auswahl für kategorie und ein optionales vertraulich.

Breaking Changes und Major-Bump

Solange am Entwurf gearbeitet wird, sind Schema-Änderungen frei möglich. Beim Veröffentlichen prüft die Plattform jedoch, ob die Änderung das bestehende Interface bricht — etwa ein entferntes Feld, ein geänderter Typ oder ein neues Pflichtfeld. In diesem Fall ist ein Major-Bump (ein Sprung der Hauptversionsnummer) nötig, und es erscheint der Dialog „Breaking-Schema-Änderung — Major-Bump bestätigen?”. Er listet die erkannten Änderungen auf und verlangt zur Bestätigung die Eingabe des Feature-Namens. Erst danach lässt sich der Major-Bump bestätigen.

Hintergrund: Eine Breaking-Schema-Änderung kann aufrufenden Code brechen, der auf der alten Definition aufsetzt. Die ausdrückliche Bestätigung sorgt dafür, dass dieser Schritt bewusst geschieht. Der gesamte Ablauf ist unter Veröffentlichen beschrieben.

Wer das Schema bearbeiten darf

Das Output-Schema bearbeiten dürfen die Rollen developer, domain_expert, platform_engineer und admin. Die Rollen compliance_officer und viewer haben nur Lesezugriff. Sobald eine Version veröffentlicht (aktiv) ist, ist sie schreibgeschützt; weitere Änderungen brauchen einen neuen Entwurf. Ist ein Feature im Lebenszyklus stillgelegt (sunset), kann es niemand mehr bearbeiten. Ein eingeblendetes Banner nennt jeweils den Grund für den Lesezugriff. Welche Rolle was darf, steht unter Rollen und Rechte.