AI Assistant

GoodData.UI provides a React component for embedding of the chat interface for AI Assistant.

AI Assistant

Prerequisites

Before you can use the AI Assistant, you need to make sure it is properly set up in GoodData Cloud. For detailed instructions, see Configure AI Assistant.

If you are using GoodData.CN, some additional configuration may be required. For details, see the AI in GoodData.CN section of the article.

AI Assistant Component Features

  • Embed UI for the AI Assistant chat.
  • Subscribe to chat events.
  • Handle links in chat messages.
  • Theming is supported out of the box through Theme Provider.
  • Customization of the initial assistant experience (welcome content and suggested questions).
  • Dedicated conversations list component for split-layout integrations.
  • Shared GenAiStore wrapper for synchronizing GenAIAssistant and GenAIConversations in one Redux store.

Basic integration example

GenAIAssistant component renders chat history and an input field for sending user messages. It does not include the logic for overlay management in case you want to render it in a floating window.

import {
    GenAIAssistant,
    ChatUserMessageEvent,
    isChatUserMessageEvent,
    LinkHandlerEvent,
} from "@gooddata/sdk-ui-gen-ai";

// Import required styles
import "@gooddata/sdk-ui-gen-ai/styles/css/main.css";

const App = () => {
    return (
        <div style={{ width: 500, height: 600, display: "flex" }}>
            {/* Wrap the chat UI in a container of desired size */}
            <GenAIAssistant
                // Optionally, add event listeners
                eventHandlers={[
                    {
                        eval: isChatUserMessageEvent,
                        handler: (event: ChatUserMessageEvent) => {
                            console.log(`User message: ${event.question}`);
                        },
                    },
                ]}
                // Optionally, provide links handler
                onLinkClick={(linkClickEvent: LinkHandlerEvent) => {
                    linkClickEvent.preventDefault();
                    console.log(`User click: ${linkClickEvent.itemUrl}`);
                    // E.g. when user asks the chatbot to find
                    // a specific dashboard and clicks on the result
                }}
                // Optionally, provide dispatcher for sending messages in the chat
                onDispatcher={(dispatch) => {
                    // Save dispatcher and use it to send messages
                }}
            />
        </div>
    );
};

Props

NameTypeDefaultDescription
localeILocale“en-US”Specifies the locale for internationalization
backendIAnalyticalBackend-Backend instance. Falls back to BackendProvider context if not specified
workspacestring-Workspace ID. Falls back to WorkspaceProvider context if not specified
colorPaletteIColorPalette-Color palette used for rendering the visualizations. If not provided, the default color palette will be used
catalogItemsCatalogItem[]-Catalog items used for autocompletion. If not provided - will be lazy-loaded when needed
settingsIUserWorkspaceSettings-Workspace settings used by the assistant UI
eventHandlersChatEventHandler[]-Event handlers for user interactions with the chat UI
onLinkClick(LinkHandlerEvent) => void-Handle user clicks on the catalog items mentioned in chat.
allowNativeLinksbooleanfalseWhether to allow native links in chat messages. If false, onLinkClick handler will be fired when clicking on links
disableManagebooleanfalseThis will disable manage permissions for the user even if the user has them defined.
disableAnalyzebooleanfalseThis will disable analyze permissions for the user even if the user has them defined.
disableFullControlbooleanfalseThis will disable full control permissions for the user even if the user has them defined.
objectTypesGenAIObjectType[]-Restricts object types used by assistant search and suggestions.
includeTagsstring[]-Includes only tagged metadata objects when assistant resolves relevant content.
excludeTagsstring[]-Excludes tagged metadata objects when assistant resolves relevant content.
onDispatcher(dispatch: EnhancedStore[“dispatch”]) => void-Dispatcher callback for assistant actions and state changes.
LandingScreenComponentProvider() => ComponentType-Factory for providing a custom initial assistant experience component. When omitted, the default landing screen with quick questions is displayed.
DisclaimerComponentProvider() => ComponentType | null-Factory for providing a custom disclaimer component shown in the assistant UI. Return null to hide disclaimer rendering.
classNamestring-Additional class name applied to the root assistant element.
isPreviewbooleanfalseInternal preview mode. Uses workspace preview agent and preview conversations. Toggling resets assistant state.

