Zum Inhalt springen
Kaiross

API, Widget, Slack, Teams, SCIM und synchronisierte Quellen

Veröffentlichte Agenten antworten auch ausserhalb der App: auf Ihrer Website, in Slack und Teams oder in Ihren Programmen. Und das Knowledge bleibt mit den Firmenordnern abgeglichen.

Stand:

REST-API

Basis: https://app.kaiross.ch/api/v1, mit dem Header Authorization: Bearer kai_… (Schlüssel aus Einstellungen → API-Schlüssel, siehe so erstellen Sie ihn). Die Agenten müssen veröffentlicht sein. Die vollständige Referenz (OpenAPI 3.1) steht auf der Seite API und MCP der App, mit Beispielen in cURL, Node.js und Python.

AnfrageZweck
GET /agentsVeröffentlichte Agenten des Workspace.
POST /agents/{id}/chatFrage an den Agenten: message, optional conversationId; Antwort als Stream (SSE) oder JSON mit "stream": false.
GET /agents/{id}/conversations, GET /conversations/{id}/messagesGespräche und Nachrichten.
POST /automations/{id}/run, GET /runs/{id}Start einer Automation und Status der Ausführung.
POST /actions/{id}/confirm, POST /actions/{id}/cancelEine vom Agenten vorgeschlagene Aktion bestätigen oder abbrechen.
Liste der Agenten
curl https://app.kaiross.ch/api/v1/agents \
  -H "Authorization: Bearer kai_…"
Eine Frage, Antwort als JSON
curl https://app.kaiross.ch/api/v1/agents/<agent-id>/chat \
  -H "Authorization: Bearer kai_…" \
  -H "Content-Type: application/json" \
  -d '{"message": "…", "stream": false}'

Limits pro Schlüssel: 120 Anfragen pro Minute, davon 30 Chats. Chat-Antworten tragen den Header X-AI-Generated: true.

Widget für die Website

  1. Veröffentlichen Sie den Agenten (Tab Allgemein → Agent veröffentlicht (externer Zugriff)).
  2. Öffnen Sie den Tab Widget, aktivieren Sie Widget aktiv und legen Sie Titel, Farbe, Position und Willkommensnachricht fest.
  3. Tragen Sie unter Autorisierte Domains (eine pro Zeile) die Websites ein, auf denen es erscheint (*.domain.ch schliesst Subdomains ein). Vermeiden Sie *, das es überall erlaubt.
  4. Legen Sie Maximale Nachrichten pro Stunde fest (Standard 300) und bei Bedarf den Text des KI-Hinweis: leer = Standardtext in der Sprache der Besucher (EU AI Act, Art. 50).
  5. Tragen Sie unter Datenschutzerklärung die https-Adresse der Datenschutzerklärung Ihrer Website ein: Besucher sehen sie neben dem Hinweis, und sie muss den Assistenten erwähnen.
  6. Speichern Sie und kopieren Sie das Snippet aus Installation in Ihre Website. Vorschau öffnet das Widget in einem neuen Tab, sobald der Agent veröffentlicht und das Widget aktiviert und gespeichert ist.
Schwebende Schaltfläche (vor </body>)
<script src="https://app.kaiross.ch/api/widget.js" data-widget-key="wk_…" async></script>
Chat auf der ganzen Seite
<iframe src="https://app.kaiross.ch/api/widget/wk_…/frame" title="Kaiross"
  style="width:100%;height:640px;border:0;border-radius:12px"></iframe>

Das Widget folgt der Sprache der Seite; data-lang="it|de|fr|en" legt sie fest. Automatische Aktionen für Besucher sind standardmässig aus: Lassen Sie sie aus, wenn der Agent schreibende Tools hat.

Unter Unterhaltungen von Besuchenden lesen Sie die Unterhaltungen aus dem Widget. Besucher können ihre eigene im Widget löschen, und auf Anfrage entfernen Sie eine mit Unterhaltung löschen. Wie lange sie aufbewahrt werden, legen Sie unter Daten und Aufbewahrung fest.

Register Widget eines Agenten
Register Widget eines Agenten
Das Register Widget: Das Widget funktioniert nur mit veröffentlichtem Agenten.

Slack-Bot

  1. Veröffentlichen Sie den Agenten, öffnen Sie dann den Tab Kanäle und klicken Sie auf Slack verbinden: Autorisieren Sie die App in Ihrem Slack-Workspace.
  2. Laden Sie die App in Kanäle ein (/invite @Kaiross) und erwähnen Sie sie; privat schreiben Sie ihr im Bereich Apps von Slack.
  3. Klicken Sie zur Kontrolle auf Test senden.

Der Bot antwortet nur Mitgliedern des Kaiross-Workspace, die den Agenten nutzen dürfen: Slack-Benutzer werden über die E-Mail erkannt.

