> For the complete documentation index, see [llms.txt](https://developer.emporix.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.emporix.io/agentic-commerce-intelligence/agentic-intelligence/configuration/tools/rag.md).

# RAG AI Tool

Retrieval-Augmented Generation (RAG) framework is capable of combining a large language model (LLM) with an external knowledge base to provide more accurate and up-to-date responses. Its inner mechanism consists in first retrieving relevant information from sources (like documents or databases) and then using that information in the LLM, enhancing its output with the specific context. RAG helps AI to generate answers that are highly-grounded in factual, real-time data, reducing "hallucinations".

In the Emporix Agentic AI, Retrieval-Augmented Generation is a capability facilitated by the RAG AI tools that you can use within an AI agent.

These native tools enable agents to perform LLM-based semantic search across various domain-specific entities stored in vector databases.

The RAG AI tools transform user queries into vector embeddings and match them against pre-computed entity embeddings using similarity metrics (for example, cosine similarity).

```mermaid
---
config:
  layout: fixed
  theme: base
  look: classic
  themeVariables:
    background: transparent
    lineColor: "#9CBBE3"
    arrowheadColor: "#9CBBE3"
    edgeLabelBackground: "#FFC128"
    edgeLabelTextColor: "#4C5359"
---
flowchart TD
  A["USER QUERY"]
  B["Transform query into<br>vector embedding"]
  C["Match against pre-computed<br>entity embeddings"]
  D["Rank by similarity<br>(e.g. cosine similarity)"]
  E["Return context-aware results"]

  A -->|"Initiate RAG mechanism"| B --> C --> D --> E

  style A fill:#3B73BB,stroke:#4C5359,color:#FFFFFF
  style B fill:#DDE6EE,stroke:#4C5359
  style C fill:#DDE6EE,stroke:#4C5359
  style D fill:#DDE6EE,stroke:#4C5359
  style E fill:#F2F6FA,stroke:#4C5359

  A@{ shape: rounded}
  B@{ shape: rounded}
  C@{ shape: rounded}
  D@{ shape: rounded}
  E@{ shape: rounded}
```

Crucially, RAG AI tools operate on semantic meaning. This differs from traditional keyword-based search, as RAG enables more accurate and context-aware retrieval even when there is no explicit keyword overlap.

To enhance search for indexed entities (like products) with RAG, an agent must be used with a previously defined RAG AI tool attached to it. The tool configuration requires a prompt, which informs the agent when the tool must be triggered. The Agentic AI provides two tool types designed for RAG workflows:

* `RAG_EMPORIX`
* `RAG_CUSTOM`

## `RAG_EMPORIX` tool type

A tool of type `RAG_EMPORIX` enables configuration and execution of the indexing and retrieval pipeline for selected Emporix-managed entities. This tool type leverages the native Emporix Vector Database, meaning there is no need to manage external infrastructure.

### Configuring RAG Emporix tool

To configure a `RAG_EMPORIX` tool, follow these steps:

{% stepper %}
{% step %}

#### Define general tool details

Open the **General** tab and set the tool basis:

* **Tool Type** – Select *RAG Emporix*.
* **Tool ID** – The identifier of the tool.
* **Tool Name** – The name displayed in the UI.
* **Prompt** – Instructions for when the agent should invoke this tool once it is attached.

<figure><img src="/files/B4O9Kx8h98FoWj0huWkF" alt="RAG Emporix tool configuration"><figcaption><p>RAG Emporix tool configuration</p></figcaption></figure>
{% endstep %}

{% step %}

#### Configure the embeddings LLM provider

Open the **Settings** tab and configure the LLM provider used to create embeddings. See [LLM providers](#llm-providers) for provider-specific details.

* **Provider** – *OpenAI*, *Self-Hosted Ollama*, or *Emporix OpenAI*.
* **Model** – The model of the chosen LLM.
* **Dimensions** – Embeddings table size (128–4096).
* **URL** – Required for *Self-Hosted Ollama* only.
* **Token** – Authentication token for the chosen provider.

{% hint style="info" %}
Emporix OpenAI is preconfigured — no further details are required.
{% endhint %}

<figure><img src="/files/3hjJWn9S5MmVPTMArpB5" alt="Configuration of RAG embeddings"><figcaption><p>Configuration of RAG embeddings</p></figcaption></figure>
{% endstep %}

{% step %}

#### Select the entity type

Choose the **Entity Type** to index and retrieve — either *Product* or a *custom entity* defined in your tenant.

{% hint style="warning" %}
Note that removing a custom entity from the Emporix system results in automatic deletion of RAG tools that reference that entity.
{% endhint %}
{% endstep %}

{% step %}

#### Configure indexed fields

Specify which fields are included in the embedding. See the [Indexed fields](#indexed-fields).

* Add default Emporix fields or custom fields to be indexed for search (via the relevant `mixin` **Key**).
* Each field has `key` (required) and optional `name` (alias used in concatenated content).

{% hint style="warning" %}
Indexed fields can include either a parent field (for example, `brand`) or one of its child fields (for example, `brand.localizedDescription.en`), but never both at the same time. When a parent field is selected, all of its child fields are automatically included in the concatenated content.
{% endhint %}

The maximum number of indexed characters in a single product is `16 000`. If the content exceeds the limit, the first `16 000` characters are embedded while the remaining characters are ignored.

<figure><img src="/files/tAwodmiUWMt3gAOZHSR4" alt="RAG tool indexed fields"><figcaption><p>Configuration of Indexed Fields for RAG Emporix tool</p></figcaption></figure>
{% endstep %}

{% step %}

#### Configure filter fields

Specify the **Filter Fields** that can be used to refine and filter vector search results before retrieval. These fields enable the agent to constrain searches based on structured attributes, reducing irrelevant matches and improving the precision and efficiency of the retrieval process.

<figure><img src="/files/20pzRSe0pMZg9Dkim9TA" alt="RAG tool filter fields"><figcaption><p>Configuration of Filter Fields for RAG Emporix tool</p></figcaption></figure>
{% endstep %}

{% step %}

#### Save the tool configuration

Review the settings on the **General** and **Settings** tabs, then choose **Save** to store the tool configuration.
{% endstep %}
{% endstepper %}

#### LLM providers

The configuration for creating embeddings includes choosing the relevant LLM provider. When indexing products using a RAG tool, the system generates appropriate embeddings by making an HTTP call to the chosen LLM.

There are three supported LLM providers you can use for creating RAG embeddings:

* **Emporix OpenAI** - This provider doesn't require any further configuration on your side, as default settings are used. It uses the OpenAI `text-embedding-3-small` model with embedding dimensions set to `1536`. The number of tokens used by each operation is registered in the Emporix system, and usage is limited to the set limit. When an AI agent uses the RAG tool, the same LLM configuration is used to create embeddings for user queries to perform search operations.
* **OpenAI** - Use your own OpenAI account within the RAG tool. Provide the specific model type, dimensions, and token.
* **Self-Hosted Ollama** - Use a custom Ollama LLM provider and model. In addition to the model, dimensions, and token, you also need to provide the URL of the hosted model to enable valid HTTP communication.

#### Indexed fields

The values of the indexed fields are later concatenated and converted into embeddings. Each line in this concatenated text corresponds to a single field and follows the structure: `{key}: {content}`.

For example, if `code`, `name.en`, and `description.en` are included in the configuration, the resulting concatenated content used for embedding looks as follows:

> ```
> code: 103155592
> name.en: Precision Screwdriver
> description.en: A high-quality set of precision screwdrivers designed for industrial and professional applications, ensuring durability and precise performance.
> ```

Depending on the entity type you selected for the tool, the form fetches the list of available fields you can choose from. The indexed fields list consists of objects with two properties: `key` and `name`. The `key` property is required, while `name` is optional and can serve as the alias for the key. If you provide the `name`, it is used in place of the `key` in the content that is transformed into embeddings.

{% hint style="success" %}
If you have custom mixin fields maintained outside of the Emporix system, you can add such fields using the **Add Custom Field** option. The path of the custom field key starts with the `mixin.` prefix.
{% endhint %}

### Indexing stage

When the tool configuration is ready, the entities can be indexed. Each time you modify a product or a specified custom entity, it gets reindexed by the RAG tool and its embedding is recalculated if necessary in the background. To trigger indexing of all items in the database, you can trigger the `Reindex` option.

<figure><img src="/files/df6DQd2qJiFqmE9p6esn" alt="Reindex" width="300"><figcaption><p>Reindex</p></figcaption></figure>

{% hint style="danger" %}
Reindexing is a computationally expensive and time-consuming operation, especially for large catalogs. It may significantly increase infrastructure costs, processing time, and overall system load. For this reason, perform reindexing only when truly necessary - for example, after major configuration changes, embedding model updates, or structural schema modifications. Avoid triggering it frequently or without clear intent.
{% endhint %}

### Retrieving stage

To search for the indexed entities, you need to attach the previously defined RAG tool to an agent. The agent uses the available tool according to the specified prompt definition.

### Example `RAG_EMPORIX` AI tool flow

The flowchart represents the process flow of the `RAG_EMPORIX` tool.

```mermaid
---
config:
  layout: fixed
  theme: base
  look: classic
  themeVariables:
    background: transparent
    lineColor: "#9CBBE3"
    arrowheadColor: "#9CBBE3"
    edgeLabelBackground: "#FFC128"
    edgeLabelTextColor: "#4C5359"
---
flowchart TD
  subgraph subGraph0["TOOL SETUP"]
    direction TB
    A["Create RAG_EMPORIX tool"]
    B["Configure embedding fields<br>(code, name, description)"]
  end
  subgraph subGraph1["INDEXING"]
    direction TB
    C["Create vector search index"]
    D["Trigger reindexing"]
    E["Generate embeddings and<br>save to collection"]
  end
  subgraph subGraph2["RETRIEVAL"]
    direction TB
    F["Attach tool to frontend agent"]
    G["User query from storefront"]
    H["RAG search for matching entities"]
    I["Display results to user"]
  end

  A --> B
  B -->|"index"| C
  C --> D --> E
  E -->|"retrieve"| F
  F --> G --> H --> I

  style A fill:#3B73BB,stroke:#4C5359,color:#FFFFFF
  style B fill:#DDE6EE,stroke:#4C5359
  style C fill:#3B73BB,stroke:#4C5359,color:#FFFFFF
  style D fill:#DDE6EE,stroke:#4C5359
  style E fill:#DDE6EE,stroke:#4C5359
  style F fill:#3B73BB,stroke:#4C5359,color:#FFFFFF
  style G fill:#DDE6EE,stroke:#4C5359
  style H fill:#DDE6EE,stroke:#4C5359
  style I fill:#F2F6FA,stroke:#4C5359

  classDef Class_01 stroke-width:1px,stroke-dasharray:0,stroke:#A1BDDC,fill:#DDE6EE
  class subGraph0 Class_01
  class subGraph1 Class_01
  class subGraph2 Class_01
  style subGraph0 color:#4C5359
  style subGraph1 color:#4C5359
  style subGraph2 color:#4C5359

  A@{ shape: rounded}
  B@{ shape: rounded}
  C@{ shape: rounded}
  D@{ shape: rounded}
  E@{ shape: rounded}
  F@{ shape: rounded}
  G@{ shape: rounded}
  H@{ shape: rounded}
  I@{ shape: rounded}
```

#### Example search results

When you apply the RAG tool in an agent available at the storefront, a user might, for example, query about products of interest using natural language. In the background, the agent triggers the RAG tool to enhance the search outcomes with RAG embeddings, match the query, and return all available matches to the user.

<figure><img src="/files/Cr1bpIq5UvgChlsVvZGT" alt="User query to agent using RAG tool"><figcaption><p>User query</p></figcaption></figure>

<figure><img src="/files/6cIDIxUiwDULElfIQKLe" alt="Agent response"><figcaption><p>Agent response</p></figcaption></figure>

## `RAG_CUSTOM` tool type

A tool of type `RAG_CUSTOM` enables integration with an external (custom) vector database, not managed by the Emporix platform. This allows the system to perform semantic search operations using embeddings stored outside of the native infrastructure.

This tool type is intended for advanced use cases where organizations prefer complete control over their vector storage, scalability, performance tuning, or cost management.

### Configuring RAG Custom tool

To configure a `RAG_CUSTOM` tool, provide valid and accessible settings so the tool can execute Retrieval-Augmented Generation (RAG) queries successfully.

{% hint style="info" %}
Before you begin, ensure a Qdrant collection with indexed products already exists and is accessible from the running environment. The tool connects to this external collection rather than creating or managing it.
{% endhint %}

Follow these steps:

{% stepper %}
{% step %}

#### Define general tool details

Open the **General** tab and set the tool basis:

* **Tool Type** – Select *RAG Custom*.
* **Tool ID** – The identifier of the tool.
* **Tool Name** – The name displayed in the UI.
* **Prompt** – Instructions for when the agent should invoke this tool once it is attached.

<figure><img src="/files/EZ3XoXIxzb71yMfx66Nw" alt="RAG custom tool configuration"><figcaption><p>RAG custom tool configuration</p></figcaption></figure>
{% endstep %}

{% step %}

#### Connect to the external vector database

Open the **Settings** tab and configure the external database connection:

* **Database URL** – The URL of the database where data is stored.
* **Database Type** – Type of the database.
* **Collection Name** – The name of the collection where products are stored.
* **Database Token** – The token for authentication to the database.

{% hint style="warning" %}
Currently, the only available database type is `Qdrant`.
{% endhint %}
{% endstep %}

{% step %}

#### Configure retrieval settings

Define how the tool queries and returns results from the external database:

* **Max Results** – The maximum number of documents returned by an agent that uses this tool.
* **Entity Type** – The entity type to retrieve from the database.

{% hint style="warning" %}
Currently, the only available entity type is `Product`.
{% endhint %}
{% endstep %}

{% step %}

#### Configure embeddings

Specify the LLM used to compute embeddings for entities in the collection:

* **Model** – The model used to compute embeddings.
* **Embeddings Token** – The token required for computing embeddings.
  {% endstep %}

{% step %}

#### Save the tool configuration

When ready, choose **Save** to store the tool configuration.

<figure><img src="/files/955Pwn7clqsTovd7yFmw" alt="RAG custom tool settings"><figcaption><p>RAG custom tool settings</p></figcaption></figure>
{% endstep %}
{% endstepper %}

### Retrieving stage

To enhance search for the indexed products with custom-defined RAG, attach the `RAG_CUSTOM` tool to an agent. The agent uses the available tool according to the specified prompt definition.

### Example `RAG_CUSTOM` AI tool flow

The flowchart represents the process flow of the `RAG_CUSTOM` tool.

```mermaid
---
config:
  layout: fixed
  theme: base
  look: classic
  themeVariables:
    background: transparent
    lineColor: "#9CBBE3"
    arrowheadColor: "#9CBBE3"
    edgeLabelBackground: "#FFC128"
    edgeLabelTextColor: "#4C5359"
---
flowchart TD
  subgraph subGraph0["TOOL SETUP"]
    direction TB
    A["Create RAG_CUSTOM tool"]
    B["Connect to Qdrant collection<br>with indexed products"]
  end
  subgraph subGraph1["RETRIEVAL"]
    direction TB
    C["Attach tool to frontend agent"]
    D["User query from storefront"]
    E["RAG search against<br>external collection"]
    F["Display results to user"]
  end

  A --> B
  B -->|"integrate"| C
  C --> D --> E --> F

  style A fill:#3B73BB,stroke:#4C5359,color:#FFFFFF
  style B fill:#DDE6EE,stroke:#4C5359
  style C fill:#3B73BB,stroke:#4C5359,color:#FFFFFF
  style D fill:#DDE6EE,stroke:#4C5359
  style E fill:#DDE6EE,stroke:#4C5359
  style F fill:#F2F6FA,stroke:#4C5359

  classDef Class_01 stroke-width:1px,stroke-dasharray:0,stroke:#A1BDDC,fill:#DDE6EE
  class subGraph0 Class_01
  class subGraph1 Class_01
  style subGraph0 color:#4C5359
  style subGraph1 color:#4C5359

  A@{ shape: rounded}
  B@{ shape: rounded}
  C@{ shape: rounded}
  D@{ shape: rounded}
  E@{ shape: rounded}
  F@{ shape: rounded}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developer.emporix.io/agentic-commerce-intelligence/agentic-intelligence/configuration/tools/rag.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.