Overview

This document describes how to configure Knowledge Discovery for End Users (KD4EU) after the Conversational AI (CAI) and AI Core components are installed. The configuration is done in three stages:

1. Matrix42 Enterprise – install and activate the extension, and verify that the chat widget is displayed and responds.
2. AI Core – connect the LLM backend and configure the knowledge source.
3. Conversational AI – connect AI Core to the chatbot project, and configure authentication and the live chat.

For recommendations on how to write or improve source materials for Retrieval-Augmented Generation (RAG) AI systems, refer to Knowledge Discovery: Best practices for knowledge sources.

Matrix42 Enterprise

Install Extension

The Matrix42 Enterprise Administrator can install Knowledge Discovery for End Users from the Extension Gallery.

Activate

After installation, the Knowledge Discovery for End Users should be activated and configured via Service Desk → Settings → Knowledge Discovery for End Users.

In Enabled, select the checkbox to activate the extension and fill out the following fields with the values displayed by the installer at the end of the installation:

┌───────────────────────┬─────────────────────────────────┐
│         Field         │ Value from the installer output │
├───────────────────────┼─────────────────────────────────┤
│ Conversational AI URL │ Conversational AI URL           │
├───────────────────────┼─────────────────────────────────┤
│ Agent Console URL     │ Agent Console URL               │
├───────────────────────┼─────────────────────────────────┤
│ Installation ID       │ Installation ID                 │
├───────────────────────┼─────────────────────────────────┤
│ Space ID              │ Space ID                        │
└───────────────────────┴─────────────────────────────────┘

Verify the chat widget

AI Core

Log in to the AI Core portal

