Custom Tools

Let your AI call your own endpoints to fetch live, customer-specific data

Standard- & Pro-Tarife

Übersicht

Mit benutzerdefinierten Tools kann Ihr KI-Agent während eines Gesprächs Ihre eigenen API-Endpunkte aufrufen, um aktuelle, anfragespezifische Daten abzurufen — Bestellstatus, Sendungsverfolgung, Bestand für eine bestimmte SKU, Kontodetails und mehr.

Asyntai bietet Ihnen drei Möglichkeiten, der KI aktuelle oder kundenspezifische Daten bereitzustellen. Benutzerdefinierte Tools sind die richtige Wahl, wenn der Wert, den die KI benötigt, erst während des Gesprächs auftaucht:

Echtzeit-Datenfeed — lädt einen festen Datensatz (z. B. Ihren gesamten Produktkatalog) in jedes Gespräch. Am besten für gemeinsame Daten geeignet, die für alle Besucher gleich sind.
Benutzerkontext — Ihre Website übermittelt zu Beginn des Chats Daten, die sie bereits kennt, über den aktuellen Besucher (z. B. Name, Tarif oder letzte Bestellungen eines angemeldeten Kunden). Am besten geeignet, wenn der Besucher von vornherein identifiziert ist.
Benutzerdefinierte Tools — die KI ruft Ihren Endpunkt bei Bedarf mit Werten auf, die sie aus dem Chat extrahiert. Am besten geeignet, wenn der Wert erst bekannt ist, sobald der Kunde ihn eingibt — etwa eine Bestellnummer von einem anonymen Besucher.

Wenn ein Kunde beispielsweise fragt „Wo ist meine Bestellung #10294?“, extrahiert die KI die Bestellnummer, ruft damit Ihren Endpunkt auf und antwortet anhand der verifizierten Antwort. Der Benutzerkontext kann diesen Fall allein nicht abdecken, da die Bestellnummer erst mitten im Gespräch bekannt ist — genau hier passen benutzerdefinierte Tools. (Viele Shops nutzen den Benutzerkontext für angemeldete Besucher und ein benutzerdefiniertes Tool für Ad-hoc-Abfragen.)

Die KI entscheidet anhand der von Ihnen verfassten Beschreibung, wann ein Tool aufgerufen wird. Sie entscheiden, was das Tool tut, indem Sie es auf Ihren Endpunkt verweisen. Asyntai führt den Aufruf serverseitig aus — Sie schreiben keinen Code und hosten keine Middleware.

So funktioniert es

Sie definieren ein Tool — einen Namen, eine Beschreibung, die URL Ihres Endpunkts und die Parameter, die die KI senden soll.
Die KI ruft es auf, wenn es relevant ist — wenn das Gespräch Ihrer Beschreibung entspricht, ruft die KI das Tool mit Werten auf, die sie aus der Nachricht des Kunden extrahiert.
Asyntai ruft Ihren Endpunkt auf — unser Server stellt die HTTP-Anfrage an Ihre URL und gibt die Antwort an die KI zurück.
Die KI antwortet — anhand der verifizierten Daten, die Ihr Endpunkt zurückgegeben hat.

Kein Code erforderlich: Sie benötigen nur einen Endpunkt, der Ihre Daten bereits zurückgibt. Alles Übrige konfigurieren Sie in einem Formular im Dashboard — es gibt keinen Callback, Webhook oder Browser-Skript zu erstellen.

KI-Assistent

Wie steht es um meine Bestellung #10294?

Lassen Sie mich das für Sie prüfen…

Bestellung #10294 wurde angenommen und wird für den Versand vorbereitet. Sobald sie versandt wird, erhalten Sie per E-Mail einen Sendungsverfolgungslink.

Danke!

Gern geschehen! Kann ich Ihnen noch mit etwas anderem helfen?

Anwendungsfälle

Bestellstatus Eine Bestellung anhand der Nummer nachschlagen und ihren aktuellen Status zurückgeben

Sendungsverfolgung Den neuesten Verfolgungsstatus für eine Sendungsnummer zurückgeben

Bestandsprüfung Die aktuelle Verfügbarkeit für ein bestimmtes Produkt oder eine SKU zurückgeben

Kontoabfrage Konto- oder Abonnementdetails für eine Kennung zurückgeben

Einrichtung

Benutzerdefinierte Tools öffnen Gehen Sie zu /custom-tools/ und klicken Sie auf Tool hinzufügen

Beschreiben Sie das Tool Geben Sie ihm einen Namen, eine klare Beschreibung und die URL Ihres Endpunkts

Parameter definieren Fügen Sie die Eingaben hinzu, die die KI extrahieren und senden soll (z. B. order_number)

