AI components

Chatbox

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 resources panel 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 check 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 of the chatbox

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.

The chatbox offers alternative capabilities for developers, though.

Attaching to streaming events

If you want to attach to streaming events, you can use addEventDelegate on the chatbox. This allows you to listen to events 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"));
    },
});

You can attach to the following events:

onChunk

Triggered upon arrival of a new chunk of text from the agent.

Parameters

  • chunk (string): The text chunk.

  • metadata (object):

    • threadID (string): The ID of the current thread.

onToolStart

Triggered when the agent starts executing a tool.

Parameters

  • metadata (object):

    • threadID (string): The ID of the current thread.

    • toolCallId (string): Unique ID of the tool call.

    • toolName (string): Name of the tool being called.

onToolInput

Triggered when the agent provides input (arguments) for a tool.

Parameters

  • metadata (object):

    • threadID (string): The ID of the current thread.

    • toolCallId (string): Unique ID of the tool call.

    • toolName (string): Name of the tool being called.

    • input (any): The arguments for the tool call.

onToolFinish

Triggered when a tool execution is finished.

Parameters

  • metadata (object):

    • threadID (string): The ID of the current thread.

    • toolCallId (string): Unique ID of the tool call.

    • output (object):

      • toolName (string): Name of the tool.

      • result (any): Result of the tool call.

onFinish

Triggered upon completion of the agent’s response.

Parameters

  • metadata (object):

    • createdAt (number): Timestamp of when the request was created.

    • finishReason (string): Reason for finishing (for example, "stop", "length").

    • input (string): User input for the request.

    • logId (string): Unique ID of the log entry.

    • model (string): Name of the model used.

    • modelResponseTime (number): Duration of the request in milliseconds.

    • output (string): Final output text from the agent.

    • steps (Array<object>): Array of steps executed (e.g., tool calls).

    • usage (object): Token usage details.

    • vectors (Array<object>): Sources used from vector search.

    • threadID (string): The ID of the current thread.

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

Other API methods

The chatbox component exposes several other methods for programmatic interaction.

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