在 Dust 中配置自訂 Actions 與 OpenAPI 工具：將對話助理升級為自動化工作流程執行器

在許多企業導入生成式 AI 的初期，AI 助理的角色往往侷限於「內部知識庫問答」。營運團隊通常會將 Notion、Google Drive 或 Confluence 等文件庫接入系統，透過檢索增強生成（RAG）技術解答同仁的提問。然而，當日常業務需要實際變更系統狀態時，單純被動的檢索很快就會碰壁：一個只能「指導如何建立工單」或「解釋如何更新 CRM 資料」的助理，依然把所有繁瑣的執行動作留給了人工。

Dust 透過原生的工具執行（Tools & Actions）機制與模型上下文協定（Model Context Protocol，MCP），成功化解了這項限制。營運與平台工程團隊能夠將以 OpenAPI 規範描述的內部 REST API，以及商業 SaaS 系統包裝為可執行的工具，讓對話助理具備跨系統的資料讀取與寫入能力。本文將完整說明如何在 Dust 中匯入與配置自訂 Actions 與 OpenAPI 工具、評估認證授權模式、建立高風險操作防護機制，並實現自然語言問答與企業業務系統的雙向自動化整合。

架構演進：從被動文件檢索到主動工作流程執行

要讓對話助理升格為工作流程的執行者，首先需要理解 Dust 底層如何協調大型語言模型（LLM）與外部系統的互動架構：

+-----------------------------------------------------------------------------------+
|                                 Dust Workspace                                    |
|                                                                                   |
|   +-----------------------+              +------------------------------------+   |
|   | 使用者提問 / Webhook  |              | 助理編排核心                       |   |
|   | 事件觸發              | ---------->  | (LLM + 系統指令 Instructions)       |   |
|   +-----------------------+              +-----------------+------------------+   |
|                                                            |                      |
|                                                            | 評估意圖與工具決策   |
|                                                            v                      |
|                                          +------------------------------------+   |
|                                          | 工具呼叫與受保護參數注入           |   |
|                                          +-----------------+------------------+   |
+------------------------------------------------------------|----------------------+
                                                             |
                     +---------------------------------------+---------------------------------------+
                     |                                                                               |
                     v                                                                               v
    +---------------------------------+                                             +---------------------------------+
    | 原生整合工具 (Built-in Tools)   |                                             | 自訂 Remote MCP / OpenAPI 服務  |
    | (HubSpot, Jira, GitHub, Slack)  |                                             | (內部微服務、自動化網關中介軟體)|
    +----------------+----------------+                                             +----------------+----------------+
                     |                                                                               |
                     | OAuth (個人憑證或工作區共用憑證)                                              | Bearer Token / 靜態 OAuth / mTLS
                     v                                                                               v
    +---------------------------------+                                             +---------------------------------+
    | 企業商用 SaaS 平台              |                                             | 企業內部專屬業務系統            |
    | (CRM 商機、工單系統、團隊通訊)  |                                             | (ERP、計費系統、私有資料庫代理) |
    +---------------------------------+                                             +---------------------------------+

在傳統的 RAG 運作下，模型僅對索引後的文件區塊進行語意搜尋並綜合整理答案。而在工具執行模式中：

1. Schema 規格公開：Dust 將工具的輸入輸出規範（由 OpenAPI 或 MCP 定義的 JSON Schema）作為後設資料提供給 LLM。
2. 意圖剖析與參數擷取：模型自對話語境中識別使用者的具體意圖，並擷取對應的結構化參數（例如工單標題、CRM 交易識別碼、優先層級）。
3. 靜態參數保護與注入：Dust 將預先配置且受保護的環境參數（例如系統基底 URL、租戶 ID 等對 LLM 隱藏的數值）直接合併注入，防止模型臆測產生錯誤。
4. 高風險人機協同核可（Human-in-the-Loop）：關鍵寫入操作會自動暫停並跳出審核視窗，必須由具備授權的人工點擊確認，才會真正發送寫入請求。
5. 執行反饋與狀態延續：外部系統的回傳結果會寫回對話歷程中，助理能根據回傳狀態向使用者呈現清楚的執行結果。

步驟一：將 OpenAPI 規範封裝為自訂 MCP 服務

Dust 原生採用開放的 Model Context Protocol（MCP）。若企業內部具備以 OpenAPI 3.0 規範定義的 REST API（例如內部客戶管理系統、權限佈建 API 或中介排程系統），最穩健的對接策略是開發輕量級的 MCP 服務作為包裝層。

使用 TypeScript SDK 定義標準工具

透過官方 TypeScript MCP SDK，工程團隊可以運用 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",
});

// 將 OpenAPI PATCH /crm/deal/update 介面封裝為可呼叫的工具
server.tool(
  "update_crm_deal_stage",
  "更新企業 CRM 業務管線中指定商機的階段與成單機率",
  {
    dealId: z.string().describe("商機的唯一英數代碼識別碼"),
    newStage: z.enum(["Qualified", "Proposal", "Contract_Sent", "Closed_Won", "Closed_Lost"]).describe("目標階段"),
    closeNotes: z.string().optional().describe("階段推進的背景說明與備註"),
  },
  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: `更新商機失敗：${response.statusText}` }],
        isError: true,
      };
    }

    const data = await response.json();
    return {
      content: [{ type: "text", text: `商機 ${dealId} 已成功更新至 ${newStage} 階段。記錄代碼：${data.id}` }],
    };
  }
);

