Anleitungen

Agententools (Übersicht)

Agententools geben Ihrer KI benutzerdefinierte Fähigkeiten. Anstatt nur aus bekanntem Text zu antworten, kann die KI beim Entwerfen einer Antwort Ihre Systeme aufrufen — zum Beispiel um den „Bestellstatus nachzuschlagen" oder ein „Lieferdatum zu überprüfen" — und das Ergebnis in ihre Antwort einflechten. Dieser Leitfaden ist die konzeptionelle, aufgabenorientierte Übersicht: was Tools sind, die vier Typen, die Sie selbst erstellen, wie Sie eines erstellen, wie Sie eine Beschreibung schreiben, die die KI tatsächlich gut nutzt, Import aus OpenAPI und die Zuweisung von Tools zu Kanälen. Für Endpunkt-, Sicherheits- und JSON Schema-Details siehe den im gesamten Dokument verlinkten Integrationsleitfaden.

Sie finden Tools unter Einstellungen → Agententools (Route /settings/agent-tools). Für die Verwaltung von Agententools ist die Rolle OWNER oder ADMIN erforderlich; Agenten und Betrachter können diese in der Regel einsehen.

Benutzerdefinierte Agent-Tools erfordern den Growth-Tarif oder höher. Bei Free und Starter wird das Erstellen eines Tools oder das Zuweisen an einen Kanal mit „Benutzerdefinierte Agent-Tools sind ab dem Growth-Tarif verfügbar" abgelehnt. Die Shopify- und WooCommerce-Tools, die beim Verbinden eines Shops automatisch erscheinen, sind davon nicht betroffen: Sie gehören in jedem Tarif zur Integration.

Die eingebauten Shop-Tools prüfen, wer fragt. Die Bestell- und Tracking-Tools, die mit einer Shopify- oder WooCommerce-Verbindung kommen, brauchen die Bestellnummer und die E-Mail-Adresse, mit der die Bestellung aufgegeben wurde, und geben nichts zurück, solange beide nicht übereinstimmen. Ein Tool, das Sie selbst bauen, bekommt diese Prüfung nicht automatisch: Gibt es die Daten eines Kunden auf eine Kennung heraus, die ein anderer Kunde erraten könnte, wird die KI sie weiterreichen. Wie sich die eingebauten verhalten, steht in Erste Schritte mit Shopify.

Was ein Agentool ist#

Ein Tool ist eine benutzerdefinierte Fähigkeit, die Sie der KI geben. Wenn die Nachricht eines Kunden nach Live- oder kontospezifischen Informationen verlangt — zum Beispiel dem Status ihrer Bestellung — kann die KI das Tool aufrufen, echte Daten zurückbekommen und diese nutzen, um eine präzise Antwort zu verfassen. Damit wird die KI von etwas, das nur Ihre Dokumentation kennt, zu etwas, das in Ihrem Namen innerhalb der von Ihnen definierten Grenzen handeln kann.

Die vier Tool-Typen, die Sie selbst erstellen#

HelpStack hat insgesamt sieben Tool-Typen. Vier davon bauen Sie selbst, sie sind unten beschrieben. Die anderen drei entstehen von allein und werden nicht über diesen Bildschirm erstellt: Shopify- und WooCommerce-Tools erscheinen, wenn Sie einen Shop verbinden, und Control-Tools sind eingebaut und Teil von HelpStack. Diese drei können Sie weder erstellen noch löschen, aber Sie können ihnen eine Notiz hinzufügen, damit die KI weiß, wie Ihr Unternehmen damit umgeht.

Server-seitig (SERVER_SIDE)

HelpStack ruft einen HTTP-Endpunkt auf, den Sie bereitstellen. Sie definieren:

Name
Beschreibung (siehe Eine gute Beschreibung schreiben — dies ist das wichtigste Feld)
URL Ihres Endpunkts
HTTP-Methode
Optionale Header
Ein Parameter-JSON Schema, das die Eingaben beschreibt, die die KI liefern muss

