CreateAnomalyDetectorTool

Introduced 2.16

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.

The CreateAnomalyDetectorTool helps create anomaly detectors based on your provided index. This tool retrieves index mappings and enables a large language 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.

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:

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>"
      }
    }
  ]
}

copy

OpenSearch responds with an agent ID, for example, as follows:

{
  "agent_id": "EuJYYo0B9RaBCvhuy1q8"
}

copy

Step 2: Run the agent

Run the agent by sending the following request:

POST /_plugins/_ml/agents/EuJYYo0B9RaBCvhuy1q8/_execute
{
  "parameters": {
    "index": "sample_weblogs_test"
  }
}

copy

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:

{
  "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"}"""
        }
      ]
    }
  ]
}

copy

You can then create an anomaly detector containing the recommended parameters by sending a request similar to the following:

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"
    }
  }
}

copy

Register parameters

The following table lists the available tool parameters for agent registration.

Execute parameters

The following table lists the available tool parameters for running the agent.