Configurando Custom Actions e Ferramentas OpenAPI no Dust: De Assistentes Conversacionais a Executores de Fluxos de Trabalho

A maioria das iniciativas empresariais com inteligência artificial generativa tem início como sistemas de consulta documental. As equipes de operações conectam Notion, Google Drive e wikis internas para que agentes realizem Geração Aumentada por Recuperação (RAG) e respondam a dúvidas frequentes dos colaboradores. No entanto, a recuperação puramente passiva atinge um limite evidente quando a rotina corporativa exige atualizações de registros, sincronização entre plataformas e abertura de chamados. Um assistente que apenas instrui como atualizar uma oportunidade no CRM ou como registrar um ticket no Jira transfere todo o esforço de execução para o operador humano.

O Dust supera essa barreira ao integrar um ecossistema nativo de ferramentas e ações (Tools & Actions) com suporte direto ao padrão aberto Model Context Protocol (MCP). Ao empacotar endpoints REST baseados na especificação OpenAPI 3.0 e integrações SaaS como ferramentas interativas, as equipes de operações podem transformar assistentes conversacionais em executores autônomos de fluxos de trabalho. Este guia detalha como estruturar ações customizadas, selecionar modelos de credenciais, aplicar travas de segurança e automatizar operações de ponta a ponta no Dust.

Evolução Arquitetural: Da Consulta Passiva à Execução Ativa

Para capacitar um assistente como executor de processos, é essencial compreender como o Dust orquestra a comunicação entre modelos de linguagem (LLMs) e sistemas externos:

+-----------------------------------------------------------------------------------+
|                                 Dust Workspace                                    |
|                                                                                   |
|   +-----------------------+              +------------------------------------+   |
|   | Entrada do Usuário /  |              | Orquestrador do Assistente         |   |
|   | Disparador Webhook    | ---------->  | (LLM + Instruções do Sistema)      |   |
|   +-----------------------+              +-----------------+------------------+   |
|                                                            |                      |
|                                                            | Avaliação de intenção|
|                                                            v                      |
|                                          +------------------------------------+   |
|                                          | Chamada de Tool e Injeção Segura   |   |
|                                          +-----------------+------------------+   |
+------------------------------------------------------------|----------------------+
                                                             |
                     +---------------------------------------+---------------------------------------+
                     |                                                                               |
                     v                                                                               v
    +---------------------------------+                                             +---------------------------------+
    | Ferramentas Nativas (Built-in)  |                                             | Servidor MCP Remoto / OpenAPI   |
    | (HubSpot, Jira, GitHub, Slack)  |                                             | (Microsserviços internos, APIs) |
    +----------------+----------------+                                             +----------------+----------------+
                     |                                                                               |
                     | OAuth (Pessoal ou Compartilhado)                                              | Bearer Token / OAuth Estático / mTLS
                     v                                                                               v
    +---------------------------------+                                             +---------------------------------+
    | Plataformas SaaS Empresariais   |                                             | Sistemas Proprietários Centrais |
    | (Oportunidades CRM, Chamados)   |                                             | (ERP, Faturamento, Bancos de Dados)
    +---------------------------------+                                             +---------------------------------+

Na arquitetura RAG convencional, o LLM realiza buscas semânticas em documentos e sintetiza respostas textuais. No modelo baseado em ferramentas de execução:

1. Disponibilização do Esquema: O Dust fornece ao LLM a definição JSON Schema das ações disponíveis (geradas a partir de OpenAPI ou MCP).
2. Interpretação e Extração de Parâmetros: O modelo identifica a intenção no contexto do diálogo e extrai os parâmetros estruturados (como ID da negociação, prioridade do chamado ou notas de acompanhamento).
3. Injeção de Parámetros Protegidos: O Dust insere automaticamente parâmetros estáticos pré-configurados (como URLs de ambiente ou IDs de projeto) que permanecem invisíveis para o LLM, prevenindo alucinações.
4. Validação Humana (Human-in-the-Loop): Ações sensíveis que alteram dados corporativos pausam a execução e solicitam autorização expressa do operador.
5. Retorno de Estado e Continuidade: A resposta da API remota é reinserida no histórico da conversa, permitindo que o assistente reporte o resultado e prossiga com o fluxo.

