Apps

Apps integrieren externe Systeme via REST-API direkt in den AI Agent, um Daten abzurufen, zu validieren oder Systemänderungen auszulösen.

Wo finde ich Apps?

Apps werden auf Workspace-Ebene verwaltet. Du erreichst sie über die Navigationsleiste oder das Workspace Dashboard.

Workspace → Apps

In diesem Bereich siehst du alle Apps, die in deinem Workspace vorhanden sind. Jede App wird mit ihrem Namen und einer eindeutigen ID angezeigt. Über den Button „Neue App anlegen" erstellst du eine neue App.

Im Workspace angelegte App müssen im jeweiligen AI Agent noch installiert werden.

---

Was sind Apps?

Eine App ist eine strukturierte Verbindung zu einer externen REST-API. Sie bündelt alle Konfigurationen, die nötig sind, um Daten aus einem externen System abzurufen oder dorthin zu senden – von der Authentifizierung bis hin zur Definition einzelner API-Endpunkte.

Typische Anwendungsfälle

• Informationsabfragen: Abruf externer Daten, z. B. Sendungsstatus über eine zuvor erfragte Sendungsnummer oder offene Rechnungsbeträge.

• Datenvalidierung: Überprüfung von IDs, Zugangsdaten oder Formularwerten auf Richtigkeit oder Existenz.

• Datenspeicherung: Übermittlung von Änderungen, z. B. bei Adress- oder Kontaktdatenaktualisierungen oder Stornierungen von Bestellungen.

Voraussetzungen

Damit eine App funktioniert, muss die angebundene API folgende technische Anforderungen erfüllen:

• API-Typ: REST (Representational State Transfer)

• Unterstützte HTTP-Methoden: GET, POST, PATCH, PUT, DELETE

• Datenformat der Rückgabe: JSON

Arrays in der API-Antwort eines einzelnen Endpunkts können aktuell nicht direkt verarbeitet werden. Als Workaround muss die Antwortstruktur „geflattert" werden – d. h. verschachtelte Array-Strukturen werden in eine flache Key-Value-Struktur umgewandelt.

---

Aufbau einer App

Eine App besteht aus mehreren Bereichen, die jeweils eine eigene Funktion haben. Du navigierst zwischen ihnen über die linke Seitenleiste innerhalb der App oder das App Dashboard. Die Bereiche umfassen: Übersicht, Basisdaten, Verbindungen, Module, DataCards, Beschreibung, Veröffentlichen, Einstellungen.

Basisdaten

Basisdaten enthalten allgemeine, wiederverwendbare Werte der App – zum Beispiel die Basis-URL einer API. Diese Daten werden automatisch jedem Request der App hinzugefügt und stehen in allen Modulen und Verbindungen über die Syntax {{schlüsselname}} zur Verfügung.

Beispiel:

{
  "baseUrl": "https://api.chucknorris.io"
}

Dieser Wert kann anschließend in Modulen als {{baseUrl}} referenziert werden, z. B.:

{
  "url": "{{baseUrl}}/jokes/random",
  "method": "GET"
}

---

Verbindungen

Verbindungen steuern die Authentifizierung gegenüber der externen API. Jede Verbindung führt beim Installieren der App einen Health Check durch – ein automatischer Test-Request, der prüfen soll, ob die Verbindung funktioniert. Die Verbindung gilt als aktiv, wenn die API einen HTTP-Statuscode zwischen 200 und 299 zurückgibt.

Mehrere Module können dieselbe Verbindung nutzen, sofern sie auf die gleiche Authentifizierung angewiesen sind.

Verbindungstypen

Beim Erstellen einer Verbindung wählst du einen von drei Typen:

• Api-Key: Authentifizierung über einen API-Schlüssel.

• Basic Auth: Authentifizierung über Benutzername und Passwort.

• Ohne Authentifizierung: Für APIs, die keine Authentifizierung erfordern.

Verbindung konfigurieren

Jede Verbindung hat zwei Tabs:

