Déployer des agents personnalisés

Après avoir créé un agent, utilisez cette page pour savoir où et comment le déployer dans Braze. Le type d’agent que vous choisissez lors de la création — agent Canvas ou agent de catalogue — détermine l’endroit où l’agent peut s’exécuter. Pour une introduction, consultez Agents Braze.

Types d’agents personnalisés

Les agents personnalisés se déploient dans différentes parties de Braze selon leur type. Consultez le tableau suivant pour trouver le chemin de déploiement adapté à votre agent.

Vous choisissez le type d’agent lors de sa création. Pour connaître les étapes de configuration, consultez Créer des agents personnalisés.

Bonnes pratiques

Ciblez des cas d’usage à forte valeur, où les agents peuvent générer le meilleur retour sur investissement (ROI), et choisissez des audiences susceptibles de réagir. Une audience réduite mais à fort potentiel donne souvent de meilleurs résultats qu’une large audience à faible potentiel.

Pour les agents d’étape Canvas, commencez par les utilisateurs qui présentent des signaux forts, comme des recherches récentes, un engagement élevé ou des données de profil riches. Élargissez ensuite à des Segments plus vastes. Pour les agents de catalogue, privilégiez les lignes dont les colonnes d’entrée nécessaires sont déjà renseignées. Chaque invocation dispose ainsi d’assez de contexte pour produire un résultat utile.

Pour tester le ROI à petite échelle avant de déployer un agent à grande échelle, utilisez une étape Chemins d’expérience. Seule une partie de votre audience entre alors dans la branche qui contient votre étape Agent.

Passer à l’échelle après un test concluant

Lorsqu’un test à petite échelle (par exemple, une branche Chemins d’expérience) montre une qualité et un ROI satisfaisants, prévoyez de déployer l’agent auprès de l’ensemble de votre audience cible, et pas seulement du groupe de test, afin que tous les utilisateurs éligibles en profitent.

Avant de passer à l’échelle, tenez compte des points suivants :

• Augmentez la limite quotidienne d’invocations de l’agent dans Agent Console pour qu’il puisse absorber le volume de toute votre audience. La valeur par défaut est de 250 000. Vous pouvez la porter jusqu’à 1 000 000, voire davantage avec votre Customer Success Manager. Consultez la section Limites quotidiennes d’invocations et de crédits.
• Vérifiez l’estimation de la Limite quotidienne de coût en crédits d’action et assurez-vous que votre espace de travail dispose de suffisamment de crédits pour des envois à grande échelle.
• Supprimez ou reconfigurez l’expérience pour que toute l’audience cible entre dans l’étape Agent (ou promouvez la variante gagnante vers le chemin principal).

Le passage à l’ensemble de l’audience augmente la consommation de crédits de manière proportionnelle. Après le lancement, surveillez l’utilisation dans Paramètres > Facturation > Utilisation des crédits > Agent Console.

Utiliser les agents d’étape Canvas

Après avoir créé un agent d’étape Canvas, ajoutez-le à un Canvas sous forme d’étape Agent pour personnaliser vos messages ou orienter les décisions en temps réel.

Fonctionnement

Lorsqu’un utilisateur atteint une étape Agent dans un Canvas, Braze envoie à votre agent les données d’entrée que vous avez configurées. L’agent traite ces données à l’aide de son modèle et de ses instructions, puis renvoie une sortie stockée dans la variable de sortie définie dans l’étape. Vous pouvez ensuite utiliser cette sortie pour la prise de décision, la personnalisation ou des traitements en aval.

Les étapes Agent s’appuient sur les variables de contexte du Canvas pour ingérer le contexte pertinent et produire une variable utilisable dans le Canvas. Pour connaître les prérequis et consulter la référence complète, consultez Étape Agent.

Ajouter une étape Agent

Pour ajouter un agent à votre Canvas :