Passo 1: Empacotando APIs OpenAPI em Servidores MCP Customizados

O Dust adota nativamente o Model Context Protocol (MCP). Caso sua equipe possua APIs REST documentadas em OpenAPI 3.0 (como microsserviços internos de suporte, automação de faturamento ou gestão de acessos), a abordagem recomendada é disponibilizá-las através de um servidor MCP intermediário.

Criação de Ferramentas com o SDK TypeScript

Utilizando o SDK oficial de MCP para TypeScript com validação de tipos via Zod:

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

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

// Expondo um endpoint OpenAPI PATCH /crm/deals/{dealId} como ação executável
server.tool(
  "update_crm_deal_stage",
  "Atualiza a fase do funil de vendas e a probabilidade de fechamento de uma oportunidade no CRM",
  {
    dealId: z.string().describe("Identificador alfanumérico único da oportunidade"),
    newStage: z.enum(["Qualified", "Proposal", "Contract_Sent", "Closed_Won", "Closed_Lost"]).describe("Fase de destino no funil"),
    closeNotes: z.string().optional().describe("Justificativa e notas contextuais da alteração"),
  },
  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: `Erro ao atualizar a oportunidade: ${response.statusText}` }],
        isError: true,
      };
    }

    const data = await response.json();
    return {
      content: [{ type: "text", text: `Oportunidade ${dealId} atualizada com sucesso para ${newStage}. Registro ID: ${data.id}` }],
    };
  }
);

Pré-Configuração de Parâmetros com Esquemas do Dust

Em operações corporativas, dados como ambientes de destino (Staging vs. Produção) ou identificadores de filial devem ser estáticos para evitar que o modelo invente valores ou altere configurações indevidas.

O pacote @dust-tt/client viabiliza a declaração de campos configuráveis na interface de criação de assistentes do Dust, ocultando-os do LLM:

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",
  "Cria um chamado de alta prioridade na fila técnica de suporte à engenharia",
  {
    // Extraídos dinamicamente pelo modelo a partir da conversa
    summary: z.string().describe("Título resumido do incidente"),
    description: z.string().describe("Descrição detalhada da falha e passos de reprodução"),
    priority: z.enum(["P1", "P2", "P3"]).describe("Classificação de criticidade do chamado"),

    // Pré-configurados estaticamente na interface do Dust; ocultos do 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 });
  }
);

Passo 2: Registro de Ferramentas e Governança de Credenciais no Dust

Com o servidor MCP acessível publicamente via HTTPS, o administrador do workspace realiza a configuração na plataforma Dust.

Fluxo de Registro

1. No console do Dust, acesse Spaces > Tools.
2. Clique no botão Add Tool.
3. Escolha uma das integrações nativas (Jira, HubSpot, Salesforce, GitHub) ou selecione Add MCP Server para registrar um servidor customizado.
4. Informe a URL pública HTTPS do servidor MCP para sincronizar as ferramentas.

Estrutura de Credenciais: Pessoais vs. Compartilhadas

A definição do formato de autenticação é fundamental para atender aos requisitos de auditoria e controle de acessos da organização:

Configuração de Rede e Conectividade Segura

Para proteger serviços internos:

• IPs Estáticos de Saída (Static Egress IPs): Valide seu domínio corporativo no Dust para habilitar o tráfego a partir de faixas de IP estáticas dedicadas do Dust, permitindo a liberação no firewall corporativo.
• URLs de Retorno de OAuth (Callbacks): Registre as URLs de retorno conforme a região do seu workspace:
  • Workspaces nos EUA: https://dust.tt/oauth/mcp_static/finalize
  • Workspaces na Europa: https://eu.dust.tt/oauth/mcp_static/finalize
  • Gateway Global: https://app.dust.tt/oauth/mcp_static/finalize

