Référence des agents

Lorsque vous créez des agents personnalisés, reportez-vous à cet article pour en savoir plus sur les paramètres clés, tels que les instructions et les schémas de sortie. Pour une configuration étape par étape, consultez Créer des agents personnalisés. Pour une introduction, consultez Agents Braze et la Foire aux questions.

Modèles

Lorsque vous configurez un agent, vous pouvez choisir le modèle qu’il utilise pour générer ses réponses. Deux options s’offrent à vous : utiliser un modèle fourni par Braze ou utiliser votre propre clé API.

Important

Le modèle Auto fourni par Braze est optimisé pour des modèles dont les capacités de réflexion suffisent à effectuer des tâches comme la récupération de données de catalogue via des sources de connaissances ou la vérification de l’appartenance à un segment. Si vous utilisez d’autres modèles, nous vous recommandons de les tester pour vérifier qu’ils conviennent à votre cas d’usage. Vous devrez peut-être ajuster vos instructions pour fournir un niveau de détail différent ou un raisonnement étape par étape aux modèles dont la vitesse et les capacités varient.

Option 1 : Utiliser un modèle fourni par Braze

C’est l’option la plus simple, sans configuration supplémentaire. Braze vous donne directement accès à des grands modèles de langage (LLM). Pour utiliser cette option, sélectionnez Auto, qui s’appuie sur les modèles Gemini.

Option 2 : Utiliser votre propre clé API

Cette option vous permet de connecter votre compte Braze à des fournisseurs comme OpenAI, Anthropic ou Google Gemini. Si vous utilisez votre propre clé API d’un fournisseur de LLM, les coûts liés aux jetons vous sont facturés directement par votre fournisseur, et non par Braze.

Nous vous recommandons de tester régulièrement les modèles les plus récents, car les anciens modèles peuvent être abandonnés ou devenir obsolètes au bout de quelques mois. Assurez-vous de disposer de crédits suffisants auprès de votre fournisseur pour exécuter vos agents à grande échelle. Vous pouvez aussi vous abonner aux notifications de l’Agent Console dans les Préférences de notification afin d’être alerté lorsque Braze détecte qu’un modèle n’est plus disponible ou rencontre des problèmes de facturation avec votre fournisseur de LLM.

Pour configurer cette option :

1. Accédez à Intégrations de partenaires > Partenaires technologiques et trouvez votre fournisseur.
2. Saisissez la clé API fournie par votre fournisseur.
3. Sélectionnez Enregistrer.

Vous pouvez ensuite revenir à votre agent et sélectionner votre modèle.

Lorsque vous utilisez un LLM fourni par Braze, les fournisseurs de ce modèle agissent en tant que sous-traitants de Braze, conformément aux conditions de l’avenant relatif au traitement des données (DPA) conclu entre vous et Braze. Si vous choisissez d’utiliser votre propre clé API, le fournisseur de votre abonnement LLM est considéré comme un fournisseur tiers au titre du contrat conclu entre vous et Braze.

Niveaux de réflexion

Certains fournisseurs de LLM vous permettent d’ajuster le niveau de réflexion du modèle sélectionné. Le niveau de réflexion détermine l’ampleur du raisonnement que le modèle mène avant de répondre, des réponses rapides et directes jusqu’aux chaînes de raisonnement plus longues. Il influe sur la qualité des réponses, la latence et la consommation de jetons.

Nous vous recommandons de commencer par le niveau Minimal et de tester les réponses de votre agent. Vous pouvez ensuite passer au niveau Faible ou Moyen si l’agent peine à fournir des réponses précises. Dans de rares cas, un niveau de réflexion Élevé peut être nécessaire, mais il peut entraîner des coûts de jetons élevés, des temps de réponse plus longs ou un risque accru d’erreurs de délai d’expiration. Si votre agent a du mal à concilier raisonnement en plusieurs étapes et temps de réponse raisonnables, envisagez de répartir votre cas d’usage entre plusieurs agents capables de travailler ensemble dans un Canvas ou un catalogue.

