From d252659c6ece49fcac82a696cf15dfa28dbbbe1c Mon Sep 17 00:00:00 2001 From: Nathalie Jonathan Date: Fri, 10 Oct 2025 15:51:42 -0700 Subject: [PATCH 1/6] Add execute tool API doc Signed-off-by: Nathalie Jonathan --- _ml-commons-plugin/api/execute-tool.md | 85 ++++++++++++++++++++++++++ _ml-commons-plugin/api/index.md | 1 + _ml-commons-plugin/api/profile.md | 2 +- _ml-commons-plugin/api/stats.md | 2 +- 4 files changed, 88 insertions(+), 2 deletions(-) create mode 100644 _ml-commons-plugin/api/execute-tool.md diff --git a/_ml-commons-plugin/api/execute-tool.md b/_ml-commons-plugin/api/execute-tool.md new file mode 100644 index 00000000000..32686624669 --- /dev/null +++ b/_ml-commons-plugin/api/execute-tool.md @@ -0,0 +1,85 @@ +--- +layout: default +title: Execute tool +parent: ML Commons APIs +nav_order: 100 +--- + +# Execute Tool API +**Introduced 3.2** +{: .label .label-purple } + +The Execute Tool API allows you to run individual tools directly without creating an agent first. This API is particularly beneficial for applications requiring quick, single-tool operations where the overhead of agent creation and management is unnecessary. + +## Use cases + +The Execute Tool API is ideal for: +- **Direct tool execution**: Run specific tools like search, data analysis, or retrieval operations without agent setup. +- **Testing and debugging**: Quickly test tool functionality during development. +- **Lightweight integrations**: Integrate specific OpenSearch capabilities into applications without full agent workflows. +- **Standalone operations**: Perform single tasks that don't require conversation memory or complex orchestration. + +## Supported tools + +This API supports all available OpenSearch tools. Each tool can be executed independently with its specific parameters. + +For more information regarding the list of available tools, see [Tools]({{site.url}}{{site.baseurl}}/ml-commons-plugin/agents-tools/tools/index/). + +## Endpoint + +```json +POST /_plugins/_ml/tools/_execute/ +``` + +## Request body field + +The following table lists all request body field. + +| Field | Data type | Required | Description | +| :--- | :--- | :--- | :--- | +| `parameters` | Object | Yes | Contains tool-specific parameters that vary depending on the tool being executed. Each tool requires different parameters based on its functionality. | + +### Parameter structure + +The `parameters` object combines the parameters used during tool registration and tool execution. The specific fields depend on the tool being executed. + +To determine the required parameters for a specific tool, refer to the individual tool documentation in the [Tools]({{site.url}}{{site.baseurl}}/ml-commons-plugin/agents-tools/tools/index/) section. + +| Component | Description | +|:-------------------------|:-----------------------------------------------| +| Tool register parameters | Parameters specified during tool registration. | +| Tool execute parameters | Parameters specified during tool execution. | + +## Example request + +```json +POST /_plugins/_ml/tools/_execute/PPLTool +{ + "parameters": { + "question": "what's the population of Seattle in 2021?", + "index": "test-population", + "model_id": "1TuQQ5gBMJhRgCqgSV79" // Remote model + } +} + +``` +{% include copy-curl.html %} + +## Example response + +```json +{ + "inference_results": [ + { + "output": [ + { + "name": "response", + "dataAsMap": { + "result":"{\"ppl\":\"source\=test-population | where QUERY_STRING([\'population_description\'], \'Seattle\') AND QUERY_STRING([\'population_description\'], \'2021\')\",\"executionResult\":\"{\\n \\\"schema\\\": [\\n {\\n \\\"name\\\": \\\"population_description\\\",\\n \\\"type\\\": \\\"string\\\"\\n }\\n ],\\n \\\"datarows\\\": [],\\n \\\"total\\\": 0,\\n \\\"size\\\": 0\\n}\"}" + } + } + ] + } + ] +} +``` \ No newline at end of file diff --git a/_ml-commons-plugin/api/index.md b/_ml-commons-plugin/api/index.md index ab34d954c0f..7ca612e0ce5 100644 --- a/_ml-commons-plugin/api/index.md +++ b/_ml-commons-plugin/api/index.md @@ -21,6 +21,7 @@ OpenSearch supports the following machine learning (ML) APIs: - [Agentic Memory APIs]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/) - [Controller APIs]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/controller-apis/index/) - [Execute Algorithm API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/execute-algorithm/) +- [Execute Tool API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/execute-tool/) - [Tasks APIs]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/tasks-apis/index/) - [Profile API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/profile/) - [Stats API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/stats/) diff --git a/_ml-commons-plugin/api/profile.md b/_ml-commons-plugin/api/profile.md index dc9ec94cbe8..f281c25dcf3 100644 --- a/_ml-commons-plugin/api/profile.md +++ b/_ml-commons-plugin/api/profile.md @@ -2,7 +2,7 @@ layout: default title: Profile parent: ML Commons APIs -nav_order: 100 +nav_order: 110 --- # Profile API diff --git a/_ml-commons-plugin/api/stats.md b/_ml-commons-plugin/api/stats.md index 45b145effe6..43b31b38061 100644 --- a/_ml-commons-plugin/api/stats.md +++ b/_ml-commons-plugin/api/stats.md @@ -2,7 +2,7 @@ layout: default title: Stats parent: ML Commons APIs -nav_order: 110 +nav_order: 120 --- # Stats API From 8c83c170dfd7d70f78840159490bb6f6756d2982 Mon Sep 17 00:00:00 2001 From: Nathalie Jonathan Date: Mon, 13 Oct 2025 10:15:10 -0700 Subject: [PATCH 2/6] Address comments Signed-off-by: Nathalie Jonathan --- _ml-commons-plugin/api/execute-tool.md | 38 ++++++++++++++++++++++++-- 1 file changed, 36 insertions(+), 2 deletions(-) diff --git a/_ml-commons-plugin/api/execute-tool.md b/_ml-commons-plugin/api/execute-tool.md index 32686624669..c0271634e38 100644 --- a/_ml-commons-plugin/api/execute-tool.md +++ b/_ml-commons-plugin/api/execute-tool.md @@ -31,6 +31,9 @@ For more information regarding the list of available tools, see [Tools]({{site.u POST /_plugins/_ml/tools/_execute/ ``` +The parameter refers to the predefined tool type name (such as PPLTool, SearchIndexTool, VectorDBTool, etc.), not a custom tool name that you define. +{: .note} + ## Request body field The following table lists all request body field. @@ -50,7 +53,38 @@ To determine the required parameters for a specific tool, refer to the individua | Tool register parameters | Parameters specified during tool registration. | | Tool execute parameters | Parameters specified during tool execution. | -## Example request +## Example requests + +### Example 1: Simple tool execution + +```json +POST /_plugins/_ml/tools/_execute/ListIndexTool +{ + "parameters": { + "question": "How many indices do I have?" + } +} +``` +{% include copy-curl.html %} + +### Example response + +```json +{ + "inference_results": [ + { + "output": [ + { + "name": "response", + "result": "row,health,status,index,uuid,pri(number of primary shards),rep(number of replica shards),docs.count(number of available documents),docs.deleted(number of deleted documents),store.size(store size of primary and replica shards),pri.store.size(store size of primary shards)\n1,yellow,open,movies,kKcJKu2aT0C9uwJIPP4hxw,2,1,2,0,7.8kb,7.8kb\n2,green,open,.plugins-ml-config,h8ovp_KFTq6_zvcBEn2kvg,1,0,1,0,4kb,4kb\n3,green,open,.plugins-ml-agent,1oGlUBCIRAGXLbLv27Qg8w,1,0,1,0,8kb,8kb\n" + } + ] + } + ] +} +``` + +### Example 2: Complex tool execution ```json POST /_plugins/_ml/tools/_execute/PPLTool @@ -65,7 +99,7 @@ POST /_plugins/_ml/tools/_execute/PPLTool ``` {% include copy-curl.html %} -## Example response +### Example response ```json { From 4aaf7eccbf0c1b19b46fc8f67892220012ce257f Mon Sep 17 00:00:00 2001 From: Nathan Bower Date: Mon, 13 Oct 2025 13:35:11 -0400 Subject: [PATCH 3/6] Apply suggestions from code review Signed-off-by: Nathan Bower --- _ml-commons-plugin/api/execute-tool.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/_ml-commons-plugin/api/execute-tool.md b/_ml-commons-plugin/api/execute-tool.md index c0271634e38..47d9118cfca 100644 --- a/_ml-commons-plugin/api/execute-tool.md +++ b/_ml-commons-plugin/api/execute-tool.md @@ -31,7 +31,7 @@ For more information regarding the list of available tools, see [Tools]({{site.u POST /_plugins/_ml/tools/_execute/ ``` -The parameter refers to the predefined tool type name (such as PPLTool, SearchIndexTool, VectorDBTool, etc.), not a custom tool name that you define. +The `` parameter refers to the predefined tool type name, such as `PPLTool`, `SearchIndexTool`, or `VectorDBTool`,---not a custom tool name that you define. {: .note} ## Request body field @@ -50,10 +50,11 @@ To determine the required parameters for a specific tool, refer to the individua | Component | Description | |:-------------------------|:-----------------------------------------------| -| Tool register parameters | Parameters specified during tool registration. | -| Tool execute parameters | Parameters specified during tool execution. | +| Tool registration parameters | Parameters specified during tool registration. | +| Tool execution parameters | Parameters specified during tool execution. | ## Example requests +The following are examples of both simple and complex tool execution. ### Example 1: Simple tool execution From 550db36849363f3fd2b7803794c491f53acbc5f6 Mon Sep 17 00:00:00 2001 From: Fanit Kolchina Date: Mon, 13 Oct 2025 16:25:15 -0400 Subject: [PATCH 4/6] Doc review Signed-off-by: Fanit Kolchina --- .../agents-tools/tools/agent-tool.md | 6 +++- .../agents-tools/tools/connector-tool.md | 6 +++- .../tools/create-anomaly-detector.md | 4 +++ .../tools/data-distribution-tool.md | 4 +++ .../agents-tools/tools/index-mapping-tool.md | 6 +++- .../agents-tools/tools/index.md | 2 ++ .../agents-tools/tools/list-index-tool.md | 6 +++- .../tools/log-pattern-analysis-tool.md | 6 +++- .../agents-tools/tools/log-pattern-tool.md | 6 +++- .../agents-tools/tools/ml-model-tool.md | 8 ++++-- .../agents-tools/tools/neural-sparse-tool.md | 5 ++++ .../agents-tools/tools/ppl-tool.md | 8 ++++-- .../agents-tools/tools/query-planning-tool.md | 6 +++- .../agents-tools/tools/rag-tool.md | 6 +++- .../agents-tools/tools/search-alerts-tool.md | 4 +++ .../tools/search-anomaly-detectors.md | 4 +++ .../tools/search-anomaly-results.md | 4 +++ .../agents-tools/tools/search-index-tool.md | 6 +++- .../tools/search-monitors-tool.md | 4 +++ .../agents-tools/tools/vector-db-tool.md | 4 +++ .../agents-tools/tools/visualization-tool.md | 6 +++- .../agents-tools/tools/web-search-tool.md | 6 +++- _ml-commons-plugin/api/execute-tool.md | 28 +++++++++++-------- 23 files changed, 119 insertions(+), 26 deletions(-) diff --git a/_ml-commons-plugin/agents-tools/tools/agent-tool.md b/_ml-commons-plugin/agents-tools/tools/agent-tool.md index 272af51e4d3..e0e4ec09c08 100644 --- a/_ml-commons-plugin/agents-tools/tools/agent-tool.md +++ b/_ml-commons-plugin/agents-tools/tools/agent-tool.md @@ -104,4 +104,8 @@ The following table lists all tool parameters that are available when running th Parameter | Type | Required/Optional | Description :--- | :--- | :--- | :--- -`question` | String | Required | The natural language question to send to the LLM. \ No newline at end of file +`question` | String | Required | The natural language question to send to the LLM. + +## Testing the tool + +You can run this tool either as part of an agent workflow or independently using the [Execute Tool API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/execute-tool/). The Execute Tool API is useful for testing individual tools or performing standalone operations. \ No newline at end of file diff --git a/_ml-commons-plugin/agents-tools/tools/connector-tool.md b/_ml-commons-plugin/agents-tools/tools/connector-tool.md index dfe4770932c..ace94c38440 100644 --- a/_ml-commons-plugin/agents-tools/tools/connector-tool.md +++ b/_ml-commons-plugin/agents-tools/tools/connector-tool.md @@ -165,4 +165,8 @@ When running the agent, you can define any parameter needed for the API call in "request_body": "{ \"number1\":\"${parameters.number1}\", \"number2\":\"${parameters.number2}\" }" } ] -``` \ No newline at end of file +``` + +## Testing the tool + +You can run this tool either as part of an agent workflow or independently using the [Execute Tool API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/execute-tool/). The Execute Tool API is useful for testing individual tools or performing standalone operations. \ No newline at end of file diff --git a/_ml-commons-plugin/agents-tools/tools/create-anomaly-detector.md b/_ml-commons-plugin/agents-tools/tools/create-anomaly-detector.md index a66d85a5cc7..404ad7eacf8 100644 --- a/_ml-commons-plugin/agents-tools/tools/create-anomaly-detector.md +++ b/_ml-commons-plugin/agents-tools/tools/create-anomaly-detector.md @@ -167,3 +167,7 @@ The following table lists the available tool parameters for running the agent. Parameter | Type | Required/Optional | Description :--- | :--- | :--- | :--- `index` | String | Required | The index name. Supports wildcards (for example, `weblogs-*`). If wildcards are used, then the tool fetches mappings from the first resolved index and sends them to the LLM. + +## Testing the tool + +You can run this tool either as part of an agent workflow or independently using the [Execute Tool API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/execute-tool/). The Execute Tool API is useful for testing individual tools or performing standalone operations. \ No newline at end of file diff --git a/_ml-commons-plugin/agents-tools/tools/data-distribution-tool.md b/_ml-commons-plugin/agents-tools/tools/data-distribution-tool.md index 6f35f900411..26ccbbe17ea 100644 --- a/_ml-commons-plugin/agents-tools/tools/data-distribution-tool.md +++ b/_ml-commons-plugin/agents-tools/tools/data-distribution-tool.md @@ -195,6 +195,10 @@ The following table lists the available tool parameters for running the agent. | `dsl` | String | Optional | A complete raw DSL query as a JSON string. If provided, takes precedence over the `filter` parameter. | | `ppl` | String | Optional | A complete PPL statement without time information. Used when `queryType` is `ppl`. | +## Testing the tool + +You can run this tool either as part of an agent workflow or independently using the [Execute Tool API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/execute-tool/). The Execute Tool API is useful for testing individual tools or performing standalone operations. + ## Limitations The Data Distribution tool has the following limitations: diff --git a/_ml-commons-plugin/agents-tools/tools/index-mapping-tool.md b/_ml-commons-plugin/agents-tools/tools/index-mapping-tool.md index 8649d2d74d7..39cc6f91091 100644 --- a/_ml-commons-plugin/agents-tools/tools/index-mapping-tool.md +++ b/_ml-commons-plugin/agents-tools/tools/index-mapping-tool.md @@ -117,4 +117,8 @@ The following table lists all tool parameters that are available when running th Parameter | Type | Required/Optional | Description :--- | :--- | :--- | :--- `question` | String | Required | The natural language question to send to the LLM. -`index` | Array | Optional | A comma-delimited list of one or more indexes for which to obtain mapping and setting information. Default is an empty list, which means all indexes. \ No newline at end of file +`index` | Array | Optional | A comma-delimited list of one or more indexes for which to obtain mapping and setting information. Default is an empty list, which means all indexes. + +## Testing the tool + +You can run this tool either as part of an agent workflow or independently using the [Execute Tool API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/execute-tool/). The Execute Tool API is useful for testing individual tools or performing standalone operations. \ No newline at end of file diff --git a/_ml-commons-plugin/agents-tools/tools/index.md b/_ml-commons-plugin/agents-tools/tools/index.md index 0f3f27be146..cd3b903107e 100644 --- a/_ml-commons-plugin/agents-tools/tools/index.md +++ b/_ml-commons-plugin/agents-tools/tools/index.md @@ -31,6 +31,8 @@ Specify a tool by providing its `type`, `parameters`, and, optionally, a `descri Each tool takes a list of parameters specific to that tool. In the preceding example, the `AgentTool` takes an `agent_id` of the agent it will run. For a list of parameters, see each tool's documentation. +You can also run tools directly without creating an agent using the [Execute Tool API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/execute-tool/), which is useful for testing individual tools or performing standalone operations. + |Tool | Description | |:--- |:--- | |[`AgentTool`]({{site.url}}{{site.baseurl}}/ml-commons-plugin/agents-tools/tools/agent-tool/) |Runs any agent. | diff --git a/_ml-commons-plugin/agents-tools/tools/list-index-tool.md b/_ml-commons-plugin/agents-tools/tools/list-index-tool.md index 79d9d0d7b0d..41c02dbe497 100644 --- a/_ml-commons-plugin/agents-tools/tools/list-index-tool.md +++ b/_ml-commons-plugin/agents-tools/tools/list-index-tool.md @@ -130,4 +130,8 @@ The following table lists all tool parameters that are available when running th Parameter | Type | Required/Optional | Description :--- | :--- | :--- | :--- -`question` | String | Required | The natural language question to send to the LLM. \ No newline at end of file +`question` | String | Required | The natural language question to send to the LLM. + +## Testing the tool + +You can run this tool either as part of an agent workflow or independently using the [Execute Tool API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/execute-tool/). The Execute Tool API is useful for testing individual tools or performing standalone operations. \ No newline at end of file diff --git a/_ml-commons-plugin/agents-tools/tools/log-pattern-analysis-tool.md b/_ml-commons-plugin/agents-tools/tools/log-pattern-analysis-tool.md index 3249fa2cd6f..0d6a7f334e9 100644 --- a/_ml-commons-plugin/agents-tools/tools/log-pattern-analysis-tool.md +++ b/_ml-commons-plugin/agents-tools/tools/log-pattern-analysis-tool.md @@ -14,7 +14,7 @@ grand_parent: Agents and tools {: .label .label-purple } -The `LogPatternAnalysisTool` performs an advanced log analysis by detecting anomalous log patterns and sequences through comparative analysis between baseline and selection time ranges. It supports the following analysis modes: +The `LogPatternAnalysisTool` performs an advanced log analysis by detecting anomalous log patterns and sequences through comparative analysis between baseline and selection time ranges. It supports the following analysis modes: - Log sequence analysis (with trace correlation) - Log pattern difference analysis @@ -192,6 +192,10 @@ The following table lists the available tool parameters for running the agent. | `selectionTimeRangeStart` | String | Required | The start time for the analysis target period, in UTC date string format (for example, `2025-06-24 07:50:26`). | | `selectionTimeRangeEnd` | String | Required | The end time for the analysis target period, in UTC date string format (for example, `2025-06-24 07:55:56`). | +## Testing the tool + +You can run this tool either as part of an agent workflow or independently using the [Execute Tool API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/execute-tool/). The Execute Tool API is useful for testing individual tools or performing standalone operations. + ## Limitations The Log Pattern Analysis tool has the following limitations: diff --git a/_ml-commons-plugin/agents-tools/tools/log-pattern-tool.md b/_ml-commons-plugin/agents-tools/tools/log-pattern-tool.md index 3bbd09b1694..a179fa3b96a 100644 --- a/_ml-commons-plugin/agents-tools/tools/log-pattern-tool.md +++ b/_ml-commons-plugin/agents-tools/tools/log-pattern-tool.md @@ -117,4 +117,8 @@ Parameter | Type | Required/Optional | Description :--- | :--- |:-----------------------| :--- | `index` | String | Required for DSL queries | The index to search for pattern analysis. | | `input` | String | Required for DSL queries | A DSL query JSON as a string. If both `input` and `ppl` are provided, `input` (DSL) takes precedence. | -| `ppl` | String | Required for PPL queries | A PPL query string. Ignored if `input` is also provided. | \ No newline at end of file +| `ppl` | String | Required for PPL queries | A PPL query string. Ignored if `input` is also provided. | + +## Testing the tool + +You can run this tool either as part of an agent workflow or independently using the [Execute Tool API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/execute-tool/). The Execute Tool API is useful for testing individual tools or performing standalone operations. \ No newline at end of file diff --git a/_ml-commons-plugin/agents-tools/tools/ml-model-tool.md b/_ml-commons-plugin/agents-tools/tools/ml-model-tool.md index ceeda405283..048028d8063 100644 --- a/_ml-commons-plugin/agents-tools/tools/ml-model-tool.md +++ b/_ml-commons-plugin/agents-tools/tools/ml-model-tool.md @@ -14,7 +14,7 @@ plugins.ml_commons.rag_pipeline_feature_enabled: true {: .label .label-purple } -The `MLModelTool` runs a machine learning (ML) model and returns inference results. +The `MLModelTool` runs a machine learning (ML) model and returns inference results. ## Step 1: Create a connector for a model @@ -164,4 +164,8 @@ The following table lists all tool parameters that are available when running th Parameter | Type | Required/Optional | Description :--- | :--- | :--- | :--- -`question` | String | Required | The natural language question to send to the LLM. \ No newline at end of file +`question` | String | Required | The natural language question to send to the LLM. + +## Testing the tool + +You can run this tool either as part of an agent workflow or independently using the [Execute Tool API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/execute-tool/). The Execute Tool API is useful for testing individual tools or performing standalone operations. \ No newline at end of file diff --git a/_ml-commons-plugin/agents-tools/tools/neural-sparse-tool.md b/_ml-commons-plugin/agents-tools/tools/neural-sparse-tool.md index b78d3d641ed..9be67422c0a 100644 --- a/_ml-commons-plugin/agents-tools/tools/neural-sparse-tool.md +++ b/_ml-commons-plugin/agents-tools/tools/neural-sparse-tool.md @@ -221,3 +221,8 @@ The following table lists all tool parameters that are available when running th Parameter | Type | Required/Optional | Description :--- | :--- | :--- | :--- `question` | String | Required | The natural language question to send to the LLM. + + +## Testing the tool + +You can run this tool either as part of an agent workflow or independently using the [Execute Tool API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/execute-tool/). The Execute Tool API is useful for testing individual tools or performing standalone operations. \ No newline at end of file diff --git a/_ml-commons-plugin/agents-tools/tools/ppl-tool.md b/_ml-commons-plugin/agents-tools/tools/ppl-tool.md index 72d8ba30b5b..2cb1cc181fa 100644 --- a/_ml-commons-plugin/agents-tools/tools/ppl-tool.md +++ b/_ml-commons-plugin/agents-tools/tools/ppl-tool.md @@ -12,7 +12,7 @@ grand_parent: Agents and tools **Introduced 2.13** {: .label .label-purple } -The `PPLTool` translates natural language into a PPL query. The tool provides an `execute` flag to specify whether to run the query. If you set the flag to `true`, the `PPLTool` runs the query and returns the query and the results. +The `PPLTool` translates natural language into a PPL query. The tool provides an `execute` flag to specify whether to run the query. If you set the flag to `true`, the `PPLTool` runs the query and returns the query and the results. ## Prerequisite @@ -201,4 +201,8 @@ Parameter | Type | Required/Optional | Description :--- | :--- | :--- | :--- `index` | String | Required | The index on which to run the PPL query. `question` | String | Required | The natural language question to send to the LLM. -`verbose` | Boolean | Optional | Whether to provide verbose output. Default is `false`. \ No newline at end of file +`verbose` | Boolean | Optional | Whether to provide verbose output. 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]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/execute-tool/). The Execute Tool API is useful for testing individual tools or performing standalone operations. \ No newline at end of file diff --git a/_ml-commons-plugin/agents-tools/tools/query-planning-tool.md b/_ml-commons-plugin/agents-tools/tools/query-planning-tool.md index 1bec951294d..9d3518d1014 100644 --- a/_ml-commons-plugin/agents-tools/tools/query-planning-tool.md +++ b/_ml-commons-plugin/agents-tools/tools/query-planning-tool.md @@ -14,7 +14,7 @@ grand_parent: Agents and tools {: .label .label-purple } -The `QueryPlanningTool` generates an OpenSearch query domain-specific language (DSL) query from a natural language question. It is a core component of [agentic search]({{site.url}}{{site.baseurl}}/vector-search/ai-search/agentic-search/index/), which enables natural language query processing through agent-driven workflows. +The `QueryPlanningTool` generates an OpenSearch query domain-specific language (DSL) query from a natural language question. It is a core component of [agentic search]({{site.url}}{{site.baseurl}}/vector-search/ai-search/agentic-search/index/), which enables natural language query processing through agent-driven workflows. The `QueryPlanningTool` supports two approaches for generating DSL queries from natural language questions: @@ -522,6 +522,10 @@ GIVE THE OUTPUT PART ONLY IN YOUR RESPONSE (a single JSON object) Output: ``` +## Testing the tool + +You can run this tool either as part of an agent workflow or independently using the [Execute Tool API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/execute-tool/). The Execute Tool API is useful for testing individual tools or performing standalone operations. + ## Related pages - [Agentic search]({{site.url}}{{site.baseurl}}/vector-search/ai-search/agentic-search/index) \ No newline at end of file diff --git a/_ml-commons-plugin/agents-tools/tools/rag-tool.md b/_ml-commons-plugin/agents-tools/tools/rag-tool.md index 24e95286a4e..9b22798ec18 100644 --- a/_ml-commons-plugin/agents-tools/tools/rag-tool.md +++ b/_ml-commons-plugin/agents-tools/tools/rag-tool.md @@ -144,4 +144,8 @@ The following table lists all tool parameters that are available when running th Parameter | Type | Required/Optional | Description :--- | :--- | :--- | :--- -`question` | String | Required | The natural language question to send to the LLM. \ No newline at end of file +`question` | String | Required | The natural language question to send to the LLM. + +## Testing the tool + +You can run this tool either as part of an agent workflow or independently using the [Execute Tool API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/execute-tool/). The Execute Tool API is useful for testing individual tools or performing standalone operations. \ No newline at end of file diff --git a/_ml-commons-plugin/agents-tools/tools/search-alerts-tool.md b/_ml-commons-plugin/agents-tools/tools/search-alerts-tool.md index 76f9e4b4dc1..c9ce8994cba 100644 --- a/_ml-commons-plugin/agents-tools/tools/search-alerts-tool.md +++ b/_ml-commons-plugin/agents-tools/tools/search-alerts-tool.md @@ -122,3 +122,7 @@ The following table lists all tool parameters that are available when running th Parameter | Type | Required/Optional | Description :--- | :--- | :--- | :--- `question` | String | Required | The natural language question to send to the LLM. + +## Testing the tool + +You can run this tool either as part of an agent workflow or independently using the [Execute Tool API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/execute-tool/). The Execute Tool API is useful for testing individual tools or performing standalone operations. \ No newline at end of file diff --git a/_ml-commons-plugin/agents-tools/tools/search-anomaly-detectors.md b/_ml-commons-plugin/agents-tools/tools/search-anomaly-detectors.md index 9f31dea057f..c0978857c25 100644 --- a/_ml-commons-plugin/agents-tools/tools/search-anomaly-detectors.md +++ b/_ml-commons-plugin/agents-tools/tools/search-anomaly-detectors.md @@ -107,3 +107,7 @@ The following table lists all tool parameters that are available when running th Parameter | Type | Required/Optional | Description :--- | :--- | :--- | :--- `question` | String | Required | The natural language question to send to the LLM. + +## Testing the tool + +You can run this tool either as part of an agent workflow or independently using the [Execute Tool API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/execute-tool/). The Execute Tool API is useful for testing individual tools or performing standalone operations. \ No newline at end of file diff --git a/_ml-commons-plugin/agents-tools/tools/search-anomaly-results.md b/_ml-commons-plugin/agents-tools/tools/search-anomaly-results.md index 2f2728e32d3..2fb7d98c967 100644 --- a/_ml-commons-plugin/agents-tools/tools/search-anomaly-results.md +++ b/_ml-commons-plugin/agents-tools/tools/search-anomaly-results.md @@ -121,3 +121,7 @@ The following table lists all tool parameters that are available when running th Parameter | Type | Required/Optional | Description :--- | :--- | :--- | :--- `question` | String | Required | The natural language question to send to the LLM. + +## Testing the tool + +You can run this tool either as part of an agent workflow or independently using the [Execute Tool API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/execute-tool/). The Execute Tool API is useful for testing individual tools or performing standalone operations. \ No newline at end of file diff --git a/_ml-commons-plugin/agents-tools/tools/search-index-tool.md b/_ml-commons-plugin/agents-tools/tools/search-index-tool.md index b0235228931..3bb6d074f15 100644 --- a/_ml-commons-plugin/agents-tools/tools/search-index-tool.md +++ b/_ml-commons-plugin/agents-tools/tools/search-index-tool.md @@ -117,4 +117,8 @@ The following table lists all tool parameters that are available when registerin 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. \ No newline at end of file +`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. + +## Testing the tool + +You can run this tool either as part of an agent workflow or independently using the [Execute Tool API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/execute-tool/). The Execute Tool API is useful for testing individual tools or performing standalone operations. \ No newline at end of file diff --git a/_ml-commons-plugin/agents-tools/tools/search-monitors-tool.md b/_ml-commons-plugin/agents-tools/tools/search-monitors-tool.md index 77b51d4964e..853e6e3fd8f 100644 --- a/_ml-commons-plugin/agents-tools/tools/search-monitors-tool.md +++ b/_ml-commons-plugin/agents-tools/tools/search-monitors-tool.md @@ -122,3 +122,7 @@ The following table lists all tool parameters that are available when running th Parameter | Type | Required/Optional | Description :--- | :--- | :--- | :--- `question` | String | Required | The natural language question to send to the LLM. + +## Testing the tool + +You can run this tool either as part of an agent workflow or independently using the [Execute Tool API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/execute-tool/). The Execute Tool API is useful for testing individual tools or performing standalone operations. \ No newline at end of file diff --git a/_ml-commons-plugin/agents-tools/tools/vector-db-tool.md b/_ml-commons-plugin/agents-tools/tools/vector-db-tool.md index 61c6028f283..8e8753e101f 100644 --- a/_ml-commons-plugin/agents-tools/tools/vector-db-tool.md +++ b/_ml-commons-plugin/agents-tools/tools/vector-db-tool.md @@ -234,3 +234,7 @@ The following table lists all tool parameters that are available when running th Parameter | Type | Required/Optional | Description :--- | :--- | :--- | :--- `question` | String | Required | The natural language question to send to the LLM. + +## Testing the tool + +You can run this tool either as part of an agent workflow or independently using the [Execute Tool API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/execute-tool/). The Execute Tool API is useful for testing individual tools or performing standalone operations. \ No newline at end of file diff --git a/_ml-commons-plugin/agents-tools/tools/visualization-tool.md b/_ml-commons-plugin/agents-tools/tools/visualization-tool.md index 98457932c2f..769f9325dce 100644 --- a/_ml-commons-plugin/agents-tools/tools/visualization-tool.md +++ b/_ml-commons-plugin/agents-tools/tools/visualization-tool.md @@ -12,7 +12,7 @@ grand_parent: Agents and tools **Introduced 2.13** {: .label .label-purple } -Use the `VisualizationTool` to find visualizations relevant to a question. +Use the `VisualizationTool` to find visualizations relevant to a question. ## Step 1: Register a flow agent that will run the VisualizationTool @@ -101,3 +101,7 @@ The following table lists all tool parameters that are available when running th Parameter | Type | Required/Optional | Description :--- | :--- | :--- | :--- `question` | String | Required | The natural language question to send to the LLM. + +## Testing the tool + +You can run this tool either as part of an agent workflow or independently using the [Execute Tool API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/execute-tool/). The Execute Tool API is useful for testing individual tools or performing standalone operations. \ No newline at end of file diff --git a/_ml-commons-plugin/agents-tools/tools/web-search-tool.md b/_ml-commons-plugin/agents-tools/tools/web-search-tool.md index 8cc5814a5f1..2f163320411 100644 --- a/_ml-commons-plugin/agents-tools/tools/web-search-tool.md +++ b/_ml-commons-plugin/agents-tools/tools/web-search-tool.md @@ -319,4 +319,8 @@ The following table lists all tool parameters that are available when running th Parameter | Type | Required/Optional | Description :--- | :--- | :--- | :--- -`question` | String | Required | The natural language question to send to the LLM. \ No newline at end of file +`question` | String | Required | The natural language question to send to the LLM. + +## Testing the tool + +You can run this tool either as part of an agent workflow or independently using the [Execute Tool API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/execute-tool/). The Execute Tool API is useful for testing individual tools or performing standalone operations. \ No newline at end of file diff --git a/_ml-commons-plugin/api/execute-tool.md b/_ml-commons-plugin/api/execute-tool.md index 47d9118cfca..6014a10d3dc 100644 --- a/_ml-commons-plugin/api/execute-tool.md +++ b/_ml-commons-plugin/api/execute-tool.md @@ -6,7 +6,7 @@ nav_order: 100 --- # Execute Tool API -**Introduced 3.2** +**Introduced 3.3** {: .label .label-purple } The Execute Tool API allows you to run individual tools directly without creating an agent first. This API is particularly beneficial for applications requiring quick, single-tool operations where the overhead of agent creation and management is unnecessary. @@ -14,6 +14,7 @@ The Execute Tool API allows you to run individual tools directly without creatin ## Use cases The Execute Tool API is ideal for: + - **Direct tool execution**: Run specific tools like search, data analysis, or retrieval operations without agent setup. - **Testing and debugging**: Quickly test tool functionality during development. - **Lightweight integrations**: Integrate specific OpenSearch capabilities into applications without full agent workflows. @@ -34,9 +35,9 @@ POST /_plugins/_ml/tools/_execute/ The `` parameter refers to the predefined tool type name, such as `PPLTool`, `SearchIndexTool`, or `VectorDBTool`,---not a custom tool name that you define. {: .note} -## Request body field +## Request body fields -The following table lists all request body field. +The following table lists all request body fields. | Field | Data type | Required | Description | | :--- | :--- | :--- | :--- | @@ -54,6 +55,7 @@ To determine the required parameters for a specific tool, refer to the individua | Tool execution parameters | Parameters specified during tool execution. | ## Example requests + The following are examples of both simple and complex tool execution. ### Example 1: Simple tool execution @@ -72,16 +74,20 @@ POST /_plugins/_ml/tools/_execute/ListIndexTool ```json { - "inference_results": [ + "inference_results": [ + { + "output": [ { - "output": [ - { - "name": "response", - "result": "row,health,status,index,uuid,pri(number of primary shards),rep(number of replica shards),docs.count(number of available documents),docs.deleted(number of deleted documents),store.size(store size of primary and replica shards),pri.store.size(store size of primary shards)\n1,yellow,open,movies,kKcJKu2aT0C9uwJIPP4hxw,2,1,2,0,7.8kb,7.8kb\n2,green,open,.plugins-ml-config,h8ovp_KFTq6_zvcBEn2kvg,1,0,1,0,4kb,4kb\n3,green,open,.plugins-ml-agent,1oGlUBCIRAGXLbLv27Qg8w,1,0,1,0,8kb,8kb\n" - } - ] + "name": "response", + "result": """row,health,status,index,uuid,pri(number of primary shards),rep(number of replica shards),docs.count(number of available documents),docs.deleted(number of deleted documents),store.size(store size of primary and replica shards),pri.store.size(store size of primary shards) +1,yellow,open,movies,kKcJKu2aT0C9uwJIPP4hxw,2,1,2,0,7.8kb,7.8kb +2,green,open,.plugins-ml-config,h8ovp_KFTq6_zvcBEn2kvg,1,0,1,0,4kb,4kb +3,green,open,.plugins-ml-agent,1oGlUBCIRAGXLbLv27Qg8w,1,0,1,0,8kb,8kb +""" } - ] + ] + } + ] } ``` From 5efa604e0f477e1309a0b3058d54052dfd8d40e9 Mon Sep 17 00:00:00 2001 From: Nathan Bower Date: Mon, 13 Oct 2025 16:30:11 -0400 Subject: [PATCH 5/6] Update _ml-commons-plugin/agents-tools/tools/search-index-tool.md Signed-off-by: Nathan Bower --- _ml-commons-plugin/agents-tools/tools/search-index-tool.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_ml-commons-plugin/agents-tools/tools/search-index-tool.md b/_ml-commons-plugin/agents-tools/tools/search-index-tool.md index 3bb6d074f15..50bab482ea5 100644 --- a/_ml-commons-plugin/agents-tools/tools/search-index-tool.md +++ b/_ml-commons-plugin/agents-tools/tools/search-index-tool.md @@ -117,7 +117,7 @@ The following table lists all tool parameters that are available when registerin 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. +`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. ## Testing the tool From 92776b0eb80c5477b90ff103798b6653dbc15595 Mon Sep 17 00:00:00 2001 From: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> Date: Mon, 13 Oct 2025 16:33:30 -0400 Subject: [PATCH 6/6] Apply suggestions from code review Signed-off-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> --- _ml-commons-plugin/api/execute-tool.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_ml-commons-plugin/api/execute-tool.md b/_ml-commons-plugin/api/execute-tool.md index 6014a10d3dc..865d79bd2a0 100644 --- a/_ml-commons-plugin/api/execute-tool.md +++ b/_ml-commons-plugin/api/execute-tool.md @@ -99,7 +99,7 @@ POST /_plugins/_ml/tools/_execute/PPLTool "parameters": { "question": "what's the population of Seattle in 2021?", "index": "test-population", - "model_id": "1TuQQ5gBMJhRgCqgSV79" // Remote model + "model_id": "1TuQQ5gBMJhRgCqgSV79" } }