Comment créer un outil (version bêta)

Fonctionnalité bêta. La création d’outils entièrement personnalisés de A à Z est en version bêta ouverte et disponible pour tous les comptes de Customer Agent. Aucune inscription n’est requise. La page Outils est en Customer Agent. La fonctionnalité est toujours en cours de développement et peut être modifiée.

Objectif de cet article

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

Avant de commencer

Vous aurez besoin des éléments suivants :

• Mot de Customer Agent activé
• Un points de terminaison HTTP que vous souhaitez que le Customer Agent appelle, un qui ne nécessite pas d’identifiants secrets (Clés d'API, jetons porteurs, etc.) pour y accéder dès aujourd’hui (les points de terminaison authentifiés seront bientôt disponibles, voir l’avertissement ci-dessous).
• Une compétence à laquelle attacher l’outil : soit un Customer Agent de compétences est fourni, soit une compétence entièrement personnalisée que vous avez créée

Si vous n’avez pas encore configuré de compétence, créez-en une d’abord. Les outils ne font rien tout seuls, ils doivent être attachés à une compétence.

Attention : le stockage sécurisé des Clés d'API et d’autres secrets sera bientôt disponible. Jusqu’à ce qu’il soit livré, ne mettez pas de Clés d'API, de jetons porteurs ou d’autres identifiants sensibles dans des outils entièrement personnalisés. La configuration de l’outil n’est pas encore un endroit sûr pour les stocker. Pour l’instant, n’utilisez que des outils dont les points de terminaison peuvent être appelés en toute sécurité sans authentification secrète (par exemple, des points de terminaison internes derrière la liste d’autorisation IP ou des points de terminaison qui acceptent des identifiants non sensibles). La prise en charge des points de terminaison authentifiés est en cours.

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

Un outil entièrement personnalisé est une demande HTTP que le Customer Agent peut effectuer au cours d’une conversation. La création d’outils entièrement personnalisés est disponible en version bêta ouverte pour tous les comptes de Customer Agent. Utilisez-en un lorsque les outils fournis par le Customer Agent ne répondent pas à vos besoins : par exemple, rechercher une commande dans votre propre système de gestion des commandes au lieu de Shopify, vérifier l’inventaire 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 de manière native.

Pour en savoir plus sur le concept sous-jacent, consultez l’article Comprendre les outils Customer Agent.

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

Accédez à Customer Agent > Outils, puis cliquez sur Créer un outil.

2. Nommez et décrivez l’outil

• Nom : un identifiant abrégé tel que « 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 : GET, POST, PUT, DELETE ou PATCH.
• URL : URL complète du points de terminaison. Vous pouvez inclure des espaces réservés pour les 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.

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

Fournissez un corps JSON. Utilisez des espaces réservés pour les valeurs que le Customer Agent doit remplir au moment de l’exécution.

Exemple de corps de texte :

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

5. Utilisez des espaces réservés pour les valeurs dynamiques

Le Customer Agent peut saisir des valeurs au moment de l’exécution à l’aide de caractères de remplissage. Remplissages courants :

• {{profile_id}} — L’identifiant de profil Klaviyo du client dans la conversation
• {{conversation_id}} — L’ID de conversation actuel
• Tout paramètre que vous définissez dans votre schéma d’entrée (p. ex., {{product_sku}}, {{order_id}})

Les espaces réservés fonctionnent dans l’URL, les en-têtes et le corps de texte.

6. Authentification

La prise en charge des points de terminaison authentifiés est imminente. D’ici là, ne mettez pas de Clés d'API, de jetons porteurs ou d’autres secrets dans un outil entièrement personnalisé. N’utilisez que des points de terminaison qui peuvent être appelés en toute sécurité sans identifiants secrets, par exemple, des points de terminaison internes protégés par une liste d’autorisation IP ou des points de terminaison publics qui acceptent des identifiants non sensibles.

Le stockage secret sécurisé est en cours et débloquera les points de terminaison authentifiés.

7. Testez l’outil

Cliquez sur Outil de test. Fournissez des valeurs fictives pour tous les paramètres d’entrée. Vérifiez que :

• La réponse est renvoyée
• Le format de réponse correspond aux attentes du Customer Agent.
• Tous les cas d’erreur sont traités

8. Enregistrez et associez une compétence

Cliquez sur Enregistrer. Pour que le Customer Agent utilise réellement l’outil, ouvrez la compétence que vous souhaitez utiliser et ajoutez-y l’outil.

Rédiger une bonne description de l’outil

La description est le champ le plus important. Le Customer Agent choisit l’outil à utiliser en fonction de la description, et non du nom. Descriptions des Bon :

• 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é

• N’utilisez pas encore d’outils entièrement personnalisés pour les points de terminaison qui nécessitent des identifiants secrets. La prise en charge des points de terminaison authentifiés est imminente. Jusqu’à ce qu’il soit expédié, n’utilisez que des points de terminaison sûrs sans authentification secrète.
• Utilisez la liste d’autorisation IP si possible. Si votre points de terminaison est interne, limitez l’accès aux plages d’adresses IP de Klaviyo plutôt que de vous fier à des secrets.
• Connaissez les données que vous envoyez. Le Customer Agent transmet les données clients à l’outil en fonction des compétences requises. Vérifiez les champs que votre points de terminaison reçoit.
• 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 : le Customer Agent n’utilise jamais l’outil.
Cause probable : La description est trop vague ou l’outil n’est pas associé à la compétence qui l’utiliserait.
Corrigé : Réécrivez la description pour décrire spécifiquement quand elle doit être utilisée. Confirmez que l’outil apparaît dans la liste d’outils de la compétence.

Symptôme : l’outil renvoie une erreur lors du test.
Cause probable : URL incorrecte, corps mal formé ou charge utile que votre points de terminaison n’accepte pas.
Corrigé : Utilisez la fonctionnalité Outil de test pour vérifier la demande et la réponse brutes. Vérifiez le format de l’URL et du corps de texte par rapport à la saisie prévue de votre points de terminaison.

Symptôme : le Customer Agent utilise l'outil mais passe des paramètres erronés.
Cause probable : Les noms des espaces réservés ne correspondent pas au schéma, ou les instructions de compétences ne sont pas claires sur ce qu’il faut passer.
Corrigé : Vérifiez que les noms des espaces réservés correspondent exactement. Mettez à jour les instructions de compétences pour indiquer explicitement quand utiliser l’outil et quels paramètres 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 seul outil peut-il être utilisé par plusieurs compétences ?
Oui. Une fois créé, un outil peut être associé à un nombre illimité de compétences.

Quelles méthodes d’authentification sont prises en charge ?
La prise en charge des points de terminaison authentifiés est imminente. Pour l’instant, utilisez des points de terminaison qui ne nécessitent pas d’identifiants secrets (points de terminaison internes avec liste d’autorisation IP ou points de terminaison publics avec identifiants non sensibles).

Que se passe-t-il si mon points de terminaison est en panne ou renvoie une erreur ?
La gestion des erreurs pour les outils entièrement personnalisés n’est pas encore conçue. Si votre points de terminaison échoue, le Customer Agent peut produire une réponse dégradée ou déroutante. Jusqu’à ce que les erreurs soient traitées, n’utilisez que des points de terminaison fiables et suivez de près le comportement des outils.

Puis-je modifier un outil après l’avoir créé ?
Oui. Vous pouvez modifier le nom, la description, la configuration et les compétences associées à tout moment.

Puis-je modifier un outil ?
La version n’est pas encore prise en charge. Les modifications apportées à un outil prennent effet immédiatement pour chaque compétence qui l’utilise.

Additional resources