Configuración de Custom Actions y Herramientas OpenAPI en Dust: De Asistentes Conversacionales a Ejecutores de Flujos de Trabajo

La mayoría de los proyectos empresariales de inteligencia artificial generativa comienzan como asistentes de búsqueda documental. Los equipos de operaciones conectan Notion, Google Drive o wikis internas para que los agentes respondan consultas corporativas mediante generación aumentada por recuperación (RAG). Sin embargo, la recuperación pasiva muestra limitaciones evidentes cuando los flujos de trabajo operativos requieren modificar registros, actualizar estados en sistemas CRM o escalar incidencias. Un asistente que únicamente describe cómo registrar un ticket en Jira o cómo cerrar una oportunidad comercial deja la ejecución práctica en manos del operador humano.

Dust supera esta barrera gracias a su arquitectura nativa de herramientas y acciones (Tools & Actions) y su compatibilidad con el estándar abierto Model Context Protocol (MCP). Al encapsular endpoints REST definidos con OpenAPI 3.0 e integraciones SaaS en forma de herramientas interactivas, los equipos de operaciones pueden transformar sus asistentes conversacionales en ejecutores activos de flujos de trabajo. Esta guía detalla cómo configurar acciones personalizadas, gobernar los modelos de autenticación, aplicar salvaguardas de seguridad e implementar automatizaciones bidireccionales en Dust.

Evolución Arquitectónica: De la Recuperación Pasiva a la Ejecución Activa

Para que un asistente asuma el rol de ejecutor de procesos, es fundamental comprender cómo orquesta Dust las llamadas a herramientas externas:

+-----------------------------------------------------------------------------------+
|                                 Dust Workspace                                    |
|                                                                                   |
|   +-----------------------+              +------------------------------------+   |
|   | Entrada de Usuario /  |              | Orquestador del Asistente          |   |
|   | Disparador Webhook    | ---------->  | (LLM + Instrucciones de Sistema)   |   |
|   +-----------------------+              +-----------------+------------------+   |
|                                                            |                      |
|                                                            | Evaluación de intención
|                                                            v                      |
|                                          +------------------------------------+   |
|                                          | Llamada a Tool e Inyección Segura  |   |
|                                          +-----------------+------------------+   |
+------------------------------------------------------------|----------------------+
                                                             |
                     +---------------------------------------+---------------------------------------+
                     |                                                                               |
                     v                                                                               v
    +---------------------------------+                                             +---------------------------------+
    | Herramientas Nativas (Built-in) |                                             | Servidor MCP Remoto / OpenAPI   |
    | (HubSpot, Jira, GitHub, Slack)  |                                             | (Microservicios internos, APIs) |
    +----------------+----------------+                                             +----------------+----------------+
                     |                                                                               |
                     | OAuth (Personal o Compartido)                                                 | Bearer Token / OAuth Estático / mTLS
                     v                                                                               v
    +---------------------------------+                                             +---------------------------------+
    | Plataformas SaaS Empresariales  |                                             | Sistemas Centrales Propietarios |
    | (Oportunidades CRM, Incidencias)|                                             | (ERP, Facturación, Bases de Datos)
    +---------------------------------+                                             +---------------------------------+

En un sistema RAG tradicional, el LLM busca fragmentos en fuentes de datos y sintetiza una respuesta. En la ejecución con herramientas:

1. Publicación del Esquema: Dust expone al LLM los esquemas JSON de las acciones disponibles (derivados de OpenAPI o especificaciones MCP).
2. Interpretación de Intención y Extracción de Argumentos: El modelo analiza la conversación y extrae los parámetros necesarios (por ejemplo, ID de oportunidad, prioridad del ticket o notas de cierre).
3. Inyección de Parámetros Protegidos: Dust inyecta variables estáticas preconfiguradas (como URLs de entorno o identificadores de inquilino) que se mantienen ocultas para el LLM, eliminando alucinaciones en campos críticos.
4. Validación con Supervisión Humana (Human-in-the-Loop): Las acciones que modifican datos críticos se pausan para requerir confirmación explícita del usuario antes de ejecutar la mutación externa.
5. Retroalimentación de Estado: La respuesta de la API remota se reincorpora al contexto conversacional, permitiendo al asistente confirmar la ejecución y continuar el flujo de trabajo.

