API du Customer Agent (version bêta)

Objectif de cet article

Définition des API du Customer Agent, activité de chaque groupe de points de terminaison et comment commencer à les appeler Les API vous permettent de configurer votre Customer Agent, de lire ce qu’il fait en production et de l’exécuter par programmation, directement sur HTTP, en plus du reste de Klaviyo API public.

Remarque : Les API Customer Agent sont en version bêta. Les points de terminaison et les schémas peuvent changer avant la disponibilité générale. Les API bêta ne sont pas destinées à une utilisation en production — consultez la politique de gestion des versions et d’abandon de Klaviyo pour en savoir plus.

Ce que les API vous permettent de faire

Les API Customer Agent couvrent 4 tâches :

1. Configurez l’agent : lisez ou mettez à jour l’agent lui-même, ainsi que ses compétences, outils, sources de connaissances et secrets.
2. Lire les conversations de production — listez et inspectez les conversations Customer Agent.
3. Créez un rapport sur les performances : volume d’extraction, taux de résolution et indicateurs par compétence.
4. Exécutez l’agent pendant un tour : envoyez une conversation et obtenez la réponse de l’agent. Il s’agit de la primitive sans tête, utile pour intégrer l’agent à votre propre surface.

Comme ces quatre tâches s’appuient toutes sur une seule API, vous pouvez les relier dans une boucle d’entraînement continue: récupérer ce qui s’est passé, diagnostiquer ce qui a fonctionné et ce qui n’a pas fonctionné, puis déployer des modifications de configuration. Avec une intégration d’API ou une connexion MCP configurée de manière sécurisée, un assistant IA comme Claude ou ChatGPT peut aider à lire les conversations, à détecter des tendances dans les échecs, et à proposer des modifications de vos compétences, outils, connaissances, et consignes.

Authentification et accès

Utilisez une clé d’API privée Klaviyo avec le champ d’application agents pour appeler ces points de terminaison. Customer Agent doit déjà être activé pour votre compte.

Lorsque vous créez la clé, vous choisissez le niveau d’accès pour le périmètre agents :

Choisissez la lecture seule si votre intégration ne nécessite que l’observation de l’agent (par exemple, un tableau de bord de reporting). Choisissez lecture/écriture s’il doit configurer l’agent ou exécuter des tournants de conversation.

1. Accédez à Paramètres > clés d’API, puis cliquez sur Créer une clé d’API privée.
2. Saisissez un nom de clé d’API privée et sélectionnez Clé personnalisée.
3. Dans la ligne Agents, sélectionnez Accès en lecture ou Accès complet pour votre intégration, à l’aide du tableau ci-dessus.
4. Cliquez sur Créer, puis cliquez sur l’icône de copie et stockez la clé en lieu sûr. Vous ne pourrez pas afficher la clé à nouveau après avoir quitté la page de confirmation.

Pour plus de détails, consultez comment créer ou cloner une clé d’API privée.

Envoyez des requêtes API depuis votre serveur vers https://a.klaviyo.com et incluez cet en-tête d’autorisation. Gardez la clé privée hors du code du navigateur et des applications destinées aux acheteurs :

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

Chaque demande doit également inclure l’en-tête de la version bêta de la révision :

revision: 2026-10-15.pre

Sans l’en-tête de révision bêta, la demande sera rejetée.

Limites

Les limites de débit dépendent du groupe de points de terminaison :

• Agent, compétences, outils, connaissances, secrets et réponses : limite de rafale de 10 requêtes par seconde, et limite stable de 150 requêtes par minute.
• Conversations, messages de conversation et rapports : limite de rafale de 3 requêtes par seconde, et limite stable de 60 requêtes par minute.

Format de la demande

Utilisez les conventions de requête JSON:API de Klaviyo, avec un format distinct pour les chargements de fichiers :

• Type de contenu : application/vnd.api+json pour les requêtes JSON. Utilisez multipart/form-data pour POST /api/agent-knowledge-files.
• Les collections paginées utilisent page[cursor] et page[size] (50 par défaut, 100 max., uniquement vers l’avant). Suivez links.next jusqu’à ce qu’il soit vide afin de récupérer les pages restantes.
• Le filtrage utilise les champs et les opérateurs pris en charge listés dans la référence de chaque point de terminaison. L’ordre de tri dépend des points de terminaison : les conversations sont les plus récentes en premier, les messages sont les plus anciens en premier, et les compétences et les outils sont triés par ID.

