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. Utilisez le tableau suivant pour trouver le bon chemin de déploiement pour votre agent.

Vous sélectionnez le type d’agent dans Agent Console lors de la création de l’agent. Pour les étapes de configuration, consultez Créer des agents personnalisés.

Bonnes pratiques

Ciblez les cas d’usage à forte valeur ajoutée où les agents peuvent générer le meilleur retour sur investissement (ROI), et choisissez des audiences susceptibles de répondre. Une audience plus restreinte mais à fort potentiel surpasse souvent une large audience à faible potentiel.

Pour les agents d’étapes Canvas, commencez par les utilisateurs présentant des signaux forts — tels que des recherches récentes, un engagement élevé ou des données de profil riches — avant d’élargir à des Segments plus larges. Pour les agents de catalogue, privilégiez les lignes dont les colonnes d’entrée nécessaires sont déjà remplies, afin que chaque invocation dispose de suffisamment 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 afin que seule une partie de votre audience entre dans la branche contenant votre étape d’agent.

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

Lorsqu’un test à petite échelle (par exemple, une branche Chemins d’expérience) affiche une qualité et un ROI satisfaisants, prévoyez de déployer l’agent auprès de l’ensemble de votre audience cible (et pas uniquement le groupe de test) afin que chaque utilisateur éligible en bénéficie.

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

• Augmentez la limite quotidienne d’invocations de l’agent dans la console d’agent afin qu’elle puisse gérer le volume total de votre audience. La valeur par défaut est de 250 000 ; vous pouvez l’augmenter jusqu’à 1 000 000 (ou davantage en contactant votre gestionnaire de la satisfaction client). Consultez Limites quotidiennes d’invocations et de crédits.
• Vérifiez l’estimation du Daily action credit cost limit et confirmez que votre espace de travail dispose de suffisamment de crédits pour des envois à grande échelle.
• Supprimez ou reconfigurez l’expérience afin que l’ensemble de l’audience cible entre dans l’étape d’agent (ou promouvez la variante gagnante vers le parcours principal).

Le passage à l’audience complète augmente la consommation de crédits de manière proportionnelle. Surveillez l’utilisation dans Settings > Billing > Credits Usage > Agent Console après le lancement.

Utiliser les agents d’étape Canvas

Après avoir créé un agent d’étape Canvas, ajoutez-le à un Canvas en tant qu’étape Agent pour personnaliser les messages ou guider la prise de décision en temps réel.

Fonctionnement

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

Les étapes Agent utilisent les variables de contexte Canvas pour ingérer le contexte pertinent et produire une variable utilisable dans le Canvas. Pour les prérequis et une 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 et 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 Agent.
4. (Facultatif) Ajoutez des valeurs de contexte supplémentaires que l’agent peut référencer lors de son exécution. Cela peut inclure des variables Liquid supplémentaires ou un contexte Canvas que vous n’avez pas encore lié dans 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 Tester le Canvas pour parcourir le chemin utilisateur complet.

Pour les types de données de sortie, le templating Liquid et les captures d’écran, consultez Étape Agent.

Cas d’usage

Utiliser la sortie de l’agent

Après l’exécution de l’agent, utilisez la variable de sortie dans votre Canvas :

• Routage du parcours : Orientez les utilisateurs vers différents parcours Canvas en fonction de la réponse de l’agent. Utilisez les parcours d’audience ou les 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 sur le profil utilisateur (par exemple, avec une étape Mise à jour utilisateur) ou envoyez-les à l’aide d’un webhook.

Pour des exemples, consultez Fonctionnement dans Étape Agent.

Gestion des erreurs et comportement de secours

Les éléments suivants s’appliquent aux agents d’étape Canvas dans une étape Agent.

• Si le modèle connecté renvoie une erreur de limite de débit du fournisseur LLM, Braze retente continuellement la requête en utilisant des délais exponentiels jusqu’à ce que l’appel réussisse ou que Braze détermine qu’il ne peut pas aboutir ; les utilisateurs passent ensuite à l’étape Canvas suivante.
• Pour les autres échecs (comme un délai d’attente dépassé ou une clé API invalide), la variable de sortie est définie sur null sauf si l’agent a des valeurs de secours configurées dans la console Agent.
• Si un agent atteint sa limite d’invocations quotidiennes, Braze applique également les valeurs de secours configurées lorsqu’elles sont présentes ; sinon, la variable de sortie est définie sur null.

