Dernière modification : 11 septembre 2025
Les agents HubSpot sont des assistants basés sur l’IA avec lesquels les utilisateurs peuvent discuter pour effectuer des tâches. Chaque agent comprend une série d’actions, appelées outils, qu’il utilisera selon les instructions de l’utilisateur. En tant que développeur, vous pouvez créer des outils d’agent personnalisés pour effectuer des tâches spécifiques et bien définies en fonction du cas d’utilisation prévu de l’agent.
En arrière-plan, les outils sont des actions de workflow personnalisées configurées pour être disponibles dans le contexte de l’agent. Les outils peuvent être utilisés par plusieurs agents et peuvent être configurés pour fonctionner à la fois avec des agents et des workflows.
À un niveau élevé, la création d’un outil d’agent consiste à :
- Ajout d’un composant d’action de workflow à une application en incluant une
workflow-actions
répertoire dans le projet, ainsi qu’un fichier de configuration*-hsmeta.json
pour l’outil. Chaque outil et chaque action de workflow que vous créez doit avoir son propre fichier de configuration*-hsmeta.json
. - Configuration de l’action pour qu’elle soit disponible dans les agents IA via le champ
supportedClients
.
Configuration du projet
Pour créer des outils, votrehsproject.json
doit avoir sa platformVersion
définie sur 2025.2
. Cette version est définie automatiquement sur tous les modèles de démarrage rapide, mais devra être mise à jour manuellement pour les projets avec des versions antérieures.
Notez que, lors de la mise à niveau d’un projet vers une version 2025.2
, vous devrez respecter les nouvelles normes de fichier de configuration *-hsmeta.json
pour la configuration de votre application et ses fonctionnalités.
Les outils d’agent et les actions de workflow personnalisées sont tous deux contenus dans le répertoire de l’application workflow-actions
.
Définition de l’outil agent
Le fichier de configuration de vos outils doit être placé dans le répertoireworkflow-actions
pour fonctionner. Les options de configuration pour les outils d’agent sont les mêmes que pour les actions de workflow personnalisées, avec la condition supplémentaire que le champ supportedClients
doit inclure le client AGENTS
.
Les champs marqués par * sont requis
Champ | Type | Description |
---|---|---|
uid * | Chaîne | un identifiant unique interne pour l’action de workflow. |
type * | Chaîne | le type de composant, qui devrait être workflow-action dans ce cas. |
actionUrl * | Chaîne | l’URL à laquelle l’outil fera une requête POST . L’URL doit être un point de terminaison accessible au public et ne peut pas être une fonction sans serveur définie dans le projet de développement. |
toolType * | String | la catégorie de fonctionnalité de l’outil. Peut être l’un des éléments suivants :
|
llmDescription * | Chaîne | une description qui aide le modèle de langage exhaustif à comprendre les fonctionnalités de l’outil. |
isPublished | Booléen | détermine si la définition est visible dans les comptes qui ont installé votre application. Par défaut, cette valeur est définie sur false . |
supportedClients * | Tableau | un tableau d’objets spécifiant les clients pris en charge par l’action de workflow personnalisée. Chaque objet du tableau doit avoir une clé client avec une valeur de chaîne indiquant le type de client. Les valeurs comprennent :
|
inputFields | Tableau | les valeurs pour les saisies que l’utilisateur a renseignées. Découvrez-en davantage sur les meilleures pratiques relatives à la quantité de champ. |
typeDefinition.name | Chaîne | le nom ou la clé du champ de saisie. |
typeDefinition.type | Chaîne | le type de valeur que le champ de saisie doit attendre. |
typeDefinition.fieldType | Chaîne | le type de champ qui apparaît aux utilisateurs qui créent le workflow. |
typeDefinition.options | Tableau | pour les types d’énumération, ce champ fournit une liste d’options. Chaque option doit comporter une value , en fonction de l’entrée fournie par l’utilisateur, et un label , qui identifie l’option dans l’outil workflows. |
inputFieldDependencies | Tableau | une liste de règles qui définissent les relations entre deux entrées ou plus, en fonction de leur dependencyType . Découvrez-en davantage dans l’exemple ici. |
labels.<locale> * | Chaîne | clé de paramètres régionaux qui correspond à la définition des paramètres régionaux. Un libellé anglais (en ) et sa définition doivent être définis au minimum. |
labels.<locale>.inputFieldDescriptions | Objet | un objet qui définit les détails des entrées de votre action. Dans l’exemple ci-dessus, cet objet comprend les champs message et priority . |
labels.<locale>.inputFieldOptionLabels | Objet | un objet requis si votre ou vos champs de saisie disposent d’options. Fournit une carte des libellés d’options de champs de saisie, saisis par la valeur ou le libellé de l’option. |
labels.<locale>.outputFieldLabels | Objet | un objet qui mappe les définitions de outputFields vers les libellés correspondants qui apparaissent dans l’outil workflows. |
labels.<locale>.actionName * | Chaîne | le nom de l’action tel qu’il apparaît dans le panneau Sélectionner une action de l’éditeur de workflows. |
labels.<locale>.appDisplayName * | Chaîne | le nom de la section du panneau Sélectionner une action où toutes les actions de l’application apparaissent. Si appDisplayName est défini pour plusieurs actions, la première trouvée sera utilisée. |
labels.<locale>.actionCardContent | Chaîne | une description récapitulative affichée dans la carte de l’action. |
labels.<locale>.executionRules | Objet | un objet qui regroupe les définitions de votre executionRules vers les messages qui apparaîtront pour les résultats d’exécution dans l’historique du workflow. |
objectTypes | Tableau | les types d’objets CRM disponibles avec lesquels cette action peut être utilisée. Si vide, l’action sera disponible pour tous les types d’objets. |
outputFields | Tableau | les valeurs résultantes de l’action qui peuvent être utilisées par des actions suivantes dans l’agent ou le workflow. Une action personnalisée peut avoir 0, 1 ou plusieurs résultats. |
executionRules | Objet | une liste des définitions que vous pouvez indiquer pour identifier les erreurs de votre service vers l’utilisateur qui crée le workflow. |
Meilleures pratiques
Lors de la création d’outils pour les agents, gardez à l’esprit la check-list des meilleures pratiques suivante :- Commencez par des champs facultatifs, puis définissez comme requis uniquement si stable.
- Libellez et décrivez les champs pour les humains et l’IA.
- Effectuez des tests avec moins d’instructions d’agent au début pour comprendre comment l’IA interprète un outil.
- Gardez les outils concentrés et faites attention à la quantité de champs.
- Utilisez les descriptions de champs pour contrôler la créativité des agents.
Remarque :Bien que certaines des recommandations ci-dessous incluent des informations sur les outils de test des agents, ces fonctionnalités de test sont encore en cours de développement. La documentation relative aux outils d’agent sera mise à jour dès que des méthodes de test seront disponibles.
Développer avec des champs facultatifs
Ne définissez pas les champs d’action (inputFields
) requis pendant le développement actif. Une fois qu’un champ a été défini comme requis et que le projet est chargé, vous ne pouvez plus le supprimer ou le mettre à jour. Vous ne devez définir un champ comme requis que lorsque vous avez confiance dans les détails du champ, tels que son name
et son type
. La raison de cette limitation est que la modification de champs requis interromprait tous les workflows actifs qui incluent l’action.
Concevoir pour une compréhension humaine et IA
Les élémentsactionName
, inputFields
et labels
doivent clairement communiquer leur utilisation et leur utilité aux humains et à l’agent. Ces champs sont notamment utilisés par l’agent pour comprendre quand appeler l’action et comment transmettre des données à l’outil. Lorsque vous créez vos outils, gardez à l’esprit que les modèles de langage exhaustifs peuvent avoir besoin de descriptions plus explicites que les utilisateurs humains. Par exemple, alors qu’une personne comprendra intuitivement un champ intitulé Date
, un modèle de langage exhaustif pourrait préférer Event start date (YYYY-MM-DD)
.
Idéalement, les outils doivent être conçus de manière à ce que les agents ne nécessitent pas d’instructions supplémentaires pour les utiliser. Cependant, dans certains cas, les détails du champ seuls peuvent ne pas être suffisants pour l’agent. Par exemple, il peut ne pas comprendre l’ordre prévu pour exécuter des outils qui dépendent des résultats d’autres outils (par exemple, un outil « Envoyer un e-mail » peut dépendre d’un outil « Obtenir les informations de contact » exécuté en premier).
Lorsque vous créez un outil, vous devez le tester dans l’agent sans ajouter d’informations à ses instructions au préalable pour mieux comprendre comment il interprète l’outil. Grâce aux tests, vous serez en mesure de déterminer si le moteur de raisonnement fonctionne correctement par lui-même ou s’il a besoin d’instructions supplémentaires.
Veillez au nombre de champs de saisie
Les agents peuvent gérer un grand nombre de champs de saisie dans chaque outil (26 saisies uniques maximum). Cependant, plus il y a de champs de saisie dans un outil, plus vous devez être clair lors de l’attribution des valeursactionName
, inputField
et label
. Les outils sont plus efficaces et fiables lorsqu’ils sont conçus pour des tâches spécifiques avec un ensemble de paramètres précis. Pour les opérations complexes, demandez-vous s’il serait plus efficace de créer plusieurs outils simples plutôt qu’un seul outil avec un nombre excessif d’entrées.
Remarque :Il est possible que HubSpot limite le nombre de saisies à l’avenir en fonction du feedback concernant la qualité des agents traitant un grand nombre de saisies.
Créativité et improvisation de l’agent de contrôle
Dans certains cas, vous souhaiterez peut-être qu’un agent soit créatif et improvise. Cependant, il peut y avoir des scénarios où vous ne souhaitez pas que l’agent improvise. Expérimentez avec les instructions du modèle de langage exhaustif dans les noms, libellés et descriptions de vos champs de saisie. Si vous avez besoin de conseils plus stricts, ajoutez des instructions à l’agent pour définir des attentes claires. Par exemple, supposons que vous confiez à un agent la tâche de générer un article de blog, l’un des champs étant le titre de l’article de blog. Selon le degré d’improvisation de l’agent, vous pouvez libeller le champ de manière permissive ou plus restrictive :- Permissif :
"Blog title"
- Restrictif :
"Blog title (must include the product name 'HubSpot CRM')"
- Permissif :
"Social post content"
- Modéré :
"Social post content (keep under 280 characters)"
- Restrictif :
"Social post content (must mention our Q4 sale, include #HubSpot, and stay under 280 characters)"
Vérification de l’origine de la requête de l’outil d’agent
Lorsqu’un agent utilise un outil pour faire une demande, il fait une requêtePOST
à l’actionUrl
de l’outil. L’appel de l’outil d’agent est authentifié par la validation de l’en-tête X-HubSpot-Signature
envoyé avec la demande. Il s’agit du même système que HubSpot utilise pour valider les demandes webhook.
Remarque :Vous ne devez pas créer de champs de saisie pour les secrets ou les clés d’API, car cela n’est pas sécurisé et ne correspond pas au modèle d’authentification prévu, notamment parce que le modèle de langage exhaustif devrait recevoir le secret/la clé d’API dans ses instructions ou la recevoir d’un autre outil.