1. Glissez-déposez le composant Agent depuis la barre latérale, ou sélectionnez le bouton plus en bas d’une étape, puis sélectionnez Agent.
2. Sélectionnez l’agent qui traite les données dans cette étape.
3. Définissez le nom de la variable de sortie. Le type de données de sortie est défini dans la console des agents.
4. (Facultatif) Ajoutez des valeurs de contexte supplémentaires auxquelles l’agent pourra se référer lors de son exécution. Il peut s’agir de variables Liquid supplémentaires ou d’un contexte Canvas que vous n’avez pas déjà lié lors de la configuration de l’agent, par exemple des valeurs que vous souhaitez transmettre uniquement au moment de l’envoi depuis cette étape.
5. Testez l’agent à l’aide de l’aperçu intégré à l’étape ou de la fonction Tester le Canvas pour parcourir l’intégralité du chemin utilisateur.

Pour en savoir plus sur les types de données de sortie, le templating Liquid et consulter des captures d’écran, reportez-vous à Étape Agent.

Cas d’usage

Utiliser la sortie de l’agent

Une fois l’agent exécuté, utilisez la variable de sortie dans votre Canvas :

• Routage du parcours : Orientez les utilisateurs vers différents chemins du Canvas en fonction de la réponse de l’agent. Utilisez des parcours d’audience ou des arbres décisionnels avec des sorties numériques, booléennes ou structurées.
• Personnalisation : Insérez la réponse de l’agent directement dans une étape Message à l’aide de Liquid.
• Traitement des données utilisateur : Analysez et standardisez les données utilisateur, puis stockez-les dans le profil utilisateur (par exemple, avec une étape Mise à jour de l’utilisateur) ou envoyez-les à l’aide d’un webhook.

Pour des exemples, consultez Fonctionnement dans Étape Agent.

Gestion des erreurs et comportement de repli

Les points suivants s’appliquent aux agents d’étape Canvas utilisés dans une étape Agent.

• Si le modèle connecté renvoie une erreur de limite de débit provenant du fournisseur du LLM, Braze relance la requête en continu avec des délais exponentiels jusqu’à ce que l’appel aboutisse ou que Braze détermine qu’il ne peut pas être finalisé ; les utilisateurs passent ensuite à l’étape suivante du Canvas.
• Pour les autres échecs (comme un délai d’expiration ou une clé API non valide), la variable de sortie est définie sur null, sauf si des valeurs de repli sont configurées pour l’agent dans la console des agents.
• Si un agent atteint sa limite d’invocations quotidienne, Braze applique également les valeurs de repli configurées, le cas échéant ; sinon, la variable de sortie est définie sur null.

Lorsque des valeurs de repli sont configurées, Braze les applique en cas d’erreurs non réessayables et d’échecs liés à la limite quotidienne. Braze génère la valeur de repli avec Liquid pour chaque utilisateur et stocke le résultat dans la variable de sortie de l’étape Agent. Sans valeurs de repli, ces échecs définissent la variable de sortie sur null. Si vous préférez configurer des valeurs par défaut propres à chaque étape Message plutôt que des valeurs de repli dans la console des agents, vous pouvez toujours utiliser des valeurs Liquid par défaut en aval. Pour ce faire, laissez les valeurs de repli vides dans la section Sortie de la configuration de l’agent, afin que les valeurs Liquid par défaut puissent s’appliquer lorsque l’agent renvoie null.

Les erreurs de limite de débit, l’indisponibilité du modèle et les échecs liés à la limite d’invocations quotidienne ne consomment pas de crédits Braze. Les délais d’expiration, en revanche, en consomment. Consultez Quand les crédits sont consommés.

• Les réponses sont mises en cache pour des entrées identiques et peuvent être réutilisées lors d’invocations identiques répétées en l’espace de quelques minutes. Les réponses mises en cache sont tout de même comptabilisées dans le total des invocations et dans les invocations quotidiennes.
• Le traitement d’un grand lot d’utilisateurs par les étapes Agent peut prendre du temps. Braze place les invocations en file d’attente selon les contrôles du flux d’invocations ; les utilisateurs peuvent donc rester en attente lors des envois à volume élevé.