Braze utilise pour les appels sortants vers les LLM les mêmes plages d’adresses IP que pour le contenu connecté. Ces plages sont répertoriées dans la liste d’adresses IP autorisées du contenu connecté. Si votre fournisseur prend en charge la liste d’adresses IP autorisées, vous pouvez restreindre la clé à ces plages afin que seul Braze puisse l’utiliser.

Important

Lorsque vous utilisez un LLM fourni par Braze, les fournisseurs de ce modèle agissent en tant que sous-traitants de Braze, conformément aux conditions de l’avenant relatif au traitement des données (DPA) conclu entre vous et Braze. Si vous choisissez d’utiliser votre propre clé API, le fournisseur de votre abonnement LLM est considéré comme un fournisseur tiers au titre du contrat conclu entre vous et Braze.

Déterminer le modèle à utiliser

Chaque fournisseur de LLM propose une combinaison légèrement différente de capacités, de coûts et de niveaux de réflexion. Voici quelques recommandations générales et bonnes pratiques :

• Pour optimiser les coûts, testez en priorité les modèles dont le coût par jeton est le plus faible. Ne passez à des modèles plus coûteux que si les modèles moins chers peinent à traiter le cas d’usage ou produisent des résultats incohérents ou inexacts.
• Pour optimiser la vitesse et les performances, testez en priorité les niveaux de réflexion les plus bas. Ne passez à des niveaux de réflexion plus élevés que si les niveaux plus bas peinent à traiter le cas d’usage ou produisent des résultats incohérents ou inexacts.
• Si les modèles moins coûteux ou les niveaux de réflexion plus bas peinent à traiter le cas d’usage ou produisent des résultats incohérents ou inexacts, envisagez de passer à des modèles plus coûteux ou à des niveaux de réflexion plus élevés.
• Pendant les tests, veillez à trouver le bon équilibre entre fiabilité et précision d’une part, et consommation de jetons et durée d’invocation d’autre part.
• Chaque cas d’usage peut avoir un modèle et un niveau de réflexion optimaux différents. Nous vous recommandons de tester minutieusement afin de vérifier que la qualité est constante et qu’aucun délai d’expiration ne survient.

Contrôles du flux d’invocations

Les contrôles du flux d’invocations suivants s’appliquent par espace de travail :

• Modèle fourni par Braze : 5 000 invocations par minute
• Utilisation de votre propre clé API : 5 000 invocations par minute

Lorsque de nombreux utilisateurs entrent simultanément dans une étape Agent, Braze met les invocations en file d’attente selon ces limites. Le traitement peut donc prendre plus de temps lors des envois à fort volume.

Limites quotidiennes d’invocations et de crédits

Chaque agent dispose d’une limite quotidienne d’invocations (250 000 par défaut ; 1 000 000 au maximum, sauf si votre contrat autorise davantage). Chaque invocation (y compris les aperçus dans l’Agent Console et les exécutions de test de Canvas qui utilisent Simuler la réponse) est prise en compte dans cette limite.

Dans l’Agent Console, la Limite quotidienne de coût en crédits d’action estime le nombre maximal de crédits qu’un agent peut consommer par jour. Braze multiplie le ratio de crédits par invocation de votre espace de travail pour le modèle sélectionné par la limite quotidienne d’invocations.

Quand les crédits sont-ils consommés ?

Braze ne facture des crédits que pour les invocations dont le traitement aboutit. Aucun crédit n’est consommé lorsqu’une invocation échoue en raison :

• d’une erreur de limite de débit renvoyée par le fournisseur de LLM (y compris les nouvelles tentatives qui finissent par échouer) ;
• de l’indisponibilité du modèle sélectionné ;
• de l’atteinte par l’agent de sa limite quotidienne d’invocations.

Des crédits sont consommés lorsqu’une invocation expire, même si l’agent ne renvoie aucun résultat exploitable.

Surveiller la consommation de crédits

Accédez à Paramètres > Facturation > Utilisation des crédits > Agent Console pour consulter la consommation de crédits, le nombre d’invocations et les ratios de crédits par agent.

Les ratios de crédits sont définis dans votre contrat et s’affichent dans le tableau de bord Utilisation des crédits (onglet Ratios de crédits et onglet Agent Console). L’estimation est mise à jour lorsque vous modifiez le modèle ou la limite d’invocations.

