Konfiguration von benutzerdefinierten Actions und OpenAPI-Tools in Dust: Konversationsassistenten zu automatisierten Workflow-Executoren ausbauen

Die Einführung generativer KI in Unternehmen beginnt typischerweise mit dialogbasierten Wissenssystemen. Betriebsteams (Operations) binden Dokumentenspeicher wie Notion, Google Drive oder interne Wikis an, um Mitarbeiteranfragen mittels Retrieval-Augmented Generation (RAG) zu beantworten. Sobald Geschäftsprozesse jedoch das Verändern von Datensätzen, das Aktualisieren von Systemzuständen oder das Erstellen von Tickets erfordern, stößt die rein passive Dokumentenabfrage an ihre Grenzen: Ein Assistent, der lediglich erklärt, wie ein Jira-Ticket angelegt oder ein CRM-Deal aktualisiert wird, überlässt die eigentliche Arbeitsausführung weiterhin dem menschlichen Mitarbeiter.

Dust löst diese Barriere durch eine native Architektur für Werkzeuge und Aktionen (Tools & Actions) in Verbindung mit dem offenen Model Context Protocol (MCP). Durch die Bereitstellung von REST-APIs nach OpenAPI-3.0-Spezifikation sowie Standard-SaaS-Schnittstellen als interaktive Tools können Operations-Teams dialogorientierte Assistenten in proaktive Workflow-Executoren transformieren. Dieser Leitfaden beschreibt, wie Teams benutzerdefinierte Actions und OpenAPI-Tools einrichten, Authentifizierungsmodelle verwalten, Sicherheits-Guardrails etablieren und geschlossene operative Automatisierungskreisläufe aufbauen.

Architektonischer Wandel: Von passiver Textabfrage zu aktiver Workflow-Ausführung

Um einen Assistenten vom passiven Abfrage-Bot zum aktiven Prozessausführer weiterzuentwickeln, ist das Verständnis der internen Tool-Orchestrierung von Dust entscheidend:

+-----------------------------------------------------------------------------------+
|                                 Dust Workspace                                    |
|                                                                                   |
|   +-----------------------+              +------------------------------------+   |
|   | Benutzereingabe /     |              | Assistenten-Orchestrator           |   |
|   | Webhook-Ereignis      | ---------->  | (LLM + Systemanweisungen)          |   |
|   +-----------------------+              +-----------------+------------------+   |
|                                                            |                      |
|                                                            | Intent-Erkennung     |
|                                                            v                      |
|                                          +------------------------------------+   |
|                                          | Tool-Aufruf & Parameter-Injektion  |   |
|                                          +-----------------+------------------+   |
+------------------------------------------------------------|----------------------+
                                                             |
                     +---------------------------------------+---------------------------------------+
                     |                                                                               |
                     v                                                                               v
    +---------------------------------+                                             +---------------------------------+
    | Native Tools (Built-in)         |                                             | Eigener Remote-MCP / OpenAPI    |
    | (HubSpot, Jira, GitHub, Slack)  |                                             | (Interne APIs, Microservices)   |
    +----------------+----------------+                                             +----------------+----------------+
                     |                                                                               |
                     | OAuth (Personal oder Shared)                                                  | Bearer Token / Statisches OAuth / mTLS
                     v                                                                               v
    +---------------------------------+                                             +---------------------------------+
    | Enterprise-SaaS-Plattformen     |                                             | Interne Kernsysteme             |
    | (CRM-Deals, Ticket-Systeme)     |                                             | (ERP, Abrechnung, Datenbanken)  |
    +---------------------------------+                                             +---------------------------------+

Im klassischen RAG-Modell sucht das Sprachmodell nach Textfragmenten und fasst diese zusammen. Bei der Ausführung über Tools gilt folgender Ablauf:

1. Schema-Bereitstellung: Dust stellt dem Modell die JSON-Schema-Definitionen der verfügbaren Actions (abgeleitet aus OpenAPI- oder MCP-Definitionen) zur Verfügung.
2. Intent-Parsing und Parameter-Extraktion: Das Modell analysiert die Benutzereingabe und extrahiert strukturierte Parameter (z. B. Ticket-Zusammenfassung, Deal-ID oder Prioritätsstufen).
3. Injektion geschützter Parameter: Feste Systemwerte (wie Basis-URLs oder Mandanten-IDs) werden vor dem LLM verborgen und von Dust automatisch in den Request injiziert, wodurch Halluzinationen vermieden werden.
4. Human-in-the-Loop-Freigabe: Schreibende Operationen mit potenziell kritischen Auswirkungen werden angehalten, bis ein autorisierter Benutzer den Aufruf explizit bestätigt.
5. Rückmeldung und Kontextfortführung: Die Antwort der externen API fließt zurück in den Konversationsverlauf, sodass der Assistent das Ergebnis bestätigen und den Prozess fortführen kann.