Paso 1: Empaquetar Especificaciones OpenAPI en Servidores MCP Personalizados

Dust utiliza de forma nativa el Model Context Protocol (MCP). Para integrar APIs REST corporativas documentadas con OpenAPI 3.0 (microservicios internos, plataformas de aprovisionamiento o pasarelas de datos), el enfoque estándar consiste en desplegar un servidor MCP que actúe como puente.

Definición Estándar de Herramientas con el SDK de TypeScript

Utilizando el SDK oficial de TypeScript para MCP y validaciones con Zod, los desarrolladores pueden definir acciones estructuradas:

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

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

// Exponiendo un endpoint OpenAPI PATCH /crm/deals/{dealId} como herramienta ejecutable
server.tool(
  "update_crm_deal_stage",
  "Actualiza la etapa del embudo comercial y la probabilidad de cierre de una oportunidad en el CRM",
  {
    dealId: z.string().describe("Identificador alfanumérico único de la oportunidad"),
    newStage: z.enum(["Qualified", "Proposal", "Contract_Sent", "Closed_Won", "Closed_Lost"]).describe("Etapa destino del embudo"),
    closeNotes: z.string().optional().describe("Justificación y notas sobre el cambio de fase"),
  },
  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: `Error al actualizar la oportunidad: ${response.statusText}` }],
        isError: true,
      };
    }

    const data = await response.json();
    return {
      content: [{ type: "text", text: `Oportunidad ${dealId} actualizada con éxito a la etapa ${newStage}. ID de registro: ${data.id}` }],
    };
  }
);

Preconfiguración de Parámetros con Esquemas de Dust

En entornos de producción, variables como el entorno de destino (Staging vs. Producción), las claves de proyecto o los identificadores de cliente deben permanecer estáticos y no deben ser generados por el LLM.

El paquete @dust-tt/client permite declarar campos preconfigurables en la definición de la herramienta. Estos valores son introducidos por los administradores en el panel de Dust y permanecen completamente ocultos para el modelo:

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",
  "Crea un ticket de incidencia de alta prioridad en la cola técnica designada",
  {
    // Parámetros extraídos dinámicamente por el LLM a partir del diálogo
    summary: z.string().describe("Resumen conciso del incidente"),
    description: z.string().describe("Descripción detallada del fallo y pasos para reproducirlo"),
    priority: z.enum(["P1", "P2", "P3"]).describe("Nivel de criticidad del incidente"),

    // Parámetros fijados estáticamente en la UI de Dust; invisibles para el modelo
    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 });
  }
);

Paso 2: Registro de Herramientas y Gestión de Credenciales en Dust

Una vez que el servidor MCP remoto o la integración SaaS está disponible, el administrador del espacio de trabajo la configura en Dust.

Procedimiento de Registro

1. En la consola de Dust, acceda a Spaces > Tools.
2. Haga clic en Add Tool.
3. Seleccione una integración comercial nativa (Jira, HubSpot, Salesforce, GitHub) o pulse Add MCP Server para registrar una API personalizada.
4. Indique la URL pública HTTPS de su servidor MCP para completar la sincronización inicial.

Estrategia de Autenticación: Credenciales Personales vs. Compartidas

La elección del modelo de credenciales define la rendición de cuentas, el control de acceso y el cumplimiento normativo:

Configuración de Red y Reglas de Cortafuegos

Al conectar servicios internos:

• IPs Estáticas de Salida (Static Egress IPs): Verifique el dominio corporativo en Dust para habilitar el enrutamiento de peticiones a través de las IPs de salida estáticas de Dust, permitiendo crear reglas estrictas en su cortafuegos.
• URLs de Retorno OAuth (Callbacks): Registre las direcciones de redirección correspondientes en su servidor de autorización:
  • Espacios en EE. UU.: https://dust.tt/oauth/mcp_static/finalize
  • Espacios en Europa: https://eu.dust.tt/oauth/mcp_static/finalize
  • Puerta de enlace global: https://app.dust.tt/oauth/mcp_static/finalize