Pour maîtriser vos dépenses, réduisez la limite quotidienne d’invocations. Pour les modèles utilisant votre propre clé (BYO), vous pouvez également choisir un modèle moins coûteux ou réduire le niveau de réflexion afin de diminuer les coûts de jetons facturés par le fournisseur. Braze Auto ne permet pas d’ajuster le niveau de réflexion.

Erreurs de limite de débit

Si le fournisseur de LLM renvoie une erreur de limite de débit lors de l’invocation d’un agent d’étape de Canvas ou d’un agent de catalogue, Braze relance la requête en continu en appliquant des délais exponentiels, jusqu’à ce que l’appel réussisse ou que Braze détermine qu’il ne peut pas aboutir.

Lorsque les nouvelles tentatives du Canvas ou du catalogue sont épuisées, le panneau de détails des Journaux affiche Erreur ainsi que le message du fournisseur (par exemple Rate limit exceeded) dans Sortie. Les nouvelles tentatives sont visibles dans les journaux, de même que la toute première invocation, quel que soit son résultat final. Par exemple, si quatre nouvelles tentatives sont nécessaires pour obtenir un succès pour un utilisateur donné, vous pouvez rechercher son ID utilisateur et voir les cinq invocations (l’originale et les quatre nouvelles tentatives) dans les Journaux : l’invocation originale et les trois premières nouvelles tentatives afficheront Erreur avec Rate limit exceeded.

Les erreurs de limite de débit ne consomment pas de crédits Braze, y compris pour les nouvelles tentatives échouées affichées dans les Journaux.

Rédiger des instructions

Les instructions sont les règles ou directives que vous donnez à l’agent (prompt système). Elles définissent son comportement à chaque exécution. Les instructions système peuvent atteindre 25 Ko.

Si vous avez créé votre agent avec BrazeAI Operator à partir d’un modèle de départ, vérifiez les instructions préremplies et modifiez-les si nécessaire.

Voici quelques bonnes pratiques générales pour bien démarrer avec vos prompts :

1. Pensez d’abord au résultat. Commencez par énoncer l’objectif.
2. Attribuez un rôle ou un persona au modèle (« Vous êtes un… »).
3. Définissez un contexte et des contraintes clairs (audience, longueur, ton, format).
4. Demandez une structure (« Renvoie du JSON/une liste à puces/un tableau… »).
5. Montrez plutôt que d’expliquer. Incluez quelques exemples de grande qualité.
6. Découpez les tâches complexes en étapes ordonnées (« Étape 1… Étape 2… »).
7. Encouragez le raisonnement (« Réfléchis aux étapes en interne, puis fournis une réponse finale concise » ou « explique brièvement ta décision »).
8. Testez, examinez et itérez. De petits ajustements peuvent nettement améliorer la qualité.
9. Gérez les cas limites avec des règles positives et explicites, et ajoutez des instructions de refus si nécessaire.
10. Mesurez et documentez en interne ce qui fonctionne pour pouvoir le réutiliser et le déployer à grande échelle.

Dans la mesure du possible, rédigez des instructions positives et explicites. Dites à l’agent ce qu’il doit faire et formulez toute restriction en termes concrets. Si un agent ignore vos règles, consultez Pourquoi mon agent n’a-t-il pas suivi mes instructions ou mes règles ?.

Exemples

Pour des configurations de départ dans l’Agent Console, consultez Modèles d’agents créés avec Operator.

Pour des exemples d’instructions complètes que vous pouvez copier ou adapter, consultez la bibliothèque de cas d’usage pour Braze Agents.

Utiliser Liquid

Inclure du Liquid dans les instructions de votre agent permet d’ajouter un niveau de personnalisation supplémentaire à sa réponse. Vous pouvez indiquer la variable Liquid exacte que l’agent reçoit et l’intégrer au contexte de votre prompt. Par exemple, au lieu d’écrire explicitement « prénom », vous pouvez utiliser l’extrait de code Liquid {{${first_name}}} :

1

Tell a one-paragraph short story about this user, integrating their {{${first_name}}}, {{${last_name}}}, and {{${city}}}. Also integrate any context you receive about how they are currently thinking, feeling, or doing. For example, you may receive {{context.${current_emotion}}}, which is the user's current emotion. You should work that into the story.

