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.
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.
├──src
   ├── hsproject.json
   ├── app/
   └── app-hsmeta.json
   └── ...
   └── workflow-actions/
     └── agent-tool-action-hsmeta.json
└──

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.
{
  "uid": "agent_tool_action",
  "type": "workflow-action",
  "config": {
    "actionUrl": "https://example.com",
    "toolType": "GET_DATA",
    "llmDescription": "A description that helps the LLM understand what this tool does.",
    "isPublished": false,
    "supportedClients": [
      {
        "client": "AGENTS"
      },
      {
        "client": "WORKFLOWS"
      }
    ],
    "inputFields": [
      {
        "typeDefinition": {
          "name": "message",
          "type": "string",
          "fieldType": "textarea"
        },
        "supportedValueTypes": ["STATIC_VALUE"],
        "isRequired": true
      },
      {
        "typeDefinition": {
          "name": "priority",
          "type": "enumeration",
          "fieldType": "select",
          "options": [
            {
              "value": "high",
              "label": "High Priority"
            },
            {
              "value": "normal",
              "label": "Normal Priority"
            },
            {
              "value": "low",
              "label": "Low Priority"
            }
          ]
        },
        "supportedValueTypes": ["STATIC_VALUE"],
        "isRequired": true
      }
    ],
    "labels": {
      "en": {
        "actionName": "My custom agent tool",
        "actionDescription": "A description of the tool.",
        "actionCardContent": "Send {{priority}} priority notification",
        "inputFieldLabels": {
          "message": "Notification Message",
          "priority": "Priority Level"
        },
        "inputFieldDescriptions": {
          "message": "Enter the message to be sent in the notification",
          "priority": "Select the priority level for this notification"
        }
      }
    },
    "objectTypes": ["CONTACT"]
  }
}

Les champs marqués par * sont requis

ChampTypeDescription
uid*Chaîneun identifiant unique interne pour l’action de workflow.
type*Chaînele type de composant, qui devrait être workflow-action dans ce cas.
actionUrl*Chaînel’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*Stringla catégorie de fonctionnalité de l’outil. Peut être l’un des éléments suivants :
  • GET_DATA : récupère des informations depuis HubSpot ou des sources externes.
  • GENERATE : génère du contenu, des résumés, des analyses ou des suggestions basés sur les données saisies.
  • TAKE_ACTION : effectue des actions CRM, telles que la création de notes ou l’attribution de tâches aux propriétaires.
llmDescription*Chaîneune description qui aide le modèle de langage exhaustif à comprendre les fonctionnalités de l’outil.
isPublishedBooléendé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*Tableauun 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 :
  • WORKFLOWS : active l’action pour les workflows.
  • AGENTS : active l’action pour les agents.
inputFieldsTableaules valeurs pour les saisies que l’utilisateur a renseignées. Découvrez-en davantage sur les meilleures pratiques relatives à la quantité de champ.
typeDefinition.nameChaînele nom ou la clé du champ de saisie.
typeDefinition.typeChaînele type de valeur que le champ de saisie doit attendre.
typeDefinition.fieldTypeChaînele type de champ qui apparaît aux utilisateurs qui créent le workflow.
typeDefinition.optionsTableaupour 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.
inputFieldDependenciesTableauune 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îneclé 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>.inputFieldDescriptionsObjetun 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>.inputFieldOptionLabelsObjetun 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>.outputFieldLabelsObjetun objet qui mappe les définitions de outputFields vers les libellés correspondants qui apparaissent dans l’outil workflows.
labels.<locale>.actionName*Chaînele 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înele 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>.actionCardContentChaîneune description récapitulative affichée dans la carte de l’action.
labels.<locale>.executionRulesObjetun 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.
objectTypesTableaules 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.
outputFieldsTableaules 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.
executionRulesObjetune 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.
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.