Dust에서 커스텀 Actions 및 OpenAPI 도구 구성하기: 대화형 어시스턴트를 자동화 워크플로 실행기로 전환하는 엔터프라이즈 가이드

많은 기업의 생성형 AI 도입은 문서 검색용 Q&A 챗봇 형태로 시작됩니다. 디지털 운영팀은 Notion, Google Drive, 사내 위키를 연결하여 검색 증강 생성(RAG)을 기반으로 임직원의 일상적인 질문에 답변하는 어시스턴트를 구축합니다. 그러나 엔터프라이즈 업무가 고객 데이터 수정, 상태 동기화, 이슈 생성 등 실제 시스템 변경을 수반하는 순간 수동적인 문서 검색 모델은 한계에 부딪힙니다. Jira 티켓 생성 규정을 안내하거나 CRM 거래 단계 변경 방법을 텍스트로 설명하기만 하는 어시스턴트는 여전히 모든 실질적 업무를 사람의 손에 남겨두기 때문입니다.

Dust는 네이티브 도구 실행 체계(Tools & Actions)와 오픈 표준인 Model Context Protocol(MCP)을 통해 이러한 구조적 한계를 해결합니다. OpenAPI 3.0 사양으로 정의된 사내 REST API와 주요 상용 SaaS를 직접 실행 가능한 도구로 통합함으로써 대화형 어시스턴트를 비즈니스 시스템의 능동적인 '워크플로 실행기(Workflow Executor)'로 진화시킬 수 있습니다. 본 가이드에서는 Dust에서 커스텀 액션을 구성하고, 인증 자격 증명 모델을 선택하며, 안전 가드레일을 적용하고, 양방향 자동화 파이프라인을 구축하는 구체적인 실무 절차를 설명합니다.

아키텍처 전환: 수동적 문서 검색에서 능동적 워크플로 실행으로

어시스턴트가 단순 응답기를 넘어 실무 프로세스를 집행하도록 만들려면 Dust 내부의 도구 오케스트레이션 메커니즘을 이해해야 합니다.

+-----------------------------------------------------------------------------------+
|                                 Dust Workspace                                    |
|                                                                                   |
|   +-----------------------+              +------------------------------------+   |
|   | 사용자 프롬프트 /     |              | 어시스턴트 오케스트레이터          |   |
|   | 웹훅 이벤트 트리거    | ---------->  | (LLM + 시스템 지침 Instructions)   |   |
|   +-----------------------+              +-----------------+------------------+   |
|                                                            |                      |
|                                                            | 의도 분석 및 도구 결정
|                                                            v                      |
|                                          +------------------------------------+   |
|                                          | 도구 호출 및 보호 파라미터 주입    |   |
|                                          +-----------------+------------------+   |
+------------------------------------------------------------|----------------------+
                                                             |
                     +---------------------------------------+---------------------------------------+
                     |                                                                               |
                     v                                                                               v
    +---------------------------------+                                             +---------------------------------+
    | 네이티브 기본 도구 (Built-in)   |                                             | 커스텀 Remote MCP / OpenAPI     |
    | (HubSpot, Jira, GitHub, Slack)  |                                             | (사내 마이크로서비스, API 게이트웨이)
    +----------------+----------------+                                             +----------------+----------------+
                     |                                                                               |
                     | OAuth (개인 인증 또는 공유 서비스 계정)                                       | Bearer 토큰 / Static OAuth / mTLS
                     v                                                                               v
    +---------------------------------+                                             +---------------------------------+
    | 상용 SaaS 비즈니스 플랫폼       |                                             | 사내 핵심 백엔드 시스템         |
    | (CRM 거래, 이슈 트래킹, 커뮤니케이션)                                         | (ERP, 결제/청구, 데이터베이스 프록시)
    +---------------------------------+                                             +---------------------------------+

기존 RAG 방식에서는 모델이 인덱싱된 텍스트 청크를 검색하고 요약 답변을 생성하는 데 그쳤습니다. 반면 도구 실행 아키텍처에서는 다음 프로세스가 진행됩니다:

1. 스키마 노출: Dust는 연동된 도구의 입출력 명세(OpenAPI 또는 MCP에서 파생된 JSON Schema)를 LLM에 메타데이터로 제공합니다.
2. 의도 파악 및 파라미터 추출: LLM은 대화 맥락에서 작업 의도를 파악하고, 호출에 필요한 필드(이슈 요약, 거래 ID, 우선순위 등)를 구조화된 형태로 추출합니다.
3. 보호된 파라미터 주입: API 베이스 URL, 환경 식별자, 테넌트 ID 등 LLM이 추측해서는 안 되는 정적 매개변수를 Dust가 안전하게 결합하며, 이 값들은 모델에 노출되지 않습니다.
4. 휴먼 인 더 루프(Human-in-the-Loop) 승인: 데이터 변경을 유발하는 고위험 액션의 경우 실행 전 사용자 확인 모달을 띄워 승인을 요구합니다.
5. 상태 피드백 및 연속성: 외부 API의 실행 결과가 대화 스레드로 반환되어 어시스턴트가 성공 여부를 보고하고 후속 작업을 이어갑니다.

1단계: OpenAPI 엔드포인트를 커스텀 MCP 서버로 패키징

Dust는 Model Context Protocol(MCP)을 기본 프로토콜로 채택하고 있습니다. 사내에서 운영 중인 OpenAPI 3.0 사양의 REST 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/deals/{dealId} 엔드포인트를 실행 도구로 노출
server.tool(
  "update_crm_deal_stage",
  "CRM 파이프라인 내 영업 기회의 단계와 수주 확률을 업데이트합니다",
  {
    dealId: z.string().describe("영업 기회의 고유 영숫자 식별자(ID)"),
    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} 단계로 변경되었습니다. 레코드 ID: ${data.id}` }],
    };
  }
);

Dust 전용 스키마를 활용한 정적 파라미터 사전 구성

운영 환경에서는 배포 대상 환경(Staging/Production), 고유 프로젝트 키, 테넌트 ID와 같은 시스템 변수가 LLM의 추론에 맡겨져서는 안 됩니다. 모델 환각으로 인해 잘못된 환경으로 쓰기 요청이 발생하는 것을 방지해야 합니다.

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",
  "지정된 엔지니어링 대기열에 고우선순위 인시던트 티켓을 생성합니다",
  {
    // 대화 맥락으로부터 LLM이 동적으로 추출하는 파라미터
    summary: z.string().describe("인시던트 요약 제목"),
    description: z.string().describe("상세 장애 현상 및 재현 절차"),
    priority: z.enum(["P1", "P2", "P3"]).describe("인시던트 심각도 등급"),

    // Dust 어시스턴트 설정 UI에서 정적으로 바인딩되며 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 });
  }
);

2단계: Dust 워크스페이스 도구 등록 및 인증 자격 증명 관리

MCP 서버가 공용 HTTPS 주소로 배포되면 워크스페이스 관리자가 Dust 시스템에 도구를 등록합니다.

도구 등록 절차

1. Dust 대시보드에서 Spaces > Tools 메뉴로 이동합니다.
2. Add Tool 버튼을 클릭합니다.
3. Jira, HubSpot, Salesforce 등 기본 상용 도구는 목록에서 선택하고, 자체 개발한 OpenAPI/MCP 서버는 Add MCP Server를 선택합니다.
4. 공개 HTTPS URL을 입력하여 초기 동기화를 완료합니다.

자격 증명 모델 선택: 개인 자격 증명 vs 공유 자격 증명

인증 모델의 선택은 사내 보안 감사와 권한 분리에 결정적인 영향을 미칩니다:

네트워크 및 방화벽 설정

사내 인프라 내부의 서비스를 연동하는 경우:

• 고정 송신 IP(Static Egress IPs): Dust 관리자 화면에서 도메인 소유권을 인증하면 Dust의 고정 송신 IP 대역을 활성화할 수 있으며, 이를 기업 방화벽의 인바운드 허용 목록에 등록합니다.
• OAuth 콜백 URL 등록: 정적 OAuth 사용 시 대상 인증 시스템에 워크스페이스 리전별 콜백 주소를 등록해야 합니다:
  • 미국 워크스페이스: https://dust.tt/oauth/mcp_static/finalize
  • 유럽 워크스페이스: https://eu.dust.tt/oauth/mcp_static/finalize
  • 글로벌 공용 엔드포인트: https://app.dust.tt/oauth/mcp_static/finalize

3단계: 안전 가드레일 및 휴먼 인 더 루프(Human-in-the-Loop) 승인 체계

AI 어시스턴트에게 운영 시스템에 대한 생성, 수정, 삭제(Write) 권한을 부여할 때는 프롬프트 주입이나 모델의 오작동을 차단할 안전장치가 필수적입니다.

1. 고위험 도구 플래그(High Stake)

CRM 거래 단계 변경이나 Jira 티켓 상태 전환 등 프로덕션 데이터를 변경하는 도구를 연결할 때 관리자는 해당 도구를 HIGH STAKE로 지정할 수 있습니다.

• 작동 방식: 어시스턴트가 도구 호출을 결정하면 백그라운드에서 임의로 실행되지 않고, 대화창에 전송할 파라미터 내역이 표시된 확인 카드가 나타납니다.
• 사용자 승인: 권한을 가진 사용자가 Approve를 클릭해야만 실제 API 요청이 발송됩니다.
• 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 옵션을 체크합니다.

• 해당 도구가 일반 어시스턴트 생성기의 도구 목록에서 숨겨져 일반 사용자가 무분별하게 추가하는 것을 방지합니다.
• 안전 지침과 엄격한 검증 로직이 사전 패키징된 전용 '스킬(Skills)'을 통해서만 호출될 수 있도록 제한됩니다.

3. 스페이스(Spaces) 기반 권한 격리

민감한 쓰기 권한 도구를 특정 제한된 스페이스(Restricted Space)에만 배치합니다. 이를 통해 해당 스페이스에 소속된 인가된 운영 팀원만이 해당 도구가 탑재된 어시스턴트를 활용할 수 있도록 물리적으로 통제합니다.

4단계: 안정적인 실행을 위한 Agent Builder 프롬프트 엔지니어링

도구가 연동된 후 어시스턴트가 작업 시점을 정확히 판단하고 유효한 매개변수를 생성할 수 있도록 시스템 지침(Instructions)을 체계적으로 작성해야 합니다.

프로덕션 프롬프트의 4대 핵심 구조

1. 역할 정의 및 업무 경계: 어시스턴트의 고유 책임 영역과 금지 행위를 명시합니다.
2. 사전 검증 절차 의무화: 쓰기 작업을 호출하기 전에 반드시 조회 도구를 실행하여 현재 상태를 확인하도록 강제합니다.
3. 파라미터 추출 및 서식 규칙: 필수 항목 추출 논리, 기본값, 텍스트 제한을 구체화합니다.
4. 예외 처리 및 가이드: 인증 오류 또는 API 에러 발생 시 사용자에게 명확한 해결 가이드를 제공합니다.

운영 인시던트 분류 및 CRM 연동 어시스턴트 지침 예시

# 역할 및 책임
당신은 테크니컬 오퍼레이션 지원 에이전트입니다. 고객이 보고한 인시던트 내용을 접수하고, CRM의 고객 계약 데이터를 조회하여 일치 여부를 검증한 후, 엔지니어링 팀을 위한 Jira 티켓을 규격에 맞게 생성하는 임무를 수행합니다.

# 도구 호출 프로토콜

## 1. 고객사 계약 확인 (HubSpot)
- 티켓을 생성하기 전 반드시 `Get Object By Email` 또는 `Search Crm Objects`를 실행하여 고객 계정을 조회하세요.
- 고객의 현재 서비스 등급(Tier)과 활성 거래 상태를 확인하세요.
- 고객 등급이 "Enterprise"인 경우 인시던트 심각도를 자동으로 P1으로 상향 조정하세요.

## 2. Jira 이슈 생성 (Jira)
- 사용 도구: `create_issue`
- 요약(summary)은 50자 이내로 명확하게 작성하며, 형식은 `[모듈명] 장애 핵심 요약`을 따르세요.
- 설명(description)에는 다음 3개 섹션을 반드시 포함하세요:
  1. 고객사 정보 (회사명, 담당자 이메일, 계약 등급)
  2. 발생 장애 증상 및 오류 로그 요약
  3. 초기 재현 절차 및 관련 링크
- 이슈 유형은 "Bug"로, 컴포넌트는 "Production-Ops"로 고정 지정하세요.

## 3. 안전 확인 및 에러 대응
- 활성 영업 기회 단계를 변경하거나 티켓을 종료하는 작업은 실행 전 사용자에게 파라미터를 제시하고 확인을 받으세요.
- 도구 호출 중 401 인증 오류가 반환되면 사용자에게 다음과 같이 안내하세요: "우측 상단 사용자 메뉴의 'Tools & Triggers'에서 Jira/HubSpot 개인 인증을 다시 연결해 주시기 바랍니다."

5단계: 웹훅 트리거를 통한 비대면 완전 자동화 파이프라인

어시스턴트는 사용자가 채팅창에 입력할 때뿐만 아니라, 외부 시스템의 이벤트 발생에 반응하여 작업을 자율적으로 수행할 수도 있습니다. 실행 도구와 Dust의 **웹훅 트리거(Webhook Triggers)**를 결합하면 무인 자동화 워크플로가 완성됩니다.

+--------------------------+          HTTP POST 이벤트          +-----------------------------+
| 외부 비즈니스 시스템     | ---------------------------------> | Dust Webhook Source         |
| (Jira, GitHub, Zendesk,  |                                    | (Spaces > Triggers)         |
| 사내 모니터링 경보)      |                                    +--------------+--------------+
+--------------------------+                                                   |
                                                                               | 페이로드 검증 및 서명 확인
                                                                               v
+--------------------------+          Action 도구 호출          +-----------------------------+
| 대상 시스템              | <--------------------------------- | Dust 어시스턴트 자율 실행   |
| (HubSpot 데이터 동기화 / |                                    | (이벤트 분석, 조건 필터링,  |
| Slack 채널 리포트 발행)  |                                    | 외부 도구 호출로 루프 완료) |
+--------------------------+                                    +-----------------------------+

웹훅 자동화 구성 절차

1. 웹훅 소스 생성 (관리자 작업):
   • 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 데이터를 어시스턴트 컨텍스트에 전달합니다.
   • 실행 프롬프트(예: "페이로드의 오류 내용을 바탕으로 내부 지식 문서를 검색한 뒤, 해당 Jira 이슈에 초기 해결 권고 댓글을 작성하라")를 입력합니다.
   • 트래픽 폭증 시 크레딧 고갈을 방지하기 위해 24시간 호출 한도(Rate Limits)를 설정합니다.

통합 방식별 비교 및 의사결정 매트릭스

요구사항과 개발 자원에 따라 최적의 도구 연동 방식을 선택할 수 있습니다:

프로덕션 배포 전 점검 체크리스트

워크플로 실행 어시스턴트를 실무 환경에 공개하기 전 다음 항목들을 반드시 점검하십시오:

• 인증 모드 적합성: 데이터 수정 작업을 수행하는 도구에 개별 감사 로그를 남기기 위한 Personal 인증이 적용되었는가? (공유 계정 사용 시 최소 권한이 적용되었는가?)
• High Stake 설정 확인: 고객 정보, 영업 기회, 프로덕션 티켓을 변경하는 모든 쓰기 도구에 High Stake 승인 모달이 설정되어 있는가?
• 정적 파라미터 은닉: 환경 설정값, 프로젝트 키 등이 ConfigurableToolInputSchemas를 통해 정적으로 바인딩되어 모델 환각으로부터 격리되었는가?
• 오류 처리 프롬프트 완비: 토큰 만료나 API 장애 발생 시 사용자에게 재인증 경로를 안내하는 프롬프트가 지침에 포함되어 있는가?
• 방화벽 IP 허용: 사내 인프라의 MCP 서버에 대해 Dust의 고정 송신 IP 대역이 인바운드 허용 목록에 등록되어 있는가?
• 웹훅 호출 한도 설정: 자동화 웹훅 트리거에 24시간 실행 제한이 설정되어 예기치 못한 호출 급증을 방지하고 있는가?

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