Passo 3: Implementando Salvaguardas e Validação Humana (Human-in-the-Loop)

Conceder a um assistente permissões para criar, alterar ou excluir registros em sistemas produtivos requer mecanismos contra alucinações e injeções de prompt.

1. Etiquetagem de Ações Críticas (High Stake)

Ao vincular ferramentas com potencial de mutação de dados (como alterar oportunidades comerciais, cancelar faturas ou criar tickets em produção), o administrador deve classificá-las como HIGH STAKE.

• Comportamento: A execução é pausada automaticamente no chat antes do envio da requisição, exibindo um card com o resumo exato dos parâmetros que serão enviados.
• Aprovação Obrigatória: O envio só ocorre quando um usuário autorizado clica em Approve.
• Controle Programático via API: Em fluxos integrados via Dust Conversation API, a validação é aprovada ou rejeitada através do endpoint POST /api/v1/w/{wId}/assistant/conversations/{cId}/messages/{mId}/validate-action.

2. Restrição de Ferramentas a Skills (Restrict to Skills)

Em Spaces > Tools, selecione a opção Restrict this tool to skills.

• A ferramenta é removida da listagem geral do Agent Builder, impedindo que colaboradores a vinculem inadvertidamente a assistentes convencionais.
• O acesso passa a ser exclusivo de "Skills" específicos que concentram instruções formais de segurança e validações de contexto.

3. Isolamento Baseado em Espaços (Spaces)

Aloque ferramentas de escrita sensíveis em espaços restritos (Restricted Spaces). Somente membros expressamente convidados para esses espaços poderão interagir com assistentes configurados com essas permissões.

Passo 4: Estruturando Prompts no Agent Builder para Execução Confiável

Após a conexão das ferramentas, a consistência das operações depende diretamente da clareza das instruções (Instructions) atribuídas ao assistente.

Pilares de um Prompt de Produção

1. Definição de Escopo e Papel: Estabelecer os limites funcionais do agente e proibições de conduta.
2. Protocolo de Checagem Prévia: Exigir leitura e confirmação do estado atual dos registros antes de qualquer modificação.
3. Mapeamento Explícito de Argumentos: Detalhar regras de extração de campos, valores padrão e formatos válidos.
4. Instruções para Tratamento de Falhas: Padronizar respostas em caso de credenciais expiradas ou indisponibilidade de serviços.

Exemplo de Configuração: Assistente de Triagem Técnica e Sincronização de CRM

# Papel e Responsabilidades
Você é o Agente de Operações e Escalonamento Técnico. Sua atribuição é analisar incidentes reportados por clientes, verificar o contrato correspondente no CRM e criar chamados técnicos estruturados no Jira.

# Protocolos de Uso de Ferramentas

## 1. Verificação de Conta no CRM (HubSpot)
- Antes de abrir qualquer chamado, consulte os dados do cliente com `Get Object By Email` ou `Search Crm Objects`.
- Obtenha o plano contratado (Tier) e os acordos comerciais vigentes.
- Caso o cliente possua plano "Enterprise", eleve automaticamente a prioridade do chamado para P1.

## 2. Abertura de Chamado no Jira (Jira)
- Ferramenta: `create_issue`
- O título (summary) deve resumir a falha em até 60 caracteres no padrão: `[Módulo] Resumo objetivo do problema`.
- A descrição (description) deve apresentar obrigatoriamente três tópicos:
  1. Contexto do Cliente (Empresa, contato, plano contratado)
  2. Comportamento Anômalo e Logs de Erro
  3. Etapas de Reprodução e Links Relevantes
- O tipo de item deve ser sempre "Bug" e o componente "Production-Ops".

