Updating documentation, removing experimental mentions, addressing comments

joshpalis · joshpalis · commit 9c4da4bf9e2f · 2025-09-30T18:28:43.000Z
Signed-off-by: Joshua Palis &lt;jpalis@amazon.com&gt;
diff --git a/_ml-commons-plugin/agents-tools/tools/query-planning-tool.md b/_ml-commons-plugin/agents-tools/tools/query-planning-tool.md
@@ -17,42 +17,9 @@ Introduced in 3.2
 {: .label .label-purple }
 <!-- vale on -->
 
-This is an experimental feature and is not recommended for use in a production environment. For updates on the progress of the feature or if you want to leave feedback, join the discussion on the [OpenSearch forum](https://forum.opensearch.org/).    
-{: .warning}
-
 The `QueryPlanningTool` generates an OpenSearch query domain-specific language (DSL) query from a natural language question.
 
-## Step 1: Enable the agentic search feature flag
-
-To use the `QueryPlanningTool`, you must first enable the `agentic_search_enabled` setting:
-
-```json
-PUT _cluster/settings
-{
-  "persistent" : {
-    "plugins.ml_commons.agentic_search_enabled" : true
-  }
-}
-```
-{% include copy-curl.html %}
-
-OpenSearch responds with an acknowledgment:
-
-```json
-{
-  "acknowledged": true,
-  "persistent": {
-    "plugins": {
-      "ml_commons": {
-        "agentic_search_enabled": "true"
-      }
-    }
-  },
-  "transient": {}
-}
-```
-
-## Step 2: Register and deploy a model
+## Step 1: Register and deploy a model
 
 The following request registers a remote model from Amazon Bedrock and deploys it to your cluster. The API call creates the connector and model in one step.
 
@@ -143,12 +110,13 @@ OpenSearch responds with the model ID:
 }
 ```
 
-## Step 3: Register an agent
+## Step 2: Register an agent
 
 You can use any [OpenSearch agent type](https://opensearch.org/docs/latest/ml-commons-plugin/agents-tools/agents/) to run the `QueryPlanningTool`. The following example uses a `flow` agent, which runs a sequence of tools in order and returns the last tool's output.
 
 When registering the agent, you can override parameters set during model registration, such as `query_planner_system_prompt` and `query_planner_user_prompt`. The following example registers an agent with a default `llmGenerated` generation_type.
 
+### LLM Generated
 ```json
 POST /_plugins/_ml/agents/_register
 {
@@ -160,16 +128,17 @@ POST /_plugins/_ml/agents/_register
       "type": "QueryPlanningTool",
       "description": "A general tool to answer any question.",
       "parameters": {
-        "model_id": "ANiSxJgBOh0h20Y9XYXl",
-        "response_filter": "$.output.message.content[0].text"
+        "model_id": "ANiSxJgBOh0h20Y9XYXl"
       }
     }
   ]
 }
 ```
 {% include copy-curl.html %}
 
-You can also register an agent with a `user_templates` generation_type which provides an LLM with an array of [OpenSearch Search Templates](https://docs.opensearch.org/latest/api-reference/search-apis/search-template/index/). These templates are provided to the LLM as additional context to assist the LLM in OpenSearch DSL generation. The following example creates a few search templates and registers an agent with a `user_template` generation_type.
+### User Templates
+
+You can also register an agent with a `user_templates` generation_type which provides an LLM with an array of [OpenSearch Search Templates]({{site.url}}{{site.baseurl}}/api-reference/search-apis/search-template/index/). These templates are provided to the LLM as additional context to assist the LLM in OpenSearch DSL generation. The following example creates a few search templates and registers an agent with a `user_template` generation_type.
 
 Creating search templates :
 ```json