運用 Dust 輸入架構預先配置靜態參數

在企業營運流程中，特定參數（如後端服務節點、測試/正式環境切換、專案識別碼 Project Key）應該維持恆定，不應交由 LLM 推敲。這不僅能大幅減少 Token 消耗，也能避免模型產生幻覺打到錯誤環境。

Dust 提供的 @dust-tt/client 支援在工具定義中宣告預先配置參數，這些參數可以在 Dust 助理設定介面中由管理員設定，且完全不向 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",
  "在指定的工程專案佇列中建立高優先層級的事件處理工單",
  {
    // 由模型從對話內容中動態剖析取得
    summary: z.string().describe("事件簡述標題"),
    description: z.string().describe("事件詳情與問題重現步驟"),
    priority: z.enum(["P1", "P2", "P3"]).describe("事件嚴重度層級"),

    // 於 Dust 助理設定介面中靜態填寫，模型端不可見
    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 });
  }
);

步驟二：在 Dust 工作區註冊工具與配置身分驗證

當 MCP 服務部署至具備公開 HTTPS 端點的環境後，工作區管理員即可將其引進 Dust 工作區。

註冊工具步驟

1. 進入 Dust 系統，切換至 Spaces > Tools。
2. 點擊 Add Tool 按鈕。
3. 若為 Jira、HubSpot、Salesforce 等常見平台，直接選取內建工具；若為自訂 OpenAPI/MCP 服務，點選 Add MCP Server。
4. 輸入 MCP 服務的公開 URL 完成初始同步。

憑證架構權衡：個人憑證 vs 共用憑證

在工具管理中選擇適當的身分驗證模式，對於資安稽核與存取權限控制至關重要：

網路安全與防火牆白名單

針對私有架構的自訂 MCP 服務：

• 靜態出口 IP (Static Egress IPs)：在 Dust 完成網域驗證後，可將 Dust 專屬的靜態出口 IP 加入伺服器防火牆允許名單，封鎖其他來源連線。
• OAuth 回呼網址 (Callback Finalization)：若使用靜態 OAuth，需在身分提供者設定中填入對應區域的 Dust 回呼網址：
  • 美區工作區：https://dust.tt/oauth/mcp_static/finalize
  • 歐區工作區：https://eu.dust.tt/oauth/mcp_static/finalize
  • 全域應用端點：https://app.dust.tt/oauth/mcp_static/finalize

步驟三：設定安全防線與人機協同核可機制（Human-in-the-Loop）

讓 AI 助理具備對生產環境進行建立、修改與刪除（Create/Update/Delete）的能力，必須伴隨嚴密的防護機制，防止因 Prompt 注入或模型失誤造成系統損害。

1. 高風險工具標記（High Stake）

在掛載可能異動重要資料的工具時（如更新 CRM 階段、刪除記錄、建立生產環境工單），管理員可將該工具標記為 HIGH STAKE。

• 防護機制：助理不會在背景靜默執行呼叫，而是會在對話視窗中暫停並展開確認卡片，清楚列出即將傳遞給 API 的所有參數。
• 人工確認：唯有具備操作權限的使用者點擊「確認」（Approve）後，請求才會真正送出。
• API 端點控制：若是透過 Dust Conversation API 進行整合，可呼叫 POST /api/v1/w/{wId}/assistant/conversations/{cId}/messages/{mId}/validate-action 完成程式化核可或拒絕。

2. 限制工具僅能在技能中使用（Restrict to Skills）

在 Spaces > Tools 介面中，勾選 Restrict this tool to skills。

• 該工具將從全域 Agent Builder 中隱藏，一般員工自建助理時無法直接調用。
• 僅有包含特定業務邏輯與驗證機制的「技能」（Skills）能夠掛載此工具，確保執行路徑受控。

3. 空間層級（Spaces）的隔離存取

將敏感的資料寫入工具配置於特定的受限空間（Restricted Space）。只有該空間內的成員才能與具備此工具特權的助理互動，避免高權限工具在一般部門間流通。

步驟四：在 Agent Builder 中設計高穩定度執行的提示詞

工具綁定完畢後，助理能否精準判斷時機、擷取必要參數並在發生錯誤時妥善應對，關鍵在於助理的系統指令（Instructions）設計。

生產環境指令架構四要素

1. 角色界限與執掌：清楚界定助理的專職範疇，明定禁止執行的操作。
2. 前置檢核程序：嚴格規定在執行任何寫入前，必須先執行查詢動作以確認標的物現況。
3. 參數擷取與型別規範：具體說明每個欄位的擷取來源、預設值與防呆檢查。
4. 異常處理指引：明確規範在遭遇權杖失效或遠端服務錯誤時的告知話術。

營運排障與 CRM 雙向聯動助理範例提示詞