Schritt 1: OpenAPI-Spezifikationen als benutzerdefinierte MCP-Server bereitstellen

Dust setzt standardmäßig auf das Model Context Protocol (MCP). Wenn Ihr Team über interne REST-APIs mit OpenAPI-3.0-Dokumentation verfügt (z. B. Kundenservice-Middleware oder Bereitstellungs-APIs), besteht der Best-Practice-Ansatz darin, einen schlanken MCP-Server als Wrapper bereitzustellen.

Standard-Tool-Definition mit dem TypeScript SDK

Mit dem offiziellen TypeScript MCP SDK und Zod-Validierung lassen sich typsichere Werkzeuge definieren:

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

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

// Bereitstellung eines OpenAPI PATCH /crm/deals/{dealId} Endpunkts als ausführbare Action
server.tool(
  "update_crm_deal_stage",
  "Aktualisiert die Pipeline-Phase und Abschlusswahrscheinlichkeit eines CRM-Deals",
  {
    dealId: z.string().describe("Eindeutige alphanumerische ID des Deals"),
    newStage: z.enum(["Qualified", "Proposal", "Contract_Sent", "Closed_Won", "Closed_Lost"]).describe("Zielphase der Pipeline"),
    closeNotes: z.string().optional().describe("Begründung und Kontextnotizen zum Phasenwechsel"),
  },
  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: `Fehler beim Deal-Update: ${response.statusText}` }],
        isError: true,
      };
    }

    const data = await response.json();
    return {
      content: [{ type: "text", text: `Deal ${dealId} erfolgreich in Phase ${newStage} überführt. Datensatz-ID: ${data.id}` }],
    };
  }
);

Vorkonfigurierte Parameter mit Dust-Schemas

In Unternehmensumgebungen dürfen sensible Umgebungsparameter wie Server-Endpunkte, Projekt-Schlüssel oder Staging-/Produktions-Schalter nicht der Schätzung des LLMs überlassen werden.

Über die Bibliothek @dust-tt/client können Entwickler vorkonfigurierbare Eingabeschemas definieren. Diese Felder werden im Dust-Assistenten-Builder vom Administrator statisch hinterlegt und bleiben für das Modell unsichtbar:

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",
  "Erstellt ein hochpriorisiertes Incident-Ticket im zugewiesenen Engineering-Board",
  {
    // Dynamisch vom Sprachmodell aus dem Gesprächskontext extrahiert
    summary: z.string().describe("Kurze Zusammenfassung des Incidents"),
    description: z.string().describe("Detaillierte Fehlerbeschreibung und Schritte zur Reproduktion"),
    priority: z.enum(["P1", "P2", "P3"]).describe("Dringlichkeitsstufe des Incidents"),

    // Im Dust Assistant Builder statisch konfiguriert; für das Modell verborgen
    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 });
  }
);

Schritt 2: Registrierung von Tools und Verwaltung von Anmeldedaten in Dust

Sobald der MCP-Server unter einer öffentlichen HTTPS-Adresse erreichbar ist, bindet der Workspace-Administrator das Werkzeug in Dust ein.

Registrierungsablauf

1. Navigieren Sie in Dust zu Spaces > Tools.
2. Klicken Sie auf Add Tool.
3. Wählen Sie für Standarddienste die native Integration (Jira, HubSpot, Salesforce) oder wählen Sie Add MCP Server für eigene OpenAPI/MCP-Dienste.
4. Geben Sie die öffentliche HTTPS-URL des MCP-Servers ein, um die Synchronisation abzuschließen.

Authentifizierungsstrategien: Persönliche vs. Geteilte Anmeldedaten

Die Wahl des Authentifizierungsansatzes ist entscheidend für Berechtigungsstrukturen und Compliance:

Netzwerksicherheit und Firewall-Freigaben

Für interne Unternehmensdienste:

• Statische Egress-IPs: Nach Verifizierung der Unternehmensdomäne in Dust sendet Dust Anfragen über feste IP-Adressen, die in Ihrer Unternehmens-Firewall freigeschaltet werden können.
• OAuth-Callback-URLs: Tragen Sie die passenden Weiterleitungs-URLs in Ihrem Identitäts-Provider ein:
  • US-Workspaces: https://dust.tt/oauth/mcp_static/finalize
  • EU-Workspaces: https://eu.dust.tt/oauth/mcp_static/finalize
  • Globales Gateway: https://app.dust.tt/oauth/mcp_static/finalize

Schritt 3: Sicherheits-Guardrails und Human-in-the-Loop etablieren

Erhalten KI-Assistenten Schreibrechte auf produktive Unternehmensdaten, sind Schutzmaßnahmen gegen Prompt-Injections und Fehlbedienungen unerlässlich.

1. High-Stake-Kennzeichnung für sensible Aktionen

Werkzeuge, die schreibende oder löschende Operationen durchführen (wie Deal-Updates im CRM oder Ticket-Abschlüsse in Jira), sollten als HIGH STAKE markiert werden.

• Ablauf: Der Assistent führt die Aktion nicht stillschweigend aus, sondern pausiert und blendet eine Bestätigungskarte mit allen Parametern ein.
• Freigabe: Erst wenn der Operator explizit auf Approve klickt, wird der API-Aufruf ausgelöst.
• API-Validierung: Bei programmatischen Workflows über die Dust Conversation API wird diese Bestätigung über den Endpunkt POST /api/v1/w/{wId}/assistant/conversations/{cId}/messages/{mId}/validate-action abgewickelt.

2. Werkzeuge auf Skills beschränken (Restrict to Skills)

Aktivieren Sie unter Spaces > Tools die Option Restrict this tool to skills.

• Das Werkzeug wird aus dem allgemeinen Assistenten-Baukasten entfernt und steht nicht für Ad-hoc-Assistenten zur Verfügung.
• Der Zugriff wird ausschließlich über zertifizierte Skills gewährt, die strikte Validierungs- und Sicherheitsinstruktionen mitbringen.

3. Isolation durch Spaces

Schreibberechtigte Tools können in geschützten Bereichen (Restricted Spaces) isoliert werden, sodass nur autorisierte Mitglieder Zugriff auf Assistenten mit diesen Fähigkeiten erhalten.

Schritt 4: Anweisungen im Agent Builder für zuverlässige Ausführung strukturieren

Die Zuverlässigkeit eines Workflow-Executors hängt maßgeblich von der Qualität der Systemanweisungen (Instructions) ab.

Kernelemente eines produktionsreifen Prompts

1. Rollen- und Zuständigkeitsgrenzen: Definition des klaren Aufgabenbereichs und unzulässiger Aktionen.
2. Vorab-Validierung: Verpflichtung, vor jedem Schreibvorgang den aktuellen Status über Lese-Tools abzufragen.
3. Parameterextraktion und Formatregeln: Exakte Kriterien für Pflichtfelder und Standardwerte.
4. Fehlerbehandlung und Wiederherstellung: Konkrete Handlungsanweisungen bei abgelaufenen Tokens oder Serverfehlern.

Beispiel: Assistent für Incident-Triage und CRM-Abgleich

# Rolle und Verantwortlichkeiten
Du bist der technische Incident-Triage-Assistent. Deine Aufgabe besteht darin, gemeldete Störungen mit Kundenverträgen im CRM abzugleichen und strukturierte Jira-Tickets für das Engineering-Team zu erstellen.

# Protokolle für Tool-Aufrufe

## 1. CRM-Vertragsprüfung (HubSpot)
- Bevor ein Ticket erstellt wird, suche das Kundenkonto über `Get Object By Email` oder `Search Crm Objects`.
- Ermittle das Support-Level (Tier) und den Status aktiver Deals.
- Bei Kunden mit "Enterprise"-Vertrag muss die Ticket-Priorität automatisch auf P1 gesetzt werden.

## 2. Jira-Ticketerstellung (Jira)
- Tool: `create_issue`
- Der Titel (summary) muss prägnant unter 60 Zeichen formatiert sein: `[Modulname] Kurze Fehlerbeschreibung`.
- Die Beschreibung (description) muss zwingend drei Abschnitte enthalten:
  1. Kundenkontext (Unternehmen, Kontakt, Support-Level)
  2. Fehlersymptome und aufgetretene Fehlermeldungen
  3. Schritte zur Reproduktion und relevante Log-Links
- Setze den Typ immer auf "Bug" und die Komponente auf "Production-Ops".

