Customer Agent-APIs (Beta)

Übersicht

Was sind die Customer Agent-APIs, was machen die einzelnen Endpunkt-Gruppen und wie rufe ich sie auf? Mit den APIs kannst du deinen Customer Agent konfigurieren, seine Produktionsaktivitäten lesen und ihn programmgesteuert ausführen – direkt über HTTP, zusammen mit der restlichen öffentlichen API von Klaviyo.

Hinweis: Die Customer Agent APIs befinden sich in der Beta-Phase. Endpunkte und Schemas können sich vor der allgemeinen Verfügbarkeit ändern. Beta-APIs sind nicht für den Produktionseinsatz vorgesehen – siehe Klaviyos Richtlinie zur Versionierung und Einstellung für Details.

Was du mit den APIs tun kannst

Die Customer Agent APIs decken 4 Aufgaben ab:

1. Konfiguriere den Agent – lies oder aktualisiere den Agent selbst sowie seine Fähigkeiten, Tools, Wissensquellen und Geheimnisse.
2. Lies dir die Unterhaltungen für die Produktion durch – listen und überprüfen du die Unterhaltungen der Customer Agent auf.
3. Berichte zur Performance – mit Metriken wie Pull-Volumen, Lösungsrate und Kennzahlen pro Qualifikation.
4. Führe den Agent eine Runde lang aus – sende eine Unterhaltung und erhalte die Antwort des Agents zurück. Dies ist das kopflose Primitiv – nützlich, um den Agenten in deine eigene Oberfläche einzubetten.

Weil diese vier Aufgaben alle hinter einer API liegen, kannst du sie in eine kontinuierliche Trainingsschleife einbinden: abrufen, was passiert ist, diagnostizieren, was funktioniert hat und was nicht, und dann Konfigurationsänderungen zurückspielen. Mit einer sicher konfigurierten API-Integration oder MCP-Verbindung kann ein KI-Assistent wie Claude oder ChatGPT dabei helfen, Unterhaltungen zu lesen, Muster bei Fehlschlägen zu erkennen und Änderungen an deinen Skills, Tools, deinem Wissen und deiner Anleitung vorzuschlagen.

Authentifizierung und Zugriff

Verwende einen privaten Klaviyo API-Schlüssel mit dem Bereich agents, um diese Endpunkte aufzurufen. Customer Agent muss für das Konto bereits aktiviert sein.

Wenn du den Schlüssel erstellst, wählst du die Zugriffsebene für den agents -Bereich aus:

Wähle schreibgeschützt, wenn deine Integration nur den Agent beobachten muss (z. B. ein Reporting-Dashboard). Wähle Lese-/Schreibzugriff, wenn der Agent konfiguriert oder Unterhaltungen ausgeführt werden sollen.

1. Navigiere zu Einstellungen > API-Schlüssel und klicke auf Privaten API-Schlüssel erstellen.
2. Gib einen Namen für den privaten API-Schlüssel ein und wähle Benutzerdefinierten Schlüssel aus.
3. Wähle in der Zeile Agents für deine Integration Lesezugriff oder Vollzugriff aus, und verwende dazu die Tabelle oben.
4. Klicke auf Erstellen, klicke dann auf das Kopiersymbol und speichere den Schlüssel sicher. Du kannst den Schlüssel nicht erneut anzeigen, nachdem du die Bestätigungsseite verlassen hast.

Weitere Details findest du unter So erstellst oder klonst du einen privaten API-Schlüssel.

Sende API-Anfragen von deinem Server an https://a.klaviyo.com und füge diesen Autorisierungs-Header hinzu. Halte den privaten Schlüssel aus Browser-Code und Apps heraus, die für Käufer*innen bestimmt sind:

Authorization: Klaviyo-API-Key your-private-api-key

Jede Anfrage muss auch den Header der Beta-Revision enthalten:

revision: 2026-10-15.pre

Ohne den Header der Beta-Revision wird die Anfrage abgelehnt.

Ratenlimits

Ratenbegrenzungen hängen von der Endpunktgruppe ab:

• Agent, Skills, Tools, Wissen, Geheimnisse und Antworten: Burst-Limit von 10 Anfragen pro Sekunde und kontinuierliches Limit von 150 Anfragen pro Minute.
• Unterhaltungen, Unterhaltungsnachrichten und Berichte: Burst-Limit von 3 Anfragen pro Sekunde und stetiges Limit von 60 Anfragen pro Minute.

Format deiner Anfrage

Verwende Klaviyos JSON:API-Anforderungskonventionen, mit einem separaten Format für Datei-Uploads:

• Inhaltstyp: application/vnd.api+json für JSON-Anfragen. Verwende multipart/form-data für POST /api/agent-knowledge-files.
• Paginierte Sammlungen verwenden page[cursor] und page[size] (Standard 50, Maximum 100, nur vorwärts). Folge links.next, bis es leer ist, um die verbleibenden Seiten abzurufen.
• Die Filterung verwendet die unterstützten Felder und Operatoren, die in der Referenz jedes Endpunkts aufgeführt sind. Die Sortierreihenfolge ist Endpunkt-spezifisch: Konversationen sind die neuesten zuerst, Nachrichten sind die ältesten zuerst, und Skills und Tools werden nach ID sortiert.

