Comment créer un outil

Objectif de cet article

Comment connecter Customer Agent à des points de terminaison HTTP à l’aide d’un outil entièrement personnalisé, rédiger une description d’outil que Customer Agent utilisera réellement, et tester votre outil avant de l’attacher à une compétence.

Avant de commencer

Vous aurez besoin des éléments suivants :

• Mot de Customer Agent activé
• Un points de terminaison HTTP accessible via un nom d’hôte public. Les adresses de réseau privé, localhost et les URL qui utilisent une adresse IP au lieu d’un nom d’hôte ne sont pas pris en charge. Si le points de terminaison nécessite une clé d’API ou un jeton, vous l’enregistrerez en tant que secret (voir les étapes 1 et 6).
• Une compétence avec des instructions modifiables à laquelle associer l’outil

Vous pouvez créer et tester l’outil avant de l’associer à une compétence. Pour l’utiliser dans les conversations, ajoutez-le aux instructions de la compétence. Si vous avez besoin d’une nouvelle compétence, consultez Comment créer une compétence.

Qu’est-ce qu’un outil entièrement personnalisé

Un outil entièrement personnalisé correspond à une requête HTTP que Customer Agent peut effectuer au cours d’une conversation. Utilisez-en un lorsque les outils fournis avec Customer Agent ne couvrent pas ce dont vous avez besoin — par exemple, rechercher une commande dans votre propre système de gestion des commandes au lieu de Shopify, vérifier les stocks dans un système d’entrepôt personnalisé ou créer un ticket dans un service d’assistance avec lequel Klaviyo ne s’intègre pas nativement.

Pour le concept sous-jacent, consultez Comprendre les outils.

Quand créer un outil entièrement personnalisé

Optez pour un outil entièrement personnalisé dans les cas suivants :

• Vous avez besoin de données en temps réel provenant d’un système avec lequel Klaviyo ne s’intègre pas déjà
• Vous souhaitez que le Customer Agent effectue une action dans un système externe (annuler un abonnement dans votre système propriétaire, créer un ticket, mettre à jour un enregistrement)
• Un outil existant ne convient pas, par exemple, vous utilisez un système OMS personnalisé au lieu de Shopify pour les commandes

Si les informations ne changent pas souvent et sont identiques pour chaque client, ajoutez-les plutôt en tant que contenu. Les outils permettent d’obtenir des données et des actions dynamiques par client.

Transition

1. Ouvrez la page Outils personnalisés

1. Accédez à Customer Agent > Connectors, puis ouvrez la carte Personnalisé.
2. Si vos points de terminaison ont besoin d’un identifiant, allez dans Secrets et cliquez sur Ajouter un secret. Saisissez un Nom et une Valeur du secret, puis cliquez sur Ajouter un secret. Ignorez cette étape si le secret est déjà enregistré ou si les points de terminaison n’en ont pas besoin.
3. Cliquez sur Créer l’outil.

2. Nommez et décrivez l’outil

• Nom de l’outil — Un identifiant court, comme « Obtenir l’inventaire » ou « Créer un ticket de retour ».
• Description : langage naturel expliquant ce que fait l’outil et quand l’utiliser. Le Customer Agent lit cette description pour décider s’il convient d’utiliser l’outil pour une demande donnée. Soyez précis.

Voici un bon exemple de description :

Récupère en temps réel le nombre de stocks pour une SKU de produit donnée à partir du système d’entrepôt. À utiliser lorsqu’un acheteur demande si un produit spécifique est en stock.

Exemple de description vague (éviter) :

Obtient des informations sur le produit.

3. Configurez la demande HTTP

• Méthode HTTP — GET, POST, PUT, DELETE ou PATCH.
• Modèle d’URL — L’URL complète des points de terminaison. Vous pouvez inclure des espaces réservés pour des valeurs dynamiques (voir l’étape 5).
• En-têtes — Tous les en-têtes requis par votre point de terminaison, y compris Content-Type et les en-têtes d’authentification.
• Paramètre de requête — Si vos points de terminaison attendent des valeurs dans la chaîne de requête, saisissez ici leurs noms et leurs valeurs. Vous pouvez utiliser des espaces réservés pour les valeurs (voir l’étape 5).

4. Configurez le corps de la demande (pour POST, PUT, PATCH)

Dans Modèle de corps, fournissez un objet JSON. Utilisez des espaces réservés pour les valeurs que Customer Agent doit renseigner au moment de l’exécution.

Exemple de corps de texte :

{
  « customer_id »: « {{profile_id}} »,
  « sku »: « {{product_sku}} »
}

5. Définir des variables pour des valeurs dynamiques

Chaque espace réservé doit avoir une variable correspondante sous Variables. Pour l’exemple de corps ci-dessus :