Conversations list component

Use GenAIConversations when you want to render conversation history and management UI separately from the assistant message pane (for example, in side-by-side layouts).

For a full split-layout wiring example that synchronizes both components (including conversation change/delete handling), see Assistant + Conversations integration.

import {
    GenAiStore,
    GenAIConversations,
    GenAIAssistant,
    setCurrentConversationAction,
    startNewConversationAction,
} from "@gooddata/sdk-ui-gen-ai";

import "@gooddata/sdk-ui-gen-ai/styles/css/main.css";

const App = () => {
    let dispatcher: (action: unknown) => void = () => undefined;

    return (
        <GenAiStore onDispatcher={(storeDispatch) => (dispatcher = storeDispatch)}>
            <GenAIConversations
                onConversationSelect={(conversation) => {
                    dispatcher(setCurrentConversationAction({ conversation }));
                }}
            />
            <GenAIAssistant />
            <button onClick={() => dispatcher(startNewConversationAction())}>New conversation</button>
        </GenAiStore>
    );
};

GenAIConversations props

NameTypeDefaultDescription
localeILocale“en-US”Specifies the locale for internationalization
backendIAnalyticalBackend-Backend instance. Falls back to BackendProvider context if not specified
workspacestring-Workspace ID. Falls back to WorkspaceProvider context if not specified
colorPaletteIColorPalette-Color palette used for rendering the visualizations
catalogItemsCatalogItem[]-Catalog items used for autocompletion. If not provided - will be lazy-loaded when needed
settingsIUserWorkspaceSettings-Workspace settings used for conversation list behavior
eventHandlersChatEventHandler[]-Event handlers for user interactions with the conversations UI
objectTypesGenAIObjectType[]-Restricts object types used by assistant search and suggestions
includeTagsstring[]-Includes only tagged metadata objects when assistant resolves relevant content
excludeTagsstring[]-Excludes tagged metadata objects when assistant resolves relevant content
onDispatcher(dispatch: EnhancedStore[“dispatch”]) => void-Dispatcher for conversation-level actions
onConversationSelect(conversation: IChatConversationLocal) => void-Called when the user selects a conversation
classNamestring-Additional class name applied to the root conversations element
isPreviewbooleanfalseInternal preview mode. Uses workspace preview agent and preview conversations only

Shared Store component

Use GenAiStore when you need to render multiple Gen AI UI components (GenAIAssistant, GenAIConversations, or custom wrappers) with a single synchronized state and dispatcher.

GenAiStore props

NameTypeDefaultDescription
backendIAnalyticalBackend-Backend instance. Falls back to BackendProvider context if not specified
workspacestring-Workspace ID. Falls back to WorkspaceProvider context if not specified
colorPaletteIColorPalette-Color palette used for rendering the visualizations
catalogItemsCatalogItem[]-Catalog items used for autocompletion
settingsIUserWorkspaceSettings-Workspace settings used by assistant and conversations components
eventHandlersChatEventHandler[]-Event handlers for user interactions emitted by child Gen AI components
objectTypesGenAIObjectType[]-Restricts object types used by assistant search and suggestions
includeTagsstring[]-Includes only tagged metadata objects when assistant resolves relevant content
excludeTagsstring[]-Excludes tagged metadata objects when assistant resolves relevant content
onDispatcher(dispatch: EnhancedStore[“dispatch”]) => void-Callback called after initialization with dispatcher for the active Gen AI store
childrenReactNode | ((genAIStore: EnhancedStore) => ReactNode)-Child component(s) or render function wrapped by the shared store
isPreviewbooleanfalseInternal preview mode. Uses workspace preview agent and preview conversations; toggling resets state