Points de terminaison de groupes

Agent

Il y a au maximum 1 Customer Agent par entreprise. Appelez GET /api/customer-agents pour trouver son ID, puis utilisez cet ID dans l’URL GET ou PATCH. La liste est vide si Customer Agent n’est pas activé pour le compte.

Compétences des agents

Vous pouvez lire les compétences préconstruites et personnalisées. Seules les compétences personnalisées peuvent être mises à jour ou supprimées. Définissez le status d’une compétence personnalisée sur draft pour la mettre en attente ou la mettre en pause, ou sur live pour l’activer.

Outils d’agent

Seuls les outils personnalisés peuvent être mis à jour ou supprimés. Après avoir créé un outil HTTP externe, associez-le à une compétence personnalisée via la relation agent-tools de la compétence. Un outil n’est pas disponible pour cette compétence tant qu’il n’est pas associé.

Connaissances de l’agent

Créez des extraits de texte, des pages web, des paires de questions-réponses, ou des dossiers en définissant source.source_type sur snippet, webpage, qa, ou folder. Pour ajouter un(e) file, utilisez le point de terminaison distinct de chargement de fichier.

Secrets de l’agent

Secrets cryptés utilisés par des outils personnalisés. Le points de terminaison de liste ne renvoie que des métadonnées sûres. La valeur secrète elle-même n’est jamais renvoyée.

Conversations

Lisez les conversations que l’agent a eues avec les clients, ou créez une conversation pour l’exécuter via l’API. Une conversation peut s’étendre sur de nombreux messages pendant une longue période. La liste peut inclure des conversations en direct et en aperçu ; utilisez filter=equals(mode,"live") pour la limiter aux conversations en direct.

Rapports

Indicateurs agrégés, limités à l’entreprise demandeuse. Les deux rapports ci-dessous sont des points de terminaison POST : transmettez les paramètres du rapport dans le corps de la requête. Ils nécessitent agents:read, donc une clé en lecture seule peut les exécuter.

Exécutez l’agent

C’est la primitive pour intégrer du Customer Agent dans votre propre surface (votre application, votre centre d’aide, un panneau d’assistance conçu par des partenaires).

Créez une conversation ouverte avec POST /api/customer-agent-conversations avant d’exécuter un tour. Le point de terminaison de réponse accepte uniquement les conversations créées via l’API. Une conversation clôturée, ou déjà acheminée vers votre équipe, ne peut pas accepter de réponses supplémentaires.

Ce qui nécessite encore l’interface utilisateur de Klaviyo

Certaines étapes de configuration ne sont pas encore disponibles dans l’API :

• Configuration des canaux (chat web, e-mail, SMS, WhatsApp) : la configuration des canaux s’effectue dans les paramètres de la plateforme Klaviyo.
• Mise en ligne sur chaque canal : l’interrupteur marche/arrêt par canal reste dans l’interface utilisateur.
• Sélection du Helpdesk — dans Customer Agent, ouvrez un canal sous canaux et configurez sa section Transfert. Consultez Gestion des paramètres de Customer Agent pour plus de détails.

Flux de travail typiques

Configurez une fois, puis maintenez

1. Créez une clé d’API privée avec la portée agents et un accès en lecture/écriture dans Klaviyo.
2. Extraire l’état actuel — GET /api/customer-agents pour trouver l’ID du Customer Agent, puis récupérer le Customer Agent et les listes de compétences, d’outils et de connaissances. Suivez les liens de pagination pour lire toutes les pages.
3. Apporter des modifications — créer ou mettre à jour des compétences personnalisées, des outils, des connaissances et des secrets, selon les besoins. Associer de nouveaux outils aux compétences qui les utilisent et définir des compétences personnalisées sur le statut : en ligne lorsque vous êtes prêt à les activer.
4. Vérifiez la production : listez les conversations récentes et extrayez un rapport sur les valeurs pour voir les performances de l’agent.
5. Itérer.

Formez votre agent en boucle

Les API sont conçues pour fermer la boucle entre ce que votre agent a fait en production et la façon dont il est configuré. Une boucle typique :

