Chatbox component

In the App Designer, you can use the pre-made custom component Chatbox. You can configure the chatbox to use an agent, have a history, or stream the responses.

Furthermore, you can customize it to your own requirements, by setting colors, icons, backgrounds, or by hooking into the actual processing logic.

Add a chatbox to an app

To add a chatbox to an app, create a new app in the App Designer and open the Component library in the Designer. Go to nep.ai and drag and drop the component chatbox into your app.

Chatbox configuration

The main configuration item for the chatbox is the agent ID. It refers to the agent that generates the responses in the chat. Furthermore, the following sections of settings exist:

Agent settings

Configure whether the agent should be streaming, whether the test mode should be enabled (this renders a button per message with some data that can be helpful in debugging, such as the amount of tokens used), or what triggeredFrom should be set on the agent.

This can help you in your analysis in the Agent Trace, as you can distinguish logs based on where the generation was triggered from.

When you select agentUseHistory, the chatbox renders a list of past conversations of the user. Furthermore, the agent response is configured to be based on a thread. If you do not use history, every message is "new" to the agent, and it cannot therefore draw upon context from previous messages.

Theming

You can theme your chatbox by either overwriting the CSS variables of the chatbox, or by defining colors in the attributes of the chatbox. To do so, select the chatbox and go to the Settings/properties pane. There, you will find the sections BrandingDark and BrandingLight. Here, you can use the color picker to define custom colors for your chatbox.

Custom source display

If you have decided to use a vector-enabled table as context for the agent to draw upon, you can configure how sources from the table are rendered. By default, the sources displays as a JSON of the relevant table row. However, when you decide that you require a different display, you can add your own components to render your row.

You can access table properties through bindings in your added components, by referencing them as for instance {/Title}.

Example

You have created a table of news articles in the Table Definition tool. There, you have created the properties Title (text), URL (text), Image (text), and Text (text). You have set up the vector store capability on that table and configured it appropriately.

In your agent configuration, you have selected your table of news articles and set the threshold and related vector store settings.

In the chat, you want to display found news articles with their title, URL, and image. To do so, you pull the following components with configuration into the contentDialogChatSourceData aggregation of the chatbox:

  • sap.m.Title: set text to {/Title}.

  • sap.m.Image: set src to {/Image}.

  • sap.m.Link: set href to {/URL} and text to whatever seems appropriate to you

Users of the chatbox can then review sources in the way you have configured it, by selecting buttons in the sources list under a message.

Programmatic usage

You can use the chatbox in multiple ways, and you can even copy the source (it is a custom component) and customize it to your needs. Beyond configuration, the chatbox exposes methods and forwards the underlying nep.ai.Agent events for programmatic interaction.

Attaching to streaming events

The chatbox forwards the underlying nep.ai.Agent events. You can use addEventDelegate to listen to them during the agent’s processing lifecycle.

Here is an example of attaching to the onChunk event and console logging the chunk:

// assuming the chatbox component is named 'chatbox' in your app
chatbox.addEventDelegate({
    onChunk: (oEvent) => {
        console.log(oEvent.getParameter("chunk"));
    },
});

For a full list of events and their parameters, see Agent events.

Removing event delegates

If you need to remove an event delegate that you previously added, you can use removeEventDelegate.

// Define the delegate object
const myDelegate = {
    onChunk: (oEvent) => {
        console.log("Chunk received");
    }
};

// Add the delegate
chatbox.addEventDelegate(myDelegate);

// Remove the delegate later
chatbox.removeEventDelegate(myDelegate);

Agent variables

You can inject dynamic context into your agent’s system prompt using agent variables. For example, you want to enable different conversational styles, and have created a prompt that uses a variable {{mode}}, you can populate the mode at runtime using setAgentVariables.

// Set variables to influence the agent's behavior
chatbox.setAgentVariables([
    { key: "mode", value: "informal" },
]);

This is particularly useful for personalizing the agent’s responses based on the current user’s context. You can retrieve the current variables using getAgentVariables().

Sending messages programmatically

You can simulate a user sending a message using pushUserMessage. This is useful for implementing "Next Best Action" buttons or quick replies where the user can select a button to send a predefined prompt.

// Example: A button press handler for a "Next Best Action"
const actionText = oEvent.getSource().getText(); // e.g., "Show Sales Report"

// Send the text as if the user typed it
chatbox.pushUserMessage(actionText);

Thread management

  • setActiveConversation(threadID): Switches the chat to a specific thread.

  • deleteThread(threadID): Deletes a specific thread.

  • renameThread(threadID, title): Renames a specific thread.

Related topics