So erstellst du ein Tool

Übersicht

So verbindest du Customer Agent über ein vollständig benutzerdefiniertes Tool mit einem HTTP-Endpunkt, schreibst eine Toolbeschreibung, die Customer Agent tatsächlich verwendet, und testest dein Tool, bevor du es an Skills anhängst.

Bevor du anfängst

Du benötigst:

• Customer Agent aktiviert
• Ein HTTP-Endpunkt, der über einen öffentlichen Hostnamen erreichbar ist. Adressen in privaten Netzwerken, localhost und URLs, die eine IP-Adresse anstelle eines Hostnamens verwenden, werden nicht unterstützt. Wenn der Endpunkt einen API-Schlüssel oder ein Token erfordert, speicherst du ihn als Secret (siehe Schritte 1 und 6).
• Ein Skill mit bearbeitbaren Anweisungen, an das du das Tool anhängen kannst

Du kannst das Tool erstellen und testen, bevor du es an einen Skill anhängst. Um es in Unterhaltungen zu verwenden, füge es zu den Anweisungen des Skills hinzu. Wenn du einen neuen Skill benötigst, siehe So erstellst du einen Skill.

Was ist ein vollständig benutzerdefiniertes Tool?

Ein vollständig benutzerdefiniertes Tool ist eine HTTP-Anfrage, die Customer Agent während eines Gesprächs stellen kann. Verwende eins, wenn die Tools, die Customer Agent mitbringt, nicht abdecken, was du brauchst – zum Beispiel, um eine Bestellung in deinem eigenen Auftragsverwaltungssystem statt in Shopify nachzuschlagen, den Lagerbestand in einem benutzerdefinierten Lagersystem zu prüfen oder ein Ticket in einem Helpdesk zu erstellen, in den Klaviyo keine native Integration hat.

Zum zugrunde liegenden Konzept siehe Tools verstehen.

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 „Benutzerdefinierte Tools“

1. Navigiere zu Customer Agent > Konnektoren und öffne dann die Karte Benutzerdefiniert.
2. Wenn dein Endpunkt eine Anmeldeinformation benötigt, gehe zu Secrets und klicke auf Secret hinzufügen. Gib einen Namen und einen Secret-Wert ein und klicke dann auf Secret hinzufügen. Überspringe diesen Schritt, wenn das Secret bereits gespeichert ist oder der Endpunkt keines benötigt.
3. Klicke auf Tool erstellen.

2. Tool benennen und beschreiben

• Tool-Name — Eine kurze Kennung wie „Inventar abrufen“ oder „Retourenticket erstellen“.
• 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

• HTTP-Methode — GET, POST, PUT, DELETE oder PATCH.
• URL-Vorlage — 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.
• Abfrageparameter — Wenn dein Endpunkt Werte in der Abfragezeichenfolge erwartet, gib hier ihre Namen und Werte ein. Du kannst Platzhalter für die Werte verwenden (siehe Schritt 5).

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

Gib in Body-Vorlage ein JSON-Objekt an. Verwende Platzhalter für Werte, die Customer Agent zur Laufzeit ausfüllen sollte.

Beispieltext:

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

5. Definiere Variablen für dynamische Werte

Jeder Platzhalter muss unter Variablen eine passende Variable haben. Für den obigen Beispiel-Body:

1. Klicke auf Variablen hinzufügen und gib profile_id als Variablenname ein. Setze Quelle auf Klaviyo Profil und Klaviyo Eigenschaft auf Klaviyo ID. Damit wird die Klaviyo Profil-ID der authentifizierten Shopper*in bereitgestellt.
2. Füge eine weitere Variable mit dem Namen product_sku hinzu. Lege Quelle auf Dynamische Variable fest, wähle String als Typ aus und beschreibe die SKU, die der Customer Agent in Beschreibung bereitstellen soll. Wähle Erforderlich aus, wenn der Endpunkt dies erfordert.

Wiederhole dies für weitere Werte, die dein Endpunkt benötigt, wie z. B. order_id. Variablennamen müssen exakt mit ihren Platzhaltern übereinstimmen. Eine Variable mit dem Namen conversation_id wird nicht automatisch mit der aktuellen Gesprächs-ID ausgefüllt.

