Document CreateAnomalyDetectorTool

_ml-commons-plugin/agents-tools/tools/create-anomaly-detector.md

@@ -0,0 +1,169 @@
+---
+layout: default
+title: CreateAnomalyDetectorTool
+has_children: false
+has_toc: false
+nav_order: 70
+parent: Tools
+grand_parent: Agents and tools
+---
+
+<!-- vale off -->
+# CreateAnomalyDetectorTool
+**Introduced 2.16**
+{: .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, see the associated [GitHub issue](https://github.com/opensearch-project/skills/issues/337).    
+{: .warning}
+
+The `CreateAnomalyDetectorTool` helps create anomaly detectors based on your provided index. This tool retrieves the index mappings and enables the language learning model (LLM) to recommend category fields, aggregation fields, and their corresponding aggregation methods, which are required by the Create Anomaly Detector API. 
+
+For comprehensive information about anomaly detectors, see [Anomaly detection]({{site.url}}{{site.baseurl}}/observing-your-data/ad/index/).
+{: .tip}
+
+## Step 1: Register a flow agent that runs the CreateAnomalyDetectorTool
+
+A flow agent runs a sequence of tools in order, returning the output of the last tool. To create a flow agent, send the following register agent request:
+
+```json
+POST /_plugins/_ml/agents/_register
+{
+  "name": "Test_Agent_For_Create_Anomaly_Detector_Tool",
+  "type": "flow",
+  "description": "this is a test agent for the CreateAnomalyDetectorTool",
+  "memory": {
+    "type": "demo"
+  },
+  "tools": [
+      {
+      "type": "CreateAnomalyDetectorTool",
+      "name": "DemoCreateAnomalyDetectorTool",
+      "parameters": {
+        "model_id": "<the model id of LLM>"
+      }
+    }
+  ]
+}
+```
+{% include copy-curl.html %} 
+
+OpenSearch responds with an agent ID, for example, as follows:
+
+```json
+{
+  "agent_id": "EuJYYo0B9RaBCvhuy1q8"
+}
+```
+{% include copy-curl.html %} 
+
+## Step 2: Run the agent
+
+Run the agent by sending the following request:
+
+```json
+POST /_plugins/_ml/agents/EuJYYo0B9RaBCvhuy1q8/_execute
+{
+  "parameters": {
+    "index": "sample_weblogs_test"
+  }
+}
+```
+{% include copy-curl.html %} 
+
+OpenSearch responds with a JSON string containing all of the recommended parameters for creating an anomaly detector, such as the string shown in the following example repsonse:
+
+```json
+{
+  "inference_results": [
+    {
+      "output": [
+        {
+          "name": "response",
+          "result":"""{"index":"sample_weblogs_test","categoryField":"ip.keyword","aggregationField":"bytes,response,responseLatency","aggregationMethod":"sum,avg,avg","dateFields":"utc_time,timestamp"}"""
+        }
+      ]
+    }
+  ]
+}
+```
+{% include copy-curl.html %} 
+
+You can then create an anomaly detector containing the recommended parameters with a request similar to the following example: 
+
+```json
+POST _plugins/_anomaly_detection/detectors
+{
+  "name": "test-detector",
+  "description": "Test detector",
+  "time_field": "timestamp",
+  "indices": [
+    "sample_weblogs_test"
+  ],
+  "feature_attributes": [
+    {
+      "feature_name": "feature_bytes",
+      "feature_enabled": true,
+      "aggregation_query": {
+        "agg1": {
+          "sum": {
+            "field": "bytes"
+          }
+        }
+      }
+    },
+    {
+      "feature_name": "feature_response",
+      "feature_enabled": true,
+      "aggregation_query": {
+        "agg2": {
+          "avg": {
+            "field": "response"
+          }
+        }
+      }
+    },
+    {
+      "feature_name": "feature_responseLatency",
+      "feature_enabled": true,
+      "aggregation_query": {
+        "agg3": {
+          "avg": {
+            "field": "responseLatency"
+          }
+        }
+      }
+    }
+  ],
+  "detection_interval": {
+    "period": {
+      "interval": 1,
+      "unit": "Minutes"
+    }
+  },
+  "window_delay": {
+    "period": {
+      "interval": 1,
+      "unit": "Minutes"
+    }
+  }
+}
+```
+{% include copy-curl.html %} 
+
+## Register parameters
+
+The following table lists the available tool parameters for agent registration.
+
+Parameter	| Type | Required/Optional | Description	
+:--- | :--- | :--- | :---
+`model_id` | String | Required | The LLM model ID used for suggesting the Creating Anomaly Detector API's required parameters.
+`model_type` | String | Optional | The model type. Valid values are `CLAUDE` (Anthropic Claude models) and `OPENAI` (OpenAI models). 
+
+## Execute parameters
+
+The following table lists the available tool parameters for running the agent.
+
+Parameter	| Type | Required/Optional | Description	
+:--- | :--- | :--- | :---
+`index` | String | Required | Index name. Supports wildcards (for example, `weblogs-*`). If wildcards are used, the tool fetches mappings from the first resolved index and sends them to the LLM. 

_ml-commons-plugin/agents-tools/tools/index.md

@@ -35,6 +35,7 @@ Each tool takes a list of parameters specific to that tool. In the preceding exa
 |[`CatIndexTool`]({{site.url}}{{site.baseurl}}/ml-commons-plugin/agents-tools/tools/cat-index-tool/)	|Retrieves index information for the OpenSearch cluster. |
 |[`ConnectorTool`]({{site.url}}{{site.baseurl}}/ml-commons-plugin/agents-tools/tools/connector-tool/)	| Uses a [connector]({{site.url}}{{site.baseurl}}/ml-commons-plugin/remote-models/connectors/) to call any REST API function. |
 |[`IndexMappingTool`]({{site.url}}{{site.baseurl}}/ml-commons-plugin/agents-tools/tools/index-mapping-tool/)	|Retrieves index mapping and setting information for an index. |
+|[`CreateAnomalyDetectorTool`]({{site.url}}{{site.baseurl}}/ml-commons-plugin/agents-tools/tools/create-anomaly-detector/)	| Let LLM to give suggested parameters for creating anomaly detector. |
 |[`MLModelTool`]({{site.url}}{{site.baseurl}}/ml-commons-plugin/agents-tools/tools/ml-model-tool/)	|Runs machine learning models.	|
 |[`NeuralSparseSearchTool`]({{site.url}}{{site.baseurl}}/ml-commons-plugin/agents-tools/tools/neural-sparse-tool/)	| Performs sparse vector retrieval. |
 |[`PPLTool`]({{site.url}}{{site.baseurl}}/ml-commons-plugin/agents-tools/tools/ppl-tool/)	|Translates natural language into a Piped Processing Language (PPL) query.	|
@@ -49,4 +50,4 @@ Each tool takes a list of parameters specific to that tool. In the preceding exa
 
 ## Developer information
 
-The agents and tools framework is flexible and extensible. You can find the list of tools provided by OpenSearch in the [Tools library](https://github.com/opensearch-project/skills/tree/main/src/main/java/org/opensearch/agent/tools). For a different use case, you can build your own tool by implementing the [_Tool_ interface](https://github.com/opensearch-project/ml-commons/blob/2.x/spi/src/main/java/org/opensearch/ml/common/spi/tools/Tool.java).
+The agents and tools framework offers flexibility and extensibility. Explore the [Tools library](https://github.com/opensearch-project/skills/tree/main/src/main/java/org/opensearch/agent/tools) for OpenSearch-provided tools. Implement the [**Tool** interface](https://github.com/opensearch-project/ml-commons/blob/2.x/spi/src/main/java/org/opensearch/ml/common/spi/tools/Tool.java) to build custom tools for different use cases.