Vector DB tool

Introduced 0.12.0

The VectorDBTool performs semantic retrieval: it embeds your query text with an embedding model and runs a k-NN search, returning the matching documents as context. You provide the text, the tool embeds it, issues the k-NN query for you, and hands back the matched documents' _id and selected _source fields.

The embedding model can be a local model or any remote connector — Bedrock, OpenAI, Vertex, Azure, or a self-hosted HTTP endpoint. The tool is cloud-agnostic: everything is keyed on the model ID, so it makes no assumption about a particular provider.

Prerequisites

Before registering the tool, you need:

• An index whose documents contain a knn_vector field, populated at ingest time with an embedding model.
• The ID of the same embedding model, deployed through the ML Commons plugin.

For retrieval to be meaningful, the model you configure on the tool must be the same one used to embed the documents at ingest time. Vectors produced by different models don't share the same space and aren't comparable.

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

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_VectorDB_tool",
  "type": "flow",
  "description": "this is a test agent for the VectorDBTool",
  "tools": [
    {
      "type": "VectorDBTool",
      "name": "DemoVectorDBTool",
      "parameters": {
        "index": "my-knowledge-base",
        "embedding_model_id": "hZj9Bo0Bpc3sThaJdY9i",
        "embedding_field": "chunks.embedding",
        "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 query text to retrieve context for:

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

The tool embeds query_text, runs a k-NN search against the embedding_field, and returns the matched documents. Each result contains the document's _id and the selected _source fields:

{
  "inference_results": [
    {
      "output": [
        {
          "name": "response",
          "result": """{"_id":"a1eMb4kBJ1eYAeTMAljY","_source":{"title":"Spatial reprojection","chunks.text":"Reproject a raster by specifying the target CRS ..."}}
{"_id":"b2eMb4kBJ1eYAeTMAljZ","_source":{"title":"Coordinate systems","chunks.text":"A coordinate reference system defines ..."}}
"""
        }
      ]
    }
  ]
}

Register parameters

The following table lists all tool parameters that are available when registering an agent.

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 query text. Must match the model used to embed the indexed documents. The alias model_id is also accepted. The model can be local or any remote connector.
embedding_field	String	Required	The knn_vector field to run the k-NN search against.
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 return for each matched document, 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 (for example, to scope results by tenant or metadata).

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 natural-language text to embed and search with. If omitted, the tool falls back to the raw input parameter.