Configurer des Actions personnalisées et des outils OpenAPI dans Dust : transformer les assistants conversationnels en exécuteurs de flux de travail

Dans la majorité des entreprises, l'adoption de l'intelligence artificielle générative débute sous la forme d'un moteur de recherche documentaire. Les équipes opérationnelles connectent Notion, Google Drive ou des wikis internes afin que des assistants répondent aux questions des collaborateurs grâce à la génération augmentée par récupération (RAG). Cependant, la simple recherche documentaire passive montre rapidement ses limites lorsque les processus métier exigent des actions concrètes : mettre à jour un CRM, faire évoluer un statut de commande ou créer un ticket d'incident. Un assistant qui se contente d'expliquer comment modifier une fiche ou ouvrir un ticket Jira laisse l'intégralité de l'exécution à la charge de l'opérateur humain.

Dust comble ce fossé grâce à son architecture native d'outils et d'actions (Tools & Actions) articulée autour du protocole ouvert Model Context Protocol (MCP). En exposant des API REST décrites au format OpenAPI 3.0 et des intégrations SaaS sous forme d'outils interactifs, les équipes opérationnelles peuvent transformer leurs assistants conversationnels en véritables exécuteurs de flux de travail. Ce guide détaille la mise en œuvre d'actions sur mesure, le choix des modes d'authentification, la configuration des garde-fous de sécurité et l'orchestration de boucles d'automatisation fermées dans Dust.

Évolution architecturale : de la recherche passive à l'exécution active

Pour permettre à un assistant d'assumer le rôle d'exécuteur opérationnel, il est indispensable de comprendre comment Dust orchestre les interactions entre modèles de langage (LLM) et systèmes tiers :

+-----------------------------------------------------------------------------------+
|                                 Dust Workspace                                    |
|                                                                                   |
|   +-----------------------+              +------------------------------------+   |
|   | Invite utilisateur /  |              | Orchestrateur de l'assistant       |   |
|   | Déclencheur Webhook   | ---------->  | (LLM + Instructions système)       |   |
|   +-----------------------+              +-----------------+------------------+   |
|                                                            |                      |
|                                                            | Évaluation de l'intention
|                                                            v                      |
|                                          +------------------------------------+   |
|                                          | Appel d'outil & Injection protégée |   |
|                                          +-----------------+------------------+   |
+------------------------------------------------------------|----------------------+
                                                             |
                     +---------------------------------------+---------------------------------------+
                     |                                                                               |
                     v                                                                               v
    +---------------------------------+                                             +---------------------------------+
    | Outils intégrés natifs          |                                             | Serveur MCP distant / OpenAPI   |
    | (HubSpot, Jira, GitHub, Slack)  |                                             | (Microservices internes, APIs)  |
    +----------------+----------------+                                             +----------------+----------------+
                     |                                                                               |
                     | OAuth (Personnel ou Partagé)                                                  | Jeton Bearer / OAuth statique / mTLS
                     v                                                                               v
    +---------------------------------+                                             +---------------------------------+
    | Plateformes SaaS d'entreprise   |                                             | Systèmes centraux propriétaires |
    | (Affaires CRM, Tickets, Comms)  |                                             | (ERP, Facturation, Bases de données)
    +---------------------------------+                                             +---------------------------------+

Dans un schéma RAG classique, le modèle se limite à rechercher des fragments indexés pour formuler une synthèse. Dans une architecture d'exécution :

