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 des réponses. Vous avez deux options : utiliser un modèle propulsé par Braze ou apporter votre propre clé API.

Important

Le modèle Auto propulsé par Braze est optimisé pour les modèles dont les capacités de raisonnement sont suffisantes pour effectuer des tâches telles que la récupération de données de catalogue via des sources de connaissances et la vérification de l’appartenance à un Segment. Lorsque vous utilisez d’autres modèles, nous vous recommandons de tester pour confirmer que votre modèle fonctionne bien pour votre cas d’usage. Vous devrez peut-être ajuster vos instructions pour donner différents niveaux de détail ou de raisonnement étape par étape aux modèles ayant des vitesses et des capacités différentes.

Option 1 : Utiliser un modèle propulsé par Braze

C’est l’option la plus simple, sans configuration supplémentaire requise. Braze fournit un accès direct aux grands modèles de langage (LLM). Pour utiliser cette option, sélectionnez Auto, qui utilise les modèles Gemini.

Important

Si vous ne voyez pas Braze Auto comme option dans le menu déroulant Model lors de la création d’un agent, contactez votre gestionnaire de la satisfaction client pour savoir comment devenir éligible à l’utilisation du modèle Braze Auto.

Option 2 : Apporter votre propre clé API

Avec cette option, vous pouvez connecter votre compte Braze à des fournisseurs comme OpenAI, Anthropic ou Google Gemini. Si vous apportez votre propre clé API d’un fournisseur de LLM, les coûts en jetons 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 dépréciés 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 également vous inscrire aux notifications de l’Agent Console dans les Préférences de notification pour ê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 cela :

1. Accédez à Partner Integrations > Technology Partners et trouvez votre fournisseur.
2. Saisissez votre clé API du fournisseur.
3. Sélectionnez Enregistrer.

Ensuite, vous pouvez 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, soumis aux conditions de l’Accord sur le traitement des données (DPA) entre vous et Braze. Si vous choisissez d’apporter votre propre clé API, le fournisseur de votre abonnement LLM est considéré comme un fournisseur tiers en vertu du contrat entre vous et Braze.

Niveaux de raisonnement

Certains fournisseurs de LLM peuvent vous permettre d’ajuster le niveau de raisonnement d’un modèle sélectionné. Les niveaux de raisonnement définissent l’étendue de la réflexion que le modèle utilise avant de répondre — des réponses rapides et directes à des chaînes de raisonnement plus longues. Cela affecte la qualité des réponses, la latence et l’utilisation des jetons.

Nous recommandons de commencer avec Faible et de tester les réponses de votre agent. Ensuite, vous pouvez ajuster le niveau de raisonnement à Bas ou Moyen si vous constatez que l’agent a des difficultés à fournir des réponses précises. Dans de rares cas, un niveau de raisonnement Élevé peut être nécessaire, bien que l’utilisation de ce niveau puisse entraîner des coûts en jetons élevés et des temps de réponse plus longs ou un risque accru d’erreurs de délai d’expiration. Si votre agent a du mal à équilibrer le raisonnement à plusieurs étapes avec des temps de réponse raisonnables, envisagez de diviser votre cas d’usage en plusieurs agents pouvant travailler ensemble dans un Canvas ou un catalogue.

Braze utilise les mêmes plages IP pour les appels LLM sortants que pour le contenu connecté. Les plages sont répertoriées dans la liste d’autorisation IP du contenu connecté. Si votre fournisseur prend en charge l’autorisation par IP, 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, soumis aux conditions de l’Accord sur le traitement des données (DPA) entre vous et Braze. Si vous choisissez d’apporter votre propre clé API, le fournisseur de votre abonnement LLM est considéré comme un fournisseur tiers en vertu du contrat entre vous et Braze.

Déterminer quel modèle utiliser

Chaque fournisseur de LLM propose un mélange légèrement différent de capacités de modèle, de coûts et de niveaux de raisonnement. Voici quelques lignes directrices générales et bonnes pratiques :

