Eine Szene mit einem Assistenten bauen

Am Ende hat Ihr Assistent eine Szene aus Widgets gebaut, sie geprüft, als Entwurf gespeichert und Ihnen ein gerendertes Bild davon gezeigt. Der Weg von der Idee zum Bild ist eine Kette aus sechs Schritten, und jede Werkzeugbeschreibung nennt den nächsten, damit ein Assistent die Reihenfolge nicht raten muss.

Schritte#

1. Die Widgets ansehen. list_widgets nennt die Widgets, aus denen eine Szene besteht: die eingebauten text, image, video, shape, graphic, document und zone, die es immer gibt, und die Widgets der Apps, die Ihre Organisation installiert hat. Jeder Eintrag zeigt Kennung, App, Namen, einen Satz, die Pflichtfelder und ob die App installiert ist. Das Widget einer nicht installierten App lässt sich in ein Dokument schreiben, läuft aber auf keinem Display.

2. Die Regeln holen. get_widget_schema liefert das vollständige JSON Schema der Konfiguration eines Widgets (Draft 2020-12): jedes Feld mit title und description, die Pflichtfelder unter required und unter examples mindestens eine vollständige Beispiel-Konfiguration. Ein Beispiel nehmen und die Werte tauschen ist der kürzeste Weg.

   Ein Wert steht in keinem Schema: die graphicId des eingebauten Widgets graphic. Sie ist eine feste Kennung aus der Bibliothek der Motive. list_graphics listet sie mit Kategorie und Schlagwörtern, durchsuchbar nach Absicht mit deutschen Wörtern wie „pfeil“ oder „kaffee“.

3. Das Dokument bauen. Ein Szenendokument hat drei Felder:

   JSONKopieren

   {  "canvas": { "width": 1920, "height": 1080, "backgroundColor": "#ffffff" },  "widgets": [    {      "id": "wgi_01K7Z9M4T0W14MCPTEXT000001",      "appId": "core",      "widgetType": "text",      "appVersionPin": "0.0.0",      "frame": { "x": 0, "y": 0, "w": 1920, "h": 1080 },      "zIndex": 0,      "config": { "content": "Welcome" }    }  ],  "transitions": {    "in": { "kind": "fade", "durationMs": 600 },    "out": { "kind": "fade", "durationMs": 600 }  }}

   Eine Szene hat keine Auflösung. Jedes Widget sitzt nach seinem frame in Einheiten der Leinwand, und die kurze Kante der Leinwand misst immer 1080: 16:9 ist 1920 × 1080, 9:16 ist 1080 × 1920. Jedes Display zeichnet so scharf, wie Gerät und Paket es erlauben. Ein Bereich ist ein Widget mit appId: "core" und widgetType: "zone". Er teilt die Szene, und seine config nennt name, primary und content: einen Inhalt, eine eigene Folge oder eine Playlist. Höchstens ein Bereich ist primary, und dieser Hauptbereich bestimmt, wie lange die Szene läuft. Bereiche überlappen sich nicht, und ein Widget in einem Bereich sitzt dort ohne eigenen Rahmen. config kommt aus Schritt 2.

4. Einen Probelauf machen. validate_scene prüft das Dokument, ohne etwas zu speichern: den Aufbau, die Regeln der Bereiche, die verwendeten Medien und jede Konfiguration gegen das Schema ihres Widgets. Jeder Befund nennt Widget und Feld:

   JSONKopieren

   {  "valid": false,  "findings": [    {      "severity": "BLOCKING",      "type": "ConfigSchemaIncompatible",      "message": "widget 'wgi_…' (text): config/content must NOT have fewer than 1 characters",      "widgetId": "wgi_…",      "field": "/content"    }  ]}

   BLOCKING verhindert später das Veröffentlichen, WARNING nicht. Ein Widget, das über den Rand der Leinwand ragt, wird gemeldet und hält nichts auf.

5. Den Entwurf anlegen oder ändern. create_scene legt einen Entwurf aus dem Dokument an, update_scene ersetzt das Dokument einer bestehenden Szene. Beide machen den Probelauf noch einmal und schreiben gar nichts, wenn ein Befund blockiert. Beide brauchen confirm: true und beschreiben ohne es nur, was sie tun würden.

   Um eine bestehende Szene zu ändern, beginnen Sie mit get_scene_document. Es liefert das Dokument des Entwurfs und seine version. Ändern Sie dieses Dokument, prüfen Sie es mit validate_scene und schicken Sie es als Ganzes an update_scene, zusammen mit expectedVersion aus derselben Antwort, damit eine fremde Änderung dazwischen nicht überschrieben wird. Einzelne Widgets lassen sich nicht ändern, und ein Assistent, der das Dokument neu erfindet, verliert jede Einstellung, die er nicht kannte.

6. Ansehen und nachbessern. render_scene rendert eine veröffentlichte Fassung und liefert das Bild als PNG in der Antwort. Ein reiner Entwurf hat keine Fassung, veröffentlichen Sie ihn also zuerst mit publish_scene. Auf ein Display kommt er dadurch nicht, solange ihm keines zugewiesen ist. Das Bild beantwortet, was kein Schema kann: ob der Text in seinem Kasten bleibt, ob etwas verdeckt ist, ob die Farben stimmen. Passt etwas nicht, geht es mit update_scene und einem neuen Veröffentlichen weiter.

Ergebnis prüfen#

• get_scene zeigt die Szene mit ihren Widgets und ohne offenen Befund.
• Das Bild aus render_scene zeigt, was Sie wollten.
• Was ein Display wirklich zeigt, beantwortet get_player_screenshot mit der jüngsten Aufnahme des Geräts. Gibt es noch keine, fordert send_player_command mit command: "screenshot" eine an.

Wenn etwas nicht klappt#

Weiterführendes#

• Alle Werkzeuge
• Was kann ein KI-Assistent mit Szenera tun?
• Wenn der Assistent keine Verbindung bekommt oder ein Werkzeug scheitert