Paso 3: Salvaguardas Operativas y Supervisión Humana (Human-in-the-Loop)

Otorgar a un agente la capacidad de crear, actualizar o eliminar registros en sistemas críticos exige medidas de mitigación contra inyecciones de prompts o errores de interpretación.

1. Etiquetado de Herramientas Críticas (High Stake)

Al configurar herramientas con impacto destructivo o de escritura (modificar acuerdos comerciales, alterar tickets o borrar registros), los administradores deben marcarlas como HIGH STAKE.

• Comportamiento: El asistente detiene la ejecución automática y despliega una ventana de confirmación en el chat con los parámetros exactos de la petición.
• Aprobación Obligatoria: La llamada a la API solo se realiza cuando un operador autorizado pulsa Approve.
• Validación vía API: En integraciones programáticas a través de la API de Dust, estas acciones se autorizan o rechazan mediante el endpoint POST /api/v1/w/{wId}/assistant/conversations/{cId}/messages/{mId}/validate-action.

2. Restricción de Herramientas a Skills (Restrict to Skills)

En Spaces > Tools, active la opción Restrict this tool to skills.

• La herramienta queda oculta del creador general de agentes, evitando que los usuarios finales la vinculen a asistentes de uso casual.
• Solo puede invocarse a través de "Skills" específicos que empaquetan directrices de seguridad y validaciones previas.

3. Aislamiento por Espacios (Spaces)

Aloje las herramientas con permisos de escritura en espacios restringidos (Restricted Spaces). De este modo, únicamente los miembros autorizados de dicho espacio podrán interactuar con los asistentes que dispongan de esas capacidades.

Paso 4: Diseño de Instrucciones en el Agent Builder

Para garantizar una ejecución determinista, las directrices del asistente (Instructions) deben estructurarse con precisión técnica.

Componentes Fundamentales de un Prompt Operativo

1. Definición de Rol y Fronteras Operativas: Delimitar las responsabilidades y prohibiciones expresas del asistente.
2. Protocolo de Validación Previa: Exigir la consulta previa del estado de los registros antes de ejecutar mutaciones.
3. Reglas de Mapeo de Parámetros: Especificar los criterios de extracción, tipos de datos y formatos obligatorios.
4. Tratamiento de Errores y Recuperación: Definir el mensaje de respuesta ante fallos de autenticación o respuestas HTTP erróneas.

Ejemplo de Configuración: Asistente de Escalado y Sincronización CRM

# Rol y Responsabilidades
Eres el Agente de Escalado Operativo y Soporte Técnico. Tu función es analizar incidencias comunicadas por usuarios, contrastar la información con los contratos en el CRM y crear tickets técnicos en Jira.

# Protocolos de Ejecución de Herramientas

## 1. Verificación del Cliente en CRM (HubSpot)
- Antes de registrar cualquier ticket, busca la cuenta mediante `Get Object By Email` o `Search Crm Objects`.
- Recupera el nivel de soporte contratado (Tier) y el estado de los acuerdos comerciales activos.
- Si la cuenta dispone de soporte "Enterprise", incrementa automáticamente la severidad de la incidencia a P1.

## 2. Creación de Incidencias en Jira (Jira)
- Herramienta: `create_issue`
- El campo summary debe resumir el problema en menos de 60 caracteres siguiendo el formato: `[Módulo] Breve descripción del fallo`.
- El campo description debe estructurarse obligatoriamente en tres apartados:
  1. Contexto de la Cuenta (Nombre de la empresa, contacto, nivel de soporte)
  2. Fallo Detectado y Mensajes de Error
  3. Pasos de Reproducción y Enlaces a Logs
- Asigna siempre el tipo de incidencia "Bug" y el componente "Production-Ops".

