Bei Alpic sind wir überzeugt, dass bei der nächsten Generation von Produkten und Diensten die Zusammenarbeit mit KI im Mittelpunkt steht. Über die Benutzeroberfläche arbeiten Menschen direkt mit Modellen zusammen, statt vorgegebenen Abläufen zu folgen.
Als OpenAI das Apps SDK veröffentlichte, haben wir sofort damit angefangen, Apps zu entwickeln. In drei Monaten entstanden zwei Dutzend ChatGPT Apps für den internen Einsatz und im Kundenauftrag, sowohl für den B2B- als auch für den B2C-Bereich, etwa in der Reisebranche, im Einzelhandel und im SaaS-Bereich.
Schon früh wurde uns klar, dass sich die Entwicklung von ChatGPT Apps grundlegend von der Entwicklung klassischer Web- oder Mobilanwendungen unterscheidet. Bewährte Muster aus der Webentwicklung wie das bedarfsgesteuerte Abrufen von Daten, die Zustandssteuerung über die Benutzeroberfläche oder die manuelle Konfiguration durch die Person, die die App bedient, funktionieren in einer Umgebung mit KI-Agenten oft schlecht oder erschweren sogar die Bedienung.
In diesem Beitrag teilen wir die 15 wichtigsten Erkenntnisse aus der Entwicklung von ChatGPT Apps für den praktischen Einsatz. Anschließend zeigen wir, wie wir diese Erfahrungen in unser Open-Source-Framework Skybridge und einen Codex Skill für die Community eingebracht haben. Damit kannst du deutlich schneller Ideen für Apps entwickeln, sie umsetzen, testen und veröffentlichen.
Das Dreikörperproblem
Bei klassischen Web-Apps war die Sache einfach. Es gab nur die Person, die die App bedient, und die Benutzeroberfläche. In einer ChatGPT App kommt das Modell als Drittes hinzu.
Eine der größten Herausforderungen bei der Entwicklung für ChatGPT besteht darin, den Informationsfluss zwischen diesen drei Beteiligten zu steuern. Klickt jemand in deinem Widget auf „Auswählen“, ändert sich die Anzeige. Das Modell, das das Gespräch steuert, erfährt davon aber erst, wenn du ihm diesen Kontext ausdrücklich mitteilst. Folgt dann die Bitte „Gib mir mehr Details zu diesem Produkt“, weiß das Modell nicht, welches Produkt die Person gerade vor sich hat.
Wir nennen das Kontextasymmetrie. Alle Beteiligten kennen einen Teil des Systemzustands, niemand hat das vollständige Bild. Bei einer guten ChatGPT App musst du nicht alles synchron halten. Du entscheidest, welche Informationen geteilt werden, wann das geschieht und wer sie braucht. Davon hängt ab, ob die Bedienung umständlich ist oder die Zusammenarbeit mit dem Agenten reibungslos funktioniert.
1. Kontext gezielt teilen
Unser erster Impuls war, „einfach alles überall zu teilen“. Das erwies sich als einer unserer ersten Fehler.
In der Praxis brauchen verschiedene Teile einer ChatGPT App oft bewusst unterschiedliche Sichten auf denselben Zustand. Warum?
- Aus Leistungsgründen: Widgets brauchen für die Anzeige oft weit mehr Daten, als das Modell je benötigt. Bei einer Reisebuchungs-App können das etwa Bilder, Preisvarianten und vorab geladene Optionen sein. Würden wir all das an das Modell senden, stiegen Token-Verbrauch und Latenz, und das Modell müsste mehr irrelevante Informationen verarbeiten.
- Für die Anwendungslogik: Manche Informationen dürfen bewusst nur einer Seite bekannt sein. Eine unserer ersten Apps war das Krimispiel Murder in the Valleys. Damit das Modell seine Rolle richtig spielen kann, muss es wissen, wer den Mord begangen hat. Die Oberfläche und die Mitspielenden dürfen das nicht erfahren. Bei einem Spiel nach dem Vorbild von Time’s Up ist es umgekehrt. Die Oberfläche zeigt den Mitspielenden das geheime Wort, das Modell darf es nicht kennen.
Statt alles zu synchronisieren, legen wir seitdem ausdrücklich fest, wer was wissen muss. Technisch bilden wir das über verschiedene Felder der Tool-Ausgabe ab:
| Feld | Zweck | Sichtbar für |
|---|---|---|
| structuredContent | Typisierte Daten für das Widget und das Modell | Widget und Modell (über die Funktionen toolOutput und callTool) |
| _meta | Metadaten zur Antwort | Nur für das Widget, für das Modell verborgen |
Bei Time’s Up haben wir das geheime Wort beispielsweise im Feld _meta nur an das Widget übergeben. So konnte das Modell versuchen, das Wort anhand der Hinweise der Mitspielenden zu erraten.
2. Lazy Loading eignet sich nur bedingt für KI-Apps
Aus der Webentwicklung waren wir Lazy Loading gewohnt. Wir riefen Daten erst beim Klicken ab, luden Details bei Bedarf und hielten die anfänglich übertragene Datenmenge möglichst klein.
In ChatGPT kehrt sich das um. Tool-Aufrufe verursachen Wartezeiten, die wegen des Sandboxings und des Reasonings des Modells oft mehrere Sekunden betragen.
In der Praxis haben wir gelernt, möglichst viele Daten schon mit der ersten Tool-Antwort zu senden und das Widget über window.openai.toolOutput mit diesen Daten zu initialisieren. Dadurch reagierte die App fast immer schneller auf Eingaben.
Wenn dein Widget Daten sicher von einem öffentlichen API-Endpunkt abrufen kann und diese Informationen nicht mit dem Modell teilen muss, kannst du im Widget natürlich weiterhin klassische XHR-Aufrufe verwenden. Meist soll das Modell die Tools aber selbstständig aufrufen können, damit sich die App im Gespräch bedienen lässt.
3. Das Modell muss wissen, was gerade angezeigt wird
Ein leicht zu übersehendes, aber entscheidendes Problem tritt auf, wenn jemand mit einem Widget interagiert, etwa ein bestimmtes Produkt in einer Liste auswählt, und anschließend im Chat eine Frage stellt. Weiß das Modell nicht, auf welchen Teil der Oberfläche sich die Frage bezieht, kann es sie nicht richtig beantworten.
Dafür haben wir window.openai.setWidgetState(state) verwendet. Damit kannst du gezielt Zustandsdaten speichern, die bei der nächsten Interaktion mit dem Modell in dessen Kontext aufgenommen werden.
Je komplexer unsere Apps wurden, desto mehr Stellen gab es, an denen wir setWidgetState aufrufen mussten, damit das Modell die Navigation nachvollziehen konnte. Deshalb haben wir eine deklarative Möglichkeit eingeführt, den Kontext der Benutzeroberfläche zu beschreiben. Statt das Modell bei jeder Interaktion per Funktionsaufruf zu informieren, versehen wir die Komponenten direkt mit einem data-llm-Attribut:
<div
data-llm={
selectedTab === "details"
? "User is viewing product details"
: "User is viewing reviews"
}
>
Product details
</div>Dafür haben wir ein Vite-Plugin entwickelt, das diese Attribute im Hintergrund ausliest und den widgetState automatisch aktualisiert. Das Modell erhält den relevanten Kontext zum richtigen Zeitpunkt, ohne dass du jede Interaktion von Hand synchronisieren musst.
Dieses Vite-Plugin und viele weitere Ansätze aus diesem Beitrag findest du in unserem Open-Source-Framework, mit dem wir unsere Erfahrungen an die Community weitergeben.
4. Unterschiedliche Interaktionen erfordern unterschiedliche APIs
In ChatGPT Apps gibt es mehrere Kommunikationswege zwischen Widget, Server und Modell. Jeder davon ist für eine bestimmte Art der Interaktion vorgesehen. Sie lassen sich daher nicht beliebig gegeneinander austauschen.
Bei der Entwicklung von ChatGPT Apps haben wir gelernt, diese Kommunikationswege ausdrücklich festzulegen und bewusst zu entscheiden, welcher Mechanismus für welchen Teil der Bedienung zuständig ist.
Die Kommunikationswege lassen sich etwa so darstellen:

Damit stehen die Grundlagen einer ChatGPT App. Du weißt, wie Kontext geteilt wird, wie das Modell erfährt, was die Oberfläche anzeigt, und auf welchen Wegen Interaktionen im System weitergegeben werden. Im nächsten Abschnitt geht es darum, was das für die Gestaltung der Oberfläche bedeutet.
Benutzeroberflächen für KI neu denken
ChatGPT Apps laufen in einer völlig neuen Umgebung. Wir haben deshalb schnell gelernt, unsere bisherigen Vorstellungen von Benutzeroberflächen zu hinterfragen und die neuen Möglichkeiten auszuschöpfen. Um gut bedienbare Apps zu entwickeln, mussten wir einige Gestaltungsprinzipien neu lernen und uns von anderen verabschieden.
5. Die Oberfläche muss sich an verschiedene Anzeigemodi und deren Grenzen anpassen
ChatGPT Apps sind nicht an ein einziges Layout gebunden. Je nachdem, wie und wann ein Widget aufgerufen wird, kann es in drei verschiedenen Modi erscheinen.
Apps können inline im Gespräch erscheinen, im Bild-in-Bild-Modus (PiP) über dem Gespräch liegen oder bei größerem Platzbedarf im Vollbildmodus angezeigt werden. Im Bild-in-Bild- und Vollbildmodus sind aufwendigere Oberflächen möglich. Allerdings blendet ChatGPT dort auch Bedienelemente ein, die das Widget nicht steuern kann. Halte die dafür vorgesehenen Bereiche auf jedem Gerät frei, etwa für die dauerhaft sichtbare Schaltfläche zum Schließen auf Mobilgeräten. So werden Inhalte nicht abgeschnitten und Bedienelemente bleiben gut erreichbar.
Mit der Zeit hat sich für uns herauskristallisiert, wann welcher Anzeigemodus sinnvoll ist:
| Darstellung | Geeignet für | |
|---|---|---|
| Inline | Standardmodus. Das Widget bleibt im Gesprächsverlauf. | Kurze Interaktionen |
| Vollbild | Das Widget füllt den gesamten Bildschirm aus. Die Chatleiste befindet sich am unteren Rand. | Komplexe Widgets, die viel Platz brauchen, etwa Karten |
| Bild-in-Bild | Das Widget ist so groß wie im Inline-Modus, bleibt aber über dem Gespräch sichtbar. | Widgets, die nach der Generierung der Antwort auch bei Rückfragen im Gespräch relevant bleiben |
6. Eingebettete Oberflächen brauchen ein einheitliches Design
Anfangs waren wir uns unsicher, wie viel gestalterischen Spielraum wir bei einer ChatGPT App nutzen sollten. Die Oberfläche war für die Menschen, die sie bedienen, neu und sollte ihnen dennoch vertraut vorkommen. Dazu brauchten wir ein einheitliches Design, das sowohl zu unseren eigenen Apps als auch zu ChatGPT passt. Ein Widget ist in eine bestehende Oberfläche eingebettet. Anders als bei einem eigenständigen Produkt fallen gestalterische Abweichungen dort sofort auf.
Das OpenAI Apps SDK UI Kit gab uns dafür eine klare Grundlage.
Das Kit basiert auf Tailwind CSS und bietet fertige Komponenten, Symbole und Design-Tokens, die auf das Designsystem von ChatGPT abgestimmt sind. Damit kamen wir schnell voran, und unsere Widgets fügten sich optisch in die Oberfläche ein. Das galt auch für eigene Komponenten, etwa für unsere Mapbox-Integration.
7. Filter in natürlicher Sprache bedienen
Klassische Dashboards haben oft Seitenleisten voller Kontrollkästchen und Schieberegler. Bei einer Oberfläche mit KI-Agenten kann das die Bedienung erschweren. Wer einen Wunsch direkt in natürlicher Sprache formulieren kann, etwa „Sonnige Reiseziele in Europa für unter 200 USD“, sollte dafür nicht erst mehrere Bedienelemente betätigen müssen. Es sollte genügen, den Wunsch zu äußern.
Bei den meisten unserer Apps haben wir deshalb auf sichtbare Filter verzichtet. Statt eine Seitenleiste zum Filtern und Sortieren anzubieten, geben wir dem Modell für unsere Tool-Parameter eine Liste zulässiger Werte (List of Values, LOV).
So kann das Modell die Nachricht direkt als Eingabe verwenden und muss nicht „raten“, welche Optionen verfügbar sind. Es kann die natürlichsprachliche Anfrage unmittelbar in die Parameter übersetzen, die unsere Backend-API erwartet. Sagt jemand „sonnig“, weiß das Modell, dass es das Tool mit weather=“sunny” aufrufen soll.
8. Dateien ermöglichen neue Formen der Interaktion
Bei der Entwicklung komplexerer Apps wurde uns klar, dass Dateien als Eingabe eine zentrale Rolle spielen können. In ChatGPT Apps ermöglichen sie neue Interaktionen. Der Einstieg muss kein Formular oder Filter sein. Er kann auch mit etwas beginnen, das die Person bereits zur Hand hat.
In einer E-Commerce-App kannst du beispielsweise ein Produktfoto im Chat hochladen, das Produkt vom Modell identifizieren lassen und anschließend direkt im Widget passende Angebote finden oder weitere Produkte entdecken.
Dazu müssen beide Seiten des Systems Dateien verarbeiten können. Auf der Modellseite können Tools über openai/fileParams direkt auf Dateien zugreifen, die im Chat hochgeladen wurden. So kann das Modell Bilder oder andere bereitgestellte Inhalte analysieren. Auf der UI-Seite können Widgets mit window.openai.uploadFile und window.openai.getFileDownloadUrl ebenfalls direkt mit Dateien arbeiten. Du kannst also in der Oberfläche zum Hochladen einer Datei auffordern oder Dateien erzeugen, die sich herunterladen und weiterverwenden lassen.
Vom lokalen System in den Produktivbetrieb
Sobald Apps die lokale Entwicklungsumgebung verlassen, stellen sich neue Fragen zu Sicherheit, Konfiguration und Entwicklungswerkzeugen. Darum geht es in dieser dritten Gruppe von Erkenntnissen.
9. CSPs sind das neue CORS
Aus Sicherheitsgründen rendert OpenAI Apps in zwei ineinander verschachtelten Iframes. Content Security Policies (CSPs) sind ein integrierter Mechanismus zur Isolierung von Iframes. In dieser Umgebung werden sie strikt durchgesetzt. Das macht sich oft durch ein bekanntes Fehlerbild bemerkbar: „Lokal funktioniert es, im Produktivbetrieb nicht.“
Während in der klassischen Webentwicklung mitunter eine großzügig formulierte Richtlinie genügt, verlangt das Apps SDK präzise Angaben.
Im App-Manifest musst du deshalb für jede Art der Interaktion genau angeben, welche Domains zugelassen sind:
| Feld | Zweck | Beispiel | Häufige Fehler |
|---|---|---|---|
| connectDomains | API- und XHR-Anfragen | https://api.weather.com | Nur die Produktions-API eintragen und die Staging-API vergessen. |
| resourceDomains | Bilder, Schriftarten, Skripte | https://cdn.jsdelivr.net | Ein allgemeines CDN wie delivr.net verwenden, ohne die Domain freizugeben. |
| frameDomains | Einbetten von Iframes | https://www.youtube.com | Ein YouTube-Video oder eine Mapbox-Instanz einbetten, ohne die Domain freizugeben. |
| redirectDomains | Externe Links, die ohne Warnung geöffnet werden | https://app.alpic.ai | Die Domain für den Checkout oder den OAuth-Callback vergessen. |
Weil wir uns früh um die CSP-Konfiguration gekümmert haben, mussten wir später im Produktivbetrieb deutlich weniger Zeit für die Fehlersuche aufwenden.
10. Kleine Widget-Einstellungen haben große Auswirkungen
Neben den CSPs regeln einige wenige Einstellungen am Widget, welche Aktionen das Widget, das Modell und die Host-Umgebung steuern. Diese Flags sind leicht zu übersehen. Sie legen jedoch wichtige Grenzen für die Navigation, den Tool-Zugriff und die Veröffentlichung fest.
Host und Navigation
widgetDomainist für die Einreichung erforderlich. Der Wert legt fest, wohin die Schaltfläche „In <App> öffnen“ im Vollbildmodus standardmäßig führt. Er spielt auch bei der Freigabe von Origins eine Rolle, da Widgets unter<widgetDomain>.web-sandbox.oaiusercontent.comgerendert werden. MitsetOpenInAppUrlhaben wir je nach Kontext auf den passenden Pfad verwiesen.
Modell und Tool-Zugriff
- Tool-Annotationen müssen den Veröffentlichungsrichtlinien entsprechen. Flags wie
readOnly,destructiveHintundopenWorldHintsind erforderlich und werden bei der Einreichung geprüft. - Die Sichtbarkeit von Tools ist entscheidend. Tools, die für das Modell nicht aufrufbar sein sollen, musst du ausdrücklich als privat kennzeichnen.
Tool-Aufrufe durch das Widget
widgetAccessiblesteuert, ob das Widget mitcallToolselbstständig Tools aufrufen kann.
Für sich genommen mag jede dieser Einstellungen nebensächlich erscheinen. Zusammen bestimmen sie, ob sich die App nach der Veröffentlichung wie vorgesehen verhält.
Kürzere Entwicklungszyklen
Das Apps SDK entwickelt sich schnell weiter, und wir arbeiten gerne mit den neuen Möglichkeiten. Um die Entwicklung einfacher und effizienter zu gestalten, haben wir unser eigenes Open-Source-Framework entwickelt und mit der Community geteilt. Die folgenden Erkenntnisse können dir einige der Schwierigkeiten ersparen, auf die wir anfangs gestoßen sind.
11. Schnelle Entwicklungszyklen brauchen Hot Reload
Als Erstes wollten wir Änderungen schneller ausprobieren können. Ressourcen bleiben wegen ihrer langen Gültigkeitsdauer (TTL) lange im Cache und werden über JSON-RPC weitergeleitet. Deshalb funktioniert das automatische Neuladen einzelner Module, wie es etwa Vite oder Next.js anbieten, bei ChatGPT Apps nicht ohne Anpassungen.
Nachdem wir uns intensiv mit der internen Funktionsweise von Vite beschäftigt hatten, entwickelten wir ein Vite-Plugin, das Widgets direkt in ChatGPT live neu lädt. Es fängt Ressourcenanfragen an den MCP-Server ab und überträgt Änderungen in Echtzeit in den Iframe von ChatGPT. So konnten wir Änderungen in der IDE sofort in ChatGPT sehen und bekamen deutlich schneller Rückmeldung.
12. Nicht jeder Test muss in ChatGPT laufen
Tests in ChatGPT sind der Maßstab. Für die ersten Entwicklungsrunden kommst du mit einem lokalen Emulator aber oft schneller voran. Das gilt besonders, wenn du an Tool-Definitionen arbeitest, für die du in ChatGPT die Verbindung zum benutzerdefinierten MCP-Server aktualisieren musst.
Deshalb haben wir einen schlanken lokalen Emulator entwickelt, der die Host-Umgebung von ChatGPT nachbildet und Debugging-Werkzeuge sowie App-spezifische Logs mitbringt. Damit konnten wir Änderungen am React-Zustand und am Layout innerhalb von Millisekunden ausprobieren. Für die Prüfung von Modellinteraktionen und Grenzfällen testeten wir direkt in ChatGPT.
13. Tests auf Mobilgeräten brauchen gezielte Unterstützung
Bei Tests auf Mobilgeräten kam eine weitere Hürde hinzu. Zum Testen in ChatGPT musst du deinen lokalen Server über einen Tunnel erreichbar machen. Vite verwendet aber standardmäßig localhost, sodass dieselbe URL von anderen Geräten aus nicht erreichbar ist.
Wir haben unser Vite-Plugin deshalb um die Domain-Weiterleitung für Ports erweitert, die über einen Tunnel erreichbar sind. Damit konnten wir sowohl auf iOS- als auch auf Android-Geräten testen und mobile Tests in unseren regulären Entwicklungsablauf aufnehmen.
14. Vertraute Abstraktionen wie React-Hooks beschleunigen die Frontend-Entwicklung
Das Apps SDK bietet umfangreiche Funktionen, stellt sie aber überwiegend über JavaScript-APIs mit niedrigem Abstraktionsniveau bereit. Da wir schon lange mit React arbeiten, wollten wir auf vertraute Konzepte zurückgreifen.
Deshalb haben wir Abstraktionen eingeführt, die sich gut mit React verwenden lassen. Dazu zählen Hooks wie useCallTool, useWidgetState und useLocale sowie Funktionen für eine anspruchsvollere Zustandsverwaltung, etwa createStore auf Basis von Zustand für komplexe Datenflüsse. Mit diesen vertrauten Frontend-Mustern brauchten wir weniger wiederkehrenden Standardcode und konnten Widgets ähnlich entwickeln wie moderne Webanwendungen.
Wie aus unseren Erfahrungen ein Codex Skill wurde
15. Erfahrungen in wiederverwendbare Werkzeuge übersetzen
Bei mehreren Apps stießen wir auf dieselben Muster. Es kostete uns Zeit, die Lösungen jedes Mal aufs Neue zu erarbeiten. Um die Entwicklung von ChatGPT Apps schneller und planbarer zu machen, haben wir unsere Erkenntnisse direkt in unsere Werkzeuge einfließen lassen und sie der Community zugänglich gemacht.
Daraus sind zwei Projekte entstanden, die sich ergänzen:
- Das Skybridge-Framework: Dieses Open-Source-Framework für React stellt viele der hier beschriebenen Muster als wiederverwendbare Bausteine bereit. Dazu gehören unsere Hooks (
useCallTool,useToolInfo), die Entwicklungswerkzeuge (HMR und lokaler Emulator) und das data-llm-Attribut. - Der Codex Skill chatgpt-apps-builder: Auf Basis des Frameworks haben wir einen eigenen Codex Skill entwickelt, der dich über den gesamten Lebenszyklus einer App hinweg unterstützt:
- Ideenfindung: Gemeinsam überlegen, wie sich eine App für die Zusammenarbeit mit einem Agenten gestalten lässt, statt lediglich die Webversion zu portieren.
- Codegenerierung: Das React-Frontend und das MCP-Server-Backend parallel erstellen und beide mit den passenden UX- und UI-Mustern vorkonfigurieren.
- Lokale Tests: Entwicklungsserver starten und lokale Apps mit ChatGPT verbinden, um Änderungen per Hot Reload in Echtzeit auszuprobieren.
- Qualitätssicherung und Veröffentlichung: Die App systematisch anhand der Einreichungsrichtlinien von OpenAI prüfen. Dazu gehören die Validierung der CSPs, die Berücksichtigung freizuhaltender Bildschirmbereiche und Tests im Produktivbetrieb.
- Bereitstellung der App: Unterstützung bei den letzten Schritten, um die App auszuliefern und weiterzuentwickeln.
Um den Skill zu installieren und zu verwenden, führe diesen Befehl aus:
npx skills add alpic-ai/skybridge
Fazit
Wer ChatGPT Apps entwickelt, muss neu überlegen, wie Kontext weitergegeben wird, wie sich Oberflächen verhalten und wie Menschen mit Modellen zusammenarbeiten. Viele unserer Erkenntnisse gehen auf Situationen zurück, in denen vertraute Muster aus der Webentwicklung in Systemen mit KI-Agenten an ihre Grenzen stießen.
Wir teilen diese Erfahrungen und haben sie in unser Open-Source-Framework und unseren Codex Skill einfließen lassen. Damit möchten wir Teams die Zeit ersparen, die es kostet, dieselben Probleme erneut zu lösen. So bleibt mehr Raum, die Möglichkeiten dieser neuen Form der Interaktion zu erkunden. Die überzeugendsten ChatGPT Apps werden über die einfache Portierung bestehender Produkte hinausgehen und von Anfang an für die Zusammenarbeit mit KI konzipiert sein.