diff --git a/_ml-commons-plugin/agents-tools/tools/agent-tool.md b/_ml-commons-plugin/agents-tools/tools/agent-tool.md index 272af51e4d..e0e4ec09c0 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 dfe4770932..ace94c3844 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 a66d85a5cc..404ad7eacf 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 6f35f90041..26ccbbe17e 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 8649d2d74d..39cc6f9109 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 0f3f27be14..cd3b903107 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 79d9d0d7b0..41c02dbe49 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 3249fa2cd6..0d6a7f334e 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 3bbd09b169..a179fa3b96 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 ceeda40528..048028d806 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 b78d3d641e..9be67422c0 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 72d8ba30b5..2cb1cc181f 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 1bec951294..9d3518d101 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 24e95286a4..9b22798ec1 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 76f9e4b4dc..c9ce8994cb 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 9f31dea057..c0978857c2 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 2f2728e32d..2fb7d98c96 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 b023522893..50bab482ea 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 77b51d4964..853e6e3fd8 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 61c6028f28..8e8753e101 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 98457932c2..769f9325dc 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 8cc5814a5f..2f16332041 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 new file mode 100644 index 0000000000..865d79bd2a --- /dev/null +++ b/_ml-commons-plugin/api/execute-tool.md @@ -0,0 +1,126 @@ +--- +layout: default +title: Execute tool +parent: ML Commons APIs +nav_order: 100 +--- + +# Execute Tool API +**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. + +## 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/ +``` + +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 fields + +The following table lists all request body fields. + +| 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 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 + +```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) +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 +""" + } + ] + } + ] +} +``` + +### Example 2: Complex tool execution + +```json +POST /_plugins/_ml/tools/_execute/PPLTool +{ + "parameters": { + "question": "what's the population of Seattle in 2021?", + "index": "test-population", + "model_id": "1TuQQ5gBMJhRgCqgSV79" + } +} + +``` +{% 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 ab34d954c0..7ca612e0ce 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 dc9ec94cbe..f281c25dcf 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 45b145effe..43b31b3806 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