Endpunkt-Gruppen

Service-Mitarbeiter

Es gibt pro Unternehmen höchstens 1 Customer Agent. Rufe GET /api/customer-agents auf, um die ID zu finden, und verwende dann diese ID in der GET- oder PATCH-URL. Die Liste ist leer, wenn Customer Agent für das Konto nicht aktiviert ist.

Agent-Skills

Vorgefertigte und benutzerdefinierte Skills können gelesen werden. Nur benutzerdefinierte Skills können aktualisiert oder gelöscht werden. Setze status eines benutzerdefinierten Skills auf draft, um ihn bereitzustellen oder zu pausieren, oder auf live, um ihn zu aktivieren.

Agent-Tools

Nur benutzerdefinierte Tools können aktualisiert oder gelöscht werden. Nachdem du ein externes HTTP-Tool erstellt hast, binde es über die agent-tools -Beziehung des Skills an einen benutzerdefinierten Skill an. Ein Tool ist für diesen Skill erst verfügbar, wenn es gebunden ist.

Agent-Wissen

Erstelle Textausschnitte, Webseiten, Q&A-Paare oder Ordner, indem du source.source_type auf snippet, webpage, qa oder folder setzt. Um eine file hinzuzufügen, verwende den separaten Datei-Upload-Endpunkt.

Agent-Geheimnisse

Verschlüsselte Geheimnisse, die von benutzerdefinierten Tools verwendet werden Der Listen-Endpunkt gibt nur sichere Metadaten zurück – der geheime Wert selbst wird nie zurückgegeben.

Unterhaltungen

Lies Unterhaltungen, die der Agent mit Shopper*innen geführt hat, oder erstelle eine Unterhaltung, um sie über die API durchzuführen. Eine Unterhaltung kann sich über einen langen Zeitraum über viele Nachrichten erstrecken. Die Liste kann Live- und Vorschau-Unterhaltungen enthalten; verwende filter=equals(mode,„live“), um sie auf Live-Unterhaltungen zu beschränken.

Berichte

Aggregierte Metriken, auf das anfragende Unternehmen beschränkt. Beide folgenden Reports sind POST-Endpunkte: Übergib die Report-Parameter im Body. Sie erfordern agents:read, sodass ein schreibgeschützter Schlüssel sie ausführen kann.

Führe den Agent aus

Dies ist die Grundvoraussetzung für das Einbetten von Customer Agent in deine eigene Oberfläche (deine App, dein Help Center, ein von Partnern erstelltes Support-Panel).

Erstelle vor dem Ausführen eines Turns eine offene Konversation mit POST /api/customer-agent-conversations. Der Antwort-Endpunkt akzeptiert nur Konversationen, die über die API erstellt wurden. Eine geschlossene Konversation oder eine Konversation, die bereits an dein Team weitergeleitet wurde, kann keine weiteren Antworten annehmen.

Was erfordert noch die Klaviyo-Benutzeroberfläche?

Einige Einrichtungsschritte befinden sich noch nicht in der API:

• Kanalkonfiguration (Web-Chat, E-Mail, SMS, WhatsApp) – die Kanaleinrichtung erfolgt in den Klaviyo-Plattform-Einstellungen.
• Liveschalten auf jedem Kanal – der Ein-/Ausschalter pro Kanal bleibt in der Benutzeroberfläche.
• Helpdesk-Auswahl — öffne in Customer Agent einen Kanal unter Kanäle und konfiguriere den Abschnitt Übergabe. Weitere Informationen findest du unter Customer Agent-Einstellungen verwalten.

Typische Workflow

Einmal konfigurieren und dann warten

1. Erstelle einen privaten API-Schlüssel mit dem agents -Scope und Lese-/Schreibzugriff in Klaviyo.
2. Aktuellen Status abrufen – GET /api/customer-agents, um die Customer Agent-ID zu finden, und dann den Customer Agent sowie die Listen für Skills, Tools und Wissen abzurufen. Folge den Paginierungslinks, um alle Seiten zu lesen.
3. Änderungen vornehmen — erstelle oder aktualisiere benutzerdefinierte Skills, Tools, Wissen und Secrets nach Bedarf. Verknüpfe neue Tools mit den Skills, die sie verwenden, und setze benutzerdefinierte Skills auf den Status: live, sobald du bereit bist, sie zu aktivieren.
4. Prüfe die Produktionsliste – Liste der letzten Unterhaltungen und rufe einen Wertebericht auf, um zu sehen, wie der Agent funktioniert.
5. Iterieren.

Trainiere deinen Agent in einer Schleife

Die APIs sind darauf ausgelegt, die Schleife zwischen dem, was dein Agent in der Produktion getan hat, und der Konfiguration zu schließen. Eine typische Schleife:

