Turning Dust Assistants into Automated Workflow Executors with Custom Actions and OpenAPI Tools

Most enterprise deployments of generative AI begin as conversational knowledge bases. Operations teams connect Notion, Google Drive, and internal wikis so agents can perform Retrieval-Augmented Generation (RAG) and answer employee questions. However, passive retrieval quickly hits a ceiling when operations workflows demand real-time writes, cross-system synchronizations, and ticket escalations. An assistant that only describes how to update a customer record or file a bug ticket leaves half the work on the human operator's plate.

Dust transforms this dynamic by enabling agents to execute actions directly in third-party systems. By bridging OpenAPI-described services through the Model Context Protocol (MCP) and integrating native action tools, operations teams can convert conversational assistants into proactive workflow executors. This guide details how operations and platform engineering teams configure custom actions, manage authentication models, enforce safety guardrails, and build closed-loop business automations in Dust.

Architectural Shift: From Passive Retrieval to Active Execution

To transition an assistant from a passive knowledge retrieval bot to an operational agent, it is essential to understand how Dust handles tool calls under the hood:

+-----------------------------------------------------------------------------------+
|                                 Dust Workspace                                    |
|                                                                                   |
|   +-----------------------+              +------------------------------------+   |
|   | User Prompt / Webhook |              | Assistant Orchestrator             |   |
|   | Event Trigger         | ---------->  | (LLM + System Instructions)        |   |
|   +-----------------------+              +-----------------+------------------+   |
|                                                            |                      |
|                                                            | Evaluates intent     |
|                                                            v                      |
|                                          +------------------------------------+   |
|                                          | Tool Calling & Parameter Injection |   |
|                                          +-----------------+------------------+   |
+------------------------------------------------------------|----------------------+
                                                             |
                     +---------------------------------------+---------------------------------------+
                     |                                                                               |
                     v                                                                               v
    +---------------------------------+                                             +---------------------------------+
    | Built-in Integration Tools      |                                             | Custom Remote MCP / OpenAPI     |
    | (HubSpot, Jira, GitHub, Slack)  |                                             | (Internal APIs, Middleware)     |
    +----------------+----------------+                                             +----------------+----------------+
                     |                                                                               |
                     | OAuth (Personal or Shared)                                                    | Bearer / Static OAuth / mTLS
                     v                                                                               v
    +---------------------------------+                                             +---------------------------------+
    | Enterprise SaaS Platforms       |                                             | Proprietary Backend Services    |
    | (CRM Deals, Tickets, Comms)     |                                             | (ERP, Billing, Custom DBs)      |
    +---------------------------------+                                             +---------------------------------+

In standard RAG, the LLM searches indexed text chunks and synthesizes an answer. When equipped with tools:

1. Schema Presentation: Dust provides the LLM with the JSON Schema definitions of available actions (derived from OpenAPI endpoints or MCP definitions).
2. Intent Parsing: The LLM extracts parameters from conversational context and structures an execution payload.
3. Parameter Injection: Dust injects pre-configured, protected operational parameters (such as environment URLs or workspace IDs) that remain hidden from the LLM.
4. Execution & Human-in-the-Loop Validation: Sensitive actions can halt for explicit operator approval before mutating remote records.
5. State Feedback: The remote API's response returns to the conversational thread, confirming completion and maintaining state continuity.

Step 1: Packaging OpenAPI Endpoints into Custom MCP Servers

Dust natively consumes tools via the open Model Context Protocol (MCP). If your operations team maintains custom REST APIs documented with OpenAPI 3.0 (e.g., internal microservices, customer provisioning APIs, or database proxies), the standard approach is to wrap those OpenAPI specs in an MCP server.

Standard Tool Definition (TypeScript SDK)

Using the official TypeScript MCP SDK, operations engineers define actionable tools with input validation enforced by 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",
});