1. Exposition des schémas : Dust transmet au modèle la définition JSON Schema des actions autorisées (dérivée des spécifications OpenAPI ou MCP).
2. Analyse d'intention et extraction : Le LLM identifie la demande au fil du dialogue et extrait les paramètres nécessaires (identifiant d'affaire, priorité du ticket, description du bogue).
3. Injection de paramètres protégés : Dust combine les entrées du modèle avec des paramètres statiques préconfigurés (URL d'environnement, clé de projet) masqués au LLM, évitant ainsi toute hallucination sur des valeurs critiques.
4. Contrôle humain (Human-in-the-Loop) : Les actions modificatrices sensibles s'interrompent pour exiger la validation formelle d'un opérateur avant toute écriture.
5. Rétroaction d'état : La réponse de l'API distante est réinjectée dans le fil conversationnel, permettant à l'assistant de confirmer l'opération et de poursuivre le processus.

Étape 1 : Encapsuler des spécifications OpenAPI dans un serveur MCP personnalisé

Dust s'appuie nativement sur le Model Context Protocol (MCP). Lorsque vous disposez d'API REST internes documentées avec OpenAPI 3.0 (services d'approvisionnement, passerelles de facturation, microservices métier), la méthode standard consiste à déployer un serveur MCP léger servant d'adaptateur.

Définition d'outils avec le SDK TypeScript

À l'aide du SDK officiel TypeScript pour MCP et de la validation de schéma Zod, les ingénieurs définissent des actions fortement typées :

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { z } from "zod";

const server = new McpServer({
  name: "ops-workflow-engine",
  version: "1.0.0",
});

// Exposition d'un point de terminaison OpenAPI PATCH /crm/deals/{dealId}
server.tool(
  "update_crm_deal_stage",
  "Met à jour l'étape du pipeline commercial et la probabilité de clôture d'une opportunité CRM",
  {
    dealId: z.string().describe("Identifiant alphanumérique unique de l'opportunité"),
    newStage: z.enum(["Qualified", "Proposal", "Contract_Sent", "Closed_Won", "Closed_Lost"]).describe("Étape cible du pipeline"),
    closeNotes: z.string().optional().describe("Justification et remarques sur le changement d'étape"),
  },
  async ({ dealId, newStage, closeNotes }) => {
    const response = await fetch(`https://api.internal.company.com/v1/deals/${dealId}/stage`, {
      method: "PATCH",
      headers: {
        "Content-Type": "application/json",
        "Authorization": `Bearer ${process.env.INTERNAL_OPS_API_KEY}`,
      },
      body: JSON.stringify({ stage: newStage, notes: closeNotes }),
    });

    if (!response.ok) {
      return {
        content: [{ type: "text", text: `Erreur lors de la mise à jour : ${response.statusText}` }],
        isError: true,
      };
    }

    const data = await response.json();
    return {
      content: [{ type: "text", text: `L'opportunité ${dealId} a été mise à jour avec succès vers ${newStage}. ID d'enregistrement : ${data.id}` }],
    };
  }
);

Préconfiguration de paramètres statiques avec les schémas Dust

En production, des variables telles que le domaine de l'API, l'environnement (Recette/Production) ou les clés de projet ne doivent pas être laissées à l'appréciation du LLM pour éviter toute altération involontaire.

La bibliothèque @dust-tt/client permet de déclarer des schémas d'entrée préconfigurables. Ces valeurs sont renseignées par l'administrateur dans l'interface de Dust et restent totalement invisibles pour le modèle :

import { ConfigurableToolInputSchemas, INTERNAL_MIME_TYPES } from "@dust-tt/client";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { z } from "zod";

const server = new McpServer({
  name: "jira-dispatch-helper",
  version: "1.0.0",
});

server.tool(
  "create_ops_incident_ticket",
  "Crée un ticket d'incident prioritaire dans la file d'attente d'ingénierie",
  {
    // Extrait dynamiquement de la conversation par le modèle
    summary: z.string().describe("Résumé concis de l'incident"),
    description: z.string().describe("Description détaillée de l'anomalie et étapes de reproduction"),
    priority: z.enum(["P1", "P2", "P3"]).describe("Niveau de gravité de l'incident"),

    // Préconfiguré dans l'interface Dust ; masqué au LLM
    projectKey: ConfigurableToolInputSchemas[INTERNAL_MIME_TYPES.TOOL_INPUT.STRING],
    environment: ConfigurableToolInputSchemas[INTERNAL_MIME_TYPES.TOOL_INPUT.STRING],
  },
  async ({ summary, description, priority, projectKey, environment }) => {
    return callJiraBackend({ summary, description, priority, projectKey, environment });
  }
);

Étape 2 : Enregistrement des outils et gestion des identifiants dans Dust

Dès que le serveur MCP est accessible via une URL HTTPS publique, l'administrateur de l'espace de travail l'intègre dans Dust.

Procédure d'enregistrement

1. Dans Dust, accédez à Spaces > Tools.
2. Cliquez sur Add Tool.
3. Sélectionnez une intégration préexistante (Jira, HubSpot, Salesforce, GitHub) ou cliquez sur Add MCP Server pour raccorder une API sur mesure.
4. Saisissez l'URL publique de votre serveur MCP pour lancer la synchronisation.

Stratégie d'authentification : identifiants personnels vs partagés

Le modèle d'authentification retenu détermine la conformité et la traçabilité des opérations :

Configuration réseau et filtrage pare-feu

Pour interconnecter des services internes :

• Adresses IP de sortie fixes (Static Egress IPs) : Validez le domaine de votre entreprise dans Dust afin que les requêtes proviennent d'adresses IP statiques identifiées, facilitant leur autorisation dans vos pare-feux.
• URLs de rappel OAuth (Callbacks) : Configurez les points de terminaison de redirection adaptés à votre zone :
  • Espaces US : https://dust.tt/oauth/mcp_static/finalize
  • Espaces EU : https://eu.dust.tt/oauth/mcp_static/finalize
  • Passerelle globale : https://app.dust.tt/oauth/mcp_static/finalize

Étape 3 : Garde-fous opérationnels et validation humaine (Human-in-the-Loop)

Déléguer à des assistants la capacité de créer, modifier ou supprimer des données dans des systèmes de production nécessite des protections rigoureuses contre les erreurs d'interprétation et les injections d'instructions.

1. Qualification d'action à fort enjeu (High Stake)

Lorsqu'un outil dispose de droits d'écriture (mise à jour d'opportunités CRM, clôture de tickets, modification d'abonnements), l'administrateur peut le qualifier de HIGH STAKE.

• Comportement : L'assistant interrompt son exécution avant l'envoi de la requête et affiche une carte récapitulative listant l'ensemble des paramètres cibles.
• Validation obligatoire : La requête API n'est expédiée que lorsqu'un collaborateur habilité clique sur Approve.
• Contrôle programmatique via l'API : Dans le cadre d'automatisations via la Dust Conversation API, ces validations peuvent être acceptées ou rejetées via le point de terminaison POST /api/v1/w/{wId}/assistant/conversations/{cId}/messages/{mId}/validate-action.

2. Restriction des outils aux compétences (Restrict to Skills)

Dans Spaces > Tools, cochez l'option Restrict this tool to skills.

• L'outil est masqué de l'interface générale de création d'assistants, empêchant les utilisateurs de l'attacher à des bots informels.
• Il n'est accessible qu'à travers des « Compétences » (Skills) dédiées intégrant des consignes d'encadrement strictes.

3. Cloisonnement par espaces (Spaces)

Installez les outils d'écriture sensibles au sein d'espaces restreints (Restricted Spaces). Seuls les membres explicitement invités dans ces espaces pourront interagir avec les assistants dotés de ces capacités d'exécution.

Étape 4 : Structuration des instructions dans l'Agent Builder

L'efficacité et la fiabilité d'un exécuteur de flux de travail reposent sur la rigueur de ses instructions système (Instructions).

Piliers d'une directive de production

1. Périmètre et rôle opérationnel : Délimiter précisément la mission de l'assistant et ce qu'il lui est formellement interdit d'effectuer.
2. Protocole de vérification préalable : Imposer une lecture de l'état actuel avant toute opération d'écriture.
3. Règles d'extraction des paramètres : Définir clairement les correspondances de champs et les valeurs par défaut.
4. Gestion des incidents et remédiation : Formaliser les messages d'assistance en cas de jeton révoqué ou d'erreur serveur.

Exemple de configuration : Assistant d'escalade d'incidents et synchronisation CRM

# Rôle et responsabilités
Tu es l'agent d'assistance aux opérations techniques. Ta mission consiste à qualifier les anomalies signalées par les utilisateurs, à vérifier les informations contractuelles dans le CRM et à créer des tickets Jira conformes aux exigences de l'ingénierie.

# Protocoles d'utilisation des outils

## 1. Vérification du compte client (HubSpot)
- Avant d'ouvrir le moindre ticket, recherche le compte client avec `Get Object By Email` ou `Search Crm Objects`.
- Identifie le niveau d'assistance souscrit (Tier) et les affaires en cours.
- Si le client bénéficie d'une formule « Enterprise », rehausse automatiquement la priorité du ticket en P1.

## 2. Création de tickets Jira (Jira)
- Outil : `create_issue`
- Le titre (summary) ne doit pas dépasser 60 caractères et respecter le format : `[NomModule] Description concise de l'incident`.
- La description (description) doit obligatoirement comporter trois sections :
  1. Contexte du compte (Entreprise, contact, niveau de support)
  2. Anomalie observée et messages d'erreur
  3. Étapes de reproduction et liens vers les journaux
- Le type de ticket doit être configuré sur "Bug" et le composant sur "Production-Ops".

## 3. Sécurité et traitement des erreurs
- Toute modification d'étape sur une opportunité active ou toute clôture de ticket doit être préalablement soumise à confirmation visuelle auprès de l'opérateur.
- Si un outil renvoie une erreur d'authentification 401, invite l'utilisateur : « Veuillez ouvrir le menu utilisateur en haut à droite sous 'Tools & Triggers' pour reconnecter vos identifiants personnels Jira ou HubSpot ».

Étape 5 : Automatisation sans saisie manuelle via les déclencheurs Webhook

Au-delà des échanges dans la fenêtre de discussion, les assistants peuvent être déclenchés par des événements système grâce aux déclencheurs Webhook (Webhook Triggers) de Dust.

+--------------------------+          Événement HTTP POST       +-----------------------------+
| Système émetteur         | ---------------------------------> | Source Webhook Dust         |
| (Jira, GitHub, Zendesk,  |                                    | (Spaces > Triggers)         |
| supervision interne)     |                                    +--------------+--------------+
+--------------------------+                                                   |
                                                                               | Vérification de signature & charge
                                                                               v
+--------------------------+          Appel d'action cible      +-----------------------------+
| Système destinataire     | <--------------------------------- | Exécution de l'assistant    |
| (Mise à jour CRM /       |                                    | (Analyse l'événement,       |
| Notification Slack)      |                                    | filtre et appelle l'outil)  |
+--------------------------+                                    +-----------------------------+

Mise en place de la chaîne d'automatisation

1. Création de la source Webhook (Administrateur) :
   • Rendez-vous dans Spaces > Triggers et cliquez sur Add source.
   • Choisissez un connecteur standard (Jira, GitHub, Linear, Zendesk) ou sélectionnez Custom webhook.
   • Pour les webhooks sur mesure, activez le contrôle de signature HMAC (sha256) pour rejeter toute requête non authentifiée.
2. Association du déclencheur à l'assistant :
   • Dans l'Agent Builder, ouvrez Triggers > Add triggers et sélectionnez la source créée.
   • Formulez les conditions en langage naturel (ex. : « Exécuter uniquement si la priorité est High et que le statut passe à Escalated »).
   • Cochez Include webhook payload afin que l'ensemble des données JSON de l'événement soit transmis au modèle.
   • Précisez la consigne d'exécution (ex. : « Analyse le journal d'erreur présent dans la charge utile, consulte la base de connaissances et poste un commentaire de recommandation technique dans le ticket Jira correspondant »).
   • Configurez des plafonds d'appels sur 24 heures (Rate Limits) pour éviter une consommation excessive de crédits lors de rafales d'événements.

Synthèse comparative des approches d'intégration

Selon vos impératifs techniques et organisationnels, plusieurs options d'intégration s'offrent à vous :

Liste de contrôle avant déploiement en production

Avant de livrer un assistant exécuteur de flux de travail aux équipes opérationnelles, contrôlez les points suivants :

• Mode d'identifiant approprié : Les outils d'écriture sont-ils configurés en identifiants personnels pour assurer la traçabilité des audits, ou le compte partagé applique-t-il les moindres privilèges ?
• Protection High Stake active : Toutes les actions modifiant ou supprimant des données opérationnelles déclenchent-elles une demande de confirmation humaine ?
• Paramètres statiques sanctuarisés : Les URL de services et les identifiants techniques sont-ils verrouillés avec ConfigurableToolInputSchemas pour éviter les hallucinations ?
• Consignes de reprise sur erreur : Les directives expliquent-elles clairement comment orienter l'utilisateur en cas de défaillance réseau ou d'expiration de session ?
• Règles réseau autorisées : Les adresses IP statiques de Dust sont-elles autorisées dans les pare-feux protégeant vos serveurs MCP internes ?
• Plafonnement des déclencheurs : Les webhooks automatisés disposent-ils de limites de requêtes sur 24 heures pour prévenir tout emballement imprévu ?

En couplant les spécifications OpenAPI, la flexibilité du protocole MCP et une gouvernance stricte des habilitations dans Dust, les équipes opérationnelles dotent leur organisation d'assistants autonomes et fiables, capables d'exécuter leurs processus de bout en bout.

Références

• Adding an MCP Server
• Personal vs Shared Credentials for Tools & MCP Servers
• Jira
• HubSpot
• Webhooks
• OpenAPI & Postman
• Dev : pre-configuring a custom MCP server
• Validate an action in a conversation message
• Multiplayer AI Documentation Index