So erstellst du ein Tool (Beta)

Beta-Funktion. Die Erstellung vollständig benutzerdefinierter Tools von Grund auf ist in der offenen Beta-Phase und für alle Customer Agent-Konten verfügbar – eine Registrierung ist nicht erforderlich. Du findest die Seite „Tools“ unter „Customer Agent“. Die Funktion wird noch erweitert und kann sich ändern.

Übersicht

So verbindest du Customer Agent mit einem vollständig benutzerdefinierten Tool mit einem beliebigen HTTP-Endpunkt, schreibst eine Beschreibung des Tools, das Customer Agent tatsächlich verwenden wird, und testest dein Tool, bevor du es an eine Qualifikation anfügst.

Bevor du anfängst

Du benötigst:

• Customer Agent aktiviert
• Ein HTTP-Endpunkt, den Customer Agent aufrufen soll – einer, für den heute keine geheimen Zugangsdaten (API-Schlüssel, Bearer-Token usw.) erforderlich sind (authentifizierte Endpunkt kommen bald, siehe Warnung unten)
• Eine Fähigkeit, mit der du das Tool verknüpfen kannst – entweder ein Skill-Customer Agent oder eine vollständig benutzerdefinierte Fähigkeit, die du erstellt hast

Wenn du noch keine Fertigkeit eingerichtet hast, erstelle zuerst eine. Tools machen nichts von sich aus – sie müssen an eine Fähigkeit gebunden sein.

Achtung: Sichere Aufbewahrung für API-Schlüssel und andere Daten ist bald verfügbar. Bis zum Versand solltest du API-Schlüssel, Inhabertoken oder andere vertrauliche Zugangsdaten nicht in vollständig benutzerdefinierte Tools einfügen. Die Toolkonfiguration ist noch kein sicherer Ort, um sie zu speichern. Verwende vorerst nur Tools mit Endpunkten, die ohne Secret Authth erreichbar sind (z. B. interne Endpunkt hinter der IP-Liste oder Endpunkt, die nicht vertrauliche Kennungen akzeptieren). Unterstützung für authentifizierte Endpunkt ist auf dem Weg.

Was ist ein vollständig benutzerdefiniertes Tool?

Ein vollständig benutzerdefiniertes Tool ist eine HTTP-Anfrage, die Customer Agent während einer Unterhaltung stellen können. Die Erstellung vollständig benutzerdefinierter Tools befindet sich in der offenen Beta-Phase und ist für alle Customer Agent-Konten verfügbar. Verwende eines dieser Tools, wenn der Customer Agent nicht auf deine Anforderungen zugeschnitten ist, z. B. wenn du eine Bestellung in deinem eigenen Bestellverwaltungssystem statt in Shopify nachschlagen, den Bestand in einem benutzerdefinierten Lagersystem überprüfen oder ein Ticket in einem Helpdesk erstellen möchtest, in den Klaviyo nicht integriert ist.

Das zugrunde liegende Konzept findest du im Artikel Grundlegendes zu Customer Agent-Tools.

Wann ein vollständig benutzerdefiniertes Tool erstellt werden sollte

Du benötigst ein vollständig benutzerdefiniertes Tool, wenn:

• Du benötigst Echtzeitdaten von einem System, mit dem Klaviyo noch nicht integriert ist
• Du möchtest, dass der Customer Agent eine Aktion in einem externen Systemdurchführt (ein Abonnement in deinem proprietären System kündigen, ein Ticket erstellen, einen Datensatz aktualisieren)
• Ein vorhandenes Tool passt nicht – du verwendest z. B. ein benutzerdefiniertes OMS anstelle von Shopify für Bestellungen

Wenn sich die Informationen nicht oft ändern und für alle Kund*innen gleich sind, füge sie stattdessen als Inhalt hinzu. Tools sind für dynamische, kundenspezifische Daten und Aktionen konzipiert.

Vorbereitung

1. Öffne die Seite Tools

Navigiere zu Customer Agent > Tools und klicke dann auf Tool erstellen.

2. Tool benennen und beschreiben