Dies ist der häufigste Fall: HelpStack wendet sich an Ihr Backend, das die Daten zurückgibt.

Client-seitig (CLIENT_SIDE)

Das Tool läuft im Browser des Website-Besuchers und nicht auf Ihrem Server. Greifen Sie darauf zurück, wenn die Aktion wirklich in den Browser des Besuchers gehört: auf eine Schaltfläche in Ihrer eigenen Oberfläche zeigen, auslesen, auf welchem Bildschirm er sich befindet, ein Panel für ihn öffnen.

Ihre Seite stellt den Handler bereit. Registrieren Sie ihn namentlich beim Widget-Skript:

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

Was der Handler zurückgibt, ist das, was die KI liest. Siehe Benutzerdefinierte Agent-Tools für den Queue-Shim, mit dem Sie registrieren können, bevor das Skript geladen ist, und für den zugrunde liegenden postMessage-Vertrag, falls Sie ihn lieber selbst beantworten möchten.

E-Mail-Anfrage (EMAIL_INQUIRY)

Die anderen beiden Typen antworten innerhalb derselben Antwort. Eine E-Mail-Anfrage nicht. Manche Fragen lassen sich aus Ihren eigenen Systemen überhaupt nicht beantworten: Ein Paket ist verspätet und nur der Versanddienst weiß, wo es ist; ein Teil ist rückständig und nur der Lieferant kann sagen, wann es rausgeht. Dieser Typ lässt die KI genau diese Stellen fragen und nimmt das Gespräch wieder auf, wenn die Antwort eintrifft.

So läuft es in der Praxis:

Ein Kunde fragt etwas, das die KI nicht allein beantworten kann.
Die KI schreibt die E-Mail selbst, in eigenen Worten, und schickt sie an die von Ihnen genannte Adresse aus einem Ihrer verbundenen Postfächer. Es gibt keine Vorlage.
Sie sagt dem Kunden, dass Sie das prüfen, mit dem von Ihnen hinterlegten Wortlaut.
Das Gespräch wechselt in den Status Wartet auf Antwort (WAITING). Das heißt nicht „braucht einen Menschen", also bleibt es aus der Arbeitsliste Ihres Teams heraus, und die Wartezeit wird von der Lösungszeit in der Analyse abgezogen.
Antwortet die Gegenseite, ordnet HelpStack die Antwort wieder der Frage zu, zu der sie gehört, und die KI schreibt dem Kunden, was sie erfahren hat. Das Gespräch geht mit einer Ungelesen-Markierung zurück auf Offen.

Während es wartet, antwortet die KI dem Kunden ganz normal weiter. Hakt der Kunde nach, sagt sie, dass sie noch wartet, statt dem Versanddienst ein zweites Mal zu schreiben.

E-Mail-Anfragen sind für jede Organisation standardmäßig ausgeschaltet. Sie brauchen wie jedes andere benutzerdefinierte Tool den Growth-Tarif, und HelpStack muss die Funktion für Sie freischalten. Das ist Absicht: Kein anderes Tool verschickt aus eigener Initiative der KI echte Post von Ihrer eigenen Domain, und das sollte nicht mit einem Tarif-Upgrade hereinkommen, über das niemand gesprochen hat.

Was Sie einstellen

Neben dem üblichen Namen, der Beschreibung und dem Parameter-JSON Schema:

Wen die KI anschreibt. Die Adresse, an die die Frage geht, zum Beispiel das Support-Postfach eines Versanddienstes.
Senden von. Einer Ihrer aktiven E-Mail-Kanäle. Dasselbe Postfach schickt die Frage und empfängt die Antwort, es muss also ein Postfach sein, das HelpStack abruft.
Wie lange gewartet wird. Zwischen 1 und 720 Stunden.
Wenn niemand rechtzeitig antwortet. Eine Erinnerung schicken, das Gespräch an einen Menschen übergeben oder dem Kunden sagen, dass es noch keine Antwort gibt.
Was die KI dem Kunden während des Wartens sagt. Eine kurze Anweisung, kein Skript. Halten Sie es kurz und versprechen Sie keinen Termin.
Wie die Frage verschickt wird. „Automatisch senden" ist heute die einzige Option, die funktioniert. „Zur Freigabe entwerfen" steht bewusst deaktiviert daneben: Die Freigabe-Warteschlange dafür ist noch nicht gebaut, ein so eingestelltes Tool würde also jeden Aufruf ablehnen, nachdem die KI dem Kunden bereits gesagt hat, sie prüfe das. Sie wird gezeigt statt versteckt, damit Sie nicht nach einer Einstellung suchen, die zu fehlen scheint.

