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#

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

Tool-Anatomie#

Eine Tool-Definition enthält folgende Felder:

Arbeitsbeispiel — get_order_status (SERVER_SIDE)#

Tool-Definition

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. Der Aufruf läuft nach ~10s ab und die Antwort ist auf 128 KB begrenzt.

Eine Antwort über dem Limit wird abgelehnt, nicht gekürzt — ein halbes JSON-Dokument lässt sich entweder nicht parsen oder ergibt schlimmstenfalls eine andere Bedeutung —, der Aufruf schlägt also fehl und der KI wird mitgeteilt, dass das Tool nicht verfügbar ist. Dasselbe passiert, wenn der Körper gar kein JSON ist, meist eine HTML-Fehlerseite eines Proxys.

Das Limit ist eine Absicherung gegen einen außer Kontrolle geratenen Endpunkt (eine paginierte Liste ohne Seitengröße, ein Debug-Dump), kein Zielwert. Größe kostet Sie auch darunter: Was Sie zurückgeben, wird vollständig geparst, ins Aufrufprotokoll geschrieben und dem Modell vorgelegt und daher bei jeder Antwort, die es verwendet, in Tokens bezahlt. Geben Sie die wenigen Felder zurück, die die KI zum Antworten braucht, nicht Ihren gesamten Datensatz — Status, voraussichtliche Lieferzeit und Sendungsnummer einer Bestellung, nicht das ganze Bestellobjekt.

