- Ajout d’un composant d’action de workflow à une application en incluant une
workflow-actionsrépertoire dans le projet, ainsi qu’un fichier de configuration*-hsmeta.jsonpour 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
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é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.
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.