eventHandlers

Each event handler must comply with the following interface:

export interface ChatEventHandler<TEvent extends ChatEvent = any> {
    /**
     * A guard for a specific event type.
     */
    eval: (event: ChatEvent) => event is TEvent;
    /**
     * Event handler.
     */
    handler: (event: TEvent) => void;
}

@gooddata/sdk-ui-gen-ai provides a set of guards for all the events that can be emitted by the chat UI.

Here is a list of the relevant events:

Event nameGuard nameDescription
ChatResetEventisChatResetEventChat history was reset
ChatUserMessageEventisChatUserMessageEventUser sent a message
ChatAssistantMessageEventisChatAssistantMessageEventAssistant responded with a message
ChatFeedbackEventisChatFeedbackEventUser gave a feedback
ChatVisualizationErrorEventisChatVisualizationErrorEventVisualization failed to render
ChatSaveVisualizationErrorEventisChatSaveVisualizationErrorEventChat failed to save visualisation
ChatSaveVisualizationSuccessEventisChatSaveVisualizationSuccessEventChat successfully saved visualisation
ChatCopyToClipboardEventisChatCopyToClipboardEventChat copy to clipboard event
ChatConversationPinnedEventisChatConversationPinnedEventConversation pinned state changed
ChatConversationPinErrorEventisChatConversationPinErrorEventConversation pin/unpin failed
ChatConversationDeleteEventisChatConversationDeleteEventConversation delete requested
ChatConversationDeletedSuccessEventisChatConversationDeletedSuccessEventConversation deleted successfully
ChatConversationDeletedErrorEventisChatConversationDeletedErrorEventConversation delete failed
ChatConversationRenameEventisChatConversationRenameEventConversation rename requested
ChatConversationRenamedSuccessEventisChatConversationRenamedSuccessEventConversation renamed successfully
ChatConversationRenamedErrorEventisChatConversationRenamedErrorEventConversation rename failed
ChatConversationChangedEventisChatConversationChangedEventActive conversation changed

onLinkClick

Handle user clicks on the catalog items mentioned in chat. If not provided, catalog items will be rendered as plain text. Each event contains the following properties:

PropertyTypeDescription
typestringType of the metadata object the user clicked on. For example, “dashboard”, “metric” etc.
idstringThe ID of the metadata object
itemUrlstringThe URL of the metadata object, if opened in GoodData Web interface
newTabbooleanWhether the link should be opened in a new tab
preventDefault() => voidPrevent default behavior of the link click

Note: If allowNativeLinks is set to false (default), you must implement the onLinkClick handler to handle the links in chat messages. Otherwise, the links will not be clickable and do not have any effect.

Initial Assistant Experience

The initial assistant experience defines what users see before they send their first message to the AI Assistant. It is used to introduce the assistant, provide guidance, and offer suggested questions to help users get started. Once a user submits a question the assistant switches to the standard chat interface. By default, the AI Assistant displays a built-in initial experience with a title and quick questions, which you can fully replace or customize to match your application’s branding and guidance needs.

Customizing the initial assistant experience

To replace the default initial experience, provide the LandingScreenComponentProvider prop. This prop accepts a factory function that returns a React component type, which is rendered as the initial assistant experience. The provider must return a component type, not JSX.

import { GenAIAssistant } from "@gooddata/sdk-ui-gen-ai";
import "@gooddata/sdk-ui-gen-ai/styles/css/main.css";

const CustomLandingScreen = () => (
    <div style={{ padding: 24 }}>
        <h3>Welcome to the embedded assistant</h3>
        <p>Describe what you are looking for and we will prepare the right insight.</p>
    </div>
);

export const App = () => <GenAIAssistant LandingScreenComponentProvider={() => CustomLandingScreen} />;

The package exports building blocks used by the default initial assistant experience. You can use these components to apply custom branding or modify content while preserving the built-in layout, accessibility, and automated question behavior.

