RAG tool

Introduced 0.12.0

The RAGTool performs retrieval-augmented generation. It retrieves with a k-NN search — exactly as the Vector DB tool does — and then asks a generation model to answer the question using the retrieved documents as context. In one step, you go from a natural-language question to a grounded answer.

The tool takes two models: an embedding model for retrieval and a generation (chat/LLM) model for the answer. Both can be local models or any remote connector, and both are referenced by ID, so the tool is cloud-agnostic.

Prerequisites

Before registering the tool, you need:

• An index whose documents contain a knn_vector field, populated at ingest time with the embedding model.
• The ID of that embedding model.
• The ID of a generation model (a chat or large language model) deployed through the ML Commons plugin.

The embedding model configured on the tool must be the same one used to embed the documents at ingest time.

Step 1: Register a flow agent that will run the RAGTool

A flow agent runs a sequence of tools in order and returns the last tool's output. To create a flow agent, send the following register agent request:

POST /_plugins/_ml/agents/_register
{
  "name": "Test_Agent_For_RAG_tool",
  "type": "flow",
  "description": "this is a test agent for the RAGTool",
  "tools": [
    {
      "type": "RAGTool",
      "name": "DemoRAGTool",
      "parameters": {
        "index": "my-knowledge-base",
        "embedding_model_id": "hZj9Bo0Bpc3sThaJdY9i",
        "embedding_field": "chunks.embedding",
        "inference_model_id": "kLj9Bo0Bpc3sThaJdY9x",
        "k": 5,
        "source_fields": ["title", "chunks.text"]
      }
    }
  ]
}

For parameter descriptions, see Register parameters.

Lucenia responds with an agent ID:

{
  "agent_id": "9X7xWI0Bpc3sThaJdY9i"
}

Step 2: Run the agent

Run the agent, providing the question to answer:

POST /_plugins/_ml/agents/9X7xWI0Bpc3sThaJdY9i/_execute
{
  "parameters": {
    "query_text": "How do I reproject a raster to a different coordinate system?"
  }
}

The tool embeds the question, retrieves the top k matching documents, fills them into the prompt template as ${parameters.context}, and asks the generation model to answer. Lucenia returns the generated answer:

{
  "inference_results": [
    {
      "output": [
        {
          "name": "response",
          "result": "To reproject a raster, specify the target coordinate reference system (CRS) ..."
        }
      ]
    }
  ]
}

Register parameters

The following table lists all tool parameters that are available when registering an agent. The RAGTool accepts every retrieval parameter of the VectorDBTool, plus the generation parameters below.

Parameter	Type	Required/Optional	Description
index	String	Required	The index to search.
embedding_model_id	String	Required	The ID of the embedding model used to embed the question. Must match the model used to embed the indexed documents. The alias model_id is also accepted.
embedding_field	String	Required	The knn_vector field to run the k-NN search against.
inference_model_id	String	Required	The ID of the generation model (chat/large language model) that produces the answer from the retrieved context.
k	Integer	Optional	The number of nearest neighbors to retrieve. Default is 10. The alias doc_size is also accepted.
source_fields	String or Array	Optional	The _source fields to include as context, as a comma-separated string or a JSON array. Default is all source fields.
filter	Object	Optional	A query domain-specific language (DSL) object applied as a filter alongside the k-NN search.
prompt_template	String	Optional	The prompt sent to the generation model. Supports the ${parameters.context} and ${parameters.question} substitution placeholders. Defaults to a grounded template that instructs the model to answer only from the provided context and to say it doesn't know when the context is insufficient.
context_field	String	Optional	The parameter name under which the retrieved context is passed to the generation model. Default is context.

Execute parameters

The following table lists all tool parameters that are available when running the agent.

Parameter	Type	Required/Optional	Description
query_text	String	Required	The question to retrieve context for and answer. If omitted, the tool falls back to the raw input parameter.