1. Cliquez sur Ajouter des variables et saisissez profile_id comme Nom de la variable. Définissez Source sur Profil Klaviyo et Propriété Klaviyo sur ID Klaviyo. Cela fournit l’ID de profil Klaviyo de l’acheteur authentifié.
2. Ajoutez une autre variable nommée product_sku. Définissez Source sur Variable dynamique, choisissez Chaîne comme Type, puis décrivez le SKU que Customer Agent doit fournir dans Description. Sélectionnez Obligatoire si le point de terminaison l’exige.

Répétez l’opération pour les autres valeurs dont vos points de terminaison ont besoin, comme order_id. Les noms de variables doivent correspondre exactement à leurs espaces réservés. Une variable nommée conversation_id n’est pas automatiquement renseignée avec l’ID de la conversation actuelle.

Utilisez les variables comme espaces réservés, tels que {{profile_id}} et {{product_sku}}, dans l’URL, les en-têtes, les paramètres de requête ou le corps. Les outils qui utilisent des variables profil Klaviyo nécessitent un acheteur authentifié ; l’absence d’une valeur de profil requise empêche l’exécution de la requête.

6. Authentification

Si votre point de terminaison requiert une clé d’API, un jeton Bearer ou un autre identifiant, stockez-le en tant que secret. Les secrets sont chiffrés, leurs valeurs ne sont jamais affichées à Customer Agent, et vous ne pouvez plus les consulter après les avoir enregistrés.

1. Dans votre outil, sous Variables, cliquez sur Ajouter des variables. Donnez un nom à la variable (par exemple, api_key), définissez Source sur Secret, puis choisissez le secret que vous avez enregistré.
2. Référencez la variable partout où votre point de terminaison attend l’identifiant : un en-tête, l’URL, un paramètre de requête ou le corps. Par exemple, ajoutez un en-tête nommé Authorization avec la valeur Bearer {{api_key}}.

Pour faire pivoter une clé, ouvrez le menu de ligne du secret, cliquez sur Mettre à jour, saisissez la valeur de remplacement, puis cliquez sur Mettre à jour. Chaque outil qui utilise le secret récupère la nouvelle valeur. La colonne Utilisé par indique quels outils référencent chaque secret, alors vérifiez-la avant d’en supprimer un.

7. Enregistrer et tester l’outil

Avant d’enregistrer, vérifiez Délai d’expiration (secondes) et Nombre maximal de nouvelles tentatives sous Paramètres. Vous pouvez définir une limite de temps globale de 1 à 10 secondes et de 0 à 3 nouvelles tentatives en cas d’échecs temporaires. Si l’outil modifie des données, assurez-vous que vos points de terminaison peuvent gérer en toute sécurité une requête répétée.

Cliquez sur Enregistrer pour créer l’outil. L’outil enregistré s’ouvre avec une section Tester.

Les tests envoient de vraies requêtes à vos points de terminaison, et peuvent modifier des données. Utilisez un profil de test et des enregistrements de test. Enregistrer et exécuter le test enregistre également toutes les modifications apportées à l’outil, y compris pour un outil déjà utilisé par des compétences en production.

Dans Test, saisissez des exemples de valeurs pour les variables dynamiques. Sélectionnez un profil de test sous profil si l’outil utilise des variables de profil Klaviyo. Cliquez sur Enregistrer et exécuter le test.

Examinez Réponse et vérifiez que :

• La réponse est renvoyée
• La réponse contient les données dont votre compétence a besoin
• Les cas d’erreur attendus renvoient des codes d’état et des messages utiles

8. Associez l’outil à une compétence

1. Accédez à Customer Agent > Compétences et ouvrez la compétence sur laquelle vous souhaitez utiliser l’outil. Si ses instructions sont en lecture seule, créez une compétence entièrement personnalisée.
2. Dans Comment répondre, saisissez / à l’endroit où l’outil doit être utilisé, puis sélectionnez l’outil dans le menu. Expliquez quand l’appeler, quelles valeurs fournir, et quoi faire avec le résultat ou une erreur.
3. Lorsque les instructions sont prêtes, cliquez sur Publier pour une compétence en brouillon, ou sur Mettre à jour pour une compétence en ligne.

Rédiger une bonne description de l’outil

Une description claire aide Customer Agent à décider quand utiliser l’outil. Les instructions de la compétence indiquent également quel outil elle appelle et comment elle utilise le résultat. Bonnes descriptions :

• Dites ce que fait l’outil en une phrase
• Indiquez quand l’utiliser en une phrase.
• Sont spécifiques aux données renvoyées ou à l’action entreprise

Les mauvaises descriptions sont vagues (« Obtient des informations sur le client »), trop générales (« Gère tout ce qui concerne les commandes ») ou indiquent au Customer Agent comment se comporter plutôt que ce que fait l’outil.