@@ -221,7 +190,6 @@ POST /_plugins/_ml/agents/_register
             "description": "A general tool to answer any question",
             "parameters": {
                 "model_id": "ANiSxJgBOh0h20Y9XYXl",
-                "response_filter": "$.output.message.content[0].text",
                 "generation_type": "user_templates",
                 "search_templates": [
                     {
@@ -240,7 +208,7 @@ POST /_plugins/_ml/agents/_register
 }
 ```
 
-Each `search_templates` array entry must have a `template_id` and `template_description`. The LLM will use the description as additional context to help it choose the best template to use when generating an OpenSearch DSL query based on the uses provided `query_text`. If the LLM determines that the provided search templates are not applicable to the given `query_text`, then the LLM will use a default match all query search template. It is important to note that the LLM will not directly render the final Opensearch DSL query with the chosen template, but rather use the template source as additional context to help it form the query.
+Each `search_templates` list entry must have a `template_id` and `template_description`. The LLM will use the description as additional context to help it choose the best template to use when generating an OpenSearch DSL query based on the uses provided `question`. If the LLM determines that the provided search templates are not applicable to the given `question`, then the LLM will use a default match all query. It is important to note that the LLM will not directly render the final OpenSearch DSL query with the chosen template, but rather use the template source as additional context to help it form the query.
 
 For parameter descriptions, see [Register parameters](#register-parameters).
 
@@ -252,16 +220,16 @@ OpenSearch responds with an agent ID:
 }
 ```
 
-## Step 4: Execute the agent
+## Step 3: Execute the agent
 
 Execute the agent by sending the following request:
 
 ```json
 POST /_plugins/_ml/agents/RNjQi5gBOh0h20Y9-RX1/_execute
 {
     "parameters": {
-        "query_planner_user_prompt": "You are an OpenSearch Query DSL generation assistant, generate an OpenSearch Query DSL to retrieve the most relevant documents for the user provided natural language question: ${parameters.query_text}, please return the query dsl only, no other texts. Please don't use size:0, because that would limit the query to return no result. please return a query to find the most relevant documents related to users question. For example: {\"query\":{\"match\":{\"species\":\"setosa\"}}} \n",
-        "query_text": "How many iris flowers of type setosa are there?"
+        "query_planner_user_prompt": "You are an OpenSearch Query DSL generation assistant, generate an OpenSearch Query DSL to retrieve the most relevant documents for the user provided natural language question: ${parameters.question}, please return the query dsl only, no other texts. Please don't use size:0, because that would limit the query to return no result. please return a query to find the most relevant documents related to users question. For example: {\"query\":{\"match\":{\"species\":\"setosa\"}}} \n",
+        "question": "How many iris flowers of type setosa are there?"
     }
 }
 ```
@@ -294,7 +262,7 @@ Parameter	| Type | Required/Optional | Description
 `response_filter` | String | Optional | A JSONPath expression used to extract the generated query from the LLM's response.
 `generation_type` | String | Optional | The type of query generation. Currently, only `llmGenerated` and `user_templates` are supported. Defaults to `llmGenerated`.
 `query_planner_system_prompt` | String | Optional | A system prompt that provides high-level instructions to the LLM. Defaults to "You are an OpenSearch Query DSL generation assistant, translating natural language questions to OpenSeach DSL Queries".
-`query_planner_user_prompt` | String | Optional | A user prompt template for the LLM. It can contain placeholders for execution-time parameters like `${parameters.query_text}`.
+`query_planner_user_prompt` | String | Optional | A user prompt template for the LLM. It can contain placeholders for execution-time parameters like `${parameters.question}`.
 `search_templates` | Array | Optional | Applicable only for `user_templates` generation_type. A list of search template IDs and descriptions which an LLM will use as context to create an OpenSearch DSL query. Each entry within the `search_templates` array must include a `template_id` and a `template_description` which provides the LLM with additional context on the contents of the search template
 
 ## Execute parameters
@@ -307,7 +275,7 @@ There are three layers of parameters to consider:
 
 2.  **Tool parameters**: The `QueryPlanningTool` uses its own set of parameters, such as `query_planner_user_prompt` and `query_planner_system_prompt`, to construct the final string that will be passed to the connector. The tool takes the `query_planner_user_prompt` string and resolves any variables within it, and the resulting string is then used to fill the appropriate variable (for example, `${parameters.query_planner_user_prompt}`) in the connector's `request_body`.
 
-3.  **Prompt variables**: These are the variables inside the `query_planner_user_prompt`, which have the format `${parameters.your_variable_name}`. These must be provided in the `_execute` API call. For example, if your `user_prompt` is "Generate a query for: ${parameters.query_text}", then you must provide a `query_text` parameter when you run the agent.
+3.  **Prompt variables**: These are the variables inside the `query_planner_user_prompt`, which have the format `${parameters.your_variable_name}`. These must be provided in the `_execute` API call. For example, if your `user_prompt` is "Generate a query for: ${parameters.question}", then you must provide a `question` parameter when you run the agent.
 
 In summary, the required parameters for an `_execute` call are the **prompt variables**. The tool's own parameters (like `query_planner_user_prompt`) can be overridden at execution time to change how the final prompt is constructed.
 
@@ -351,7 +319,7 @@ POST /_plugins/_ml/agents/your_agent_id/_execute
 
 ## Next steps
 
-This is an experimental feature. See the following GitHub issues for information about future enhancements:
+See the following GitHub issues for information about future enhancements:
 
 - [[RFC] Design for Agentic Search #1479](https://github.com/opensearch-project/neural-search/issues/1479)
 - [[RFC] Agentic Search in OpenSearch #4005](https://github.com/opensearch-project/ml-commons/issues/4005)
