Conversational UI

Last modified: August 20, 2024

Introduction

With the Conversational UI module, you can create an AI-based chat user interface. It contains the needed data model, pages, snippets and building blocks to do so. You can integrate with any LLM and knowledge base to create your own full screen, sidebar or modal chat. It integrates with the Atlas framework and is the basis for the AI Bot Starter App. It is also included in the Blank GenAI App.

Mendix has produced a Conversational AI Design Checklist which suggests some best practices for introducing conversational AI into your app.

Typical Use Cases

Typical use cases include the following:

Create a chat interface for users to chat with Large Language Models (LLM).
Allow users to switch between different implementations by switching providers.
Include advanced capabilities to control the model’s behavior, for example by setting the temperature parameter.
Easily extend the chat interface with advanced concepts, such as RAG or the ReAct pattern. For more information, see Using Generative AI.

Features

The Conversational UI module provides the following functionalities:

UI components that you can drag and drop onto your pages, for example:
- Layouts to have a sidebar or floating popup chat
- Pages that you can use in your navigation for chat
- Snippets that you can use directly on your pages, for example to display messages or a history sidebar
- A floating button that for opening a chat
Operations to set up your context, interact with the model, and add the data to be displayed in the UI
Domain model to store the chat conversations and additional information
Integration with any model that is compatible with GenAI Commons

Limitations

This module is intended to enable chat interactions between a user and an AI model. It is not designed for conversations between two human users.

Prerequisites

To use the Conversational UI module, your Mendix Studio Pro version must be 9.24.2 or higher.

You must also ensure that you have the prerequisite modules that Conversational UI requires. The modules are included by default in the Blank GenAI App and the AI Bot Starter App, otherwise you must install them yourself:

Finally, you must also install and configure a connector that is compatible with GenAI Commons. Mendix provides platform-supported integration with either (Azure) OpenAI or Amazon Bedrock. You can also integrate with custom models, by making them compatible with the GenAI Commons Request and Response.

Installation

Follow the instructions in Using Marketplace Content to import the Conversational UI into your app.

Configuration

To use Conversational UI in your app, you must perform the following tasks:

Configure the relevant user roles.
Create a chat context.
Associate a provider and create an action microflow.
Use the pages and snippets to create your UI.

Technical Reference

To help you work with the Conversational UI module, the following sections of this document list the available entities and activities that you can use in your application.

Module Roles

Make sure that the module role User is part of the user roles that are intended to chat with the model. Optionally, you can grant the _addOn_ReadAll role to admin roles, so that users with that role can read all messages.

Module role	Description
`User`	Role needed for every user that should be able to interact with the chat components. Users can only read their own messages (and related data).
`_addOn_ReadAll`	Role can be granted additionally. Users with both roles can read all data.

ChatContext

The ChatContext is the central entity in the UI and microflows. It can only be viewed by the owner (see Module Roles for exceptions). The object needs to be created for every new chat interaction and comprises the messages that are sent to and received from the model. A ProviderConfig should be associated via ChatContext_ProviderConfig_Active in order to execute the correct action microflow.

If you need additional attributes or associations on the ChatContext, use an extension entity that refers to the object which can then be retrieved and altered when needed (for example in the action microflow). The AI Bot Starter App shows an example of this approach.

Chat Context Operations

The following operations can be found in the toolbox for processing the ChatContext:

Create ChatContext & Set ActionMicroflow creates a new ChatContext and a new ProviderConfig (or a specialization of such depending on the input). The ProviderConfig is added to the ChatContext and set to active. Additionally, the action microflow of the new ProviderConfig is set.
Create ChatContext & Set ProviderConfig creates a new ChatContext and sets a given ProviderConfig to active.
Create ChatContext & Set ProviderConfig (List) creates a new ChatContext and adds a ProviderConfig to the ChatContext and sets it to active. In addition, a list of ProviderConfigs can be added to the ChatContext (non-active, but selectable in the UI).
Set ConversationID sets the ConversationID on the ChatContext. Storing the ConversationID is needed for chat with history within Retrieve and Generate with Amazon Bedrock.
Set Topic sets the Topic of the ChatContext. This attribute can be used in the History sidebar while making historical chats visible to users.

Request Operations