Verwende die Variablen als Platzhalter, wie {{profile_id}} und {{product_sku}}, in der URL, in Headern, in Abfrageparametern oder im Body. Tools, die Klaviyo Profil -Variablen verwenden, erfordern authentifizierte Shopper*innen; ein fehlender erforderlicher Profilwert verhindert, dass die Anfrage ausgeführt wird.

6. Authentifizierung

Wenn dein Endpunkt einen API-Schlüssel, Bearer-Token oder andere Zugangsdaten erfordert, speichere ihn als Secret. Secrets sind verschlüsselt, ihre Werte werden dem Customer Agent nie angezeigt, und du kannst sie nach dem Speichern nicht mehr ansehen.

1. Klicke in deinem Tool unter Variablen auf Variablen hinzufügen. Gib der Variable einen Namen (zum Beispiel api_key), setze Quelle auf Secret, und wähle das Secret aus, das du gespeichert hast.
2. Verweise auf die Variable überall dort, wo dein Endpunkt die Zugangsdaten erwartet: in einem Header, in der URL, in einem Abfrageparameter oder im Body. Füge zum Beispiel einen Header mit dem Namen Authorization und dem Wert Bearer {{api_key}} hinzu.

Um einen Schlüssel zu rotieren, öffne das Zeilenmenü des Secrets, klicke auf Aktualisieren, gib den Ersatzwert ein und klicke dann auf Aktualisieren. Jedes Tool, das das Secret verwendet, übernimmt den neuen Wert. Die Spalte Verwendet von zeigt, welche Tools auf jedes Secret verweisen. Prüfe das, bevor du eines löschst.

7. Speichere und teste das Tool

Überprüfe vor dem Speichern Timeout (Sekunden) und Maximale Wiederholungsversuche unter Einstellungen. Du kannst ein globales Zeitlimit von 1–10 Sekunden und 0–3 Wiederholungsversuche für vorübergehende Fehler festlegen. Wenn das Tool Daten ändert, stelle sicher, dass dein Endpunkt eine wiederholte Anfrage sicher verarbeiten kann.

Klicke auf Speichern, um das Tool zu erstellen. Das gespeicherte Tool wird mit einem Abschnitt Test geöffnet.

Tests senden echte Anfragen an deinen Endpunkt und können Daten ändern. Verwende ein Testprofil und Testdatensätze. Test speichern und ausführen speichert auch alle Bearbeitungen am Tool, einschließlich eines Tools, das bereits von Live-Skills verwendet wurde.

Gib in Test Beispielwerte für die dynamischen Variablen ein. Wähle unter Profil ein Testprofil aus, wenn das Tool Variablen für Klaviyo Profil verwendet. Klicke auf Speichern und Test durchführen.

Überprüfe Antwort und stelle sicher, dass:

• Die Antwort wird erfolgreich zurückgegeben
• Die Antwort enthält die Daten, die dein Skill benötigt.
• Erwartete Fehlerfälle geben nützliche Statuscodes und Meldungen zurück

8. Hänge das Tool an einen Skill an

1. Navigiere zu Customer Agent > Skills und öffne den Skill, in dem du das Tool verwenden möchtest. Wenn seine Anweisungen schreibgeschützt sind, erstelle einen vollständig benutzerdefinierten Skill.
2. Gib unter How to respond / an der Stelle ein, an der das Tool verwendet werden soll, und wähle das Tool im Menü aus. Erkläre, wann es aufgerufen werden soll, welche Werte bereitgestellt werden sollen und was mit dem Ergebnis oder einem Fehler zu tun ist.
3. Wenn die Anweisungen bereit sind, klicke für einen Entwurf-Skill auf Veröffentlichen oder für einen Live-Skill auf Aktualisieren.

Verfassen einer guten Werkzeugbeschreibung

Eine klare Beschreibung hilft Customer Agent zu entscheiden, wann das Tool verwendet werden soll. Die Anweisungen der Skills leiten auch, welches Tool sie aufruft und wie sie das Ergebnis verwendet. 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