## 3. Segurança e Contingência de Erros
- Qualquer atualização que altere a fase de uma oportunidade de venda ou encerre chamados deve ser confirmada previamente com o usuário.
- Caso ocorra um erro 401 de autenticação, oriente o operador: "Por favor, acesse Tools & Triggers no menu de usuário para reconectar suas credenciais do Jira ou HubSpot".

Passo 5: Automação Contínua com Gatilhos de Webhook

Para construir fluxos operacionais que não dependem de digitação humana no chat, as ferramentas de execução podem ser associadas aos Disparadores de Webhook (Webhook Triggers) do Dust.

+--------------------------+          Requisição HTTP POST      +-----------------------------+
| Sistema Externo          | ---------------------------------> | Origem Webhook do Dust      |
| (Jira, GitHub, Zendesk,  |                                    | (Spaces > Triggers)         |
| Monitoramento interno)   |                                    +--------------+--------------+
+--------------------------+                                                   |
                                                                               | Validação de Assinatura e Dados
                                                                               v
+--------------------------+          Executa Ação no Destino   +-----------------------------+
| Plataforma de Destino    | <--------------------------------- | Execução do Agente Dust     |
| (Atualização no CRM /    |                                    | (Analisa evento, valida     |
| Notificação no Slack)    |                                    | filtros e aciona ferramenta)|
+--------------------------+                                    +-----------------------------+

Configurando o Fluxo de Automação por Webhook

1. Criar a Origem do Webhook (Administrador):
   • Acesse Spaces > Triggers e clique em Add source.
   • Escolha um provedor integrado (Jira, GitHub, Linear, Zendesk) ou selecione Custom webhook.
   • Para webhooks customizados, configure autenticação por assinatura HMAC no cabeçalho com algoritmo sha256 para bloquear requisições não autorizadas.
2. Associar o Gatilho ao Assistente:
   • No Agent Builder, acesse Triggers > Add triggers e selecione a fonte criada.
   • Defina os critérios de acionamento em linguagem natural (exemplo: "Executar somente quando a prioridade do chamado for High e o status mudar para Escalated").
   • Marque a opção Include webhook payload para disponibilizar o corpo JSON do evento no contexto do assistente.
   • Forneça a instrução de execução (exemplo: "Extraia as informações de erro do payload, consulte os guias na base de conhecimento e adicione um comentário com recomendações no chamado correspondente do Jira").
   • Estipule limites de execução (Rate Limits) para janelas de 24 horas, protegendo o orçamento de créditos contra picos de tráfego.

Comparativo de Opções de Integração

Avalie os modelos de integração de acordo com a complexidade técnica e os requisitos de segurança da sua operação:

Checklist de Prontidão para Produção

Antes de disponibilizar assistentes executores para as equipes de linha de frente, valide os seguintes itens:

• Modelo de Autenticação Validado: Ferramentas com permissão de escrita utilizam credenciais pessoais para garantir rastreabilidade nas auditorias de SaaS?
• Salvaguarda High Stake Ativada: Todas as operações de criação, exclusão ou atualização de dados de clientes possuem confirmação humana configurada?
• Parâmetros Estáticos Protegidos: Chaves de ambiente, URLs internas e identificadores de locatário foram declarados com ConfigurableToolInputSchemas para evitar alucinações?
• Tratamento de Exceções Definido: O prompt do assistente orienta adequadamente o usuário caso ocorram erros de rede ou falhas de autorização?
• Liberação de Tráfego de Rede: As faixas de IP estáticas de saída do Dust foram autorizadas nos firewalls que protegem os servidores MCP internos?
• Limitação de Chamadas em Webhooks: Gatilhos automáticos contam com limites de execução em 24 horas para conter disparos em massa?

Ao combinar especificações OpenAPI, o protocolo MCP e governança de credenciais no Dust, as equipes de operações convertem assistentes conversacionais em executores automatizados confiáveis, integrados ao ecossistema produtivo da empresa.

Referências

• 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