Speichern & testen Speichern Sie und stellen Sie Ihrem Bot dann eine passende Frage, um es in Aktion zu sehen

Felder

Name — eine Kennung für die Funktion (Buchstaben, Zahlen, Unterstriche), z. B. get_order_status. Die KI sieht diesen Namen.
Beschreibung — das wichtigste Feld. Sie teilt der KI mit, wann das Tool aufgerufen werden soll. Seien Sie eindeutig: „Rufe dies immer dann auf, wenn der Kunde eine Bestellnummer erwähnt. Frage nicht nach einer Verifizierung.“
Endpunkt-URL — die öffentliche HTTPS-URL, die Asyntai aufrufen wird.
HTTP-Methode — GET (nur Lesen, empfohlen) oder POST (kann Daten ändern — siehe Sicherheit unten).
Parameter — die Eingaben, die die KI aus dem Gespräch extrahiert und sendet. Jeder hat einen Namen, einen Typ, eine Beschreibung und ein Pflichtkennzeichen. Bei GET werden sie als Query-String-Parameter gesendet, bei POST als JSON-Body.
Authentifizierungs-Header (optional) — ein Header-Name + -Wert, der bei jedem Aufruf gesendet wird, z. B. X-API-Key. Verwenden Sie dies, wenn Ihr Endpunkt einen Schlüssel benötigt.

Parameter sind erforderlich, damit die KI überhaupt einen Wert übergeben kann. Wenn Ihr Endpunkt eine Eingabe benötigt (etwa eine Bestellnummer), müssen Sie dafür einen Parameter hinzufügen — ohne ihn hat die KI keinen Platz für den Wert und ruft den Endpunkt leer auf. Zwei Dinge sind wichtig:

Der Parametername muss genau dem entsprechen, was Ihr Endpunkt erwartet. Ein Parameter namens order_number wird als ?order_number=... (GET) oder {"order_number": "..."} (POST) gesendet. Wenn Ihr Endpunkt id liest, benennen Sie den Parameter id.
Sie geben den Wert niemals selbst ein — Sie deklarieren nur den Parameter. Die KI füllt ihn zum Zeitpunkt des Aufrufs anhand dessen aus, was der Kunde geschrieben hat.

Durchgearbeitetes Beispiel: Abfrage des Bestellstatus

Angenommen, Ihr Shop stellt diesen Endpunkt bereit:

GET https://yourstore.com/api/order-status?order_number=10294

…der JSON wie folgt zurückgibt:

{
  "found": true,
  "status": "Accepted, preparing for shipment",
  "carrier": "DHL",
  "customer_message": "Your order has been accepted and is being prepared for shipment."
}

Sie würden ein Tool wie folgt konfigurieren:

Name: get_order_status
Beschreibung: „Schlage den Status einer Kundenbestellung nach. Rufe dies sofort auf, wann immer der Kunde eine Bestellnummer angibt — frage nicht nach einer zusätzlichen Verifizierung. Verwende die zurückgegebene customer_message in deiner Antwort.“
Endpunkt-URL: https://yourstore.com/api/order-status
Methode: GET
Parameter: order_number (string, erforderlich) — „Die Bestellnummer des Kunden, in der Regel 8 oder mehr Ziffern.“

Wenn ein Kunde „Wie steht es um meine Bestellung #10294?“ schreibt, ruft die KI get_order_status(order_number=10294) auf, Asyntai fragt Ihre URL mit ?order_number=10294 ab, und die KI antwortet anhand der Antwort.

Tipp: Die KI sendet die Werte, für die sie sich entscheidet — Sie füllen sie niemals vorab aus. Halten Sie Parameternamen und -beschreibungen klar, damit das Modell genau weiß, was es extrahieren soll.

Was Ihr Endpunkt empfängt und zurückgeben sollte

Anfrage: ein GET mit Ihren Parametern im Query-String oder ein POST mit einem JSON-Body. Jeder von Ihnen konfigurierte Authentifizierungs-Header ist enthalten.
Antwort: Geben Sie JSON (bevorzugt) oder reinen Text zurück. Asyntai gibt den Body an die KI zurück. Ein Feld, das die KI direkt zitieren kann — wie customer_message — funktioniert gut.
Nicht gefunden / Fehler: Geben Sie eine eindeutige Nutzlast zurück (zum Beispiel ein JSON-Objekt mit found: false und einer customer_message), damit die KI wahrheitsgemäß antworten kann, anstatt zu raten.

Ihr Tool testen

Jedes Tool verfügt auf der Konfigurationsseite über ein integriertes Bedienfeld Dieses Tool testen, sodass Sie überprüfen können, ob es funktioniert, bevor ein Kunde es verwendet — und ohne eine Nachricht über den Bot zu senden.