1. Aktuelle Konversationen abrufen — Konversationen per GET abrufen, gefiltert nach created_at und status; für Produktionskonversationen equals(mode,„live“) zum Filter hinzufügen. Rufe die Customer Agent-Nachrichten jeder Konversation ab und folge links.next, um jede Seite zu lesen.
2. Diagnose: Klassifiziere jede Unterhaltung als erfolgreich oder fehlgeschlagen. Suche nach Mustern: Sind Eskalationen rund um ein Thema gruppiert? Werden bestimmte Fähigkeiten weitergeleitet, obwohl sie das nicht sollten? Fehlt dem Support-Mitarbeiter das erforderliche Wissen?
3. Du kannst Metriken abrufen – den Wertebericht für das Volumen und die Lösungsrate sowie den Skill-Value-Bericht für Aufschlüsselungen nach Fähigkeiten. Bestätige, dass die Muster aggregiert zurückgehalten werden.
4. Schlage Änderungen vor – basierend auf den Fehlermustern entscheidest du, was geändert werden soll: Bearbeite die Anweisungen einer Qualifikation, füge ein Wissensfragment hinzu, erstelle ein neues benutzerdefiniertes Tool, verschärfe eine Tonfall-Regel und füge einen Eskalationsauslöser hinzu.
5. Wende Änderungen an – PATCHE die betroffenen Fähigkeiten, VERÖFFENTLICHE neue Wissensquellen usw.
6. Loop Wiederhole dies im nächsten Fenster mit den Unterhaltungen.

Es kann ein KI-Assistent wie Claude, ChatGPT oder Cursor verwendet werden, um Konversationen abzurufen, Lücken zu finden, konkrete Bearbeitungen vorzuschlagen und Änderungen mit deiner Freigabe anzuwenden. Verbinde es über den Klaviyo MCP-Server oder deine eigenen API-Integrationen, und bewahre private API-Schlüssel in einer sicheren Konfiguration auf, statt in Prompts. Der MCP-Server unterstützt viele dieser Aufgaben, aber zum Erstellen oder Aktualisieren von Secrets und zum Hochladen von Knowledge-Dateien sind direkte API-Aufrufe erforderlich.

Agent in deine eigene Oberfläche einbetten

Verwende mode: preview zum Testen ohne Abrechnung oder Produktionsmetriken. mode: live ist für echte Interaktionen von Shopper*innen und zählt zur Abrechnung und zu Produktionsmetriken. Die Beta-Nutzungswarnung oben gilt weiterhin.

1. Erstelle einen Schlüssel mit dem Umfang „Agents“ (lesen/schreiben).
2. Erstelle eine Konversation — sende von deinem Server aus einen POST an /api/customer-agent-conversations mit dem ausgewählten mode. Speichere die zurückgegebene Konversations-ID.
3. Öffne eine Unterhaltung in deiner Benutzeroberfläche – erfasse die Eingaben der Kund*innen.
4. Einen Turn ausführen — von deinem Server aus per POST an /api/customer-agent-responses senden, mit mode, messages und der gespeicherten ID in data.relationships.conversation.data.id. Verwende den Beziehungstyp customer-agent-conversation. Füge den Gesprächsverlauf in messages ein und ende mit der neuesten Nachricht der Shopper*innen mit role: user.
5. Die Antwort rendern — verarbeite die zurückgegebenen Ereignisse der Reihe nach und zeige die Nachrichten der Agent*in sowie alle unterstützten strukturierten Daten in deiner Oberfläche an. Verarbeite Handoff-Ereignisse in deinen Integrationen. Die API gibt Ereignisse zusammen ohne Streaming zurück; sie liefert sie nicht über einen Kanal.
6. Wiederhole dies für jeden Turn, indem du dieselbe Konversations-ID und denselben Modus verwendest, solange die Konversation geöffnet ist. Beende nach einer harten oder stillen Übergabe die Anfragen nach Agent*innenantworten und leite Shopper*innen an dein Support-Team weiter.

FAQ

Gibt es einen MCP-Server?

Ja. Der remote gehostete Klaviyo-MCP-Server umfasst Customer Agent-Tools für Skills, Tools, Wissen, geheime Metadaten, Konversationen, Berichte und das Ausführen des Agenten. Das Erstellen einer Konversation, das Erstellen oder Aktualisieren von Secrets und das Hochladen von Wissensdateien erfordern direkte API-Aufrufe. Siehe Klaviyo-MCP-Server.

Ist das stabil genug, um darauf aufzubauen?

Beta bedeutet, dass sich das Schema ändern kann. Die Endpunkte sind voll abrufbar, aber wir verpflichten uns noch nicht zu langfristiger Stabilität. Versende keine produktionskritischen Integrationen für die Beta-Version.

Wo finde ich das vollständige Schema?

Die vollständige Referenz befindet sich im Klaviyo Entwicklerportal unter https://developers.klaviyo.com/en/reference/. Die Customer Agent-Endpunkte werden in der Revision 2026-10-15.pre unter Beta APIs angezeigt.

Verwandte Artikel