Considérations de sécurité

• Stockez les identifiants en tant que secrets. Ne collez jamais une clé d’API ou un jeton directement dans un en-tête, une URL ou un corps de requête. Ajoutez-la en tant que secret et référencez-la à l’aide d’une variable Secret (voir l’étape 6).
• Utilisez la liste d’autorisation d’adresses IP lorsque c’est possible. Votre point de terminaison doit toujours être accessible via un nom d’hôte public ; les adresses de réseau privé et localhost sont bloqués. Utilisez la mise en liste d’autorisation comme couche de protection supplémentaire, en complément de l’authentification.
• Faites attention aux données que vous envoyez. La configuration de votre demande et les sources de variables déterminent quelles valeurs sont envoyées aux points de terminaison. Les instructions de la compétence guident les valeurs que Customer Agent fournit pour les variables dynamiques. Vérifiez quels champs vos points de terminaison reçoivent.
• Limites de taux. Si votre points de terminaison comporte des limites de taux, assurez-vous qu’elles sont suffisamment élevées pour gérer le volume de conversations attendu.

Résolution de problèmes

Symptôme : Customer Agent n’utilise jamais l’outil.
Cause probable : La description est trop vague, ou l’outil n’est pas inclus dans les instructions publiées de la compétence.
Correctif : Réécrivez la description pour décrire précisément quand il doit être utilisé. Dans Comment répondre, insérez l’outil à l’aide de / et expliquez quand l’appeler. Cliquez sur Publier ou Mettre à jour pour appliquer les instructions.

Symptôme : L’outil renvoie une erreur pendant le test.
Cause probable : URL incorrecte, corps mal formé, données de profil obligatoires manquantes, ou une charge utile que votre point de terminaison n’accepte pas.
Correctif : Dans Test, examinez Aperçu de la requête et Réponse. Vérifiez l’URL, les en-têtes et le corps par rapport aux entrées attendues par votre point de terminaison. Si l’outil utilise des variables de profil Klaviyo, sélectionnez un profil de test avec les valeurs obligatoires.

Symptôme: Customer Agent utilise l’outil, mais transmet des paramètres incorrects.
Cause probable: Une variable a une source ou des propriétés de profil incorrectes, ou les instructions de la compétence ne précisent pas clairement quoi transmettre.
Correctif: Vérifiez les noms des variables, les sources et les propriétés de profil sélectionnées dans Variables. Mettez à jour les descriptions des variables et les instructions de la compétence afin d’indiquer explicitement ce qu’il faut fournir.

Symptôme : L’outil est lent, ce qui retarde les réponses.
Cause probable : latence du Points de terminaison.
Correctif : Optimisez votre points de terminaison. Vérifiez si vous pouvez mettre les résultats de votre côté en cache.

FAQ

Un outil peut-il être utilisé par plusieurs compétences ?
Oui. Une fois créé, un outil peut être utilisé par plusieurs compétences. Insérez-le dans les instructions modifiables de chaque compétence, puis publiez ou mettez à jour chaque compétence.

Quelles méthodes d’authentification sont prises en charge ?
Toute méthode qui envoie un identifiant statique avec la requête, comme un jeton Bearer ou un en-tête de clé d’API. Stockez l’identifiant en tant que secret et référencez-le avec une variable Secret (voir l’étape 6). Les flux qui doivent récupérer ou actualiser un jeton au moment de la requête, comme OAuth, ne sont pas pris en charge dans les outils entièrement personnalisés.

Que se passe-t-il si mon point de terminaison est indisponible ou renvoie une erreur ?
Klaviyo signale les échecs de l’outil à Customer Agent. Les échecs temporaires peuvent être réessayés dans la limite du délai d’expiration et des limites de nouvelle tentative de l’outil. Dans les instructions de la compétence, expliquez comment répondre si l’outil ne peut pas traiter la demande, par exemple en proposant de passer la main. Utilisez des points de terminaison fiables et surveillez de près le comportement de l’outil.

Puis-je modifier un outil après l’avoir créé ?
Oui. Ouvrez l’outil depuis Customer Agent > Connectors > Custom, modifiez son nom, sa description ou la configuration de la requête, puis cliquez sur Enregistrer. Ajoutez ou supprimez l’outil dans les instructions de chaque compétence.

Puis-je gérer les versions d’un outil ?
La gestion des versions n’est pas encore prise en charge. Les modifications enregistrées s’appliquent à l’outil partagé utilisé par toutes les compétences qui le référencent. Enregistrer et exécuter le test enregistre également les modifications, donc vérifiez quelles compétences en production utilisent l’outil avant de le modifier.

Ressources supplémentaires