## 3. Confirmación de Seguridad y Errores
- Si una acción va a modificar el estado de una oportunidad comercial o cerrar un ticket, muestra los parámetros al usuario y solicita confirmación explícita.
- Si una herramienta devuelve un error 401 de autenticación, instruye al operador: "Por favor, accede a Tools & Triggers desde el menú de usuario para reconectar tus credenciales personales de Jira o HubSpot".

Paso 5: Automatización Desatendida con Disparadores Webhook

Para alcanzar una automatización completa sin intervención humana en el chat, los equipos de operaciones combinan las herramientas con Disparadores Webhook (Webhook Triggers).

+--------------------------+          Petición HTTP POST        +-----------------------------+
| Sistema Externo          | ---------------------------------> | Origen Webhook de Dust      |
| (Jira, GitHub, Zendesk,  |                                    | (Spaces > Triggers)         |
| Monitorización interna)  |                                    +--------------+--------------+
+--------------------------+                                                   |
                                                                               | Verificación de Firma y Carga Útil
                                                                               v
+--------------------------+          Ejecuta Acción en Destino +-----------------------------+
| Destino Remoto           | <--------------------------------- | Ejecución del Agente Dust   |
| (Actualiza CRM /         |                                    | (Analiza evento, aplica     |
| Alerta en Slack)         |                                    | filtros y llama al tool)    |
+--------------------------+                                    +-----------------------------+

Configuración del Flujo Webhook

1. Crear el Origen Webhook (Administrador):
   • Diríjase a Spaces > Triggers y pulse Add source.
   • Seleccione un proveedor nativo (Jira, GitHub, Zendesk, Linear) o elija Custom webhook.
   • Para webhooks personalizados, habilite la validación de firmas mediante cabecera HMAC (sha256) para rechazar peticiones ilegítimas.
2. Vincular el Disparador al Agente:
   • En el Agent Builder, acceda a Triggers > Add triggers y asocie el origen configurado.
   • Defina la condición de ejecución en lenguaje natural (por ejemplo: "Ejecutar únicamente cuando la prioridad del ticket sea High y el estado cambie a Escalated").
   • Marque Include webhook payload para que el contenido JSON del evento esté disponible en el contexto del modelo.
   • Configure el mensaje de activación (por ejemplo: "Analiza el error recibido, busca la solución en la base de conocimientos y añade un comentario con recomendaciones en el ticket de Jira correspondiente").
   • Establezca límites de frecuencia (Rate Limits) en periodos de 24 horas para prevenir sobrecostos de créditos derivados de ráfagas de eventos.

Comparativa de Alternativas de Integración

Dependiendo de los requisitos técnicos y la gobernanza corporativa, los equipos pueden optar por diferentes enfoques:

Lista de Comprobación para Puesta en Producción

Antes de desplegar asistentes ejecutores en entornos operativos reales, verifique los siguientes puntos:

• Modelo de Credenciales Adecuado: ¿Se han configurado credenciales personales en las herramientas de escritura para mantener una trazabilidad estricta en las auditorías de SaaS?
• Protección High Stake Activa: ¿Están marcadas como High Stake todas las acciones que alteran datos de clientes, contratos o tickets de soporte?
• Ocultación de Parámetros Críticos: ¿Se han preconfigurado URLs de servicio y claves de entorno mediante ConfigurableToolInputSchemas para evitar alucinaciones del LLM?
• Instrucciones Claras de Gestión de Errores: ¿Indica el prompt del asistente cómo comunicar fallos de red o problemas de autorización al usuario?
• Reglas de Red en Cortafuegos: ¿Se han autorizado las IPs estáticas de salida de Dust en las pasarelas que protegen los servicios MCP internos?
• Control de Tasa en Webhooks: ¿Se han fijado límites de invocación diaria en los disparadores automáticos para mitigar tormentas de eventos?

La combinación de especificaciones OpenAPI, servidores MCP y políticas de gobernanza en Dust permite superar el paradigma de los bots pasivos, consolidando una infraestructura de automatización conversacional fiable y segura.

Referencias

• 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