Die Beschreibung des Tools ist der Ort für Ihre Regeln zu dieser Gegenseite. „Nenne nur die Bestellnummer, niemals E-Mail oder Telefon des Kunden" ist genau die Zeile, die die KI liest, bevor sie schreibt.

Geben Sie dem Tool ein Feld für die Bestell- oder Sendungsnummer

Das ist wichtiger, als es aussieht.

Bevor eine Anfrage Ihr Postfach verlässt, entfernt HelpStack aus Betreff und Text, was sensibel aussieht: lange Ziffernfolgen, benannte Geheimnisse wie ein Passwort oder eine Kartennummer, E-Mail-Adressen. Was die KI in einen benannten Parameter Ihres Tools geschrieben hat, trackingNumber oder orderId, geht unverändert durch. Was sie in den Freitext getippt hat, nicht.

Ein Tool, dessen Parameter nur Betreff und Text sind, kann also nicht nach einem Paket fragen. Die Sendungsnummer geht geschwärzt raus und der Versanddienst hat nichts, womit er arbeiten könnte. Dieselbe Form macht noch etwas kaputt: HelpStack erkennt eine Wiederholungsfrage über den Vergleich der benannten Parameter, ohne sie wird also die nächste, wirklich andere Frage in diesem Gespräch als Dublette abgelehnt.

Das Tool-Formular warnt Sie darauf unter dem Parameter-Editor, und die Warnung verschwindet, sobald das Schema ein eigenes Feld für die Kennnummer hat. Der manuelle Dialog zeigt aus demselben Grund dieselbe Warnung.

Der Filter ist ein Sicherheitsnetz, keine Garantie. Er fängt offensichtliche Fehler ab. Er ist kein System zur Verhinderung von Datenabfluss und behauptet nicht, alles zu finden. Schreiben Sie in die Beschreibung des Tools klar, was die KI nennen darf und was nicht, und wählen Sie Gegenstellen, denen Sie die Frage ohnehin anvertrauen würden.

Was Sie im Gespräch sehen

Unter dem Kundenverlauf bekommt jede Frage, die die KI verschickt hat, eine eigene Karte. Klappen Sie eine auf, sehen Sie die Frage so, wie sie tatsächlich rausgegangen ist (mit einem Hinweis, falls unterwegs etwas entfernt wurde), und jede Nachricht, die seither mit der Gegenseite gewechselt wurde. Dieser Nebenverlauf taucht sonst nirgends in Ihrem Posteingang auf, diese Karte ist also der einzige Ort, an dem Sie ihn lesen können.

Eine Karte steht in einem dieser Zustände: Wartet auf Antwort, Beantwortet, Muss geprüft werden, Keine Antwort rechtzeitig, Abgebrochen oder Konnte nicht gesendet werden.

Muss geprüft werden heißt: Eine Antwort ist eingetroffen, und HelpStack konnte nicht erkennen, ob sie die Frage beantwortet. Das Gespräch wird an einen Menschen übergeben, und die Karte bietet drei Möglichkeiten an, direkt neben dem Schriftwechsel, um den es geht:

Das ist die Antwort. Schließt die Frage mit dieser Antwort ab und lässt die KI dem Kunden schreiben. Das Gespräch verlässt Ihre Warteschlange.
Keine Antwort, weiter warten. Lässt die Frage offen, damit eine spätere, klarere Nachricht sie noch abschließen kann, und setzt das Gespräch zurück auf Wartet auf Antwort.
Frage schließen. Gibt die Frage auf. Dem Kunden wird nichts gesagt, und das Gespräch bleibt bei Ihnen.