• Verbindung: Hier definierst du die Abfragestruktur für den Health Check als JSON – also URL und Methode des Test-Requests. Auf die Basisdaten kannst du auch hier über {{schlüsselname}} zugreifen.

• Parameter: Hier kannst du Parameter als JSON hinterlegen, die in der Abfragestruktur verwendet werden können.

Beispiel:

{
  "url": "{{baseUrl}}/api/health",
  "method": "GET",
  "headers": {
    "x-api-key": "{{parameters.apiKey}}"
  }
}

---

Module

Module definieren die eigentlichen API-Aufrufe. Jedes Modul entspricht einem bestimmten Endpunkt oder einer Aktion der API. Module werden als Schritte im Flow-Builder eingebunden und führen dort automatisierte Aktionen aus.

Aktuell unterstützen Module den Typ Action – damit löst ein Modul eine definierte API-Anfrage aus, wenn es im Flow ausgeführt wird.

Modul konfigurieren

Ein Modul hat drei Tabs:

Request

Hier definierst du die Abfragestruktur des API-Calls als JSON. Die Struktur erbt automatisch die Werte aus den Basisdaten. Du kannst also direkt auf {{baseUrl}} und andere dort definierte Schlüssel zugreifen.

Zusätzlich verknüpfst du hier das Modul mit einer Verbindung – diese liefert die Authentifizierungsinformationen für den Request.

Parameter

Hier legst du die Eingabeparameter des Moduls als JSON-Array fest. Diese Parameter können im Request verwendet werden – z. B. als Werte in der URL, im Body oder in Query-Parametern.

Output

Hier definierst du die Ausgabeparameter des Moduls als JSON-Array. Pro Ausgabeparameter gibst du Folgendes an:

• name: Schlüsselname im API-Response

• type: Datentyp (z. B. text)

• label: Anzeigename im Flow Builder/ Variablen-Picker

Die definierten Ausgabeparameter stehen nach dem Ausführen des Moduls imFlow Builder als Variablen zur Verfügung.

Beispiel:

[
  {
    "name": "value",
    "type": "text",
    "label": "Witz"
  },
  {
    "name": "id",
    "type": "text",
    "label": "ID"
  }
]

---

DataCards

DataCards sind Informationskarten, die im Posteingang auf der rechten Seite in den Konversationsinformationen angezeigt werden. Sie zeigen automatisch Daten aus Apps an – z. B. Kunden- oder Bestellinformationen – und ermöglichen so einen schnellen Überblick, ohne den Chat verlassen zu müssen.

Für jede DataCard hinterlegst du einen Namen und eine URL, von der die Daten geladen werden.

---

Beschreibung

Für jede App kann eine Beschreibung in Markdown hinterlegt werden. Der Editor zeigt links die Markdown-Eingabe und rechts eine Live-Vorschau der gerenderten Ausgabe.

Die Beschreibung hilft dabei, den Zweck, die Funktionsweise und die Nutzung der App zu dokumentieren – und erleichtert anderen Nutzern die Einbindung im Flow Builder.

---

Veröffentlichen

Über den Bereich „Veröffentlichen" kannst du eine Veröffentlichung deiner App oder deren neuen Version beantragen. Veröffentlichte Apps sind im App-Marktplatz für alle Nutzer der Plattform verfügbar.

Der Prozess läuft wie folgt ab:

1. Du legst eine App an oder nimmst Änderungen an der App vor.

2. Du klickst im Navigationspunkt „Veröffentlichen" auf „App veröffentlichen".

3. Das Epic AI-Team prüft die App und gibt sie frei.

4. Nach der Freigabe ist die App im App-Marktplatz verfügbar.

Änderungen, die nach einer Veröffentlichung vorgenommen werden, sind nicht automatisch öffentlich. Um Änderungen zu veröffentlichen, muss erneut eine Veröffentlichung beantragt werden.

Der Bereich zeigt dir den aktuellen Status deiner App sowie eine Versionshistorie deiner bisherigen Veröffentlichungen.

Die möglichen Statuswerte sind:

• In der Warteschlange: Die Anfrage wurde eingereicht und wartet auf Bearbeitung.

