# 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.

> **Typ:** anleitung
> **Für wen:** Alle, die einen Assistenten Szenen gestalten lassen, und Entwicklerinnen und Entwickler, die verstehen wollen, was er dabei tut
> **Voraussetzung:** ein verbundener Assistent mit dem Bereich **Szenen**, siehe [Einen KI-Assistenten verbinden](/de/mcp/connect-assistant)
> **Ort:** ein Gespräch mit Ihrem Assistenten

## 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:

   ```json
   {
     "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:

   ```json
   {
     "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

| Symptom | Bedeutung | Lösung |
|---|---|---|
| `create_scene` oder `update_scene` liefert Befunde und speichert nichts | Ein Befund blockiert. | Die genannten Felder korrigieren und `validate_scene` erneut aufrufen. |
| `update_scene` antwortet `conflict` | Jemand hat die Szene dazwischen geändert. | Das Dokument mit `get_scene_document` neu lesen und die Änderung auf den neuen Stand anwenden. |
| `render_scene` sagt, es gebe keine Fassung | Die Szene ist noch ein reiner Entwurf. | Sie mit `publish_scene` veröffentlichen und dann rendern. |
| `render_scene` sagt, eine Vorschau sei nicht verfügbar | In Ihrer Umgebung ist kein Dienst für Vorschaubilder eingerichtet. | Das Ergebnis stattdessen mit `get_player_screenshot` auf einem Display prüfen. |
| Ein Widget steht im Dokument, aber nicht auf dem Display | Seine App ist in Ihrer Organisation nicht installiert. | Die App installieren oder ein eingebautes Widget verwenden. |

## Weiterführendes

- [Alle Werkzeuge](/de/mcp/tools)
- [Was kann ein KI-Assistent mit Szenera tun?](/de/mcp/about-mcp)
- [Wenn der Assistent keine Verbindung bekommt oder ein Werkzeug scheitert](/de/mcp/troubleshooting)