Search Index tool
Introduced 2.13
The SearchIndexTool searches an index using a query written in query domain-specific language (DSL) and returns the query results.
Step 1: Register a flow agent that will run the SearchIndexTool
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_Search_Index_Tool",
"type": "flow",
"description": "this is a test for search index tool",
"tools": [
{
"type": "SearchIndexTool"
}
]
}
OpenSearch responds with an agent ID:
{
"agent_id": "9X7xWI0Bpc3sThaJdY9i"
}
Step 2: Run the agent
Before you run the agent, make sure that you add the sample OpenSearch Dashboards Sample eCommerce orders dataset. To learn more, see Adding sample data.
Then, run the agent by sending the following request. The SearchIndexTool takes one parameter named input. This parameter includes the index name and the query:
POST /_plugins/_ml/agents/9X7xWI0Bpc3sThaJdY9i/_execute
{
"parameters": {
"input": "{\"index\": \"opensearch_dashboards_sample_data_ecommerce\", \"query\": {\"size\": 20, \"_source\": \"email\"}}"
}
}
For parameter descriptions, see Execute parameters.
The query passed in the previous request is equivalent to the following query:
GET opensearch_dashboards_sample_data_ecommerce/_search
{
"size": 20,
"_source": "email"
}
OpenSearch returns the query results:
{
"inference_results": [
{
"output": [
{
"name": "response",
"result": """{"_index":"opensearch_dashboards_sample_data_ecommerce","_source":{"email":"eddie@underwood-family.zzz"},"_id":"_bJVWY0BAehlDanXJnAJ","_score":1.0}
{"_index":"opensearch_dashboards_sample_data_ecommerce","_source":{"email":"mary@bailey-family.zzz"},"_id":"_rJVWY0BAehlDanXJnAJ","_score":1.0}
{"_index":"opensearch_dashboards_sample_data_ecommerce","_source":{"email":"gwen@butler-family.zzz"},"_id":"_7JVWY0BAehlDanXJnAJ","_score":1.0}
{"_index":"opensearch_dashboards_sample_data_ecommerce","_source":{"email":"diane@chandler-family.zzz"},"_id":"ALJVWY0BAehlDanXJnEJ","_score":1.0}
{"_index":"opensearch_dashboards_sample_data_ecommerce","_source":{"email":"eddie@weber-family.zzz"},"_id":"AbJVWY0BAehlDanXJnEJ","_score":1.0}
{"_index":"opensearch_dashboards_sample_data_ecommerce","_source":{"email":"diane@goodwin-family.zzz"},"_id":"ArJVWY0BAehlDanXJnEJ","_score":1.0}
{"_index":"opensearch_dashboards_sample_data_ecommerce","_source":{"email":"oliver@rios-family.zzz"},"_id":"A7JVWY0BAehlDanXJnEJ","_score":1.0}
{"_index":"opensearch_dashboards_sample_data_ecommerce","_source":{"email":"abd@sutton-family.zzz"},"_id":"BLJVWY0BAehlDanXJnEJ","_score":1.0}
{"_index":"opensearch_dashboards_sample_data_ecommerce","_source":{"email":"wilhemina st.@tran-family.zzz"},"_id":"BbJVWY0BAehlDanXJnEJ","_score":1.0}
{"_index":"opensearch_dashboards_sample_data_ecommerce","_source":{"email":"rabbia al@baker-family.zzz"},"_id":"BrJVWY0BAehlDanXJnEJ","_score":1.0}
{"_index":"opensearch_dashboards_sample_data_ecommerce","_source":{"email":"rabbia al@romero-family.zzz"},"_id":"B7JVWY0BAehlDanXJnEJ","_score":1.0}
{"_index":"opensearch_dashboards_sample_data_ecommerce","_source":{"email":"eddie@gregory-family.zzz"},"_id":"CLJVWY0BAehlDanXJnEJ","_score":1.0}
{"_index":"opensearch_dashboards_sample_data_ecommerce","_source":{"email":"sultan al@pratt-family.zzz"},"_id":"CbJVWY0BAehlDanXJnEJ","_score":1.0}
{"_index":"opensearch_dashboards_sample_data_ecommerce","_source":{"email":"eddie@wolfe-family.zzz"},"_id":"CrJVWY0BAehlDanXJnEJ","_score":1.0}
{"_index":"opensearch_dashboards_sample_data_ecommerce","_source":{"email":"sultan al@thompson-family.zzz"},"_id":"C7JVWY0BAehlDanXJnEJ","_score":1.0}
{"_index":"opensearch_dashboards_sample_data_ecommerce","_source":{"email":"sultan al@boone-family.zzz"},"_id":"DLJVWY0BAehlDanXJnEJ","_score":1.0}
{"_index":"opensearch_dashboards_sample_data_ecommerce","_source":{"email":"george@hubbard-family.zzz"},"_id":"DbJVWY0BAehlDanXJnEJ","_score":1.0}
{"_index":"opensearch_dashboards_sample_data_ecommerce","_source":{"email":"boris@maldonado-family.zzz"},"_id":"DrJVWY0BAehlDanXJnEJ","_score":1.0}
{"_index":"opensearch_dashboards_sample_data_ecommerce","_source":{"email":"yahya@rivera-family.zzz"},"_id":"D7JVWY0BAehlDanXJnEJ","_score":1.0}
{"_index":"opensearch_dashboards_sample_data_ecommerce","_source":{"email":"brigitte@morris-family.zzz"},"_id":"ELJVWY0BAehlDanXJnEJ","_score":1.0}
"""
}
]
}
]
}
Using the tool in a conversational agent
In a conversational agent that uses function calling, the LLM provides the tool input according to the tool’s input schema. By default, the input schema requires the LLM to provide the index and query parameters. To have the LLM provide only a question, specify the index and a query in the tool parameters and define a custom input schema in attributes.input_schema.
The following tool definition runs a neural query on the test_population_data index. The LLM provides a question, which the tool uses as the query_text:
{
"type": "SearchIndexTool",
"name": "retrieve_population_data",
"description": "This tool provides population data of US cities.",
"parameters": {
"input": "{\"index\": \"${parameters.index}\", \"query\": ${parameters.query} }",
"index": "test_population_data",
"query": {
"query": {
"neural": {
"population_description_embedding": {
"query_text": "${parameters.question}",
"model_id": "your_text_embedding_model_id"
}
}
},
"size": 2,
"_source": "population_description"
}
},
"attributes": {
"input_schema": {
"type": "object",
"properties": {
"question": {
"type": "string",
"description": "Natural language question"
}
},
"required": [ "question" ],
"additionalProperties": false
},
"strict": false
}
}
For a complete example, see Using the Search Index tool with a neural query.
Execute parameters
The following table lists all tool parameters that are available when running the agent.
| Parameter | Type | Description |
|---|---|---|
input | String | The index name and the query to use for search, in JSON format. The index parameter contains the name of the index, and the query parameter contains the query formatted in Query DSL. For example, "{\"index\": \"opensearch_dashboards_sample_data_ecommerce\", \"query\": {\"size\": 22, \"_source\": \"category\"}}". The input parameter and the index and query parameters it contains are required unless you provide the top-level index and query parameters. |
index | String | The name of the index to search. Used together with query when input is not provided. |
query | String | The search query in Query DSL format, as a JSON string (for example, "{\"size\": 1, \"_source\": \"email\"}"). Used together with index when input is not provided. |
return_raw_response | Boolean | If true, the tool returns the full search response as a JSON object instead of one line per hit. Default is false. |
Testing the tool
You can run this tool either as part of an agent workflow or independently using the Execute Tool API. The Execute Tool API is useful for testing individual tools or performing standalone operations.