## 3. Sicherheitsabfragen und Fehlerbehebung
- Bei Statusänderungen aktiver Deals oder Ticket-Schließungen müssen alle Parameter vorab zur Bestätigung ausgegeben werden.
- Antwortet ein Tool mit HTTP 401 (Authentifizierungsfehler), instruiere den Nutzer: "Bitte öffnen Sie das Nutzermenü oben rechts unter 'Tools & Triggers' und verbinden Sie Ihre persönlichen Zugangsdaten für Jira/HubSpot neu."

Schritt 5: Vollautomatisierung durch Webhook-Trigger

Neben interaktiven Chat-Eingaben können Assistenten durch Ereignisse aus Drittsystemen über Webhook-Trigger in Dust vollautomatisiert gestartet werden.

+--------------------------+          HTTP-POST-Ereignis        +-----------------------------+
| Externes System          | ---------------------------------> | Dust Webhook-Quelle         |
| (Jira, GitHub, Zendesk,  |                                    | (Spaces > Triggers)         |
| internes Monitoring)     |                                    +--------------+--------------+
+--------------------------+                                                   |
                                                                               | Payload- & HMAC-Prüfung
                                                                               v
+--------------------------+          Führt Tool-Aktion aus     +-----------------------------+
| Zielplattform            | <--------------------------------- | Dust Assistenten-Ausführung |
| (CRM-Update /            |                                    | (Analysiert Event, filtert  |
| Slack-Benachrichtigung)  |                                    | und schließt Workflow ab)   |
+--------------------------+                                    +-----------------------------+

Einrichtung des Webhook-Workflows

1. Webhook-Quelle anlegen (Administrator):
   • Öffnen Sie Spaces > Triggers und wählen Sie Add source.
   • Wählen Sie einen Standard-Provider (Jira, GitHub, Linear, Zendesk) oder Custom webhook.
   • Für eigene Webhooks können Sie eine HMAC-Signaturprüfung (sha256) aktivieren, um unautorisierte Aufrufe abzuwehren.
2. Trigger an Assistenten binden:
   • Wählen Sie im Agent Builder unter Triggers > Add triggers die Quelle aus.
   • Definieren Sie Ausführungsbedingungen in natürlicher Sprache (z. B.: "Nur ausführen, wenn die Ticket-Priorität High ist und der Status auf Escalated wechselt").
   • Aktivieren Sie Include webhook payload, um den JSON-Inhalt an den Assistenten zu übergeben.
   • Formulieren Sie die Ausführungsanweisung (z. B.: "Analysiere den Fehlerbericht im Payload, suche Lösungen im Wiki und erstelle einen Lösungsvorschlag als Kommentar im Jira-Ticket").
   • Konfigurieren Sie ein 24-Stunden-Ratenlimit (Rate Limits), um unbeabsichtigte Kosten durch Ereignis-Kaskaden zu verhindern.

Vergleich der Integrationsarchitekturen

Wählen Sie die passende Architektur anhand Ihrer funktionalen Anforderungen und Sicherheitsvorgaben:

Checkliste vor dem Produktivgang

Prüfen Sie vor der Freigabe für operative Teams folgende Punkte:

• Passendes Authentifizierungsmodell: Wurden schreibende Werkzeuge mit Personal Credentials konfiguriert, um lückenlose SaaS-Audit-Logs sicherzustellen?
• High-Stake-Schutz aktiv: Sind alle Aktionen, die Geschäftsdaten verändern oder löschen können, mit einer Freigabepflicht versehen?
• Sensible Parameter abgeschirmt: Werden Umgebungs-URLs und Mandantenschlüssel über ConfigurableToolInputSchemas statisch injiziert statt vom Modell generiert?
• Robuste Fehlerbehandlung: Enthalten die Anweisungen klare Handlungsleitfäden für den Fall von Authentifizierungs- oder Netzwerkfehlern?
• Netzwerk-Freigaben: Wurden die statischen Egress-IPs von Dust in den Firewalls vor internen MCP-Servern freigeschaltet?
• Ratenbegrenzung bei Webhooks: Sind automatisierte Trigger mit 24-Stunden-Obergrenzen gegen Lastspitzen abgesichert?

Durch die Kombination von OpenAPI-Standards, MCP-Werkzeugen und transparenter Rechteverwaltung verwandeln Operations-Teams Dust-Assistenten von reinen Frage-Antwort-Systemen in zuverlässige operative Ausführungseinheiten.

Referenzen

• 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