Skip to main content
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.
Lorsque vous créez vos outils, vous devez également garder à l’esprit un ensemble de bonnes pratiques pour garantir des performances de meilleure qualité.

Configuration du projet

Pour créer des outils, votre hsproject.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épertoire workflow-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

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.
Découvrez-en davantage sur chacune de ces meilleures pratiques dans les sections ci-dessous.
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éments actionName, 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 valeurs actionName, 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')"
Prenons un autre exemple, considérons les libellés de champs de saisie suivants destinés au contenu des publications sur les réseaux sociaux :
  • 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ête POST à 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.
Dernière modification le 10 février 2026