Sind in einem Gespräch zwei Fragen gleichzeitig offen, zeigen beide Karten die Markierung. Sie gehört zum Gespräch und nicht zu einer einzelnen Frage, kann also nicht sagen, welche Antwort sie ausgelöst hat. Genau deshalb zeigt die Karte den Schriftwechsel: Lesen Sie beide, und Sie sehen, welche Gegenstelle tatsächlich geschrieben hat.

Sie können eine Gegenstelle auch selbst fragen. Öffnen Sie im Gespräch das Menü ⋮, wählen Sie Dritte Partei fragen, wählen Sie das Tool, füllen Sie seine Felder aus und bearbeiten Sie Betreff und Text. Es geht denselben Weg, den auch die KI nimmt, mit denselben Grenzen. Für die Entscheidung über eine Antwort gibt es keine Abkürzung: Diese drei Schaltflächen bleiben in der Karte, damit niemand eine Antwort annimmt, die er nicht gelesen hat.

Was die KI mit der Antwort macht

Wird die Antwort als Antwort erkannt, bekommt die KI deren Text als Kontext für die Nachricht, die sie Ihrem Kunden schreibt. Die KI ist angewiesen, in Ihrem Ton zu antworten und keine Tools oder internen Abläufe zu erwähnen, und die üblichen Antwortregeln gelten ebenfalls. Trotzdem schreibt die Gegenseite damit in einen Prompt. Wenn das für ein bestimmtes Postfach eine Rolle spielt, lassen Sie die Freigabe für den Kanal eingeschaltet, damit ein Mensch den Entwurf liest, bevor er rausgeht.

Asynchroner Auftrag (CALLBACK_JOB)

Ein asynchroner Auftrag ist das Geschwister der E-Mail-Anfrage, nur für Arbeit statt für eine Frage und für eine Maschine statt für einen Menschen. Die KI übergibt einen Auftrag an eines Ihrer Systeme, das Gespräch wartet, und es wird fortgesetzt, sobald dieses System den Auftrag als erledigt meldet.

Verwenden Sie ihn, wenn die Arbeit wirklich länger dauert, als eine Antwort warten kann: ein Rebuild, eine Massenaktualisierung, ein Rendering, alles, was bei Ihren Workern in der Warteschlange liegt. Wenn Ihr System antworten kann, während die Anfrage offen ist, nehmen Sie stattdessen ein serverseitiges Tool: Die Einrichtung ist einfacher und die Antwort kommt in derselben Nachricht.

Worin er sich von einer E-Mail-Anfrage unterscheidet:

	E-Mail-Anfrage	Asynchroner Auftrag
Wer wird gefragt	Eine Person	Eines Ihrer Systeme
Wartet typischerweise	Stunden oder Tage	Sekunden bis eine Stunde
Ist die Antwort eine Antwort?	Die KI beurteilt das	Ihr System sagt es selbst
Wenn niemand antwortet	Kann eine Erinnerung senden	Keine Erinnerungen; die Frist entscheidet

Die Einrichtung erfordert eine Entwicklerin oder einen Entwickler auf Ihrer Seite: Ihr System muss den Auftrag annehmen und HelpStack nach Abschluss zurückrufen. Der Vertrag ist beschrieben in Asynchrone Tools (Callback).

Verfügbarkeit. Asynchrone Aufträge stehen hinter einem Feature-Flag. Bitten Sie uns, es für Ihre Organisation zu aktivieren; danach erstellen und bearbeiten Sie das Tool selbst unter Einstellungen → Agententools, genau wie eine E-Mail-Anfrage.

Tools erstellen und verwalten#

Unter Einstellungen → Agententools können Sie:

Ein Tool erstellen (wählen Sie seinen Typ, füllen Sie dann die Felder aus).
Ein vorhandenes Tool bearbeiten.
Ein Tool löschen.
Ein Tool Aktiv / inaktiv schalten, ohne es zu löschen.