1. Récupérer les conversations récentes — RÉCUPÉREZ des conversations filtrées par created_at et status, en ajoutant equals(mode,"live") au filtre pour les conversations de production. Récupérez les Customer Agent-messages de chaque conversation, puis suivez links.next pour lire chaque page.
2. Diagnostiquez : pour chaque conversation, classez-la comme une réussite ou un échec. Recherchez des modèles : les escalades sont-elles regroupées autour d’un sujet ? Certaines compétences sont-elles détournées alors qu’elles ne devraient pas l’être ? L’agent ne dispose-t-il pas des connaissances dont il a besoin ?
3. Obtenez des indicateurs : générez un rapport sur les valeurs pour le volume et le taux de résolution, ainsi qu’un rapport sur les valeurs de compétences pour les répartitions par compétence. Confirmez le maintien des modèles dans l’ensemble.
4. Proposez des modifications en fonction des modèles d’échec, décidez de ce qu’il faut modifier : modifiez les instructions d’une compétence, ajoutez un extrait de connaissances, créez un nouvel outil personnalisé, resserrez une règle de ton, ajoutez un déclencheur d’escalade.
5. Appliquer les changements — CORRIGER les compétences affectées, AFFICHER de nouvelles sources de connaissances, etc.
6. Boucle. Répétez l’opération pour la fenêtre de conversations suivante.

Vous pouvez utiliser un assistant IA comme Claude, ChatGPT, ou Cursor pour extraire des conversations, identifier des lacunes, proposer des modifications spécifiques, et appliquer des changements avec votre approbation. Connectez-le via le serveur MCP de Klaviyo, ou via vos propres intégrations d’API, et conservez les clés d’API privées dans une configuration sécurisée, plutôt que dans les prompts. Le serveur MCP prend en charge un grand nombre de ces tâches, mais la création ou la mise à jour de secrets, ainsi que le chargement de fichiers de connaissances, nécessitent des appels directs à l’API.

Intégrer l’agent à votre propre surface

Utilisez mode: preview pour effectuer des tests, sans facturation ni indicateurs de production. mode: live est destiné aux interactions réelles avec les acheteurs, et est pris en compte dans la facturation et les indicateurs de production. L’avertissement ci-dessus concernant l’utilisation de la version bêta s’applique toujours.

1. Créez une clé avec l’étendue des agents (lecture/écriture).
2. Créer une conversation — depuis votre serveur, envoyez une requête POST à /api/customer-agent-conversations avec le mode choisi. Enregistrez l’ID de conversation renvoyé.
3. Ouvrez une conversation dans votre interface utilisateur pour recueillir les commentaires de l’acheteur.
4. Exécuter un tour — depuis votre serveur, effectuez un POST vers /api/customer-agent-responses avec mode, messages, et l’ID enregistré dans data.relationships.conversation.data.id. Utilisez le type de relation customer-agent-conversation. Incluez l’historique de la conversation dans messages, en terminant par le message le plus récent de l’acheteur avec role: user.
5. Rendre la réponse — traiter les événements renvoyés dans l’ordre et afficher les messages de l’agent ainsi que toutes les données structurées prises en charge dans votre interface. Gérer les événements de transfert dans votre intégration. L’API renvoie les événements ensemble, sans diffusion en continu ; il ne les transmet pas via un canal.
6. Répétez pour chaque tour en utilisant le même identifiant de conversation et le même mode tant que la conversation est ouverte. Après un transfert brutal ou silencieux, cessez de demander des réponses de l’agent, puis acheminez l’acheteur vers votre équipe d’assistance.

FAQ

Existe-t-il un serveur MCP ?

Oui. Le serveur MCP Klaviyo hébergé à distance inclut des outils Customer Agent pour les compétences, les outils, les connaissances, les métadonnées secrètes, les conversations, les rapports, et l’exécution de l’agent. La création d’une conversation, la création ou la mise à jour de secrets, ainsi que le téléversement de fichiers de connaissances nécessitent des appels directs à l’API. Voir le serveur MCP de Klaviyo.

Est-ce assez stable pour continuer ?

La version bêta signifie que le schéma peut changer. Les points de terminaison sont entièrement réalisables, mais nous ne nous engageons pas encore à assurer une stabilité à long terme. N’envoyez pas d’intégrations essentielles à la production pour la version bêta.

Où puis-je trouver le schéma complet ?

La référence complète se trouve dans le portail de développement Klaviyo à l’adresse https://developers.klaviyo.com/en/reference/. Les points de terminaison Customer Agent apparaissent sous API bêta dans la révision 2026-10-15.pre.

Articles connexes