AI Assistant

@gooddata/sdk-ui-gen-ai embeds the chat of the GoodData AI Assistant in a React application. This page lists its components, events, slots, and actions. For step-by-step tasks, see Combine the AI Assistant with your app, Customize the AI Assistant, and Control the AI Assistant from your code.

Prerequisites

The component shows the AI Assistant that your GoodData organization runs; it doesn’t set it up. Before you embed it:

• Turn on and configure the AI Assistant, including which users get the AI Assistant workspace permission. See Configure AI Assistant.
• Connect a language model. See Configure LLM Providers and Models for AI Assistant.
• Decide what data the assistant may send to the model. See Sharing Data With AI.

Which AI features you get depends on your GoodData plan and entitlements. On GoodData.CN, the AI setup differs; check the GoodData.CN documentation for your version.

Components

The components support theming through the Theme Provider.

Basic usage

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}`);
                    // For example, when the user asks the assistant to find
                    // a specific dashboard and clicks the result
                }}
                // Optionally, provide dispatcher for sending messages in the chat
                onDispatcher={(dispatch) => {
                    // Save dispatcher and use it to send messages
                }}
            />
        </div>
    );
};

Agents

GoodData Cloud’s current assistant is the Agentic AI Assistant; the earlier chat assistant is deprecated. The component reads your workspace settings and shows what your organization has turned on, for example several conversations per user and suggested follow-up questions.

An agent is one configuration of the assistant: how it communicates, which skills it can use, whether it can use AI Knowledge, and which user groups get it. Organization administrators create agents in AI Hub; see Agents. The assistant’s skills, such as Key Driver Analysis, forecasting, anomaly detection, and alerts, are listed in Agentic Capabilities.

When a user has access to more than one agent, the component shows an agent chooser, so they can switch agents in a conversation. You can customize the chooser, switch the agent from your code with the setSelectedAgentAction action, and follow changes with ChatAgentChangeEvent.

Interaction Intelligence

Interaction Intelligence shows how the assistant arrived at an answer: a timeline of the processing steps behind one response, grouped into categories you can open for details. When it’s on, each answer gets a control that opens the panel below it.

It’s off by default. Both of these must be true for it to show:

• You pass allowInteractionIntelligence to GenAIAssistant (or to GenAiStore).
• The enableGenAiInteractionIntelligence setting is on for the workspace.

<GenAIAssistant allowInteractionIntelligence />

The panel is also exported as GenAiInteractionIntelligence, for a custom layout inside GenAiStore. It takes the responseId of an assistant response and an onClose callback.

Display mode

Use mode to switch the assistant between the compact docked layout, intended for a side panel, and the wide fullscreen layout, intended for a full-page section.

The assistant always fills its parent element, so mode does not resize it - sizing and positioning of the chrome around it stays under your control. What the property changes is the internal layout: in the fullscreen mode on large screens, the initial assistant experience is laid out for a wide container, with the suggested questions arranged in a row and the input centered in the available space.

The ChatModeChangeEvent (type onModeChange) is emitted whenever the display mode changes inside the assistant, so that your application can keep its own chrome in sync. That includes a dispatched setFullscreenAction and the expand and minimize control of the chat header when the assistant is embedded in a chat dialog.

Passing a new value through mode dispatches setFullscreenAction as well, so that change is reported too. A controlled application can still feed the reported value straight back as mode: the assistant dispatches only when the prop differs from the last value it applied, so the loop settles after one extra event.

Note that on small screens the fullscreen layout is always used, regardless of mode. This forced layout is not reported through the event, as it is not part of the mode your application controls.

For a toggle example, see Switch between the docked and fullscreen layouts.

Events

Pass event handlers in the eventHandlers prop of GenAIAssistant, GenAIConversations, or GenAiStore. Each handler complies with this 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 exports a guard for every event the chat UI emits:

The sections below describe the events with extra properties.

ChatAssistantMessageEvent

This event is triggered when the assistant completes a response. If the response activates any skills, the optional skills property holds their identifiers and display titles.

ChatDefinitionReceivedEvent

This event is triggered immediately when a message with a visualization or dashboard definition is received from history or from a stream.

Example usage:

<GenAIAssistant
    eventHandlers={[
        {
            eval: isChatDefinitionReceivedEvent,
            handler: (event: ChatDefinitionReceivedEvent) => {
                console.log(`Received ${event.definitionType} definition:`, event.itemId);
                if (event.definitionType === "dashboard") {
                    // handle dashboard definition
                    console.log(event.dashboard);
                }
            },
        },
    ]}
/>

ChatClarificationQuestionsEvent

This event is triggered when the assistant presents clarification questions, and again when the user submits answers or cancels the questions by sending another message.

Use responses to tell the stages of the clarification flow apart:

• undefined: the questions were received and presented, and the user has not responded yet.
• An object: the user submitted the form. A non-empty object holds the answered questions; omitted questions were skipped. An empty object means the user submitted the form and skipped every question.
• null: the user skipped the form entirely, for example by sending another message.

Example usage:

<GenAIAssistant
    eventHandlers={[
        {
            eval: isChatClarificationQuestionsEvent,
            handler: (event: ChatClarificationQuestionsEvent) => {
                if (event.responses === undefined) {
                    console.log("Clarification questions presented:", event.questions);
                } else if (event.responses === null) {
                    console.log("Clarification questions cancelled");
                } else {
                    console.log("Clarification answers submitted:", event.responses);
                }
            },
        },
    ]}
/>

ChatUserAnswersEvent

This event is triggered when the user submits answers to clarification questions. The answers array holds only the answered questions: skipped questions are left out, and the array is empty if the user skips every question.

Clarification answer turns emit chatUserAnswers instead of chatUserMessage. To count all user turns, handle both event types.

Each ChatClarificationAnswer holds the question and the selected option:

Example usage:

<GenAIAssistant
    eventHandlers={[
        {
            eval: isChatUserAnswersEvent,
            handler: (event: ChatUserAnswersEvent) => {
                console.log("Clarification interaction:", event.interactionId);
                event.answers.forEach(({ questionText, answer }) => {
                    console.log(`${questionText}: ${answer.optionText}`);
                });
            },
        },
    ]}
/>

ChatModeChangeEvent

This event is triggered whenever the assistant display mode changes, for example between "docked" and "fullscreen".

Example usage:

<GenAIAssistant
    eventHandlers={[
        {
            eval: isChatModeChangeEvent,
            handler: (event: ChatModeChangeEvent) => {
                console.log(`New assistant mode: ${event.mode}`);
            },
        },
    ]}
/>

ChatAgentChangeEvent

This event is triggered whenever the assistant agent changes. Its type string is onSelectedAgentAction.

Example usage:

<GenAIAssistant
    eventHandlers={[
        {
            eval: isChatAgentChangeEvent,
            handler: (event: ChatAgentChangeEvent) => {
                console.log(`Agent changed from ${event.previousAgentId} to ${event.agentId}`);
            },
        },
    ]}
/>

ChatContextChangeEvent

This event is triggered whenever the assistant context is changed.

Example usage:

<GenAIAssistant
    eventHandlers={[
        {
            eval: isChatContextChangeEvent,
            handler: (event: ChatContextChangeEvent) => {
                console.log(`Context changed: ${event.contextType}`);
            },
        },
    ]}
/>

Link clicks

onLinkClick handles clicks on the catalog items that the chat mentions. Without it, the items are rendered as plain text. The handler receives a LinkHandlerEvent with these properties:

For action: "copy", return the URL that should be copied to the clipboard; if the handler returns undefined, nothing is copied. For action: "open", the return value is ignored.

Route saved dashboards by their URL and pass draft dashboards to your application’s dashboard runtime. A draft is not saved yet, so use the dashboard definition and its insights instead of loading it by id or itemUrl:

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

const handleLinkClick = (event: LinkHandlerEvent): string | undefined => {
    if (event.type !== "dashboard" || event.action !== "open") {
        return event.itemUrl;
    }

    event.preventDefault();

    if (event.dashboardStatus === "draft") {
        if (event.dashboard) {
            openDraftDashboard({ dashboard: event.dashboard, insights: event.insights ?? [] });
        }
        return undefined;
    }

    if (event.newTab) {
        window.open(event.itemUrl, "_blank", "noopener,noreferrer");
    } else {
        navigate(event.itemUrl);
    }
    return undefined;
};

<GenAIAssistant onLinkClick={handleLinkClick} />;

navigate stands for your application’s router and openDraftDashboard for your dashboard runtime, which must initialize the dashboard from both the dashboard and its insights.

Key Driver Analysis component

GenAiKeyDriverAnalysis is a dialog that runs Key Driver Analysis (“Explain” on a chart) on visualizations the assistant generates. When a user asks to explain a data point in the chat, the request goes to the shared store, and the dialog mounted under that store opens with the analysis.

Mount it next to GenAIAssistant inside a shared GenAiStore:

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

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

const App = () => (
    <GenAiStore>
        <div style={{ width: 500, height: 600, display: "flex" }}>
            <GenAIAssistant />
        </div>
        <GenAiKeyDriverAnalysis />
    </GenAiStore>
);

Explain actions on charts are available when GenAiKeyDriverAnalysis is mounted under the active GenAiStore; without it, they are disabled. To turn them on or off explicitly, set enableKeyDriverAnalysis on the ConversationVisualizationContent or ConversationKdaContent slot (see Customize message content).

Slots

Customize parts of the assistant UI by passing components in the slots prop of GenAIAssistant or GenAIConversations. Each slot component receives the Default component and its defaultProps, so you can wrap the default rendering or replace it. Customize the AI Assistant shows an example for every slot.

Available actions

Dispatch these actions through the store dispatcher that onDispatcher or useGenAiDispatcher gives you. Control the AI Assistant from your code has examples.

• clearThreadAction - reset the chat thread
• startNewConversationAction - start a new conversation
• setCurrentConversationAction - set active conversation in the chat
• setSelectedAgentAction - change the assistant agent
• setAmbientUserContextAction - set the ambient user context
• setUserContextAction - set or merge the user context
• setFullscreenAction - switch the assistant between the docked and the fullscreen layout
• 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

useGenAiDispatcher hook

You can use the useGenAiDispatcher hook to retrieve the dispatcher when working within the GenAiStore context.

import { useGenAiDispatcher, startNewConversationAction } from "@gooddata/sdk-ui-gen-ai";

const MyComponent = () => {
    const dispatch = useGenAiDispatcher();

    const handleNewConversation = () => {
        dispatch(startNewConversationAction());
    };

    return <button onClick={handleNewConversation}>New Conversation</button>;
};

Conversation state hooks

These hooks read the conversations of the current GenAiStore. They’re @alpha and may change without a major version bump.

• useGenAiConversations(): returns all conversations in the current store, or undefined before they are loaded.
• useGenAiConversationsLoaded(): returns whether the conversations have been loaded.
• useGenAiCurrentConversation(): returns the active conversation, if any.

See Build your own conversation list for an example.

Props

GenAIAssistantProps, GenAIConversationsProps, and GenAiStoreProps are type aliases, which the generated Props tables don’t support yet, so their props are listed by hand. The generated table at the end lists the slots (IGenAIAssistantSlots).

GenAIAssistant

GenAIAssistant takes every GenAiStore prop except children, plus these:

GenAIConversations

GenAIConversations takes every GenAiStore prop except children, plus these:

GenAiStore

IGenAIAssistantSlots