Control the AI Assistant from your code

Drive the AI Assistant from your application by dispatching actions to its store. The list of actions is on the reference page.

Get the dispatcher

Take the dispatcher from the onDispatcher callback of GenAIAssistant or GenAiStore:

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

type ChatDispatcher = Parameters<NonNullable<GenAIAssistantProps["onDispatcher"]>>[0];

export const App = () => {
    const [dispatcher, setDispatcher] = useState<ChatDispatcher | null>(null);

    return <GenAIAssistant onDispatcher={(dispatch) => setDispatcher(() => dispatch)} />;
};

Inside a GenAiStore, call the useGenAiDispatcher hook instead:

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>;
};

Reset the chat thread

Dispatch clearThreadAction:

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

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

Send messages and manage conversations

The examples below use dispatcher from the previous section. conversation is an IChatConversationLocal, for example from useGenAiCurrentConversation, and userContext is an IGenAIUserContext.

import {
    clearThreadAction,
    startNewConversationAction,
    setCurrentConversationAction,
    setFullscreenAction,
    newMessageAction,
    pinConversationAction,
    renameConversationAction,
    deleteConversationAction,
    setSelectedAgentAction,
    setAmbientUserContextAction,
    setUserContextAction,
    makeUserItem,
} from "@gooddata/sdk-ui-gen-ai";

// Retrieve dispatcher from chat UI

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

// Switch the assistant to the fullscreen layout
dispatcher(setFullscreenAction({ isFullscreen: true }));

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

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

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

// Change assistant agent
dispatcher(setSelectedAgentAction({ agentId: "new-agent-id", showChangeEvent: true }));

// Set ambient user context
dispatcher(setAmbientUserContextAction({ userContext }));

// Set or merge user context
dispatcher(setUserContextAction({ userContext, replaceUserContext: true }));

Migrate from makeUserMessage to makeUserItem

If your integration still sends messages like this:

dispatcher(newMessageAction(makeUserMessage([makeTextContents("Hello", [])])));

Migrate to makeUserItem:

dispatcher(newMessageAction(makeUserItem({ type: "text", text: "Hello" })));

When migrating, remove makeUserMessage and makeTextContents from imports and use makeUserItem for new user chat items.

Control the AI Assistant from your code

Get the dispatcher

Reset the chat thread

Send messages and manage conversations

Migrate from makeUserMessage to makeUserItem

Related