Integrationen

Verbinden Sie Ihre KI-Agenten mit externen Systemen. Fügen Sie einen MCP-Server hinzu, importieren Sie eine OpenAPI-Spezifikation oder richten Sie HTTP-Endpunkte von Hand ein. Danach hinterlegen Sie Zugangsdaten sicher in der Secret-Verwaltung und testen alles direkt im Dashboard.

Integrationen erweitern die Fähigkeiten Ihres Agenten über das Beantworten von Fragen aus der Wissensdatenbank hinaus. Über eine Verbindung kann Ihr Agent während eines Gesprächs externe APIs aufrufen: Live-Daten abfragen, den Lagerbestand prüfen, den Status einer Bestellung abrufen oder Abläufe in anderen Systemen auslösen.

Sie verwalten Integrationen unter Integrationen in der Seitenleiste. Die Seite hat zwei Tabs:

• Tools: die Verbindungen, die Ihre Agenten aufrufen können. Jede Verbindung steuert ein oder mehrere Tools bei.
• Secrets: verschlüsselte API-Schlüssel und Zugangsdaten, auf die Verbindungen mit $secret:key verweisen.

Verbindungen und Secrets legen Sie einmal pro Organisation an, und alle Agenten teilen sie. Jeder Agent wählt dann aus, welche Verbindungen er nutzt (siehe Tools mit Agenten verknüpfen).

Wer was darf

Mitglieder mit der Rolle Mitglied sehen den Eintrag Integrationen in der Seitenleiste nicht. Öffnen sie die URL direkt, werden sie zum Chat weitergeleitet. Builder können alles ansehen und bestehende Tools mit Agenten verknüpfen. Um Verbindungen und Secrets zu erstellen oder zu ändern, braucht es die Rolle Admin oder Owner.

Integrierte Tools

Neben Verbindungen verfügen Agenten über eine Reihe integrierter Tools. Die meisten davon richten Sie im Agenten-Editor ein (Tab Konfigurieren), nicht auf der Seite Integrationen:

Verbindungen

Eine Verbindung ist ein externes System, das Ihre Organisation angebunden hat. Jede Verbindung steuert ein oder mehrere Tools bei, die ein Agent aufrufen kann, wenn er entscheidet, dass die Aktion zum Gespräch passt.

URL und Zugangsdaten richten Sie einmal ein, und zwar an der Verbindung. Alles darunter übernimmt sie. Jeder Agent schaltet dann die Verbindungen ein, die er braucht, mit allen ihren importierten Tools.

Es gibt zwei Arten. Sie wählen sie im ersten Schritt beim Hinzufügen:

Eine dritte Karte, Managed, sehen nur Mitarbeitende der botts.ai Plattform. Siehe Managed-Tools.

Eine Verbindung hinzufügen

Klicken Sie im Tab Tools auf Neues Tool. Das Hinzufügen läuft über einen Assistenten in drei Schritten. Eine Anzeige Quelle → Verbindung → Importieren zeigt, wo Sie stehen. Mit einem Klick darauf wechseln Sie zwischen Schritten, die Sie bereits besucht haben.

Wenn Sie eine bestehende Verbindung bearbeiten, beginnen Sie bei Schritt 2. Die Quelle einer Verbindung lässt sich nach dem Erstellen nicht mehr ändern.

Der Katalog

Schritt 1 zeigt unter Beliebte Integrationen einen kuratierten Katalog mit rund zwei Dutzend Anbietern, als eine einzige Liste, in der die Einträge zuoberst stehen, die Sie heute schon verbinden können. Über die Suche filtern Sie die Liste nach Name, Beschreibung oder Kategorie (CRM, Handel, Support, Produktivität, Marketing, Zahlungen, Schweizer Unternehmenssoftware). Die meisten Einträge sind MCP-Server; einige wenige, darunter Bexio, weclapp und lexoffice, sind OpenAPI-Importe. Jeder Eintrag zeigt mit einem Chip MCP oder API, welche Art er ist.