Create Request from ChatContext creates a Request object that is used as input parameter in a Chat with History operation as part of the action microflow. For more information about the Chat with History operation, see (Azure) OpenAI or Amazon Bedrock.
Get Current User Prompt gets the current user prompt. It can be used in the action microflow, because the CurrentUserPrompt from the chat context is no longer available.
Update Assistant Response processes the response of the model and adds the new message and any sources to the UI. This is typically one of the last steps of the logic in an action microflow.

Message

A Message contains the content of both user and assistant messages, distinguishable by the Role attribute (such as User or Assistant).

Source

The model can return Sources which can be added to a message and displayed in the UI for the user. This can increase the understanding of the reasoning process, for example, why a model came up with a specific response. The content of the sources can come from a knowledge base or the model, depending on the implementation.

SuggestedUserPrompt

It is possible to add suggested user prompts to a ChatContext. They appear as a button for new chats. When a user clicks the Suggested User Prompt that appears above the chat input box, the action microflow sends the content of the prompt to the model and starts a predefined chat in the interface. New SuggestedUserPrompts can be created and added to a ChatContext with the Add SuggestedUserPrompt toolbox action.

AdvancedSettings

AdvancedSettings can be used to allow users to configure parameters which can influence the model’s behavior (see Configuration Snippets). Currently, only temperature is exposed to users in the module by the slider input element. The object needs to be created when the chat context is shown to the page, for example in a navigation flow. Ranges can be set to control the values a user can select.

ProviderConfig

The ProviderConfig contains the selection of the model provider for the AI Bot to chat with. This contains an action microflow that is executed when the Send button is clicked. You can store additional information, such as connection details, on the ProviderConfig by using a specialization and adding the necessary fields. For an example implementation, see the AI Bot Starter App.

The Create ProviderConfig for ChatContext toolbox action adds a new ProviderConfig (or a specialization of such depending on the input) to a ChatContext. The ProviderConfig can optionally also be set to active if IsActive is set to true. Additionally, the action microflow of the new ProviderConfig is set.

Action Microflow

The Action Microflow is executed by clicking the Send button. It handles the interaction between the LLM connectors and the Conversational UI entities. An example for each are provided in The USE_ME folder included in the Conversational UI module contains example action microflows for both OpenAI and Amazon Bedrock. You can copy these microflows and modify them for your use cases, or use them directly for test purposes.

Using the Action Microflow

Add the action microflow to an existing ProviderConfig by using the Set ActionMicroflow toolbox action. Note that the action does not commit the object, so you must also add a step to commit it after.

Creating a Custom Action Microflow

If you want to create your own custom action microflow, keep the following considerations in mind:

Only one input parameter of ChatContext is accepted.
The return type needs to be a Success Boolean.
Use the request operations to facilitate the interaction between the chat context and the model.
When creating the ProviderConfig, use Set ActionMicroflow to set the microflow.

Pages and Layouts

You can include the following pages in your navigation, or copy them to your module and modify them to suit your use case:

ConversationalUI_FullScreenChat - This page displays a centered chat interface on a full screen responsive page.
ConversationalUI_PopUp - This is a floating pop-up in the bottom-right corner. To open it, users can click the Snippet_FloatingChatButton that floats in the bottom-right corner. Alternatively, you can use the building block Floating Button OpenChat from the toolbox to create your custom opening logic.
ConversationalUI_Sidebar - This page displays the chat interface on the right side with the full height.

All pages expect a ChatContext that needs to have an active ProviderConfig. The user can chat with the LLM on all pages, but not configure any additional settings, such as the model or system prompt. This needs to happen before the page was opened, for example, or in the action microflow that is stored in the active ProviderConfig.

Snippets

Drag the following snippets onto your other pages to quickly build your own version of the chat interface.

Chat Interface Snippets

Chat interface snippets contain the whole chat history as a list view, and below that a text area for users to enter the user prompt. There are some UI components that show an error message, when a call has failed, or that show progressing loading bots when waiting for the response. When a user clicks the Send button, the action microflow is executed.

The following versions are available and can be swapped as needed:

Snippet_ChatContext_ConversationalUI - This snippet shows both the user messages and the responses on the left side of the container.
Snippet_ChatContext_ConversationalUI_Bubbles - This snippet shows the user messages on the right side and the responses on the left side, similarly to common chat apps. The content is placed inside colored cards (bubbles).

If the snippet does not fit your use case, you can inline the snippet to customize it to your needs.

Message Snippets

The messages snippets are already part of the Chat Interface Snippets, but can be used individually in your custom setup. They contain the content of the messages list view.