Dans la section Journaux de l’Agent Console, vous pouvez consulter le détail des entrées et sorties de l’agent pour comprendre quelle valeur est générée à partir du Liquid.

Données reçues par les agents

Le contexte d’un agent n’est pas une mémoire conversationnelle ouverte. Contrairement à un assistant conversationnel, un agent ne voit que les données que vous lui transmettez explicitement au moment de son appel : il ne parcourt pas les profils utilisateurs, ne déduit pas les champs manquants et ne vous signale pas l’absence d’informations requises.

Concevez chaque agent comme un pipeline délibéré allant de l’entrée à la sortie. Fournissez chaque point de donnée dont l’agent a besoin à l’aide d’une ou plusieurs des méthodes suivantes :

1. Liquid dans les instructions : Insérez directement dans le prompt de l’agent des attributs utilisateur ({{${first_name}}}) et des variables de contexte Canvas ({{context.${variable_name}}}) sous forme de modèles.
2. + Contexte de l’agent : Sélectionnez des sources de connaissances, l’appartenance à un Segment, des directives de marque, Tout le contexte Canvas ou des données d’interaction utilisateur dans l’Agent Console.
3. Étapes Contexte : Définissez ou mettez à jour des variables context.* en amont dans le Canvas, avant l’exécution d’une étape Agent.
4. Contexte supplémentaire dans l’étape Agent : Transmettez à l’agent, au moment de l’envoi et depuis la configuration de l’étape, toutes les valeurs supplémentaires modélisées en Liquid qui ne sont pas déjà fournies par les autres méthodes.

Veillez à insérer ces variables de contexte en Liquid dans les instructions de l’agent, à joindre les fichiers de contexte que l’agent doit consulter, ou à sélectionner Ajouter tout le contexte Canvas. Si une valeur n’est transmise par aucun de ces canaux, l’agent ne la reçoit pas. Listez les entrées requises dans vos instructions ou dans les prérequis des cas d’usage, puis vérifiez les entrées dans Agent Console > Journaux après vos tests.

Pour les agents de catalogue, utilisez les Champs de la section Sortie plutôt qu’un schéma JSON ; vous pouvez toujours rédiger des instructions demandant au modèle une sortie clé-valeur correspondant à ces noms de champs.

Pour en savoir plus sur les bonnes pratiques de rédaction de prompts, consultez les guides des fournisseurs de modèles suivants :

• OpenAI
• Anthropic
• Gemini

Sorties

Si vous avez créé votre agent avec BrazeAI Operator à partir d’un modèle de départ, vérifiez le schéma de sortie prérempli et modifiez-le si nécessaire.

Schémas de base

Les schémas de base correspondent à une sortie simple renvoyée par un agent. Il peut s’agir d’une chaîne de caractères, d’un nombre, d’un booléen, d’un tableau de chaînes de caractères ou d’un tableau de nombres.

Par exemple, si vous souhaitez recueillir les scores de sentiment des utilisateurs à partir d’une simple enquête de satisfaction pour savoir dans quelle mesure vos clients sont satisfaits après avoir reçu un produit, vous pouvez sélectionner Nombre comme schéma de base pour structurer le format de sortie.

Important

Les tableaux sont disponibles uniquement pour les agents d’étape du canvas, et non pour les agents de catalogue.

Schémas avancés

Les options de schéma avancé permettent de structurer manuellement des champs ou d’utiliser du JSON.

• Champs : Une approche sans code pour imposer une sortie d’agent que vous pouvez utiliser de manière cohérente.
• JSON : Une approche avec code pour créer un format de sortie précis, dans lequel vous pouvez imbriquer des variables et des objets au sein du schéma JSON. Disponible uniquement pour les agents d’étape du canvas, et non pour les agents de catalogue.

Nous vous recommandons d’utiliser des schémas avancés lorsque vous souhaitez que l’agent renvoie une structure de données comportant plusieurs valeurs définies de manière structurée, plutôt qu’une sortie à valeur unique. La sortie est ainsi mieux formatée et constitue une variable de contexte cohérente.

Sortie de secours