Lorsque des valeurs de secours sont configurées, Braze les applique pour les erreurs non réessayables et pour les échecs liés à la limite quotidienne. Braze effectue le rendu de la valeur de secours avec Liquid par utilisateur et stocke le résultat dans la variable de sortie de l’étape Agent. Sans valeurs de secours, ces échecs définissent la variable de sortie sur null. Si vous préférez configurer des valeurs par défaut spécifiques à l’étape dans les étapes Message plutôt que des valeurs de secours dans la console Agent, vous pouvez toujours utiliser les valeurs Liquid par défaut en aval. Pour cela, laissez les valeurs de secours vides dans la section Sortie de la configuration de l’agent afin que les valeurs par défaut Liquid 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 quotidiennes ne consomment pas de crédits Braze. Les délais d’attente dépassés consomment des crédits. 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 pour des invocations identiques répétées dans un délai de quelques minutes. Les réponses mises en cache comptent toujours dans le total et les invocations quotidiennes.
• Les étapes Agent peuvent prendre du temps pour traiter un grand lot d’utilisateurs. Braze met en file d’attente les invocations selon les contrôles de flux d’invocation, de sorte que les utilisateurs peuvent rester en attente lors des envois à fort volume.

Pour la configuration de l’étape Agent et les détails d’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 au catalogue à l’avenir.

Fonctionnement

Après le lancement, l’agent s’exécute et évalue chaque ligne, en prenant 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 le déploiement de l’agent. Si vous avez sélectionné Recalculate when catalog rows update, toutes les valeurs de ce champ sont mises à jour si les champs sources existants changent.

Lorsque vous configurez les colonnes d’entrée pour 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 devant contenir des valeurs : les colonnes sélectionnées sont marquées comme obligatoires par défaut, mais vous pouvez retirer des colonnes qui peuvent rester vides sans bloquer l’agent. L’agent ignore une ligne uniquement lorsqu’une colonne que vous avez laissée comme obligatoire 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 mauvaise qualité.

Les agents de catalogue respectent également les dépendances entre les 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 Apply AI agent. 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 ne peut pas se produire :

• 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 Apply AI agent.
3. Assignez 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 Only run when required columns have values pour ignorer les lignes où une ou plusieurs colonnes d’entrée sélectionnées sont vides. Lorsque cette option est activée, sélectionnez quelles colonnes d’entrée doivent être renseignées pour que l’agent s’exécute : toutes les colonnes sélectionnées sont obligatoires par défaut, mais vous pouvez en retirer certaines qui peuvent rester vides sans bloquer une exécution.
6. Décidez si l’agent doit recalculer les champs lorsque les lignes du catalogue sont mises à jour. Si vous ne sélectionnez pas cette option, l’agent ne s’exécute qu’une seule fois par ligne.
7. Sélectionnez Add fields pour déployer l’agent et consulter les estimations de coût. La fenêtre modale Cost estimation indique combien de fois l’agent s’exécutera sur ce catalogue, ce qui correspond approximativement au nombre total de lignes. Pour continuer, sélectionnez Confirm.

Bonnes pratiques pour les agents de catalogue

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

Ne laissez pas une colonne marquée comme obligatoire si vous vous attendez à ce qu’elle reste vide pour certaines lignes tout en souhaitant que l’agent s’exécute : retirez-la plutôt de l’ensemble obligatoire. Ignorer les lignes incomplètes évite une consommation incorrecte de jetons et maintient une qualité de résultat élevée.

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 pour Response Field afin de l’utiliser dans le champ du catalogue.

Supposons que vous ayez 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 Response Field pour remplir la colonne avec les descriptions de l’agent.

Vous pouvez également remplacer manuellement le contenu généré par l’agent dans la cellule en sélectionnant Edit Item et en mettant à jour la description générée par l’agent avec vos modifications. 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 limitation du débit, Braze retente continuellement la requête en utilisant des délais exponentiels jusqu’à ce que l’appel réussisse ou que Braze détermine qu’il ne peut pas être complété.
• Pour les autres échecs (tels qu’un délai d’expiration ou une clé API invalide), la valeur du champ de catalogue n’est pas mise à jour. Les agents de catalogue ne prennent pas en charge la configuration de valeurs de secours dans la console d’agents.
• Vous pouvez consulter les journaux de l’agent pour obtenir des détails sur les exécutions échouées.
• Les agents de catalogue sont limités au traitement de valeurs d’entrée d’un maximum de 25 Ko par ligne.

Surveiller votre agent

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

Dans la section Utilisation de votre agent, vous pouvez consulter et naviguer vers les emplacements où l’agent est activement utilisé dans les catalogues et les Canvas.

Dans la section Journaux de votre agent, vous pouvez surveiller les appels réels de l’agent qui se produisent dans vos Canvas et catalogues. Vous pouvez filtrer par des informations telles que la plage de dates, le résultat (succès ou échec) ou l’emplacement d’appel. Vous pouvez également sélectionner Exporter en CSV pour exporter les journaux affichés sur la page en cours uniquement.

Conseil

Vous pouvez également surveiller les erreurs de limite d’invocations quotidiennes dans le Journal d’activité des messages.

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

Pour les agents d’étapes Canvas, les journaux incluent une section Sortie de repli qui affiche toute sortie de repli utilisée lorsque l’invocation a échoué.

Utiliser Currents

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

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

Consultez le Glossaire des événements d’engagement liés aux messages pour plus de détails.

Articles connexes

• Étape d'agent
• Référence pour les agents
• Questions fréquentes