# 角色與任務
你是企業的技術營運支援助理。你的職責是協助維運同仁將客戶回報的系統異常，與 CRM 中的合約資料進行比對，並在 Jira 中建立符合規範的工程工單。

# 工具使用守則

## 1. 客戶資料與合約等級查詢 (HubSpot)
- 在建立任何 Jira 工單前，務必先呼叫 `Get Object By Email` 或 `Search Crm Objects` 確認客戶資訊。
- 查詢客戶當前的方案等級（Tier）與進行中的重要交易。
- 若客戶為 Enterprise 等級，請自動將後續工單嚴重度提升為 P1。

## 2. Jira 工單建立 (Jira)
- 工具名稱：`create_issue`
- 標題（summary）長度必須小於 60 字，格式統一為：`[模組名稱] 異常現象摘要`。
- 描述（description）必須包含三個固定區塊：
  1. 客戶背景（公司名稱、聯絡人信箱、簽約等級）
  2. 觀察到的錯誤訊息與現象
  3. 問題重現步驟與記錄檔連結
- 工單類別固定設定為 "Bug"，元件欄位設定為 "Production-Ops"。

## 3. 安全核對與錯誤排除
- 針對會變更現有商機或結案的動作，在執行前必須完整輸出參數並要求使用者明確核准。
- 若工具回傳 401 或權限錯誤，請清楚引導使用者：「請點選個人頭像中的 Tools & Triggers 重新連結你的 Jira/HubSpot 個人憑證」。

步驟五：結合 Webhooks 打造無須人工輸入的全自動閉環

除了透過使用者在對話介面中手動觸發外，營運團隊還可以將動作工具與 Dust 的 Webhook Triggers 深度整合，建構由外部事件驅動的全自動工作流程。

+--------------------------+          HTTP POST 事件            +-----------------------------+
| 外部業務系統             | ---------------------------------> | Dust Webhook Source         |
| (Jira、GitHub、Zendesk、 |                                    | (Spaces > Triggers)         |
| 企業內部告警平台)        |                                    +--------------+--------------+
+--------------------------+                                                   |
                                                                               | 載荷解析與 HMAC 驗證成功
                                                                               v
+--------------------------+          執行工具 Actions          +-----------------------------+
| 遠端目標系統             | <--------------------------------- | Dust 助理自主執行           |
| (HubSpot 欄位同步更新 /  |                                    | (剖析事件內容、比對過濾條件 |
| Slack 頻道發送通報)      |                                    | 呼叫外部 API 完成閉環)      |
+--------------------------+                                    +-----------------------------+

設定 Webhook 自動化管線

1. 建立 Webhook 來源（管理員權限）：
   • 前往 Spaces > Triggers，點選 Add source。
   • 選取內建事件源（Jira、GitHub、Linear、Zendesk 等）或點選 Custom webhook。
   • 自訂來源可啟用 Signature header 與 sha256 演算法，由 Dust 自動產製簽名金鑰並驗證請求真偽。
2. 在助理中綁定觸發條件：
   • 進入 Agent Builder 的 Triggers > Add triggers，選擇已建立的來源。
   • 以自然語言設定過濾條件（例如：「僅在工單優先層級為 High 且狀態變更為 Escalated 時執行」）。
   • 勾選 Include webhook payload，確保外部事件的完整 JSON 資料送達助理環境。
   • 設定執行指示（例如：「根據 Payload 中的錯誤訊息檢索知識庫，並呼叫 Jira 工具在該工單下方留言提供初步修復指引」）。
   • 配置 24 小時呼叫頻次上限（Rate Limits），防止外部系統事件風暴導致過量運算消耗。

方案比較與決策架構

在規劃不同自動化場景時，營運團隊通常在以下三種整合模式間做取捨：

進入生產環境前的自檢清單

在將工作流程執行助理推向一線業務人員前，請確認以下關鍵設定：

• 憑證模式合規：具有資料寫入權限的工具，是否優先採用 Personal 憑證以保留真實稽核記錄；若採用 Shared 憑證，服務帳號是否符合最小權限原則？
• 高風險標記確認：能刪除資料、修改合約或對外發送訊息的關鍵動作，是否已開啟 High Stake 人工核可機制？
• 敏感參數遮蔽：系統 URL、資料庫租戶代碼等常數是否已透過 ConfigurableToolInputSchemas 靜態注入，避免由模型猜測？
• 提示詞防呆機制：Prompt 中是否清楚規範連線中斷、授權失敗時的錯誤訊息與明確的復原步驟？
• 網路出口設定：針對企業內部部署的 MCP 服務，是否已在防火牆將 Dust 的靜態出口 IP 列入白名單？
• 觸發器頻次限制：與 Webhook 串接的自動化助理，是否設定了適當的呼叫次數上限以防止異常呼叫擴散？

透過將 OpenAPI 介面標準化為 MCP 工具，配合健全的身分驗證與人機協同安全機制，企業營運團隊能讓 Dust 助理擺脫單純回答問題的被動型態，真正轉化為高效且值得信賴的自動化業務執行核心。

參考資料

• 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