• Pour l’efficacité des coûts, privilégiez le test de modèles à faible coût en jetons avant les modèles plus coûteux. N’ajustez vers des modèles plus coûteux que si les modèles moins chers peinent avec le cas d’usage ou génèrent des résultats incohérents ou imprécis.
• Pour l’efficacité en termes de vitesse et de performance, privilégiez le test de niveaux de raisonnement inférieurs avant les niveaux supérieurs. N’ajustez vers des niveaux de raisonnement supérieurs que si les niveaux inférieurs peinent avec le cas d’usage ou génèrent des résultats incohérents ou imprécis.
• Si les modèles à faible coût ou les niveaux de raisonnement inférieurs peinent avec le cas d’usage ou génèrent des résultats incohérents ou imprécis, envisagez de passer à des modèles plus coûteux ou à des niveaux de raisonnement supérieurs.
• Pendant les tests, veillez à équilibrer la fiabilité et la précision avec l’utilisation des jetons et la durée d’invocation.
• Chaque cas d’usage peut avoir un modèle et un niveau de raisonnement optimaux différents. Nous recommandons de tester minutieusement pour vérifier une qualité constante sans dépassement de délai.

Contrôles de flux d’invocation

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

• Modèle propulsé par Braze : 5 000 invocations par minute
• Apport 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, de sorte que le traitement peut prendre plus de temps lors d’envois à fort volume.

Limites quotidiennes d’invocations et de crédits

Chaque agent dispose d’une limite d’invocations quotidienne (250 000 par défaut ; 1 000 000 maximum, sauf si votre contrat autorise davantage). Chaque invocation (y compris les aperçus de l’Agent Console et les exécutions de test Canvas utilisant Simulate response) est comptabilisée dans cette limite.

Dans l’Agent Console, la limite quotidienne de coût en crédits d’action estime le maximum 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 d’invocations quotidienne.

Quand les crédits sont consommés

Braze ne facture des crédits que pour les invocations qui achèvent leur traitement. Les crédits ne sont pas consommés lorsqu’une invocation échoue en raison :

• D’une erreur de limitation du débit du 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 d’invocations quotidienne

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

Surveiller l’utilisation des crédits

Accédez à Settings > Billing > Credits Usage > 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 proviennent de votre contrat et apparaissent sur le tableau de bord Credits Usage (onglet Credit Ratios et onglet Agent Console). L’estimation se met à jour lorsque vous modifiez le modèle ou la limite d’invocations.

Pour gérer les dépenses, réduisez la limite d’invocations quotidienne. Pour les modèles apportez votre propre clé (BYO), vous pouvez également choisir un modèle moins coûteux ou réduire le niveau de raisonnement pour diminuer les coûts en jetons du fournisseur. Braze Auto ne prend pas en charge l’ajustement du niveau de raisonnement.

Erreurs de limitation du débit

Si le fournisseur de LLM renvoie une erreur de limitation du débit lors d’une invocation d’agent d’étape Canvas ou d’agent de catalogue, 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.

Lorsque les nouvelles tentatives Canvas ou catalogue sont épuisées, le panneau de détails des Logs affiche Error et le message du fournisseur (tel que Rate limit exceeded) dans Output. Les nouvelles tentatives sont visibles dans les logs, y compris la toute première invocation, quel que soit son succès ou son échec final. Pour un utilisateur donné, s’il faut quatre nouvelles tentatives pour finalement obtenir un succès, vous pouvez rechercher l’ID utilisateur et voir les cinq (l’originale plus les quatre nouvelles tentatives) dans les Logs, et l’originale plus les trois premières nouvelles tentatives afficheront Error avec Rate limit exceeded.

Les erreurs de limitation du débit ne consomment pas de crédits Braze, y compris les nouvelles tentatives échouées affichées dans les Logs.

Instructions d’écriture

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

