Integrationen

Benutzerdefinierte Agent-Tools

Geben Sie der KI Live-Zugriff auf Ihre Systeme: Definieren Sie Tools, die das LLM während der Antworterstellung aufrufen kann, um Bestellstatus abzurufen, Konten nachzuschlagen, den Lagerbestand zu prüfen und vieles mehr.

Kurzüberblick#


Tool-Typen	`SERVER_SIDE` (HTTP-Aufruf von HelpStack) oder `CLIENT_SIDE` (im Browser des Besuchers ausgeführt)
Verwaltung über	Dashboard + `/api/agent-tools` (Organisationsebene), `/api/channels/[id]/agent-tools` (Kanalebene)
Authentifizierung	Dashboard-Sitzung (werden von Ihrem Team konfiguriert)
Server-Tool-Timeout	~10s, Antwort auf ~10 KB begrenzt
Client-Tool-Timeout	~5s (Socket-Roundtrip)
Protokollierung	Jeder Aufruf wird in `ToolCallLog` aufgezeichnet

Die konzeptuelle Übersicht finden Sie im Agent-Tools-Leitfaden. Diese Seite ist die technische Referenz.

Tool-Anatomie#

Eine Tool-Definition enthält folgende Felder:

Feld	Erforderlich	Hinweise
Name	ja	Der Funktionsname, den das LLM aufruft, z. B. `get_order_status`. Muss ein gültiger Funktionsbezeichner sein
Beschreibung	ja	Das LLM liest diese, um zu entscheiden, wann das Tool aufgerufen werden soll. Max. ~2000 Zeichen (validiert). Seien Sie präzise
URL	ja (serverseitig)	Muss HTTPS sein. SSRF-geschützt: eine Blockliste lehnt interne/private Netzwerkziele ab
Methode	nein	`GET` \| `POST` \| `PUT` \| `PATCH`. Standard `POST`
Header	nein	Optionales JSON-Objekt. Kann verschlüsselt/maskiert werden (für API-Schlüssel/Token verwenden)
Parameter-Schema	ja	Ein JSON-Schema-Objekt, das die Argumente beschreibt, die das LLM ausfüllt (`parametersSchema`)
Typ	ja	`SERVER_SIDE` oder `CLIENT_SIDE`
Aktiv	—	Umschalten, um das Tool zu aktivieren/deaktivieren, ohne es zu löschen

Arbeitsbeispiel — `get_order_status` (SERVER_SIDE)#

Tool-Definition

Feld	Wert
Name	`get_order_status`
Typ	`SERVER_SIDE`
Methode	`POST`
URL	`https://api.YOURCOMPANY.com/orders/status`
Header	`{ "Authorization": "Bearer YOUR_API_TOKEN" }` (als verschlüsselten Header speichern)
Beschreibung	`Look up the current status and tracking info for a customer order by its order number. Call this whenever the customer asks where their order is, when it will arrive, or to confirm an order was placed.`

Parameter-Schema (JSON Schema)

{
  "type": "object",
  "properties": {
    "order_number": {
      "type": "string",
      "description": "The customer's order number, e.g. ORD-10432"
    }
  },
  "required": ["order_number"]
}

Anfrage, die Ihr Endpunkt erhält

Bei einem Tool-Aufruf sendet HelpStack die vom LLM bereitgestellten Argumente als Request-Body (bei POST/PUT/PATCH), zusammen mit Ihren konfigurierten Headern und Content-Type: application/json:

POST /orders/status HTTP/1.1
Host: api.YOURCOMPANY.com
Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json

{ "order_number": "ORD-10432" }

Antwort-Vertrag, den Ihr Endpunkt einhalten muss

Geben Sie JSON zurück, das das Modell lesen kann. Halten Sie es klein — Antworten sind auf ~10 KB begrenzt und der Aufruf läuft nach ~10s ab.

{
  "status": "shipped",
  "carrier": "DHL",
  "tracking_number": "JD0140...",
  "estimated_delivery": "2026-06-02"
}

Die KI erhält diesen Payload als Tool-Ergebnis und verarbeitet ihn in ihre Antwort. Es gibt keinen vorgeschriebenen Envelope — geben Sie beliebige nützliche Felder zurück, aber machen Sie sie selbstbeschreibend, damit das Modell sie korrekt verwendet.

Gute Beschreibungen verfassen#