• In Bearbeitung: Das Epic AI-Team prüft die App gerade.

• Angenommen: Die App wurde freigegeben und ist im Marktplatz verfügbar.

• Zurückgezogen: Die Veröffentlichung wurde zurückgezogen.

---

Einstellungen

In den Einstellungen kannst du folgende Konfigurationen vornehmen:

• Allgemein: Den Namen der App ändern und speichern.

• Logo & Erscheinungsbild: Logo hochladen oder entfernen (JPEG, PNG oder SVG, maximal 2 MB) sowie eine Hintergrundfarbe festlegen. Beides bestimmt, wie die App z. B. im Flow Builder dargestellt wird.

• Event-Emitter: Eine URL hinterlegen, an die ausgelöste Events der App gesendet werden – z. B. wenn die App installiert wird. Jede Anfrage enthält die zugehörige AI Agent-ID und App-ID als Query-Parameter.

• Details: Technische Informationen zur App – App-ID (kopierbar), Erstellungsdatum und Datum der letzten Aktualisierung.

• App löschen: Die App dauerhaft löschen. Alle Daten gehen dabei verloren und können nicht wiederhergestellt werden.

Das Löschen einer App kann nicht rückgängig gemacht werden. Prüfe vorher, ob die App noch in aktiven AI Agents eingebunden ist.

---

App erstellen und verwalten

App erstellen

1. Navigiere zu Workspace → Apps.

2. Klicke auf „Neue App anlegen".

3. Vergib einen Namen und bestätige mit „Erstellen". Du landest direkt in der App-Übersicht.

4. Konfiguriere die App über die Bereiche Basisdaten, Verbindungen, Module, DataCards und Beschreibung.

Verbindung erstellen

1. Öffne die gewünschte App und navigiere zu Verbindungen.

2. Klicke auf „Erstellen".

3. Vergib einen Namen und wähle den passenden Typ (Api-Key, Basic Auth oder Ohne Authentifizierung).

4. Klicke auf „Verbindung erstellen", um die Verbindung anzulegen.

5. Konfiguriere anschließend den Health-Check-Request im Tab Verbindung und hinterlege bei Bedarf Parameter im Tab Parameter.

6. Speichere die Verbindung über „Speichern".

Modul erstellen

1. Öffne die gewünschte App und navigiere zu Module.

2. Klicke auf „Modul erstellen".

3. Vergib einen Namen und bestätige mit „Erstellen".

4. Konfiguriere den Request im Tab Abfrage und verknüpfe das Modul über „Verbindung hinzufügen" mit einer Verbindung.

5. Lege bei Bedarf Eingabeparameter im Tab Parameter und Ausgabeparameter im Tab Output fest.

6. Speichere das Modul über „Speichern".

DataCard erstellen

1. Öffne die gewünschte App und navigiere zu DataCards.

2. Klicke auf „DataCard erstellen".

3. Vergib einen Namen und hinterlege die URL, von der die Daten geladen werden sollen.

4. Klicke auf „DataCard erstellen".

Beschreibung bearbeiten

1. Öffne die gewünschte App und navigiere zu Beschreibung.

2. Schreibe deine Dokumentation im Markdown-Editor links; die Vorschau rechts aktualisiert sich live.

3. Klicke auf „Speichern", um die Änderungen zu übernehmen, oder „Zurücksetzen", um sie zu verwerfen.

App löschen

1. Öffne die gewünschte App und navigiere zu Einstellungen.

2. Klicke auf „Löschen".

Das Löschen ist endgültig. Alle Daten der App – inkl. Verbindungen, Module und DataCards – gehen unwiderruflich verloren.

---

Beispiel: Chuck Norris API anbinden

Dieses Beispiel zeigt, wie du eine einfache öffentliche REST-API (ohne Authentifizierung) als App einrichtest und ein Modul erstellst, das einen zufälligen Witz abruft.

1. App erstellen

Navigiere zu Workspace → Apps und lege eine neue App mit dem Namen „Chuck Norris API" an.

2. Basisdaten hinterlegen