Si vous avez créé votre agent avec BrazeAI Operator en utilisant un modèle de départ, passez en revue les instructions préremplies et modifiez-les si nécessaire.

Voici quelques bonnes pratiques générales pour vous aider à démarrer avec le prompting :

1. Commencez par la fin. Énoncez d’abord l’objectif.
2. Donnez au modèle un rôle ou un persona (« Vous êtes un… »).
3. Définissez un contexte et des contraintes clairs (audience, longueur, ton, format).
4. Demandez une structure (« Retournez du JSON/une liste à puces/un tableau… »).
5. Montrez, ne dites pas. Incluez quelques exemples de haute qualité.
6. Décomposez les tâches complexes en étapes ordonnées (« Étape 1… Étape 2… »).
7. Encouragez le raisonnement (« Réfléchissez aux étapes en interne, puis fournissez une réponse finale concise » ou « expliquez brièvement votre décision »).
8. Testez, inspectez et itérez. De petits ajustements peuvent entraîner de grands gains de 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 ce qui fonctionne en interne pour la réutilisation et la mise à l’échelle.

Rédigez des instructions positives et explicites dans la mesure du possible. Dites à l’agent quoi faire et formulez les restrictions 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 les configurations de départ dans la console d’agent, consultez Modèles d’agents créés avec Operator.

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

Utiliser Liquid

L’inclusion de Liquid dans les instructions de votre agent peut ajouter un niveau supplémentaire de personnalisation à sa réponse. Vous pouvez spécifier la variable Liquid exacte que l’agent reçoit et l’inclure dans le contexte de votre prompt. Par exemple, au lieu d’écrire explicitement « prénom », vous pouvez utiliser l’extrait 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 Logs de la console d’agent, vous pouvez consulter les détails des entrées et sorties de l’agent pour comprendre quelle valeur est rendue à partir du Liquid.

Quelles données les agents reçoivent

Le contexte de l’agent n’est pas une mémoire conversationnelle ouverte. Contrairement à un assistant de chat, un agent ne voit que les données que vous lui transmettez explicitement au moment de l’invocation : il ne parcourt pas les profils utilisateurs, ne déduit pas les champs manquants et ne vous informe pas lorsque des informations requises sont absentes.

Concevez chaque agent comme un pipeline délibéré entrée-sortie. Connectez chaque point de donnée dont l’agent a besoin en utilisant une ou plusieurs des méthodes suivantes :

1. Liquid dans les instructions : Intégrez les attributs utilisateur ({{${first_name}}}) et les variables de contexte Canvas ({{context.${variable_name}}}) directement dans le prompt de l’agent.
2. + Contexte de l’agent : Sélectionnez des sources de connaissances, l’appartenance à un Segment, les directives de marque, All Canvas Context ou les données d’interaction utilisateur dans la console d’agent.
3. Étapes de contexte : Définissez ou mettez à jour les variables context.* en amont dans le Canvas avant l’exécution d’une étape Agent.
4. Contexte supplémentaire sur l’étape Agent : Transmettez toute valeur supplémentaire modélisée en Liquid non déjà spécifiée par les autres méthodes à l’agent au moment de l’envoi depuis la configuration de l’étape.

Assurez-vous soit d’intégrer ces variables de contexte en Liquid dans les instructions de l’agent, de joindre des fichiers de contexte que l’agent devrait consulter, ou de sélectionner Add All Canvas Context. Si une valeur n’est pas transmise par l’un de ces canaux, l’agent ne la reçoit pas. Listez les entrées requises dans vos instructions ou dans les prérequis du cas d’usage, et vérifiez les entrées dans Console d’agent > Logs après les tests.

Pour les Catalog Agents, utilisez Fields dans la section Output plutôt que le schéma JSON ; vous pouvez toujours rédiger des instructions qui demandent au modèle une sortie clé-valeur correspondant à ces noms de champs.

Pour plus de détails sur les bonnes pratiques de prompting, consultez les guides des fournisseurs de modèles suivants :