Les valeurs de secours sont disponibles uniquement pour les agents d’étape du canvas. Dans la section Sortie de la console des agents d’un agent d’étape du canvas, vous pouvez définir les valeurs que Braze utilise en cas d’échec d’un appel.

Pour les schémas JSON, Braze lit le schéma et génère un champ de saisie pour chaque propriété, ce qui vous permet de définir une valeur de secours par clé. Pour les schémas Champs, vous saisissez une valeur de secours pour chaque champ. Pour les schémas de base, vous saisissez une seule valeur de secours. Les agents d’étape du canvas prennent en charge Liquid dans les valeurs de secours.

Pour connaître les étapes de configuration, consultez Configurer les valeurs de secours. Pour en savoir plus sur le comportement à l’exécution dans Canvas, consultez Gestion des erreurs et comportement de secours.

Par exemple, vous pouvez utiliser un format de sortie dans un agent destiné à créer un exemple d’itinéraire de voyage pour un utilisateur à partir d’un formulaire qu’il a soumis. Le format de sortie vous permet de définir que chaque réponse de l’agent doit renvoyer des valeurs pour tripStartDate, tripEndDate et destination. Chacune de ces valeurs peut être extraite des variables de contexte et placée dans une étape Message pour la personnalisation à l’aide de Liquid.

• champs
• schéma json

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

{
  "type": "object",
  "properties": {
    "sentiment": {
      "type": "string"
    },
    "reasoning": {
      "type": "string"
    }
  },
  "required": [
    "sentiment",
    "reasoning"
  ]
}

Contexte de catalogue et champs

Pour qu’un Canvas Step Agent puisse accéder aux données d’un catalogue, créez une source de connaissances à partir de ce catalogue, puis ajoutez-la via + Agent context. L’agent interroge la source de connaissances pour récupérer les lignes correspondantes. Il n’envoie au LLM que les données de catalogue pertinentes, ce qui réduit la consommation de jetons et améliore la précision de la récupération. Vous ne pouvez pas associer le catalogue directement comme contexte d’agent. Les agents configurés avec l’ancienne option Add catalog fields, avant l’arrivée des sources de connaissances, peuvent continuer à utiliser ce contexte jusqu’à ce que vous les migriez.

Lorsque vous déployez un Catalog Agent sur un champ de catalogue, activez le contrôle des entrées obligatoires et choisissez les colonnes sélectionnées qui doivent être renseignées pour que l’agent s’exécute. L’agent ignore une ligne uniquement lorsque l’une de ces colonnes obligatoires est vide ou manquante, par exemple un champ gender qui n’a pas encore été rempli. Les colonnes sélectionnées sont obligatoires par défaut, mais vous pouvez retirer celles qui peuvent rester vides sans bloquer l’exécution. Vous évitez ainsi de gaspiller des jetons sur des données incomplètes.

Les Catalog Agents respectent également l’ordre des colonnes lorsque des champs d’entrée dépendent les uns des autres. Si la colonne D doit être générée à partir des colonnes B et C, l’agent ne s’exécute pas sur la colonne D tant que B et C ne contiennent pas de valeurs pour cette ligne.

Pour découvrir des scénarios de déploiement et des exemples, consultez Utiliser les Catalog Agents et Bonnes pratiques pour les Catalog Agents.

Contexte d’appartenance aux Segments

Vous pouvez sélectionner jusqu’à cinq Segments que l’agent utilisera pour vérifier l’appartenance de chaque utilisateur lorsqu’il est utilisé dans un Canvas. Imaginons que votre agent dispose d’un contexte d’appartenance configuré pour un Segment « Loyalty Users », et qu’il soit utilisé dans un Canvas. Lorsque les utilisateurs entrent dans une étape Agent, l’agent peut vérifier si chaque utilisateur fait partie de chacun des Segments que vous avez indiqués dans la console de l’agent, puis utiliser cette appartenance (ou non-appartenance) comme contexte pour le LLM.

Directives de marque

Vous pouvez sélectionner des directives de marque que votre agent devra respecter dans ses réponses. Par exemple, si vous souhaitez que votre agent rédige un SMS pour inciter les utilisateurs à souscrire un abonnement à une salle de sport, vous pouvez utiliser ce champ pour faire référence à votre directive prédéfinie au ton audacieux et motivant.