Navigiere zu Basisdaten und trage die Basis-URL der API ein:

{
  "baseUrl": "https://api.chucknorris.io"
}

Speichere die Eingabe.

3. Verbindung erstellen

Navigiere zu Verbindungen und erstelle eine neue Verbindung:

• Name: Chuck Norris Status

• Typ: Ohne Authentifizierung

Konfiguriere den Health-Check-Request im Tab Verbindung:

{
  "url": "{{baseUrl}}",
  "method": "GET"
}

Speichere die Verbindung.

4. Modul erstellen

Navigiere zu Module und erstelle ein neues Modul:

• Name: get_joke

Konfiguriere den Request im Tab Request:

{
  "url": "{{baseUrl}}/jokes/random",
  "method": "GET"
}

Verknüpfe das Modul mit der Verbindung „Chuck Norris Status".

Wechsle zum Tab Output und definiere die Ausgabeparameter:

[
  {
    "name": "value",
    "type": "text",
    "label": "Witz"
  },
  {
    "name": "id",
    "type": "text",
    "label": "ID"
  }
]

Speichere das Modul.

Das Modul get_joke ist jetzt einsatzbereit und kann im Flow Builder als Schritt eingebunden werden. Nach der Ausführung stehen die Variablen Witz und ID im Flow zur Verfügung.

---

Arrays in der API-Response (Workaround)

Arrays in der API-Antwort eines einzelnen Endpunkts können aktuell nicht direkt verarbeitet werden. Falls ein Endpunkt ein Array zurückgibt, muss die Antwortstruktur „geflattert" werden – d. h. die verschachtelten Einträge werden auf oberster Ebene mit einem Index als Präfix abgelegt.

Beispiel – Original (nicht verarbeitbar):

{
  "total": 2,
  "results": [
    {
      "id": "1001",
      "properties": {
        "name": "Firma A",
        "amount": "5000",
        "status": "offen"
      }
    },
    {
      "id": "1002",
      "properties": {
        "name": "Firma B",
        "amount": "7500",
        "status": "abgeschlossen"
      }
    }
  ]
}

Beispiel – Geflattert (verarbeitbar):

{
  "total": 2,
  "0_id": "1001",
  "0_name": "Firma A",
  "0_amount": "5000",
  "0_status": "offen",
  "1_id": "1002",
  "1_name": "Firma B",
  "1_amount": "7500",
  "1_status": "abgeschlossen"
}

Merkmale der geflatteten Struktur:

• Jeder Eintrag aus results erhält einen numerischen Index als Präfix (0_, 1_, …).

• Alle verschachtelten Felder werden auf oberster Ebene abgelegt.

• Meta-Informationen wie total oder Paging-Angaben bleiben unverändert erhalten.

---

Best Practices

• Basisdaten sinnvoll nutzen: Hinterlege wiederkehrende Werte wie die Basis-URL in den Basisdaten. So musst du Änderungen – z. B. bei einem API-Versionswechsel – nur an einer Stelle vornehmen, statt in jedem Modul einzeln.

• Sprechende Namen vergeben: Vergib für Module und Verbindungen Namen, die ihren Zweck klar beschreiben. Im Flow Builder siehst du später nur den Modulnamen – ein Name wie get_sendungsstatus ist deutlich hilfreicher als modul_1.

• Beschreibung pflegen: Nutze die Beschreibungsfunktion, um den Zweck der App und die Funktionsweise der einzelnen Module zu dokumentieren. Das erleichtert die Einbindung durch andere Teammitglieder erheblich.

• Health Check sorgfältig konfigurieren: Der Health Check wird beim Installieren der App ausgeführt. Wähle einen Endpunkt, der zuverlässig erreichbar ist und keine Seiteneffekte hat – z. B. einen einfachen GET-Request auf die Basis-URL.

• Output-Parameter aussagekräftig benennen: Das label-Feld im Output-Tab bestimmt, wie die Variable später im Flow Builder und im Variablen-Picker angezeigt wird. Wähle Labels, die den Inhalt klar beschreiben – z. B. „Sendungsstatus" statt „value".