• OpenAI
• Anthropic
• Gemini

Sorties

Si vous avez créé votre agent avec BrazeAI Operator en utilisant un modèle de départ, examinez le schéma de sortie pré-rempli et modifiez-le si nécessaire.

Schémas de base

Les schémas de base sont 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 collecter les scores de satisfaction des utilisateurs à partir d’une enquête de retour d’expérience simple pour déterminer le degré de satisfaction de vos clients après réception d’un produit, vous pouvez sélectionner Number comme schéma de base pour structurer le format de sortie.

Important

Les tableaux sont uniquement disponibles pour les agents d’étape Canvas, pas pour les agents de catalogue.

Schémas avancés

Les options de schéma avancé incluent la structuration manuelle des champs ou l’utilisation de JSON.

• Fields : une méthode sans code pour imposer une sortie d’agent que vous pouvez utiliser de manière cohérente.
• JSON : une approche par 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 Canvas, pas pour les agents de catalogue.

Nous recommandons d’utiliser les 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. Cela permet à la sortie d’être mieux formatée en tant que variable de contexte cohérente.

Sortie de secours

Les valeurs de secours sont disponibles uniquement pour les agents d’étape Canvas. Dans la section Output de la console de l’agent pour un agent d’étape Canvas, vous pouvez définir des valeurs que Braze utilise lorsqu’une invocation échoue.

Pour les schémas JSON, Braze lit le schéma et génère un champ de saisie pour chaque propriété afin que vous puissiez définir une valeur de secours par clé. Pour les schémas Fields, 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 Canvas prennent en charge Liquid dans les valeurs de secours.

Pour les étapes de configuration, consultez Configurer les valeurs de secours. Pour le comportement à l’exécution dans Canvas, consultez Gestion des erreurs et comportement de secours.

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

• fields
• json schema

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 donner à un Canvas Step Agent l’accès aux données d’un catalogue, créez une source de connaissances à partir du catalogue et ajoutez-la comme + Agent context. L’agent interroge la source de connaissances pour récupérer les lignes correspondantes et n’envoie au LLM que les données de catalogue pertinentes, ce qui minimise la consommation de jetons et améliore la précision de la récupération. N’attachez pas le catalogue directement comme contexte d’agent. Les agents configurés avec l’ancienne option Add catalog fields avant la disponibilité des sources de connaissances peuvent continuer à utiliser ce contexte jusqu’à leur migration.

Lorsque vous déployez un Catalog Agent sur un champ de catalogue, activez le contrôle d’entrée obligatoire et choisissez quelles colonnes sélectionnées doivent être renseignées avant que l’agent ne 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 des colonnes qui peuvent être vides sans bloquer l’exécution. Cela évite de gaspiller des jetons sur des données incomplètes.

Les Catalog Agents respectent également l’ordre des colonnes lorsque les 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 les scénarios de déploiement et les 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 pourra consulter pour vérifier l’appartenance de chaque utilisateur lorsqu’il est utilisé dans un Canvas. Imaginons que votre agent dispose d’un accès à l’appartenance au Segment « Loyalty Users » et qu’il est utilisé dans un Canvas. Lorsque les utilisateurs entrent dans une étape Agent, l’agent peut vérifier si chaque utilisateur est membre de chacun des Segments que vous avez spécifiés dans la console de l’agent, et utiliser l’appartenance (ou la non-appartenance) de chaque utilisateur comme contexte pour le LLM.

Directives de marque

Vous pouvez sélectionner des directives de marque que votre agent doit respecter dans ses réponses. Par exemple, si vous souhaitez que votre agent génère un texte SMS pour encourager les utilisateurs à s’inscrire à un abonnement en salle de sport, vous pouvez utiliser ce champ pour faire référence à vos directives prédéfinies, audacieuses et motivantes.

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 côte à côte par rapport à 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 Agent Management en archivant les agents qui ne sont pas activement utilisés. Pour archiver un agent :

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