• Name – eine kurze Kennung wie „Get Inventory“ oder „Create Return Ticket“.
• Beschreibung – Natürliche Sprache, die erklärt, was das Tool macht und wann es verwendet wird. Customer Agent liest diese Beschreibung, um zu entscheiden, ob das Tool für eine bestimmte Anfrage verwendet werden soll. Sei konkret.

Ein gutes Beispiel für eine Beschreibung:

Ruft die Echtzeit-Bestandszählung für eine bestimmte Produkt-SKU aus dem Lagersystem ab. Verwende sie, wenn Kund*innen fragen, ob ein bestimmtes Produkt auf Lager ist.

Ein vages Beschreibungsbeispiel (vermeiden):

Ruft Produktinformationen ab.

3. Konfiguriere die HTTP-Anfrage

• Methode: GET, POST, PUT, DELETE oder PATCH.
• URL – Die vollständige Endpunkt-URL. Du kannst Platzhalter für dynamische Werte einfügen (siehe Schritt 5).
• Header – Alle Header, die dein Endpunkt benötigt, einschließlich Content-Type und Authentifizierungs-Header.

4. Konfiguriere den Anforderungstext (für POST, PUT, PATCH).

Gib einen JSON-Text an. Verwende Platzhalter für Werte, die Customer Agent zur Laufzeit ausfüllen sollte.

Beispieltext:

{
  „customer_id“: „{{profile_id}}“,
  „SKU“: „{{product_sku}}“
}

5. Platzhalter für dynamische Werte verwenden

Customer Agent können zur Laufzeit Werte mithilfe von Platzhaltern eingeben. Häufige Platzhalter:

• {{profile_id}} – Die Klaviyo-Profil-ID des Kunden in der Unterhaltung
• {{conversation_id}} – Die aktuelle Unterhaltungs-ID
• Alle Parameter, die du in deinem Eingabeschema definierst (z. B. {{product_sku}}, {{order_id}})

Platzhalter funktionieren in URL, Header und Textkörper.

6. Authentifizierung

Der Support für authentifizierte Endpunkt ist in Kürze verfügbar. Bis dahin solltest du keine API-Schlüssel, Inhabertoken oder andere Geheimnisse in ein vollständig benutzerdefiniertes Tool einfügen. Verwende nur Endpunkt, die ohne geheime Zugangsdaten erreichbar sind, z. B. interne Endpunkt, die durch eine IP-AllowListing geschützt sind, oder öffentliche Endpunkt, die nicht vertrauliche Kennungen akzeptieren.

Der sichere geheime Speicher ist unterwegs und schaltet authentifizierte Endpunkt frei.

7. Tool testen

Klicke auf Testtool. Gib Beispielwerte für alle Eingabeparameter an. Überprüfe, dass:

• Die Antwort wird erfolgreich zurückgegeben
• Das Antwortformat entspricht den Erwartungen der Customer Agent
• Alle Fehlerfälle werden behandelt

8. Speichere und füge eine Fertigkeit hinzu

Klicke auf Speichern. Damit der Customer Agent das Tool auch wirklich nutzen kann, öffne die gewünschte Fertigkeit und füge das Tool dort hinzu.

Verfassen einer guten Werkzeugbeschreibung

Die Beschreibung ist das wichtigste Feld. Der Customer Agent wählt das zu verwendende Tool ausschließlich anhand der Beschreibung und nicht anhand des Namens aus. Gute Beschreibungen:

• Sag, was das Tool in einem Satz macht
• Sag, wann du sie in einem Satz verwenden solltest
• die zurückgegebenen Daten oder die durchgeführten Aktionen genau beschreiben

Schlechte Beschreibungen sind vage („Ruft Kundeninformationen ab“), zu allgemein („Behandelt alles, was mit Bestellungen zusammenhängt“) oder sagen dem Customer Agent, wie er sich verhalten soll, anstatt was das Tool tut.

Sicherheitsüberlegungen

