Skip to main content

Dust Integration

📚

Prerequisites​

  • You must have admin access in Dust.
  • You’ll need a Coalesce Catalog API Token. If you don’t have one, reach out to the Catalog ops team to request a new token.

Installation​

Summary​

✅ The Dust agent is created at the workspace level. Once set up, it will be accessible to all users in your workspace.

Creating a new Dust agent to work with our AI Assistant is quick and easy:

  1. Set the Catalog API Token as a Dust app secret (CATALOG_API_TOKEN)
  2. Create a new Dust app that can call the Catalog public API
  3. Create a new Dust agent that uses the app above as a tool to send results from the Catalog AI Assistant to your Dust users

Set the Catalog API Token as a Dust app secret​

🔒Secrets usable in Dust apps to avoid showing sensitive data in blocks definitions.

  • Go to Admin tab on the top left menu
  • Go to Developers > Secrets on the left menu
  • Click on the Create Secret button
  • Set the new secret CATALOG_API_TOKEN with its value and then click Create

Create a new Dust app​

♻️

  • This app will act as a tool for the agent.

  • It will use the Catalog public API, authenticated with the API Token defined earlier as a secret.

  • The app will follow two main steps:

    • Send the user's question, email, and the Dust conversationId to the Catalog AI Assistant, and receive a jobId in return.
    • Poll the Catalog public API to retrieve the AI Assistant’s response using the jobId.

  • Create the new empty app coalesceAiAssistant

    Screen Recording 2025-06-16 at 13.54.26.mov

    • Go to Spaces tab in the top left menu
    • Go to Open Spaces > Apps
    • Click on Create a new app button
      • app name: coalesceAiAssistant
      • app description: Calling the Catalog AI Assistant to answer your question and show helpful assets

  • Add the app logic

    • Build the app blocks according to the document below

    Dust app code blocks

Create a new Dust agent​

♻️ The CoalesceAIAssistant agent will use the app created above as a tool to interact with the Catalog public API, then return the final response to the user.

  • Create a new agent with an instruction prompt

    Screen Recording 2025-06-16 at 13.54.26.mov

    • Click on Create > New Agent

    • Set Advanced settings

      • Model selection: Claude Sonnet (recommended)
      • Creativity level: Deterministic (recommended)

    • Copy and paste this prompt and then click on Next

      Dust agent main prompt

  • Assign the coalesceAiAssistant app created above as a tool

    Screen Recording 2025-06-16 at 14.24.17.mov

    • Remove all existing tools
    • Click on Add tools > Run Dust app
    • Select the coalesceAiAssistant app then click on Save
    • Click on Next

  • Configure the global settings and publish the agent

    • Name the agent CoalesceAiAssistant
    • Update the agent icon
    • Test the agent in the bottom-right corner before publishing
    • Set the access to Published

Debug​

  • Tool inspection in the chat

    Screen Recording 2025-06-17 at 14.45.33.mov

    You can click on Tool inspection directly in your chat box to view both the input and output of the tool.

  • Tool logs

    Screen Recording 2025-06-17 at 14.46.55.mov

    • Each response from CoalesceAiAssistant triggers a tool call (coalesceAiAssistant).
    • You can view a detailed log of every call, including step-by-step output, by going to the app > Logs > API.

Update​

  • Since the Dust agent uses our AI Assistant public API, any updates to the AI Assistant will automatically be reflected in Dust.
    • Updates on the Catalog side are designed to be backward compatible.
    • We’ll let you know if any update requires action on your part.
  • As the Dust app and agent are installed in your Dust workspace, you’re responsible for updating them if needed. Catalog will notify you if an update is required.