Jeder Eintrag trägt ein Vertrauens-Badge und einen Hinweis zur Authentifizierung. Die Badges lauten Offiziell (der Endpunkt gehört dem Anbieter selbst und stammt aus dessen Dokumentation oder Registry-Eintrag), Verifiziert und Community. Heute sind alle Einträge im Katalog Offiziell. Der Hinweis zur Authentifizierung lautet Ohne Login, API-Schlüssel oder OAuth (bald).

Jede URL im Katalog wurde vom eigenen Backend von botts.ai aus geprüft. Dabei kam entweder ein vollständiger MCP-Handshake zustande, oder der Server antwortete mit einer Authentifizierungsabfrage, die belegt, dass URL und Transport echt sind. Einträge, die als einzige Anmeldung OAuth unterstützen, werden angezeigt, sind aber deaktiviert, weil der MCP-Client noch keinen interaktiven OAuth-Ablauf ausführt. Aus demselben praktischen Grund sind Einträge deaktiviert, die mehr eigene Header brauchen, als das Formular speichern kann.

MCP-Server

Das Model Context Protocol (MCP) ist ein offener Standard, über den KI-Assistenten Tools zur Verfügung gestellt werden. Statt jeden Endpunkt selbst zu beschreiben, verweisen Sie botts.ai auf einen Remote-MCP-Server. botts.ai fragt den Server dann, was er kann.

Einen Server verbinden