Fichiers de contexte

Téléversez des documents de référence afin qu’un agent puisse consulter du contenu statique à chaque invocation — par exemple, un guide de ton, un document de politique ou une spécification produit. Les fichiers de contexte sont disponibles pour les agents d’étape Canvas et les agents de catalogue.

Pour joindre des fichiers :

1. Dans l’étape Instructions, sélectionnez + Agent context > Upload files.
2. Ajoutez un ou plusieurs fichiers. Les types pris en charge sont PDF, TXT, MD et CSV.
3. Enregistrez l’agent. Les fichiers sont téléversés lors de l’enregistrement. Ils restent en attente dans le navigateur et sont inclus lorsque vous prévisualisez l’agent.

Vous pouvez joindre jusqu’à 10 fichiers par agent. L’ensemble des fichiers joints peut totaliser jusqu’à 15 Mo. Lorsque vous joignez des fichiers de contexte, indiquez à l’agent dans vos instructions comment les utiliser. Par exemple, vous pouvez inclure : « Suivez le ton et la terminologie du guide de style joint. » Une section Files vide est comptabilisée dans l’avertissement needs setup tant que vous n’avez pas joint au moins un fichier.

Braze envoie les fichiers joints à chaque invocation de l’agent, y compris les prévisualisations dans la console d’agent. Étant donné que les fichiers sont inclus à chaque exécution, des pièces jointes volumineuses peuvent augmenter la consommation de jetons et la latence.

Les fichiers de contexte diffèrent des directives de marque : les directives de marque sont des paramètres d’espace de travail synthétisés, tandis que les fichiers de contexte sont des documents que vous téléversez directement vers un seul agent. Pour les étapes de configuration, consultez Ajouter du contexte.

Historique d’interaction spécifique à l’utilisateur

Les données d’interaction d’un utilisateur incluent les Campaign et les messages Canvas récemment reçus par canal, le contenu de chaque message et si l’utilisateur a interagi avec chacun d’entre eux. Vous pouvez inclure ces données en tant que contexte spécifique à l’utilisateur qu’un agent peut consulter lorsqu’il est invoqué pour un utilisateur dans un Canvas. L’historique d’interaction spécifique à l’utilisateur peut aider à influencer un agent pour qu’il rédige des textes qui résonnent avec chaque utilisateur lorsque sa mission est de rédiger des messages personnalisés.

Historique des versions

La Console des agents enregistre une nouvelle version chaque fois que vous enregistrez des modifications apportées à l’agent. L’onglet Historique des versions répertorie chaque version enregistrée et les modifications entre les enregistrements.

1. Ouvrez l’agent dans la Console des agents.
2. Sélectionnez l’onglet Historique des versions.
3. Sélectionnez une version pour examiner sa configuration.

Pour inspecter les modifications d’une version, sélectionnez Voir. Braze affiche un diff en ligne de style code qui met en évidence les ajouts et les suppressions. Le contenu supprimé apparaît avec un style barré en rouge. Lorsque vous ajoutez ou supprimez des fichiers de contexte, le diff liste les noms des fichiers joints.

Si vous devez restaurer les instructions d’une version précédente, ouvrez Voir pour cette version, copiez le texte des instructions et collez-le dans votre champ Instructions actuel.

Conseil

Dans la vue du diff en ligne, appuyez sur ⌘ + A (macOS) ou Ctrl + A (Windows) pour sélectionner toutes les instructions sans le balisage de suppression en rouge, afin de pouvoir copier et restaurer le texte propre.

Dupliquer des agents

Dupliquez un agent pour tester des améliorations ou des itérations en parallèle de l’original. Utilisez l’historique des versions pour consulter ou restaurer des configurations antérieures. Pour dupliquer un agent :

1. Survolez la ligne de l’agent et sélectionnez le menu .
2. Sélectionnez Dupliquer.

Archiver des agents

À mesure que vous créez des agents personnalisés, vous pouvez organiser la page Gestion des agents en archivant ceux que vous n’utilisez plus activement. Pour archiver un agent :

1. Survolez la ligne de l’agent et sélectionnez le menu .
2. Sélectionnez Archiver.