{
  "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.

Die verifizierte E-Mail-Adresse des Kunden (gebundene Parameter)#

Auf einem E-Mail-Kanal ist die Adresse, von der eine Nachricht kam, die Identität des Kunden. Ein SERVER_SIDE-Tool kann HelpStack bitten, einen seiner Parameter mit dieser Adresse zu füllen. Ein Tool „meine Bestellungen abrufen" braucht dann keine Bestellnummer, und niemand kann die KI dazu bringen, die Bestellungen einer anderen Person abzurufen, indem er deren Adresse eintippt.

Fügen Sie dem Parameter "x-helpstack-bind": "conversation.senderEmail" hinzu:

{
  "type": "object",
  "properties": {
    "customer_email": {
      "type": "string",
      "x-helpstack-bind": "conversation.senderEmail"
    },
    "status": {
      "type": "string",
      "enum": ["open", "shipped", "delivered"],
      "description": "Optional filter by order status"
    }
  },
  "required": ["customer_email"]
}

Was passiert:

• Die KI sieht den Parameter nie. Er wird aus dem Schema und aus required entfernt, bevor das Tool angeboten wird.
• HelpStack füllt ihn bei jedem Aufruf mit der Absenderadresse der E-Mail-Unterhaltung, in Kleinbuchstaben: im Query-String bei GET, im JSON-Body bei POST/PUT/PATCH oder in einem Platzhalter {customer_email} in der URL. Sendet die KI trotzdem einen Wert dafür, wird er verworfen.
• Das Tool wird nur in E-Mail-Unterhaltungen angeboten. Website-Chat, Messenger, Instagram, WhatsApp und die anderen Kanäle haben keine verifizierte Adresse, daher sieht die KI das Tool dort nicht und fragt den Kunden nach dem, was Ihre anderen Tools brauchen, etwa Bestellnummer und E-Mail-Adresse.
• Nur SERVER_SIDE-Tools und Parameter der obersten Ebene können gebunden werden, und conversation.senderEmail ist der einzige unterstützte Wert. Alles andere wird beim Speichern abgelehnt.

Begrenzen Sie die Abfrage auf Ihrer Seite: Geben Sie die Daten dieses Kunden zurück und nichts anderes. Jede Antwort geht an dieselbe Adresse, mit der das Tool aufgerufen wurde, daher erreicht das Ergebnis den Inhaber dieses Postfachs.

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#

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. Eine x-helpstack-bind-Erweiterung an einem Parameter oder an einem Property-Schema in der Spezifikation bleibt erhalten (siehe den Abschnitt zu gebundenen Parametern oben).

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.

Wiederholungen werden nicht protokolliert. Wenn HelpStack eine vergangene Konversation erneut abspielt, um die Antwortqualität zu messen, wird ein Tool mit GET (oder HEAD) genau wie bei einer echten Antwort aufgerufen, Ihr Endpunkt kann also eine Abfrage zu einer älteren Nachricht sehen. Ein Tool mit einer anderen Methode wird während einer Wiederholung nie aufgerufen, und Aufrufe aus einer Wiederholung erscheinen nicht in ToolCallLog.

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:

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

Einen Handler registrieren

Das Widget-Skript stellt window.HelpStack bereit. Registrieren Sie einen Handler namentlich, und er wird aufgerufen, sobald die KI dieses Tool nutzt:

<script src="https://helpstack.eu/widget.js?id=CHANNEL_ID" async></script>
<script>
  window.HelpStack = window.HelpStack || function () {
    (window.HelpStack.q = window.HelpStack.q || []).push(arguments);
  };

  window.HelpStack('registerTool', 'highlight', async ({ section }) => {
    document.querySelector(`#${section}`)?.scrollIntoView({ behavior: 'smooth' });
    return { highlighted: section };
  });
</script>

Der Queue-Shim in der Mitte bedeutet, dass Sie registrieren können, bevor widget.js geladen ist; das Skript leert die Warteschlange beim Start. Was Ihr Handler zurückgibt, ist das, was die KI liest, und wenn er eine Ausnahme wirft, wird der KI mitgeteilt, dass das Tool fehlgeschlagen ist. Dieselbe Funktion liegt nach dem Laden des Skripts auch auf ChatWidget.registerTool(name, fn).

Beispiel-Handler

Vier Muster, in der Reihenfolge, in der Teams sie üblicherweise bauen. Jedes zeigt die Tool-Definition, die Sie im Dashboard eintragen, und den Handler, den Sie auf Ihrer Seite registrieren. Sie sind bewusst klein gehalten: Ein clientseitiges Tool sollte eine Sache tun und ein kurzes, schlichtes Objekt zurückgeben.

1. Auslesen, wo der Besucher ist (ohne Parameter)

Das nützlichste erste Tool. Es kostet nichts und verhindert, dass die KI rät, was der Besucher gerade ansieht.

Definition

{ "type": "object", "properties": {}, "required": [] }

Handler

window.HelpStack('registerTool', 'where_is_the_user', async () => ({
  page: location.pathname,
  title: document.title,
  // Whatever "where they are" means in your UI: an open tab, a wizard step, a route.
  section: document.querySelector('[data-active-section]')?.dataset.activeSection ?? null,
}));

2. Auf etwas auf der Seite zeigen

Definition

{
  "type": "object",
  "properties": {
    "target": {
      "type": "string",
      "description": "What to highlight, in the customer's own words: a button label, a section name, or a menu item."
    }
  },
  "required": ["target"]
}

Handler

window.HelpStack('registerTool', 'highlight', async ({ target }) => {
  const el = document.querySelector(`[data-tour="${CSS.escape(target)}"]`);
  if (!el) {
    // Not found is a normal outcome, not a failure. Say so and let the AI recover.
    return { found: false, target };
  }
  el.scrollIntoView({ behavior: 'smooth', block: 'center' });
  el.classList.add('hs-highlight');
  setTimeout(() => el.classList.remove('hs-highlight'), 3000);
  return { found: true, target };
});

3. Inhalte an die KI zurücklesen

Definition

{
  "type": "object",
  "properties": {
    "section": { "type": "string", "description": "Section name as the customer would say it." }
  },
  "required": ["section"]
}

Handler

window.HelpStack('registerTool', 'read_section', async ({ section }) => {
  const root = document.querySelector(`[data-section="${CSS.escape(section)}"]`);
  if (!root) return { found: false, section };

  const fields = {};
  root.querySelectorAll('[data-field]').forEach((el) => {
    // Keep it small — the result goes into the AI's context on every call.
    fields[el.dataset.field] = (el.value ?? el.textContent ?? '').trim().slice(0, 500);
  });
  return { found: true, section, fields };
});

Geben Sie Feldschlüssel zurück, die die KI Ihnen zitieren kann. Genau das macht ein Schreib-Tool wie das nächste möglich.

4. Etwas für den Besucher schreiben

Das wertvollste Muster und dasjenige, bei dem die größte Vorsicht geboten ist: Die KI verändert jetzt den Bildschirm des Besuchers.

Definition

{
  "type": "object",
  "properties": {
    "section": { "type": "string", "description": "Section name, as returned by read_section." },
    "field":   { "type": "string", "description": "Field key exactly as read_section returned it." },
    "text":    { "type": "string", "description": "The complete new contents of that field." }
  },
  "required": ["section", "field", "text"]
}

Handler

window.HelpStack('registerTool', 'fill_field', async ({ section, field, text }) => {
  const el = document.querySelector(
    `[data-section="${CSS.escape(section)}"] [data-field="${CSS.escape(field)}"]`
  );
  if (!el) return { written: false, reason: 'field not found', section, field };

  el.value = text;
  // Frameworks that track their own state need to be told.
  el.dispatchEvent(new Event('input', { bubbles: true }));
  el.scrollIntoView({ behavior: 'smooth', block: 'center' });
  return { written: true, section, field };
});

⚠️ Ausfüllen, nicht absenden. Lassen Sie den Besucher die Änderung lesen und selbst speichern. Ein Tool, das an seiner Stelle veröffentlicht, macht aus einem hilfreichen Vorschlag eine nicht rückgängig zu machende Aktion, und die KI kann das Ergebnis nicht sehen.

Handler schreiben, die sich anständig verhalten

• Geben Sie kleine, schlichte Objekte zurück. Das Ergebnis fließt bei jedem Aufruf in den Kontext der KI. Geben Sie { found: true, section, fields } zurück, niemals einen DOM-Knoten, eine Komponente oder einen 50-KB-Blob.
• „Nicht gefunden" ist ein Ergebnis, kein Fehler. Geben Sie { found: false } zurück und lassen Sie die KI etwas Sinnvolles sagen. Eine Ausnahme erzeugt einen Tool-Fehlschlag, und die KI erfährt nur, dass etwas kaputt ist.
• Bleiben Sie deutlich unter dem ~5-Sekunden-Timeout. Keine Netzwerkaufrufe, auf die der Besucher warten muss. Wenn Sie Ihr Backend brauchen, machen Sie stattdessen ein SERVER_SIDE-Tool daraus.
• Legen Sie niemals etwas offen, das der Besucher nicht ohnehin sehen kann. Ein clientseitiges Tool läuft auf einer öffentlichen Seite ohne eigene Authentifizierung. Lesen Sie keine Auth-Tokens, keine Daten anderer Kunden und nichts hinter Ihren eigenen Berechtigungsprüfungen.
• Benennen Sie Parameter in der Sprache des Kunden, nicht in der Ihres Schemas. Die KI füllt sie aus dem, was der Kunde geschrieben hat. target: "der Speichern-Button" funktioniert; elementId: "btn-save-primary" nicht.

Das zugrunde liegende Protokoll

registerTool ist eine dünne Hülle um postMessage, und Sie können die Nachrichten auch selbst beantworten — nützlich, wenn Sie bereits einen Message-Router haben oder ein Tool bedienen möchten, das das Widget nicht kennt.

⚠️ Wenn Sie einen Handler über window.HelpStack registrieren, beantworten Sie dasselbe Tool nicht zusätzlich mit einem eigenen Listener. Das iframe nimmt die erste Antwort pro callId, zwei Antworten liefern sich also ein Rennen. Das Widget bleibt bei Tools ohne Handler stumm, genau damit ein bestehender eigener Listener weiter funktioniert.

Das Widget-iframe sendet jeden clientseitigen Aufruf an sein übergeordnetes Fenster:

{ type: 'TOOL_EXECUTE', callId: '…', toolName: 'highlight', parameters: { … } }

Anschließend wartet es auf eine dieser Antworten, abgeglichen über callId:

{ type: 'TOOL_RESULT', callId: '…', result: { … } }   // whatever the AI should read
{ type: 'TOOL_ERROR',  callId: '…', error: 'why it failed' }

Ein Handler auf Ihrer eigenen Seite genügt also:

window.addEventListener('message', (event) => {
  // Required. Without this check any page in an iframe could drive your tools.
  if (event.origin !== 'https://helpstack.eu') return;
  const { type, callId, toolName, parameters } = event.data ?? {};
  if (type !== 'TOOL_EXECUTE') return;

  const reply = (result) =>
    event.source.postMessage({ type: 'TOOL_RESULT', callId, result }, event.origin);
  const fail = (error) =>
    event.source.postMessage({ type: 'TOOL_ERROR', callId, error }, event.origin);

  if (toolName === 'highlight') {
    const el = document.querySelector(parameters.selector);
    if (!el) return fail('No element matches that selector.');
    el.scrollIntoView({ behavior: 'smooth', block: 'center' });
    el.classList.add('my-highlight');
    reply({ ok: true, message: 'Highlighted it. Tell the customer to look at the ring.' });
  }
});

Drei Dinge, die Sie wissen sollten, bevor Sie darauf aufbauen:

• Antworten Sie innerhalb des 5-Sekunden-Timeouts, und antworten Sie ehrlich. Bei einem Timeout löst der Aufruf zu { success: false, error: 'timeout' } auf, und die KI macht ohne ihn weiter. Antworten Sie nicht, bevor Sie wissen, dass die Aktion funktioniert hat — eine KI, der „hervorgehoben" gesagt wird, obwohl nichts hervorgehoben wurde, schickt den Kunden auf die Suche nach etwas, das nicht auf seinem Bildschirm ist, und das ist schlimmer als gar kein Tool.
• Was Sie in result schreiben, ist das, was die KI liest. Ein Satz, der erklärt, was passiert ist, bringt Ihnen eine bessere Antwort als { ok: true }.
• Der Besucher ist womöglich nicht auf einer Seite, die das leisten kann. Geben Sie ein Ergebnis zurück, das das sagt, statt still zu scheitern, damit die KI es erklären kann.

Kombinieren Sie das mit window.ChatWidget.identify(identity, metadata), damit die KI weiß, welchem Konto sie hilft, bevor sie irgendetwas aufruft.

Aktionsschaltflächen (CLIENT_ACTION)#

Ein CLIENT_SIDE-Tool läuft in dem Moment, in dem die KI es aufruft. Das passt zum Auslesen der Seite, aber nicht zu allem, was der Besucher sehen muss: Auf einem Handy verdeckt der geöffnete Chat die ganze Seite, die Seite ändert sich also dahinter, und der Besucher bekommt es nicht mit. Schlimmer noch, die Antwort sagt dann „Ich habe Mein Team für Sie geöffnet“ über etwas, das er nie gesehen hat.

Ein CLIENT_ACTION-Tool wird auf dieselbe Weise deklariert (Name, Beschreibung, Parameter-Schema), aber HelpStack führt es nie aus, wenn die KI es aufruft:

1. Die KI ruft das Tool auf. HelpStack prüft die Argumente gegen Ihr Schema (nicht deklarierte Argumente werden verworfen) und hängt eine Schaltfläche an die Antwort. Der KI wird mitgeteilt, dass die Schaltfläche nur angeboten wurde, also schreibt sie „tippen Sie auf Zeig es mir“ und nie „ich habe geöffnet“.
2. Der Besucher sieht die Antwort mit der Schaltfläche darunter.
3. Tippt er darauf, weicht das Widget aus, falls es die Seite verdeckt (standardmäßig auf Handys), und lässt unten am Bildschirm eine kleine Schaltfläche Zurück zum Chat stehen.
4. Der Handler Ihrer Seite läuft. Bei Erfolg bleibt Zurück zum Chat stehen, bis der Besucher darauf tippt. Bei einem Fehler kommt der Chat zurück, mit Ihrer Meldung unter der Antwort.

Eine Antwort trägt höchstens 2 Schaltflächen. Schaltflächen gibt es nur im Web-Chat: Bei E-Mail, WhatsApp und den anderen Kanälen werden der KI diese Tools gar nicht angeboten.

Einen Aktions-Handler registrieren

<script>
  window.HelpStack = window.HelpStack || function () {
    (window.HelpStack.q = window.HelpStack.q || []).push(arguments);
  };

  window.HelpStack('registerAction', 'show_element', async ({ element }) => {
    const el = document.querySelector(`[data-help="${element}"]`);
    if (!el) return { ok: false, message: 'That part of the page is not here.' };
    el.scrollIntoView({ behavior: 'smooth', block: 'center' });
    el.classList.add('help-highlight');
    return { ok: true };
  });
</script>

• Geben Sie { ok: false, message } zurück, um einen Fehler zu melden. Der Besucher sieht message im Chat, und die KI liest sie in ihrem nächsten Zug. Jeder andere Rückgabewert, oder gar keiner, zählt als Erfolg. Eine geworfene Ausnahme ist ein Fehler.
• Ein Handler hat 10 Sekunden. Navigation plus Warten auf ein Element dauert meist weniger als 3.
• Ein bestehendes CLIENT_SIDE-Tool lässt sich im Bearbeitungsformular oder mit update_agent_tool auf CLIENT_ACTION umstellen (und zurück); Name, Parameter und Aufrufverlauf bleiben erhalten. Andere Typwechsel sind nicht möglich.
• Derselbe Name kann mit registerTool und mit registerAction registriert werden. Der Typ des Tools in HelpStack entscheidet, welchen die KI bekommt.
• Hat die Seite den Handler nicht registriert (eine alte Seite, eine andere Website), wird die Schaltfläche deaktiviert angezeigt.
• Schaltflächen bleiben im Gespräch und funktionieren nach einem Neuladen wieder, solange die Seite den Handler erneut registriert.

Der Schaltflächentext

HelpStack fügt jedem CLIENT_ACTION-Tool, das die KI sieht, einen optionalen Parameter label hinzu, damit sie die Schaltfläche in der Sprache der Antwort beschriften kann (höchstens 24 Zeichen). Ihr Handler erhält label nie. Ohne Label steht auf der Schaltfläche „Zeig es mir“ in der Sprache des Gesprächs („Show me“, „Pokaži mi“, „Ukáž mi“, ...).

Was das Widget beim Tippen tut

Pro Kanal einstellbar unter Kanäle → Erscheinungsbild → Wenn Besucher auf „Zeig es mir“ tippen:

„Vollbild“ meint das, was der Besucher gerade sieht, keine Vermutung anhand des Browsernamens.

Widget-API

Diese Aufrufe funktionieren auf jeder Seite mit widget.js, mit oder ohne Schaltflächen:

Protokolle

Jede Schaltfläche schreibt bis zu vier ToolCallLog-Zeilen: OFFERED, wenn die KI sie angehängt hat, TAPPED, wenn der Besucher darauf getippt hat, danach SUCCESS oder FAILED mit der Meldung Ihres Handlers. Ein Aufruf, den HelpStack abgelehnt hat (ungültige Argumente, eine dritte Schaltfläche), wird mit dem Grund als FAILED protokolliert.

Verwandte Themen#

• Agent-Tools-Leitfaden
• API-Referenz
• Widget-Einbettung
• Glossar