• Speichere Anmeldedaten als Secrets. Füge niemals einen API-Schlüssel oder ein Token direkt in einen Header, eine URL oder einen Body ein. Füge ihn als Secret hinzu und referenziere ihn mit einer Secret-Variable (siehe Schritt 6).
• Verwende nach Möglichkeit die IP-Zulassungsliste. Dein Endpunkt muss weiterhin über einen öffentlichen Hostnamen erreichbar sein; Adressen in privaten Netzwerken und localhost werden blockiert. Nutze Allowlisting als zusätzliche Schutzebene neben der Authentifizierung.
• Achte darauf, welche Daten du sendest. Deine Anfragekonfiguration und Variablenquellen bestimmen, welche Werte an den Endpunkt gesendet werden. Skills-Anweisungen steuern die Werte, die Customer Agent für dynamische Variablen bereitstellt. Prüfe, welche Felder dein Endpunkt empfängt.
• 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 ist nicht in den veröffentlichten Anweisungen der Skills enthalten.
Behebung: Überarbeite die Beschreibung so, dass sie konkret beschreibt, wann es verwendet werden soll. Füge in So antwortest du das Tool mit / ein und erkläre, wann du es aufrufen solltest. Klicke auf Veröffentlichen oder Aktualisieren, um die Anweisungen anzuwenden.

Symptom: Das Tool gibt während des Tests einen Fehler zurück.
Wahrscheinliche Ursache: Falsche URL, fehlerhafter Body, fehlende erforderliche Profildaten oder ein Payload, das dein Endpunkt nicht akzeptiert.
Behebung: Überprüfe unter Test die Anfragevorschau und die Antwort. Überprüfe URL, Header und Body anhand der erwarteten Eingabe deines Endpunkts. Wenn das Tool Variablen für Klaviyo Profil verwendet, wähle ein Testprofil mit den erforderlichen Werten aus.

Symptom: Customer Agent verwendet das Tool, übergibt aber falsche Parameter.
Wahrscheinliche Ursache: Eine Variable hat die falsche Quelle oder Profileigenschaften, oder die Skills-Anweisungen sind unklar darüber, was übergeben werden soll.
Lösung: Überprüfe die Variablennamen, Quellen und ausgewählten Profileigenschaften unter Variablen. Aktualisiere die Variablenbeschreibungen und Skills-Anweisungen, damit sie eindeutig angeben, was bereitgestellt werden soll.

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 Skills verwendet werden?
Ja. Nach der Erstellung kann ein Tool von mehreren Skills verwendet werden. Füge es in die bearbeitbaren Anweisungen jedes Skills ein und veröffentliche oder aktualisiere jedes Skill.

Welche Authentifizierungsmethoden werden unterstützt?
Alle Methoden, die eine statische Anmeldeinformation mit der Anfrage senden, z. B. ein Bearer-Token oder ein API-Schlüssel-Header. Speichere die Anmeldeinformation als Secret und verweise mit einer Secret-Variable darauf (siehe Schritt 6). Flow, die zum Zeitpunkt der Anfrage ein Token abrufen oder aktualisieren müssen, z. B. OAuth, werden in vollständig benutzerdefinierten Tools nicht unterstützt.

Was passiert, wenn mein Endpunkt nicht verfügbar ist oder einen Fehler zurückgibt?
Klaviyo meldet Tool-Fehler an Customer Agent. Vorübergehende Fehler können innerhalb der Timeout- und Wiederholungslimits des Tools erneut versucht werden. Erkläre in den Anweisungen der Skills, wie du reagieren sollst, wenn das Tool die Anfrage nicht abschließen kann, z. B. indem du eine Übergabe anbietest. Verwende zuverlässige Endpunkte und überwache das Verhalten des Tools genau.

Kann ich ein Tool nach dem Erstellen bearbeiten?
Ja. Öffne das Tool über Customer Agent > Connectors > Custom, bearbeite den Namen, die Beschreibung oder die Anfragekonfiguration und klicke dann auf Speichern. Füge das Tool in den Anweisungen der jeweiligen Skills hinzu oder entferne es.

Kann ich ein Tool versionieren?
Versionierung wird noch nicht unterstützt. Gespeicherte Änderungen gelten für das freigegebene Tool, das von jedem Skill verwendet wird, der darauf verweist. Speichern und Test ausführen speichert ebenfalls Änderungen. Prüfe daher, welche Live-Skills das Tool verwenden, bevor du es bearbeitest.

Weitere Ressourcen