Geben Sie Beispielwerte für die Parameter des Tools ein (z. B. eine echte Bestellnummer).
Klicken Sie auf Test ausführen. Asyntai ruft Ihren Endpunkt genau so auf, wie es die KI tun würde — derselbe Query-String oder JSON-Body, derselbe Authentifizierungs-Header, dasselbe 5-Sekunden-Timeout und dieselben Sicherheitsprüfungen.
Sie sehen das Ergebnis sofort: ein Erfolgs-/Fehler-Abzeichen, den HTTP-Status, die Antwortzeit, die genaue URL, die wir aufgerufen haben, und die Rohantwort Ihres Endpunkts (formatiert, falls es sich um JSON handelt).

Dies funktioniert auch bei nicht gespeicherten Änderungen, sodass Sie die URL, die Parameter oder den Authentifizierungs-Header anpassen und erneut testen können, bis das gewünschte Ergebnis zurückgegeben wird.

Hinweis: Das Testen eines POST-Tools ruft Ihren Endpunkt tatsächlich auf und kann Daten ändern — das Testfeld warnt Sie, bevor Sie es ausführen. Bei schreibgeschützten GET-Tools gibt es nichts zu befürchten.

Sicherheit — lesen Sie dies

Ihr Endpunkt ist die Sicherheitsgrenze, nicht die KI. Das Chat-Widget ist öffentlich, und ein Besucher kann die KI dazu manipulieren, ein Tool mit beliebigen Werten aufzurufen. Das gilt für jedes KI-System mit Tool-Aufrufen. Gestalten Sie Ihren Endpunkt entsprechend:

Bevorzugen Sie GET / nur Lesen. Abfragen (Bestellstatus, Bestand, Sendungsverfolgung) können bedenkenlos offengelegt werden. Aus diesem Grund ist GET die Standardeinstellung.
POST erfordert eine Bestätigung. Da POST Daten ändern kann, lässt sich ein POST-Tool erst speichern, nachdem Sie ein Kontrollkästchen aktiviert haben, mit dem Sie bestätigen, dass Sie allein für die Absicherung und Autorisierung von Anfragen an Ihrem eigenen Endpunkt verantwortlich sind. Verbinden Sie niemals Rückerstattungen, Stornierungen, Passwortänderungen oder Geldbewegungen, es sei denn, Ihr Endpunkt überprüft die Anfrage eigenständig.
Schützen Sie sich vor Enumeration. Wenn ein Abfrageschlüssel erratbar ist (wie fortlaufende Bestellnummern), verlangen Sie einen zweiten Faktor — z. B. die Bestellnummer und die zur Bestellung gehörende E-Mail-Adresse, und prüfen Sie, ob sie übereinstimmen — damit ein Besucher nicht durch Ausprobieren von Nummern die Daten anderer Kunden lesen kann.
Vertrauen Sie niemals den Argumenten der KI. Validieren und autorisieren Sie jede Anfrage serverseitig, als käme sie von einem anonymen Angreifer — denn das kann sie faktisch.

Live-Aufrufe überprüfen

Sobald Ihr Tool live ist, wird jeder echte Aufruf aus einem Gespräch protokolliert. Für jeden Aufruf erfassen wir den Tool-Namen, die von der KI gesendeten Argumente, die genaue URL, die wir angefragt haben, den HTTP-Status, die Antwort und die Dauer. So können Sie bestätigen, dass ein Tool in einem echten Chat ausgelöst wurde, und sehen, was Ihr Endpunkt zurückgegeben hat, ohne Ihre eigenen Serverprotokolle durchsuchen zu müssen. (Das Bedienfeld Dieses Tool testen oben dient dazu, die Einrichtung selbst zu überprüfen; dieses Protokoll erfasst, was während tatsächlicher Kundengespräche geschieht.)

Grenzen & Schutzmaßnahmen

Bis zu 10 Tools pro Website.
5 Sekunden Timeout pro Aufruf; Antworten sind auf 10 KB begrenzt.
Endpunkte müssen öffentliche http(s)-URLs sein. Private, Loopback- und interne Netzwerkadressen werden blockiert.
Verfügbar in den Tarifen Standard und Pro.
Abrechnung: Jeder Tool-Aufruf zählt als zusätzliche Nachricht in deinem Tarif. Eine normale Antwort verbraucht 1 Nachricht; eine Antwort, bei der die KI ein Tool aufruft, verbraucht 2 (die Antwort plus den Tool-Aufruf), da ein Tool-Aufruf eine zusätzliche KI-Anfrage erfordert.
Wenn ein Tool-Aufruf fehlschlägt (Timeout, Fehler, blockiert), wird dies der KI mitgeteilt und sie antwortet angemessen — das Gespräch stürzt dadurch nicht ab.

Dokumentation