Microsoft-Teams-Bot

  1. Erstellen Sie im Azure-Portal eine Ressource «Azure Bot» (App-Typ: Single Tenant empfohlen) und notieren Sie App ID und Tenant ID.
  2. Setzen Sie unter Konfiguration den Messaging endpoint aus dem Tab Kanäle; fügen Sie unter den Kanälen in Azure Microsoft Teams hinzu.
  3. Erstellen Sie in der in Entra ID registrierten App ein Client-Secret und fügen Sie es mit App ID und Tenant ID in Kaiross ein, dann speichern.
  4. Klicken Sie auf App-Paket herunterladen und laden Sie es in Teams hoch (Apps → Apps verwalten → App hochladen) oder im Teams Admin Center für das ganze Unternehmen.

SCIM-Provisioning (Entra ID, Okta)

Mit SCIM werden die Benutzer Ihres Identity Providers zu Mitgliedern des Workspace, und Gruppen entsprechen den Kaiross-Rollen mit demselben Namen. Wird ein Benutzer deaktiviert, verliert er den Zugang zum Workspace.

  1. Kopieren Sie unter Einstellungen → Workspace-Sicherheit → SCIM-Provisioning die SCIM-Basis-URL (https://app.kaiross.ch/api/scim/v2) und klicken Sie auf Token generieren. Kopieren Sie das Token sofort: Es wird später nicht mehr angezeigt.
  2. Microsoft Entra ID: Unternehmensanwendungen → Neue Anwendung → Eigene Anwendung erstellen; Provisioning → Automatisch mit Mandanten-URL = SCIM-Basis-URL und Geheimes Token = Token; Mapping userName ← userPrincipalName (oder mail), externalId ← objectId; Benutzer und Gruppen zuweisen und das Provisioning starten.
  3. Okta: Applications → Create App Integration, SCIM-Provisioning aktivieren; SCIM connector base URL = SCIM-Basis-URL, Unique identifier = userName, Authentication = HTTP Header (Bearer) mit dem Token; unter To App Create Users, Update User Attributes und Deactivate Users aktivieren; mit Push Groups Gruppen mit Rollen verknüpfen.

Kaiross entfernt nie den letzten Administrator: Eine solche Anfrage wird abgelehnt.

Synchronisierte Quellen

Eine Quelle hält das Knowledge des Agenten mit einem Ordner abgeglichen: Neue und geänderte Dateien werden indexiert, entfernte gelöscht. Dienste: Google Drive, SharePoint/OneDrive, Dropbox, Box, S3, FTP/SFTP und lokale Ordner mit dem sync-agent.

  1. Erstellen Sie zuerst die Verbindung unter Integrationen (z. B. Google Drive oder SharePoint).
  2. Öffnen Sie im Agenten Synchronisierung → Quelle hinzufügen, wählen Sie die Verbindung und den Ordner.
  3. Legen Sie Häufigkeit, Unterordner einschliessen, Maximale Grösse (MB) und allfällige Filter fest (Nur diese Formate, Pfade ausschliessen, die Folgendes enthalten), dann Erstellen und synchronisieren.

Berechtigungen der Quelle beachten (standardmässig aktiv): Jedes Dokument ist im Chat nur für Personen sichtbar, die es in der Quelle öffnen können (Benutzer, Domains und Gruppen von Drive, SharePoint, Dropbox oder Box). Ist die Option aus, sehen alle Benutzer des Agenten alle synchronisierten Dokumente.

Lokale Ordner: sync-agent

Für einen Ordner auf einem PC oder Dateiserver sendet der sync-agent, ein kleines Programm (Node.js 20 oder neuer, keine zu installierenden Abhängigkeiten), neue oder geänderte Dateien an Kaiross. Das Paket des sync-agent erhalten Sie von Kaiross.

  1. Im Agenten: Synchronisierung → Quelle hinzufügen → Woher: Ordner auf PC oder Server (sync-agent) → Erstellen und Token generieren. Das Token (ks_…) ist nur einmal sichtbar.
  2. Klicken Sie auf config.json kopieren und speichern Sie die Datei im Ordner des sync-agent: serverUrl ist die Kaiross-Adresse gefolgt von /api, watchPath der zu synchronisierende Ordner.
  3. Testen Sie mit npm start und installieren Sie ihn dann als Dienst beim Systemstart (macOS, Windows, Linux) mit npm run install-service.
config.json
{
  "serverUrl": "https://app.kaiross.ch/api",
  "token": "ks_…",
  "watchPath": "C:\\Data\\Shared",
  "fullScanMinutes": 30
}
Test, Installation und Entfernung des Dienstes
npm start
npm run install-service
npm run uninstall-service