1. Wählen Sie in Schritt 1 MCP-Server oder einen MCP-Anbieter aus dem Katalog.
2. Geben Sie die Server-URL (zum Beispiel https://api.example.com/mcp/) und unter Servername einen Namen ein. Name und Beschreibung übernimmt botts.ai beim Verbinden vom Server, und Sie können sie anpassen.
3. Richten Sie die Authentifizierung ein, falls der Server sie verlangt: Keine, Bearer Token, Basic Auth oder Benutzerdefinierter Header (siehe Authentifizierung). Login Token funktioniert nur bei HTTP-API-Verbindungen, und MCP-Verbindungen haben kein Feld Zusätzliche Header.
4. Starten Sie den Verbindungstest. botts.ai führt einen MCP-Handshake durch und listet die Tools des Servers auf.

Manche Server antworten unter /mcp, andere unter /mcp/. Schlagen der Verbindungstest oder das Laden der Tools unter der eingegebenen Adresse fehl, versucht botts.ai es einmal mit der jeweils anderen Variante (mit oder ohne abschliessenden Schrägstrich). Kommt diese weiter, trägt botts.ai sie für Sie ins Feld ein.

Tools importieren

Werden die Tools eines Servers erkannt, sind sie damit noch nicht aktiv. Klicken Sie im Schritt Importieren auf Tools laden: botts.ai fragt den Server nach seinen Tools und listet sie mit ihren Beschreibungen auf. Beim ersten Laden sind alle Tools angehakt. Entfernen Sie den Haken bei denen, die Sie nicht wollen, und klicken Sie dann auf Speichern (die Schaltfläche bleibt deaktiviert, bis mindestens ein Tool angehakt ist). Um die Auswahl später zu ändern, klappen Sie auf der Karte der Verbindung die Anzahl der Tools auf, klicken auf Tools verwalten und danach auf Erneut laden und Speichern. Jedes importierte Tool wird zu einem normalen Agenten-Tool bei jedem Agenten, für den diese Verbindung eingeschaltet ist.

Die Tools werden unter einem Namen mit Namensraum registriert, servername__toolname. So kommen sich zwei Server, die beide ein Tool search anbieten, nie in die Quere.

Wenn sich ein Server ändert

botts.ai speichert die Tool-Definitionen, die Sie importiert haben, und Ihre Agenten verwenden genau diese. Fügt der Server später Tools hinzu, ändert oder entfernt er welche, ändert sich für Ihre Agenten nichts, bis ein Admin Tools verwalten öffnet, auf Erneut laden klickt und speichert.

Beim erneuten Laden bleiben die importierten Tools angehakt, solange der Server sie noch anbietet. Tools, die der Server nicht mehr anbietet, verschwinden, und neu angebotene Tools erscheinen ohne Haken. So wird nie etwas Neues automatisch freigegeben. Beim Speichern übernimmt botts.ai für die angehakten Tools die aktuellen Beschreibungen und Eingabeschemas des Servers. Lesen Sie diese deshalb, bevor Sie speichern. Das ist Absicht: Eine Tool-Beschreibung ist eine Anweisung an Ihr Modell. Ein Server, der ein Tool unbemerkt neu definiert, könnte sonst verändern, was Ihr Agent tut.

Ändern Sie die Server-URL einer Verbindung oder wechseln Sie ihre Zugangsdaten zwischen einem Organisations-Secret und einem persönlichen Secret, werden ihre importierten Tools entfernt. Das Dashboard zeigt dann «Server geändert: bitte Tools neu laden und bestätigen.»

HTTP-API-Verbindungen

Eine HTTP-API-Verbindung besteht aus einer Basis-URL und einer Reihe von Endpunkten. Die Zugangsdaten richten Sie einmal an der Verbindung ein, und sie gelten für jeden Endpunkt darunter.

Endpunkte

Jeder Endpunkt unter der Verbindung wird zu einem Tool, das der Agent aufrufen kann:

Jeder Endpunkt, dessen Methode nicht GET ist, trägt das Badge schreibt, und die Liste der Endpunkte zeigt, wie viele davon schreiben (zum Beispiel «5 Endpunkte · 2 schreibend»). Ein Endpunkt ohne Beschreibung wird markiert, weil die KI keine Grundlage hat, um ihn auszuwählen.

Aus OpenAPI importieren

Veröffentlicht die API eine OpenAPI-Spezifikation, müssen Sie die Endpunkte nicht abtippen.

1. Erstellen oder bearbeiten Sie eine HTTP-API-Verbindung. Unter der Liste der Endpunkte finden Sie Aus OpenAPI importieren.
2. Geben Sie die URL der Spezifikation an (zum Beispiel https://api.example.com/openapi.json). botts.ai liest JSON und YAML und sucht unter Ihrer Basis-URL automatisch nach einer Spezifikation. Findet es eine, sagt es Ihnen das. Die Spezifikation muss über eine URL abrufbar sein: Es gibt kein Feld, in das Sie sie einfügen können. Eine Spezifikation, die nur lokal bei Ihnen liegt, müssen Sie deshalb zuerst an einem erreichbaren Ort bereitstellen.
3. Prüfen Sie die vorgeschlagenen Endpunkte. Über die Suche grenzen Sie die Liste ein, mit Alle / Keine wählen Sie alle auf einmal aus oder ab.
4. Importieren Sie Ihre Auswahl.

Endpunkte, die schreiben, sind nicht vorausgewählt. Diese wählen Sie bewusst selbst aus. Hat eine Spezifikation mehr als 25 lesende Endpunkte, ist gar keiner vorausgewählt: Suchen Sie die benötigten und haken Sie sie an. Das Suchfeld erscheint, sobald eine Spezifikation mehr als 12 Endpunkte hat, und Alle / Keine wirken auf die aktuellen Suchergebnisse.

Parameter

Jeder Parameter hat einen Namen, einen Typ (string, number, integer oder boolean), eine Beschreibung für die KI und eine Pflicht-Markierung. Die Parameter bilden die Funktionssignatur des Tools: Das Modell liest Namen, Typen und Beschreibungen und entscheidet danach, welche Werte es aus dem Gespräch übernimmt. Präzise Beschreibungen verbessern direkt, wie zuverlässig der Agent die Argumente ausfüllt.

Zwei Optionen verändern, was das Modell sieht:

• Erlaubte Werte einschränken macht aus einem Parameter eine feste Liste von Optionen. So kann das Modell keinen Status und keine Kategorie erfinden, die Ihre API nicht akzeptiert.
• Fest macht aus einem Parameter eine Konstante, die die KI nie sieht und nicht ändern kann. Sie wird bei jedem Aufruf mitgesendet, und der Wert darf ein Verweis wie $secret:key sein. Nutzen Sie das für Mandanten-IDs, Kontonummern und andere Werte, die zur Verbindung gehören und nicht zum Gespräch.

Parameter, die aus einem Platzhalter {param} im Pfad stammen, werden über den Pfad selbst verwaltet: Entfernen Sie den Platzhalter, um den Parameter zu entfernen.

Authentifizierung

Die Felder für Token, Passwort und Header-Wert akzeptieren alle Verweise wie $secret:key, und jedes dieser Felder hat einen Auswahl-Chip $secret, der einen solchen Verweis für Sie einfügt. Sie können ein Secret auch direkt anlegen, ohne das Formular zu verlassen. Speichern Sie Zugangsdaten immer als Secrets, statt sie im Klartext einzufügen.

Login Token

Manche APIs vergeben keine langlebigen Schlüssel: Sie senden Zugangsdaten an einen Login-Endpunkt und verwenden das Token, das zurückkommt. Die Authentifizierung Login Token erledigt das für Sie.

Wird ein zwischengespeichertes Token abgelehnt, bevor seine Gültigkeit abläuft (weil es widerrufen oder ausgetauscht wurde oder das Zielsystem neu gestartet ist), meldet sich die Verbindung automatisch einmal neu an und wiederholt die Anfrage ein einziges Mal.

Geltungsbereich der Zugangsdaten: geteilt oder pro Benutzer

Jede Verbindung läuft entweder mit gemeinsamen oder mit persönlichen Zugangsdaten. Das legen Sie nicht separat fest: Es ergibt sich aus dem Secret, das Sie in die Auth-Felder eintragen.

Sobald ein Secret referenziert ist, zeigt das Formular über den Auth-Feldern, welcher der beiden Fälle gilt, und die Karte der Verbindung zeigt es neben der URL. Legen Sie ein Secret direkt über den Chip $secret an, bestimmt dessen Umschalter Org / Persönlich, ob die Verbindung organisationsweit oder pro Benutzer gilt.

Mit Pro Benutzer kann ein Team eine Verbindung gemeinsam nutzen, während jede Person im externen System unter eigenem Namen handelt. Das hat zwei Folgen, die Sie kennen sollten: Auf öffentlichen Agenten funktioniert es nicht (wer Ihre Website besucht, hat kein botts.ai Konto), und für ein Mitglied, für das unter dem Schlüssel der Verbindung kein persönliches Secret hinterlegt ist, bewirkt es nichts. Secrets erstellen können nur Admins und Owner. Ein Admin hinterlegt deshalb die Zugangsdaten jeder Kollegin und jedes Kollegen mit dem Geltungsbereich Nur für {name} (siehe Secrets). Um eine Verbindung mit Pro Benutzer zu testen oder ihre Tools zu laden, braucht der Admin unter demselben Schlüssel ein eigenes persönliches Secret. Sonst meldet die Prüfung Eigene Zugangsdaten nötig.

Eine Verbindung mit Pro Benutzer löst nur die eigenen Secrets jedes Mitglieds auf. Mischen Sie in den Auth-Feldern ein persönliches Secret mit Organisations-Secrets, funktioniert das deshalb für niemanden. Das Formular warnt Sie, wenn die Felder gemischt sind, und verweigert das Speichern.

So werden Anfragen gesendet

• GET und DELETE: Die Tool-Argumente werden als Query-Parameter in der URL gesendet und mit einem allfälligen Query-String zusammengeführt, der bereits im Endpunkt steht.
• POST, PUT und PATCH: Die Tool-Argumente werden als JSON-Request-Body gesendet.
• Pfadvariablen: Enthält der Pfad {param} und liefert das Modell ein passendes Argument, wird dieses prozentcodiert, in die URL eingesetzt und aus den übrigen Argumenten entfernt. Beispiel: orders/{order_id} mit order_id: 1234 wird zu orders/1234.
• Secrets: Verweise wie $secret:key in URL, Headern und Auth-Feldern werden beim Aufruf aufgelöst. Existiert ein referenziertes Secret nicht, wird der Platzhalter als wörtlicher Text gesendet.
• Timeout: Im Chat brechen Aufrufe nach 30 Sekunden ab. Bei Sprache (Telefon und Sprachfunktion im Widget) wird ein Tool-Aufruf nach 15 Sekunden gestoppt, und der Agent erfährt, dass die Zeit abgelaufen ist.

Antworten und Fehlerbehandlung

• Erfolg (2xx): Der Body der Antwort geht unverändert an das Modell (JSON wird serialisiert, reiner Text bleibt reiner Text). Sehr grosse Antworten werden auf rund 50'000 Zeichen gekürzt, wobei Anfang und Ende erhalten bleiben. So kann ein einzelnes übergrosses Ergebnis das Gespräch nicht verdrängen. Bei Sprache ist die Grenze deutlich enger: Alle Tool-Ergebnisse eines Gesprächsschritts teilen sich rund 24 KB. Geben Sie Endpunkten, die ein Telefon- oder Sprachagent nutzt, deshalb eine Antwort-Pipeline.
• HTTP-Fehler (4xx/5xx): Der Body der Antwort bleibt dem Modell aus Sicherheitsgründen verborgen. Der Agent erfährt nur The external API returned HTTP <status>. sowie einen kurzen Hinweis, der sich allein aus dem Statuscode ergibt. Dieser sagt ihm, was er als Nächstes tun soll und dass er keine Daten erfinden darf.
• Verbindungsfehler: Der Agent sieht The external API call failed. und einen Hinweis, dass er die Integration als nicht erreichbar melden soll, statt zu raten.

Das heisst: Alles, was der Agent lesen und an die Kundschaft weitergeben soll, muss mit einem 2xx-Statuscode zurückkommen. Ist ein Produkt zum Beispiel nicht an Lager, geben Sie 200 mit {"in_stock": false, "restock_date": "2026-09-01"} zurück statt 404.

Weil Verbindungen Nebenwirkungen haben können (einen Termin buchen, ein Ticket erstellen), wiederholt die Plattform sie nie automatisch und führt auch keinen Gesprächsschritt erneut aus, nachdem ein solcher Aufruf stattgefunden hat.

Antwort-Pipeline

Manche APIs antworten korrekt, aber wenig hilfreich: hundert Datensätze, wo der Agent fünf braucht, oder fünfzig Felder, wo zwei zählen. Eine Antwort-Pipeline kürzt die Antwort, bevor das Modell sie überhaupt sieht. Das senkt die Kosten und verhindert Verwirrung.

Öffnen Sie bei einem Endpunkt Antwort-Pipeline (erweitert) und geben Sie eine JSON-Liste von Schritten ein, die der Reihe nach angewendet werden:

Ein Argument, das ein Schritt search oder filter liest, nutzt nur die Pipeline. Es wird nicht an Ihre API gesendet, Sie können es also als zusätzlichen Parameter am Endpunkt anlegen.

[
  { "step": "project", "fields": ["id", "name", "status"] },
  { "step": "search",  "arg": "query", "over": ["name"], "min_score": 60 },
  { "step": "sort",    "by": "name", "order": "asc" },
  { "step": "top",     "n": 5 },
  { "step": "render",  "format": "tsv", "empty_text": "No matching records." }
]

Die Pipeline wird beim Speichern geprüft. Ein fehlerhafter Schritt wird also schon bei der Konfiguration abgelehnt und nicht erst mitten im Gespräch.

Sicherheit: blockierte Endpunkte

Um Missbrauch zu verhindern, gelten für Endpunkte von Verbindungen Einschränkungen:

• Erlaubt sind nur URLs mit http:// und https://.
• Vor jedem Aufruf wird der Hostname aufgelöst und geprüft. Endpunkte, die auf private Netzwerke, localhost, Link-Local- oder Cloud-Metadaten-Adressen oder andere interne oder reservierte Bereiche zeigen, werden blockiert. Dasselbe gilt für Hostnamen, die sich nicht auflösen lassen.

Ein blockierter Aufruf liefert Endpoint blocked by security policy. zurück. Einfach gesagt: Ihre Verbindungen erreichen das öffentliche Internet, aber keine internen oder privaten Hosts. Dieselbe Prüfung gilt für die URLs von MCP-Servern. Wenn Sie dedizierte oder interne Infrastruktur anbinden müssen, lesen Sie Managed-Tools.

Eine Verbindung testen

Getestet wird in zwei Stufen, und der Testdialog stellt sie als zwei getrennte Fragen.

Stufe 1: Funktioniert die Verbindung? Bei einem MCP-Server ist das ein Handshake, der Erreichbarkeit und gültigen Zugang belegt, ganz ohne Parameter. Bei einer HTTP-API ist es ein einzelner Aufruf an die Basis-URL. Das Ergebnis wird klar benannt: Verbindung funktioniert, Server nicht erreichbar, Zugang abgelehnt, Serverfehler, Adresse blockiert, Ungültige URL, Secret fehlt oder Eigene Zugangsdaten nötig (eine Verbindung mit Pro Benutzer, für die Sie kein persönliches Secret haben).

Eine Basis-URL, die antwortet, ohne Zugangsdaten zu prüfen, ergibt ein weiteres Ergebnis: Server erreichbar. Die Adresse ist echt, sagt aber nichts über Ihren Schlüssel aus. Das ist kein Fehler, und genau dafür gibt es Stufe 2.

Stufe 2: Ist das Tool richtig konfiguriert? Wählen Sie einen Endpunkt oder ein erkanntes Tool und führen Sie es aus. Die Parameter sind mit Beispielwerten aus dem Schema vorausgefüllt, sodass die meisten Tests nur einen Klick brauchen. Sie können die Werte in einem Formular oder als rohes JSON bearbeiten und das Ergebnis zwischen einer lesbaren Übersicht und den Rohdaten umschalten. Hat der Endpunkt eine Antwort-Pipeline, zeigt das Ergebnis, was der Agent nach der Pipeline erhalten würde, und eine fehlerhafte Pipeline erscheint als Tool meldet einen Fehler. Ein Test im Dashboard wartet bis zu 10 Sekunden auf Ihre API, weniger als die 30 Sekunden, die ein Aufruf im Live-Chat erhält.

Ein Endpunkt, der schreibt, verlangt vor dem Ausführen eine Bestätigung, denn der Test ist ein echter Aufruf gegen Ihr echtes System.

Zum Testen braucht es die Rolle Admin oder Owner. Ist der direkte Test bestanden, prüfen Sie den ganzen Ablauf im Test-Chat des Agenten: Kontrollieren Sie, ob der Agent das Tool im richtigen Moment wählt und die Parameter korrekt herausliest. Um diese Prüfung zu behalten, speichern Sie das Gespräch als Test (siehe Tests). In Testläufen sind Verbindungen zunächst ausgeschaltet und mit Kann echte Aktionen ausführen gekennzeichnet: Schalten Sie eine ein, ruft jeder Test sie wirklich auf, ohne Wiederholung. Verbindungen mit Pro Benutzer sind in Tests nicht verfügbar.

Tools mit Agenten verknüpfen

Verbindungen gehören zur Organisation; jeder Agent wählt die Verbindungen, die er nutzt:

1. Öffnen Sie den Agenten im Agenten-Editor (Tab Konfigurieren).
2. Klappen Sie den Abschnitt Tools auf. Er listet alle Verbindungen Ihrer Organisation (jeden MCP-Server und jede HTTP-API) mit je einem Schalter auf, und die Kopfzeile des Abschnitts zeigt, wie viele zugewiesen sind.
3. Schalten Sie die Verbindungen ein, die dieser Agent nutzen soll.

Schalten Sie eine Verbindung ein, erhält der Agent alle Tools, die darauf importiert sind. Soll keiner Ihrer Agenten ein bestimmtes Tool nutzen, lassen Sie es beim Import der Verbindung weg.

Gibt es noch keine Tools, verlinkt der Abschnitt auf die Seite Integrationen. Builder können hier Tools zuweisen und entfernen, auch wenn sie keine neuen erstellen können.

Eine Verbindung mit Pro Benutzer zeigt das Badge Pro Benutzer. Ausserdem sehen Sie, unter welchen Schlüsseln jedes Mitglied ein persönliches Secret braucht, damit die Verbindung auch bei ihm funktioniert.

Eine Verbindung lässt sich auch für die ganze Organisation global deaktivieren. Sie zeigt dann im Agenten-Editor das Badge Global deaktiviert und wird von allen Agenten übersprungen, bis sie wieder aktiviert wird, unabhängig von den Schaltern der einzelnen Agenten. Für diese globale Einstellung gibt es derzeit keinen Schalter im Dashboard; sie ist nur über die API verfügbar.

Managed-Tools

Der Typ einer Verbindung kennt auch Managed. Managed-Verbindungen richten Mitarbeitende der botts.ai Plattform für dedizierte oder interne Infrastruktur ein, zum Beispiel für ein ERP oder eine Fabrik-Bridge, die in Ihrer Umgebung läuft. Im Vergleich zu normalen Verbindungen gilt für Managed-Verbindungen:

• Sie umgehen die Sperre für private Netzwerke und erreichen so interne Hosts.
• Sie wiederholen den Aufruf bei Verbindungsfehlern automatisch (bis zu 3 Versuche im Abstand von 1 Sekunde). Normale Verbindungen wiederholen Aufrufe nie.
• Sie zeigen in der Liste ein bernsteinfarbenes Badge Managed.

Managed-Verbindungen können Sie nicht selbst erstellen; die Auswahl Typ ist Mitarbeitenden der Plattform vorbehalten. Wenn Sie eine dedizierte Integration mit internen Systemen brauchen, wenden Sie sich an botts.ai.

Secrets

Der Tab Secrets ist der sichere Speicher für API-Schlüssel und andere Zugangsdaten, die Ihre Verbindungen brauchen. Jedes Secret hat:

• Name: eine Anzeigebezeichnung, z. B. «Acme API-Schlüssel».
• Schlüssel: die Kennung, auf die Sie mit $secret:key verweisen, z. B. acme_api_key.
• Wert: die Zugangsdaten selbst.

Sicherheitseigenschaften

• Secret-Werte werden auf Schweizer Infrastruktur verschlüsselt gespeichert, und botts.ai zeigt sie Ihnen nie wieder an. Selbstverständlich werden sie an das System gesendet, für das sie gelten, also dorthin, wo dieser Anbieter seine Dienste betreibt. Die Datenresidenz der Zugangsdaten selbst richtet sich deshalb nach der Verbindung, für die Sie sie verwenden.
• Werte sind nur schreibbar: Nach dem Erstellen gibt weder das Dashboard noch die API den Wert eines Secrets je wieder aus. Die Liste zeigt nur Name, Schlüssel und Geltungsbereich. In Testergebnissen werden aufgelöste Secret-Werte in der angezeigten URL unkenntlich gemacht. Der Body der Antwort wird jedoch unverändert angezeigt: Ein Endpunkt, der die Anfrage zurückspiegelt, gibt sie also vollständig zurück.
• Es gibt keine Bearbeitungsfunktion. Um ein Secret auszutauschen, löschen Sie es und legen es mit demselben Schlüssel neu an. Verbindungen, die auf $secret:key verweisen, funktionieren ohne Änderung weiter.
• Verweise wie $secret:key werden beim Aufruf in der URL, in Header-Werten und in Authentifizierungsfeldern aufgelöst.

Geltungsbereiche

Verwenden Sie Organisations-Secrets für jede Verbindung, die ein Agent in Live-Gesprächen auf einem öffentlichen Kanal nutzt. Persönliche Secrets werden nur bei Anfragen des Mitglieds aufgelöst, dem sie gehören. Im Gespräch mit jemandem, der Ihre Website besucht, würde also nichts gefunden.

Der dritte Geltungsbereich löst ein praktisches Problem: Eine Verbindung mit Pro Benutzer funktioniert nur für Mitglieder, für die unter ihrem Schlüssel ein persönliches Secret hinterlegt ist. Ein Admin kann bei einem bestehenden persönlichen Secret (einem Schlüssel ohne organisationsweiten Wert) Für weiteren Benutzer hinzufügen wählen und denselben Schlüssel für ein anderes Teammitglied hinterlegen. So funktioniert die Verbindung für das ganze Team, ohne dass jemand ein Passwort teilen muss. Der Schlüssel bleibt dabei an das Original gebunden; gesetzt werden nur die Person und der Wert.

Ein doppelter Schlüssel im selben Geltungsbereich wird abgelehnt. Wählen Sie für jedes Secret einen eindeutigen Schlüssel.

Best Practices

1. Schreiben Sie klare Beschreibungen. Der Agent entscheidet anhand der Beschreibung, wann er ein Tool nutzt. Vage Beschreibungen führen dazu, dass das Tool im falschen Moment zum Einsatz kommt. Dasselbe gilt für die Beschreibungen der Parameter: Sie steuern, was das Modell herausliest.
2. Importieren Sie die Endpunkte, die Sie brauchen, nicht alle. Jedes zugewiesene Tool steht als Text im Prompt des Modells. Zwanzig Endpunkte, wo drei genügen würden, machen den Agenten langsamer, teurer und unentschlossener.
3. Halten Sie APIs schnell. Der Agent wartet auf die Antwort, bevor er das Gespräch fortsetzt (bis zu 30 Sekunden im Chat, 15 Sekunden bei Sprache). Langsame APIs erzeugen unangenehme Pausen.
4. Geben Sie nützliche Informationen mit einem 2xx-Status zurück. Der Agent sieht den Body einer 4xx- oder 5xx-Antwort nie, nur den Statuscode. Soll der Agent der Kundschaft «nicht gefunden» oder «nicht an Lager» erklären können, geben Sie das als 200 mit einem aussagekräftigen JSON-Body zurück.
5. Kürzen Sie grosse Antworten mit einer Pipeline, statt das Modell die ganze Antwort durcharbeiten zu lassen.
6. Speichern Sie Zugangsdaten als Secrets. Fügen Sie API-Schlüssel nie direkt in URLs oder Header ein. Verwenden Sie Verweise wie $secret:key, damit sie verschlüsselt bleiben und unkenntlich gemacht werden.
7. Testen Sie zuerst beide Stufen. Prüfen Sie die Verbindung, dann den Endpunkt, und bestätigen Sie danach im Test-Chat des Agenten, dass der Agent das Tool im richtigen Moment auslöst. Speichern Sie dieses Gespräch anschliessend als Test.
8. Fangen Sie einfach an. Beginnen Sie mit einer Verbindung und ein paar Endpunkten und bauen Sie aus, sobald Sie sehen, wie Ihr Agent sie nutzt.

Zuletzt aktualisiert am 4. Oktober 2026