Tool-Aufrufe werden protokolliert, sodass Sie überprüfen können, was die KI aufgerufen hat.

Eine Notiz zu einem eingebauten Tool hinzufügen

Shopify-, WooCommerce- und Control-Tools lassen sich nicht bearbeiten oder löschen — sie werden von uns gepflegt, und eine Verbesserung ihrer Funktionsweise erreicht Sie automatisch. Damit hätten Sie normalerweise keine Möglichkeit, der KI etwas Spezifisches über Ihr Unternehmen mitzuteilen, deshalb nehmen diese Tools stattdessen eine Notiz entgegen.

Die Notiz wird der Beschreibung des Tools hinzugefügt, statt sie zu ersetzen. Genau das lässt beides gleichzeitig zu: Wir verbessern den Wortlaut weiter, und Ihre Anweisung überlebt jede Aktualisierung. Nutzen Sie sie für das, was nur Sie wissen:

Bestellungen nach 14:00 Uhr werden am nächsten Werktag versandt.

Wir liefern nicht an Postfächer. Fragen Sie nach einer Straßenanschrift, bevor Sie eine Lieferung zusagen.

Lassen Sie die Notiz leer, um sie zu entfernen. Alles Übrige am Tool bleibt unseres.

Eine gute Beschreibung schreiben#

Die Beschreibung ist entscheidend — sie ist das, was die KI liest, um zu entscheiden, wann sie das Tool aufrufen soll. Schreiben Sie sie wie Anweisungen an einen neuen Kollegen, der Ihre Systeme noch nie gesehen hat:

Sagen Sie wann man es verwendet und wofür es da ist.
Sagen Sie, welche Informationen erforderlich sind, um es aufzurufen.

Ein gutes Beispiel:

„Verwenden Sie dies, wenn der Kunde nach dem Status einer bestehenden Bestellung fragt. Erfordert deren Bestellnummer."

Hier würde ORDER_NUMBER einer der im Parameter-JSON Schema des Tools definierten Parameter sein. Eine vage Beschreibung veranlasst die KI, das Tool zum falschen Zeitpunkt aufzurufen oder es ganz zu überspringen; eine klare macht es zuverlässig.

Import aus OpenAPI#

Wenn Ihre Systeme bereits über eine OpenAPI-Spezifikation verfügen, müssen Sie Tools nicht einzeln definieren. Verwenden Sie „Aus OpenAPI importieren" und stellen Sie Ihre Spezifikation bereit — HelpStack generiert Tools daraus. Dies ist der schnellste Weg, eine bestehende API für die KI zugänglich zu machen.

Organisationsweite vs. kanalspezifische Tools#

Tools können organisationsweit definiert werden, sodass sie überall verfügbar sind.
Tools können auch pro Kanal zugewiesen oder überschrieben werden unter Einstellungen → Kanäle → Kanal → Tools.

Das bedeutet, Sie können einen gemeinsamen Satz von Tools behalten und dennoch anpassen, welche Tools ein bestimmter Kanal verwenden kann — zum Beispiel, indem Sie ein Bestellnachschlage-Tool nur auf Ihrem Support-Kanal verfügbar machen.

E-Mail-Anfrage-Tools gibt es nur organisationsweit. Sie erstellen und bearbeiten sie unter Einstellungen → Agententools, nie in der Tools-Registerkarte eines Kanals; ein kanalgebundenes Tool dieser Art würde an keiner Stelle auftauchen, an der Sie es bearbeiten oder abschalten könnten. Es erreicht trotzdem jeden Kanal, und das Postfach, aus dem es sendet, gehört zum Tool selbst.

Weiterführende Informationen#

Dieser Leitfaden bleibt absichtlich konzeptionell. Für die technischen Details — Endpunkt-Verträge, Authentifizierung und Sicherheit, Header und wie Sie das Parameter-JSON Schema schreiben — siehe den Integrationsleitfaden:

Benutzerdefinierte Agententools (Integrationsleitfaden)