Pour en savoir plus sur la configuration de l’étape Agent et son comportement à l’exécution, consultez Gestion des erreurs dans Étape Agent. Pour plus de détails, consultez Gestion des erreurs dans Braze Agents.

Utiliser les agents de catalogue

Après avoir créé un agent de catalogue, appliquez-le à un champ de catalogue pour générer ou calculer automatiquement des valeurs pour chaque ligne. L’agent s’exécute également sur les nouvelles lignes ajoutées ultérieurement au catalogue.

Fonctionnement

Une fois lancé, l’agent s’exécute et évalue chaque ligne en intégrant les colonnes sélectionnées dans son contexte pour produire un résultat. Les agents s’exécutent sur toutes les nouvelles lignes ajoutées après leur déploiement. Si vous avez sélectionné Recalculer lors de la mise à jour des lignes du catalogue, toutes les valeurs de ce champ sont mises à jour lorsque les champs sources existants changent.

Lorsque vous configurez les colonnes d’entrée d’un agent de catalogue, activez le contrôle intégré au produit qui indique quelles colonnes sélectionnées doivent être renseignées avant que l’agent ne s’exécute (les libellés peuvent varier légèrement selon l’espace de travail). Une fois ce contrôle activé, choisissez le sous-ensemble de colonnes qui doivent contenir des valeurs. Les colonnes sélectionnées sont requises par défaut, mais vous pouvez retirer celles qui peuvent rester vides sans bloquer l’agent. L’agent ignore une ligne uniquement lorsqu’une colonne que vous avez laissée comme requise est vide ou manquante, par exemple un champ gender qui n’a pas été renseigné. Une exécution sans le contexte requis gaspille des jetons et peut produire un résultat de faible qualité.

Les agents de catalogue respectent également les dépendances entre colonnes. Si la colonne D est générée à partir des colonnes B et C, l’agent ne s’exécute pas sur la colonne D pour une ligne tant que B et C ne contiennent pas de valeurs pour cette ligne.

Vous pouvez actualiser et modifier les champs de votre catalogue qui utilisent des agents. Pour retirer un agent d’une colonne, désélectionnez Appliquer l’agent IA. La colonne redevient alors une colonne non agentique, et les champs conservent les dernières valeurs appliquées par l’agent lors de sa dernière exécution sur le catalogue.

Les références circulaires dans les catalogues ne sont pas prises en charge, ce qui signifie que le scénario suivant est impossible :

• La colonne agentique 1 utilise la colonne agentique 2 comme entrée
• La colonne agentique 2 utilise la colonne agentique 1 comme entrée

Ajouter un agent à un champ de catalogue

Pour ajouter un agent à votre champ de catalogue :

1. Dans votre catalogue, ajoutez un nouveau champ.
2. Sélectionnez Appliquer l’agent IA.
3. Attribuez un agent à ce champ.
4. Sélectionnez les colonnes à transmettre en entrée. Si aucune n’est sélectionnée, l’agent a accès à toutes les colonnes du catalogue.
5. (Facultatif) Activez Exécuter uniquement lorsque les colonnes requises contiennent des valeurs pour ignorer les lignes dont une ou plusieurs colonnes d’entrée sélectionnées sont vides. Lorsque cette option est activée, sélectionnez les colonnes d’entrée qui doivent être renseignées pour que l’agent s’exécute. Toutes les colonnes sélectionnées sont requises par défaut, mais vous pouvez retirer celles qui peuvent rester vides sans bloquer une exécution.
6. Indiquez si l’agent doit recalculer les champs lors de la mise à jour des lignes du catalogue. Si vous ne sélectionnez pas cette option, l’agent ne s’exécute qu’une seule fois par ligne.
7. Sélectionnez Ajouter des champs pour déployer l’agent et consulter les estimations de coûts. La fenêtre modale Estimation des coûts indique le nombre de fois que l’agent s’exécutera sur ce catalogue, soit à peu près le nombre total de lignes. Pour continuer, sélectionnez Confirmer.