Die Beschreibung ist das bei weitem wichtigste Feld — sie ist das Einzige, was das LLM verwendet, um zu entscheiden, ob und wann das Tool aufgerufen werden soll.

Geben Sie an, was das Tool zurückgibt und wann es aufgerufen werden soll („Rufen Sie dies auf, wenn der Kunde fragt …").
Erwähnen Sie die Formulierungen, die Kunden tatsächlich verwenden.
Beschreiben Sie jeden Parameter klar in der description seines Schemas.
Bleiben Sie unter dem ~2000-Zeichen-Limit (der Speicherdialog validiert dies und zeigt Fehler an).

Sicherheit & SSRF-Schutz#

Nur HTTPS. Einfache HTTP-URLs werden abgelehnt.
SSRF-Blockliste. Interne/private Netzwerkziele (Loopback, private RFC1918-Bereiche, Link-local, Metadaten-Endpunkte) sind blockiert, damit ein Tool nicht auf interne Infrastruktur gerichtet werden kann.
Geheime Header. Legen Sie API-Schlüssel/Token in Header, die verschlüsselt/maskiert statt im Klartext gespeichert werden können.
Behandeln Sie den Tool-Endpunkt als öffentlich zugänglich — authentifizieren Sie Anfragen (z. B. ein Bearer-Token in Headern) und validieren Sie Eingaben auf Ihrer Seite.

Timeouts & Limits#

	Serverseitig	Clientseitig
Timeout	~10s	~5s
Antwort-Limit	~10 KB	—
Bei Fehler/Timeout	Protokolliert; KI wird informiert, dass das Tool nicht verfügbar ist, und setzt mit der bestmöglichen Antwort fort

Fehler werden graceful degradiert — ein defektes oder langsames Tool blockiert nie eine Antwort; die KI fährt einfach ohne diese Daten fort.

Organisations- vs. Kanal-Tools + semantische Filterung#

Tools können auf Organisations-Ebene und auf Kanal-Ebene definiert werden.
Für ein bestimmtes Gespräch werden Organisations- und Kanal-Tools zusammengeführt, wobei ein Kanal-Tool ein Organisations-Tool mit demselben Namen überschreibt.
Der zusammengeführte Satz wird semantisch nach Relevanz für die Kundenanfrage gefiltert, sodass ein großer Tool-Katalog nicht jeden LLM-Aufruf aufbläht — nur relevante Tools werden angeboten.
Ausgewählte Tools werden in OpenAI/Anthropic-Funktionsdefinitionen umgewandelt und bei der Antworterstellung angeboten.

OpenAPI-Import#

Sie können Tools aus einer vorhandenen API bootstrappen: Fügen Sie eine OpenAPI 3.0-Spezifikation ein oder laden Sie sie hoch, und HelpStack extrahiert deren Operationen in Tool-Definitionen, die Sie prüfen und speichern. Dies ist der schnellste Weg, eine vorhandene REST-API der KI zugänglich zu machen.

Protokollierung#

Jeder Tool-Aufruf wird in ToolCallLog aufgezeichnet. Den Aufrufverlauf eines Tools (Argumente, Ergebnis, Timing) können Sie über folgenden Endpunkt einsehen:

GET /api/agent-tools/[id]/logs

Verwenden Sie die Protokolle, um zu debuggen, warum ein Tool aufgerufen wurde oder nicht, und um Timeouts/Fehler zu erkennen.

Clientseitige Tools (fortgeschritten)#

CLIENT_SIDE-Tools werden auf dieselbe Weise deklariert (Name, Beschreibung, Parameter-Schema), werden aber im Browser des Website-Besuchers ausgeführt, vermittelt durch den Widget-Socket:

Die KI gibt einen Tool-Aufruf für ein CLIENT_SIDE-Tool aus.
Der Server sendet tool:execute an das Widget.
Das Widget führt es aus und antwortet mit tool:result (oder tool:error).
Es gibt einen ~5s-Timeout; bei Timeout wird der Aufruf graceful degradiert (Tool nicht verfügbar).

Es gibt heute keine öffentliche JS-API zur Registrierung clientseitiger Tool-Handler im Widget-Loader. Die clientseitige Ausführung erfolgt server-/iframe-vermittelt — behandeln Sie es als erweiterte Funktion und erwarten Sie keinen registerTool()-artigen Snippet auf Ihrer Seite. Siehe Widget-Einbettung.