Available components:

  • DefaultLandingScreen
  • DefaultLandingTitle and DefaultLandingTitleAscent
  • DefaultLandingQuestion

To extend the default experience (for example, to customize the suggested questions), wrap DefaultLandingScreen in your own component and provide custom children:

import {
    DefaultLandingScreen,
    DefaultLandingQuestion,
    DefaultLandingTitle,
    DefaultLandingTitleAscent,
} from "@gooddata/sdk-ui-gen-ai";

const CustomDefaultLanding = () => (
    <DefaultLandingScreen>
        <DefaultLandingTitle>
            <DefaultLandingTitleAscent>Ask AI to explore your workspace</DefaultLandingTitleAscent>
            <br />
            Pick one of the suggestions below.
        </DefaultLandingTitle>
        <DefaultLandingQuestion
            question="Show revenue by product for 2024"
            answer="Here is the revenue by product for 2024"
        />
        <DefaultLandingQuestion question="What is our YoY trend?" answer="Here is the year-over-year trend" />
    </DefaultLandingScreen>
);

export const App = () => <GenAIAssistant LandingScreenComponentProvider={() => CustomDefaultLanding} />;

You can also reuse individual building blocks, such as DefaultLandingQuestion, inside a fully custom layout. This allows you to create a personalized introduction while keeping the pre-wired assistant behavior for suggested questions.

Each DefaultLandingQuestion automatically dispatches a user message and triggers the assistant response, using the same mechanism as the chat input.

const CustomLandingScreen = () => (
    <div className="my-company-landing">
        <h3>Welcome back!</h3>
        <p>Use the shortcuts to get started quickly.</p>
        <div className="my-company-landing__actions">
            <DefaultLandingQuestion
                question="List my top KPIs"
                answer="Here are your top KPIs"
                title="Top KPIs"
            />
            <DefaultLandingQuestion
                question="Create a new dashboard"
                answer="Here is a blank dashboard to start with"
                title="New dashboard"
            />
        </div>
    </div>
);

Use these building blocks to mix default styling and accessibility features with your own branding, while still benefiting from the automated assistant interactions.

Resetting the chat thread

To reset the chat thread, use the reset method on the ChatThread interface.

const chatThread = backend.workspace(workspaceId).genAI().getChatThread();

await chatThread.reset();

or dispatch clear thread action by using dispatcher

import { clearThreadAction } from "@gooddata/sdk-ui-gen-ai";

// Retrieve dispatcher from chat UI
dispatcher(clearThreadAction());

Actions that are now available

  • clearThreadAction - reset the chat thread
  • startNewConversationAction - start a new conversation
  • setCurrentConversationAction - set active conversation in the chat
  • newMessageAction - add message to the stack and get response from the assistant
  • pinConversationAction - pin or unpin a conversation
  • renameConversationAction - rename an existing conversation
  • deleteConversationAction - delete a conversation

Example usage:

import {
    clearThreadAction,
    startNewConversationAction,
    setCurrentConversationAction,
    newMessageAction,
    pinConversationAction,
    renameConversationAction,
    deleteConversationAction,
    makeUserItem,
    makeUserMessage,
    makeTextContents,
} from "@gooddata/sdk-ui-gen-ai";

// Retrieve dispatcher from chat UI

// Clear thread action
dispatcher(clearThreadAction());
// For case with single conversation only
dispatcher(newMessageAction(makeUserMessage([makeTextContents("Hello", [])])));
// For case with multiple conversations
dispatcher(startNewConversationAction());
dispatcher(setCurrentConversationAction({ conversation }));
dispatcher(newMessageAction(makeUserItem({ type: "text", text: "Hello" })));

// Pin/unpin conversation
dispatcher(pinConversationAction({ conversation, pinned: true }));

// Rename conversation
dispatcher(renameConversationAction({ conversation, title: "Weekly performance review" }));

// Delete conversation
dispatcher(deleteConversationAction({ conversation }));