• Verwende noch keine vollständig benutzerdefinierten Tools für Endpunkt, die geheime Zugangsdaten benötigen. Der Support für authentifizierte Endpunkt ist in Kürze verfügbar. Verwende bis zum Versand nur Endpunkt, die ohne Geheimbestätigung anrufbar sind.
• Verwende, wo möglich, eine zugelassene IP-Liste. Wenn dein Endpunkt intern ist, solltest du den Zugriff auf Klaviyo IP-Bereiche beschränken, anstatt dich auf geheime Daten zu verlassen.
• Achte darauf, welche Daten du versendest. Der Customer Agent gibt Kundendaten basierend auf den Anweisungen in der Qualifikationsanleitung an das Tool weiter. Überprüfe, welche Felder dein Endpunkt erhält.
• Ratenlimits. Wenn dein Endpunkt Ratenlimits hat, stelle sicher, dass diese hoch genug sind, um dein erwartetes Unterhaltung-Volumen zu bewältigen.

Fehlerbehebung

Symptom: Customer Agent verwendet das Tool nie.
Wahrscheinliche Ursache: Die Beschreibung ist zu vage oder das Tool hängt nicht von der Fähigkeit ab, die es verwenden würde.
Fix: Schreibe die Beschreibung neu, um genau zu beschreiben, wann sie verwendet werden sollte. Bestätige, dass das Tool in der Werkzeugliste der Qualifikation erscheint.

Symptom: Das Tool gibt während des Tests einen Fehler zurück.
Wahrscheinliche Ursache: Falsche URL, falsch formatierter Text oder eine Nutzlast, die dein Endpunkt nicht akzeptiert.
Fix: Verwende die Testtool-Funktion, um die Rohanforderung und -antwort zu überprüfen. Überprüfe die URL und das Textkörperformat mit der erwarteten Eingabe deines Endpunkts.

Symptom: Customer Agent verwendet das Tool, übergibt aber falsche Parameter.
Wahrscheinliche Ursache: Die Platzhalternamen stimmen nicht mit dem Schema überein, oder die Anweisungen zum Bestehen sind unklar.
Fix: Überprüfe, ob die Platzhalternamen genau übereinstimmen. Aktualisiere die praktischen Anweisungen, um deutlich zu machen, wann du das Tool verwenden solltest und welche Parameter du angeben solltest.

Symptom: Das Tool ist langsam und verursacht Verzögerungen bei den Antworten.
Wahrscheinliche Ursache: Endpunkt-Latenz.
Fix: Optimiere deinen Endpunkt. Prüfe, ob du die Ergebnisse auf deiner Seite zwischenspeichern kannst.

FAQ

Kann ein Tool von mehreren Mitarbeitern genutzt werden?
Ja. Einmal erstellt, kann ein Tool an eine beliebige Anzahl von Fertigkeiten angehängt werden.

Welche Authentifizierungsmethoden werden unterstützt?
Der Support für authentifizierte Endpunkt ist in Kürze verfügbar. Verwende vorerst Endpunkt, die keine geheimen Zugangsdaten erfordern (interne Endpunkt mit zugelassener IP-Liste oder öffentliche Endpunkt mit nicht vertraulichen Kennungen).

Was passiert, wenn mein Endpunkt ausgefallen ist oder eine Fehlermeldung zurückgibt?
Die Fehlerbehandlung für vollständig benutzerdefinierte Tools ist noch nicht vollständig integriert. Wenn dein Endpunkt fehlschlägt, kann der Customer Agent eine eingeschränkte oder verwirrende Antwort hervorrufen. Bis zur Fehlerbehebung solltest du nur Endpunkt verwenden, die dir sicher sind – und das Verhalten der Tools genau überwachen.

Kann ich ein Tool nach der Erstellung bearbeiten?
Ja. Du kannst den Namen, die Beschreibung, die Konfiguration und die angehängten Fertigkeiten jederzeit bearbeiten.

Kann ich ein Tool versionieren?
Die Versionierung wird noch nicht unterstützt. Änderungen an einem Tool werden sofort für jede Fertigkeit wirksam, die es verwendet.

Weitere Ressourcen