Log in to the administrator account (https://cai-aicore.<your-domain>/admin/login) using the username & password provided by installer (see KD4EU installation for Version 1.3 → Installation → Save the tenant data →  ).

Connect the LLM backend

1. Navigate to CONFIG → SECRETS and click the green "ADD SECRET" button.
2. Configure the LLM provider's name, API URL, and credentials.
3. For Azure OpenAI, enable Azure OpenAI Service and supply the appropriate API Version.
4. For a llama.cpp service, enable This is a LlamaCpp server. Enable Use max_tokens instead of max_completion_tokens only if the backend requires that parameter.
5. Click Save.

Use a provider that supports the required operations. The chat and embedding services may use different secrets. In an air-gapped installation, use internally reachable services with the required models already available.

Configure Pass Through

1. Navigate to CONFIG → PASSTHROUGH.
2. Enable "Enable pass through" and select the backend you just configured. Available models from the provider's API should appear in the "Force Model" dropdown. Select one of the suggestions. If no models appear, verify your configuration in SECRETS, as your URL or API key may be incorrect.

Set up Apuri, the configuration assistant

Apuri is the assistant panel in the AICore administrator portal. It can search the bundled AICore documentation and help with configuration and troubleshooting. It can also propose supported source and document-processing changes for review. 

Prerequisites: 

• A saved LLM secret with a reachable chat backend.
• A chat model that supports tool/function calling. An embedding-only provider cannot host Apuri.
• For an air-gapped installation, an internally reachable model service. Apuri uses bundled documentation, but still needs its configured LLM backend.

Enable Apuri:

1. Open Config → Secrets.
2. If creating a new secret, complete the provider settings and click Save first. Apuri controls are disabled until the secret exists.
3. Edit the saved secret.
4. Select Enable for configuration assistant.
5. In Assistant model, select the chat model to use.
6. Click Save.
7. Click Apuri chat bubble button in the top navigation bar to open the assistant panel. Reload the page if the button has not appeared.

Only one secret can be enabled for Apuri at a time. Enabling another secret switches the assistant to that backend. The Assistant model is selected separately from the RAG and pass-through models. You do not need to generate a public AICore API key or enable RAG to use Apuri inside the administrator portal.

Check the assistant:

Start with a documentation question:

> How do I configure a Demo Source and verify that its documents are available to RAG?

Confirm that Apuri responds with relevant guidance. You can then ask it to inspect supported settings or help prepare a configuration change. Review any proposed change in the approval card and approve or discard it there. For source changes, follow the resulting reindex guidance - saving a source is not proof that indexing has completed.

Use the clear-chat control in the panel to start a fresh conversation.

Generate the API key

1. Navigate to CONFIG → "API & Authentication" and reset the "API Key". Save the key immediately, as it cannot be displayed later, only reset.

The API key and the AI Core URL will be required for the project configuration in the Conversational AI administrator portal (see 3. Conversational AI). You can verify their correctness using tools such as curl or Postman, or any OpenAI-compatible client. Example queries are available on the main page of the AI Core management panel.

Add and Test a Demo RAG Source

After configuring the Pass Through connection and API key, add a Demo Source to verify that the AI Core RAG/KD4EU pipeline is working correctly.

The Demo Source provides built-in sample content and does not require an external URL, credentials, or uploaded files.

Prerequisites

Before configuring the Demo Source, make sure that:

• An LLM backend is configured;
• Pass-through requests are working;
• A chat model is available;
• An embedding model is configured.

Enable RAG

In the AI Core portal, navigate to: 

CONFIG → RAG Chat Settings

Configure the following settings:

• Enable RAG: enabled;
• Multiple Databases: disabled for the initial setup;
• Auto Refresh: disabled for the initial test;
• Backend: select the configured LLM backend;
• Model: select a chat model;
• System Template: keep the default value.

The following values can be used for an initial test:

Click Save to apply the configuration.

These settings activate RAG and define the chat model used to generate answers based on retrieved document content.

Configure Embeddings

In the AI Core portal, navigate to: 

CONFIG → EMBEDDINGS

Configure the following settings:

• Embeddings: enabled;
• Backend: select the configured provider or backend;
• Model: select an embedding-capable model, for example text-embedding-3-small;
• Vector Size: enter the vector dimension supported by the selected embedding model;
• Indexing Threads: keep the default value of 4 for the initial test.

Click Save to apply the configuration.

Incorrect embedding configuration can result in the following issues:

• reindexing fails;
• no documents are returned by search;
• RAG Chat generates an answer without using indexed documents.

Add the Demo Source

In the AI Core portal, navigate to: 

RAG INDEX → Sources Configuration

Click Add New Source, and then select Demo Source.

Configure the following fields:

• Source Name: enter a descriptive name, for example animal-facts;
• Category Name Source: keep the default value source-name.

Alternatively, select custom and enter a custom category name.

Click Save.

The Demo Source creates built-in sample content about ten animals. No additional connection details or authentication credentials are required.

Index the Demo Source

In the AI Core portal, navigate to: 

RAG INDEX → Reindex

Click Start Reindexing and wait until the indexing process is completed.

A successful indexing run for the Demo Source should create ten documents.

The indexing result can be verified in the following areas:

• RAG INDEX → Sources Summary;
• RAG INDEX → Search.

Verify the Indexed Documents

In the AI Core portal, navigate to: 

RAG INDEX → Search

Search for a term included in the Demo Source, for example:

• cheetah;
• penguin;
• platypus.

The search results should contain indexed chunks from the configured Demo Source.

If the search returns results, document indexing and retrieval are working correctly.

If no results are returned:

1. Check whether the reindexing process completed successfully.
2. Verify the embedding backend, model, and vector size.
3. Check the document count in RAG INDEX → Sources Summary.
4. Check Failed Documents, if available, for indexing errors.

Test RAG Chat

In the AI Core portal, navigate to: 

Chat & Test → RAG

Enter a question related to the Demo Source, for example:

• What is the fastest land animal?
• Tell me about penguins.
• What makes the platypus unique?

The generated answer should be based on the indexed Demo Source content.

The RAG Chat page also displays the API endpoint used for RAG requests:

/rag/v1/chat/completions

For more details on various knowledge sources configuration, see:

• M42 Intelligence: AI Knowledge Discovery
• Data Sources section in the AI Core portal Docs.

Conversational AI

Log in to the Conversational AI administrator portal (https://cai-admin.<your-domain>) with the administrator credentials displayed by the installer (see KD4EU Installation for Version 1.3 → Installation → Save the tenant data).

Add the AI Core API key as a secret

1. Navigate to: BUILD / AI Chatbot / Secrets.
2. Click the New secret button.
3. In the Name field, enter a name for this key, using UPPERCASE letters.
4. In the Value field, paste the AI Core API key. Depending on the AI Core configuration, this is either the key generated in AI Core → CONFIG → API & Authentication, or the key of the agent defined in AI Core → Agents.
5. Recommended: Uncheck the Allow viewing the secret value checkbox to prevent viewing this secret value from the admin panel after creation.
6. Save the secret.

Add the AI Core Configuration

1. Navigate to: Integrations / Gen AI.
2. Click the New configuration button.
3. In the Name field, enter any name for this configuration.
4. In the API URL field, paste the AI Core API URL. Depending on the AI Core configuration, this is either the AI Core URL used with the key from API & Authentication, or the endpoint of the agent defined in AI Core → Agents.
5. From the Select an API Key dropdown, select the secret created in the previous step.
6. Save the configuration.

Assign the AI Core Configuration to the Project

1. Navigate to: BUILD / AI Chatbot / Projects.
2. Open the available project.
3. Go to the Knowledge sources section.
4. In the Type field, select Gen AI.
5. In the Gen AI dropdown, select the configuration created in the previous step.
6. Click the green Save button in the top-left corner.

From this moment, the widget in this project will respond using the specified AI Core backend.

Enable M42 Enterprise Authentication

M42 Enterprise authentication identifies the End User who is chatting. Without it, neither the chat widget nor AI Core knows who the End User is, so the chatbot cannot provide user-specific content, and the conversation is anonymous.

When the M42 Enterprise authentication is enabled:

• the End User identity is passed to the chatbot and AI Core, so answers can be tailored to the specific user;
• Agents see the End User name in the live chat and chat history, instead of a generated user number.

To enable the M42 Enterprise authentication:

1. Navigate to: BUILD / AI Chatbot / Projects.
2. Open the available project.
3. Go to the Advanced section → M42 authentication.
4. Select the Enable authentication checkbox.
5. Choose “M42 Enterprise” in Authentication type drop down.
6. In Authentication URL, adjust the following URL by changing the placeholder to your Matrix42 Enterprise instance:

   https://{my_Matrix42Enterprise_URL}/m42Services/api/userinfo

7. Click the green Save button in the top-left corner.

Configure Live Chat

Live Chat lets Service Desk Agents browse and handle active chats and chat history directly in Matrix42 Enterprise. Agents are signed in automatically – no separate credentials are required.

To configure Live Chat:

1. Make sure the Knowledge Discovery for End Users extension version is installed.
2. Log in to the Conversational AI administrator portal (https://cai-admin.<your-domain>).
3. Click the Avatar menu → Settings → General.
4. In Agent Console → Authentication URL, enter the token-validation API URL of your Matrix42 Enterprise instance:

   https://{my_Matrix42Enterprise_URL}/m42Services/api/userinfo

5. Click Save & Close.

To open Live Chat, the Service Desk Agent clicks the Ask Neo button in the top-right corner of the Service Desk. Neo opens with Assistant and a Live Chat tab.