Bonnes pratiques pour les agents de catalogue

Déterminez les colonnes dont l’agent a besoin avant de l’appliquer à un champ de catalogue. Après avoir activé les contrôles d’entrées requises pour le champ, sélectionnez les colonnes contenant les données que votre agent doit lire, puis retirez toute colonne pouvant rester vide sans bloquer une exécution. L’agent ignore une ligne uniquement lorsqu’une colonne que vous avez laissée comme requise est vide.

Ne laissez pas une colonne marquée comme requise si vous pensez qu’elle restera vide pour certaines lignes et que vous souhaitez tout de même que l’agent s’exécute : retirez-la plutôt de l’ensemble des colonnes requises. Ignorer les lignes incomplètes évite une consommation inutile de jetons et préserve la qualité des résultats.

Cas d’usage

Définir les champs de réponse

Si votre agent utilise des champs comme format de sortie, vous pouvez sélectionner le champ correspondant de l’agent dans Champ de réponse pour l’utiliser dans le champ du catalogue.

Supposons que vous disposiez d’un agent qui ajoute des descriptions de produits à un catalogue, avec les champs suivants pour structurer le format de sortie :

Vous pouvez ajouter un champ nommé product_description à un catalogue et sélectionner description comme Champ de réponse pour remplir la colonne avec les descriptions de l’agent.

Vous pouvez également remplacer manuellement la cellule générée par l’agent en sélectionnant Modifier l’élément et en modifiant la description générée. Pour revenir à la description générée par l’agent, sélectionnez le symbole d’actualisation dans la cellule.

Gestion des erreurs

• Si le fournisseur de LLM renvoie une erreur de limite de débit, Braze relance la requête en continu avec des délais exponentiels jusqu’à ce que l’appel aboutisse ou que Braze détermine qu’il ne peut pas être exécuté.
• Pour les autres échecs (comme un délai d’expiration ou une clé API non valide), la valeur du champ du catalogue n’est pas mise à jour. Les agents de catalogue ne permettent pas de configurer des valeurs de repli dans la console des agents.
• Vous pouvez consulter les logs de l’agent pour obtenir des détails sur les exécutions ayant échoué.
• Les agents de catalogue sont limités au traitement de valeurs d’entrée de 25 Ko maximum par ligne.

Surveiller votre agent

La surveillance fonctionne de la même manière, que votre agent s’exécute dans un Canvas ou dans des catalogues.

Dans la section Utilisation de votre agent, vous pouvez voir les catalogues et les Canvas qui utilisent activement l’agent, et y accéder directement.

Dans la section Journaux de votre agent, vous pouvez surveiller les appels réels de l’agent dans vos Canvas et catalogues. Vous pouvez filtrer selon différents critères, comme la plage de dates, le résultat (réussite ou échec) ou l’emplacement de l’appel. Vous pouvez aussi sélectionner Exporter CSV pour exporter uniquement les journaux affichés sur la page actuelle.

Conseil

Vous pouvez également surveiller les erreurs liées à la limite quotidienne d’invocations dans le journal d’activité des messages.

Sélectionnez Afficher pour un appel d’agent spécifique afin de consulter l’entrée, la sortie et l’ID utilisateur.

Pour les agents d’étape du canvas, les journaux comprennent une section Sortie de secours qui affiche la sortie de secours utilisée lorsque l’invocation a échoué.

Utiliser Currents

Vous pouvez aussi utiliser ces événements Currents pour accéder aux schémas d’enregistrement Kafka :

• Événements d’exécution d’agent
• Événements d’invocation d’outil

Pour en savoir plus, consultez le glossaire des événements d’engagement liés aux messages.

Articles connexes

• Étape Agent
• Référence pour les agents
• Foire aux questions