// Exposing an OpenAPI POST /crm/deal/update endpoint as an executable action
server.tool(
  "update_crm_deal_stage",
  "Updates the sales pipeline stage and probability for an enterprise CRM deal",
  {
    dealId: z.string().describe("The unique alphanumeric ID of the deal"),
    newStage: z.enum(["Qualified", "Proposal", "Contract_Sent", "Closed_Won", "Closed_Lost"]).describe("Target pipeline stage"),
    closeNotes: z.string().optional().describe("Summary of reasons for stage advancement"),
  },
  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 updating deal: ${response.statusText}` }],
        isError: true,
      };
    }

    const data = await response.json();
    return {
      content: [{ type: "text", text: `Deal ${dealId} successfully transitioned to ${newStage}. Updated record ID: ${data.id}` }],
    };
  }
);

Pre-Configuring Parameters with Dust Schemas

Operations teams frequently need to inject static variables (such as environment endpoints, regional flags, or internal tenant identifiers) without exposing them to the LLM. This prevents hallucinated endpoints and protects internal topology.

Dust provides @dust-tt/client schemas to declare pre-configurable fields that the agent builder can populate statically in the Dust UI:

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",
  "Creates a high-priority incident ticket in the designated engineering queue",
  {
    // Dynamically extracted by the model from conversational text
    summary: z.string().describe("Short incident summary"),
    description: z.string().describe("Detailed incident notes and reproduction steps"),
    priority: z.enum(["P1", "P2", "P3"]).describe("Incident severity rating"),

    // Pre-configured in the Dust Agent Builder UI; hidden from LLM generation
    projectKey: ConfigurableToolInputSchemas[INTERNAL_MIME_TYPES.TOOL_INPUT.STRING],
    environment: ConfigurableToolInputSchemas[INTERNAL_MIME_TYPES.TOOL_INPUT.STRING],
  },
  async ({ summary, description, priority, projectKey, environment }) => {
    // Execution receives static inputs seamlessly alongside LLM outputs
    return callJiraBackend({ summary, description, priority, projectKey, environment });
  }
);

Step 2: Registering Tools and Configuring Credentials in Dust

Once custom MCP endpoints or native SaaS integrations are identified, workspace administrators configure and authenticate them within Dust.

Accessing Workspace Tool Management

1. In Dust, navigate to Spaces > Tools.
2. Click Add Tool.
3. Select from native third-party integration tools (e.g., Jira, HubSpot, GitHub, Salesforce) or click Add MCP Server to connect your custom OpenAPI server.

Authentication Topology: Personal vs. Shared Credentials

Selecting the appropriate credential architecture determines accountability, auditability, and access control:

Network and Firewall Configuration

When connecting custom internal servers:

• Public HTTPS Endpoint: Your MCP server must be exposed to an external URL or API gateway.
• Static Egress IPs: If your company restricts network ingress via IP whitelisting, verify your workspace domain in Dust and restrict inbound traffic to Dust's static egress IP addresses.
• OAuth Callback Finalization: Register regional redirect URIs in your OAuth provider:
  • US Workspaces: https://dust.tt/oauth/mcp_static/finalize
  • EU Workspaces: https://eu.dust.tt/oauth/mcp_static/finalize
  • Global App Gateway: https://app.dust.tt/oauth/mcp_static/finalize

Step 3: Enforcing Safety Guardrails and Human-in-the-Loop Validation

Allowing conversational agents to perform create, update, and delete actions introduces operational risks if prompt injections, hallucinations, or operator misunderstandings occur. Dust provides built-in mechanisms to maintain strict operational integrity.

1. High-Stake Action Tagging

When attaching mutation tools (such as updating CRM deals, modifying customer records, or creating production Jira tickets), administrators can flag tools as High Stake.

• Behavior: Rather than executing silently in the background, the assistant pauses generation and presents a confirmation modal in the conversation window displaying the exact payload.
• Execution: The write action executes only after an authorized human clicks Approve.
• Programmatic Validation: When orchestrating workflows through the Dust Conversation API, external systems validate these steps using the POST /api/v1/w/{wId}/assistant/conversations/{cId}/messages/{mId}/validate-action endpoint.

2. Restricting Tools to Skills

Under Spaces > Tools, administrators can check Restrict this tool to skills.

• Isolation: The tool is hidden from the general agent builder and cannot be selected ad-hoc by employees in casual chat.
• Controlled Access: It becomes available exclusively through designated "Skills"—modular packages containing specific instructions, guardrail logic, and prerequisite data sources.

3. Space-Based Partitioning

Tools configured within a specific Restricted Space are accessible only to agents and users belonging to that Space. This prevents billing or customer-success write actions from leaking into general company spaces.

Step 4: Configuring the Assistant Builder for Reliable Execution

With tools secured, the next step is configuring the agent's behavior in the Assistant Builder. Effective workflow execution requires explicit instructions on when and how to invoke actions.

Essential Instruction Architecture

A production-grade ops prompt should always establish four elements:

1. Persona & Scope: The precise business boundary of the assistant.
2. Pre-Execution Validation Rules: Conditions that must be met before an action is triggered (e.g., required data fields).
3. Execution Protocol: The exact sequencing of read and write tools.
4. Failure Handling: How to communicate API errors or ambiguous user requests.

Practical Assistant Configuration Example

Below is a production instruction template for an Ops Escalation & CRM Sync Assistant:

# Role & Operational Scope
You are the Technical Operations Escalation Agent. Your primary responsibility is to investigate customer-reported issues, correlate them with CRM account records, and create actionable engineering tickets.

# Tool Usage Protocols

## 1. CRM Verification (HubSpot)
- Before creating any ticket, search for the account using the `Get Object By Email` or `Search Crm Objects` tool.
- Retrieve the customer's subscription tier and open deal context.
- If the account is on an Enterprise plan, escalate the incident priority to P1 automatically.

## 2. Jira Issue Creation (Jira)
- Tool: `create_issue`
- Summarize the core defect in under 80 characters for the summary field.
- Construct the description with three mandatory sections:
  1. Customer Context (Company Name, Tier, Contact)
  2. Observed Error / Behavior
  3. Steps to Reproduce & Relevant Logs
- Always set the issue type to "Bug" and component to "Production-Ops".

## 3. Human Confirmation & Safety
- Confirm all parameter values with the user before invoking any update that modifies active deal stages or closes tickets.
- If an API returns an error, output the exact error message and advise the operator to check their personal OAuth credentials under Tools & Triggers.

Step 5: Automating the Pipeline with Webhooks

Conversational assistants typically require a human to type a prompt. To build fully automated, autonomous workflow loops, operations teams pair action tools with Dust Webhook Triggers.

+--------------------------+          HTTP POST Event           +-----------------------------+
| External System          | ---------------------------------> | Dust Webhook Source         |
| (Jira, GitHub, Zendesk,  |                                    | (Spaces > Triggers)         |
| Custom Webhook Endpoint) |                                    +--------------+--------------+
+--------------------------+                                                   |
                                                                               | Payload & Signature Verified
                                                                               v
+--------------------------+          Runs Action Tool          +-----------------------------+
| Remote Destination       | <--------------------------------- | Dust Agent Execution        |
| (HubSpot Updated /       |                                    | (Parses event, evaluates    |
| Slack Notification)      |                                    | filter, calls MCP actions)  |
+--------------------------+                                    +-----------------------------+

Setting Up Webhook Automation

1. Create Webhook Source (Admin):
   • Navigate to Spaces > Triggers > Add source.
   • Choose a built-in provider (e.g., Jira, Linear, GitHub, Zendesk) or select Custom webhook.
   • For custom sources, configure HMAC signature verification by specifying the Signature header and algorithm (sha256).
2. Attach Trigger to Agent:
   • In the Agent Builder, navigate to Triggers > Add triggers and link the webhook source.
   • Configure a plain-language condition (e.g., "Run only when ticket priority is High and status changes to Escalated").
   • Check Include webhook payload so the full JSON body is delivered into the agent's context.
   • Set a default prompt instruction: "Extract the issue details from the payload, query the related customer in HubSpot, and update the CRM ticket association."
   • Define execution rate limits (e.g., maximum 50 runs per hour) to safeguard operational budgets.

Operational Scenarios: Comparison & Trade-Offs

When deploying action-oriented assistants, operations teams typically choose between three primary integration paths based on complexity, governance, and development overhead:

Checklist for Production Deployment

Before releasing workflow-executing assistants to frontline teams, verify each operational milestone:

• Credential Scoping: Have write-heavy tools been configured with Personal credentials to ensure accurate SaaS audit logs, or is an explicit service account designated?
• High-Stake Protection: Are all endpoints capable of modifying live customer data flagged as High Stake?
• Parameter Shielding: Are static API paths, database identifiers, and sensitive flags pre-configured using ConfigurableToolInputSchemas rather than left to LLM guesswork?
• Prompt Guardrails: Do agent instructions specify validation criteria, required fields, and clear error recovery procedures?
• Network Egress: Have corporate firewall rules whitelisted Dust's static egress IP addresses where internal APIs are targeted?
• Rate Limiting: Are webhook triggers configured with reasonable run thresholds to avoid unexpected credit consumption during event spikes?

By uniting OpenAPI endpoints, MCP tools, and robust credential governance, operations teams can evolve Dust from a passive answering machine into a dependable, automated digital workforce.

References

• 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