Add connector tool (#7384)

* add connector tool Signed-off-by: Yaliang Wu <[email protected]> * address comments Signed-off-by: Yaliang Wu <[email protected]> * Doc review Signed-off-by: Fanit Kolchina <[email protected]> * Update _ml-commons-plugin/agents-tools/tools/connector-tool.md Signed-off-by: kolchfa-aws <[email protected]> * Update _ml-commons-plugin/agents-tools/tools/connector-tool.md Signed-off-by: kolchfa-aws <[email protected]> * Update _ml-commons-plugin/agents-tools/tools/connector-tool.md Signed-off-by: kolchfa-aws <[email protected]> * Update _ml-commons-plugin/agents-tools/tools/connector-tool.md Co-authored-by: Yaliang Wu <[email protected]> Signed-off-by: kolchfa-aws <[email protected]> * Update _ml-commons-plugin/agents-tools/tools/connector-tool.md Co-authored-by: Yaliang Wu <[email protected]> Signed-off-by: kolchfa-aws <[email protected]> * Update _ml-commons-plugin/remote-models/blueprints.md Signed-off-by: kolchfa-aws <[email protected]> * Apply suggestions from code review Co-authored-by: Nathan Bower <[email protected]> Signed-off-by: kolchfa-aws <[email protected]> --------- Signed-off-by: Yaliang Wu <[email protected]> Signed-off-by: Fanit Kolchina <[email protected]> Signed-off-by: kolchfa-aws <[email protected]> Co-authored-by: kolchfa-aws <[email protected]> Co-authored-by: Fanit Kolchina <[email protected]> Co-authored-by: Nathan Bower <[email protected]>
opensearch-project · Jun 20, 2024 · 14b8afc · 14b8afc
1 parent 737e227
commit 14b8afc
Show file tree

Hide file tree

Showing 2 changed files with 169 additions and 0 deletions.
diff --git a/_ml-commons-plugin/agents-tools/tools/connector-tool.md b/_ml-commons-plugin/agents-tools/tools/connector-tool.md
@@ -0,0 +1,168 @@
+---
+layout: default
+title: Connector tool
+has_children: false
+has_toc: false
+nav_order: 20
+parent: Tools
+grand_parent: Agents and tools
+---
+
+<!-- vale off -->
+# Connector tool
+**Introduced 2.15**
+{: .label .label-purple }
+<!-- vale on -->
+
+The `ConnectorTool` uses a [connector]({{site.url}}{{site.baseurl}}/ml-commons-plugin/remote-models/connectors/) to call any REST API function. For example, you can use a `ConnectorTool` to call a Lambda function through its REST API interface.
+
+## Step 1: Register a connector with an execute action
+
+The `ConnectorTool` can only run an `execute` action within a connector. Before you can create a `ConnectorTool`, you need to configure a connector and provide an `execute` action in the `actions` array. The `execute` action is used to invoke a function at a REST API endpoint. It is similar to the `predict` action, which is used to invoke a machine learning (ML) model. 
+
+For this example, you'll create a connector for a simple AWS Lambda function that accepts two integers and returns their sum. This function is hosted on a dedicated endpoint with a specific URL, which you'll provide in the `url` parameter. For more information, see [Lambda function URLs](https://docs.aws.amazon.com/lambda/latest/dg/lambda-urls.html).
+
+To create a connector, send the following request:
+
+```json
+POST _plugins/_ml/connectors/_create
+{
+  "name": "Lambda connector of simple calculator",
+  "description": "Demo connector of lambda function",
+  "version": 1,
+  "protocol": "aws_sigv4",
+  "parameters": {
+    "region": "YOUR AWS REGION",
+    "service_name": "lambda"
+  },
+  "credential": {
+    "access_key": "YOUR ACCESS KEY",
+    "secret_key": "YOUR SECRET KEY",
+    "session_token": "YOUR SESSION TOKEN"
+  },
+  "actions": [
+    {
+      "action_type": "execute",
+      "method": "POST",
+      "url": "YOUR LAMBDA FUNCTION URL",
+      "headers": {
+        "content-type": "application/json"
+      },
+      "request_body": "{ \"number1\":\"${parameters.number1}\", \"number2\":\"${parameters.number2}\" }"
+    }
+  ]
+}
+```
+{% include copy-curl.html %} 
+
+OpenSearch responds with a connector ID:
+
+```json
+{
+  "connector_id": "Zz1XEJABXWrLmr4mewEF"
+}
+```
+
+## Step 2: Register a flow agent that will run the ConnectorTool
+
+For this example, the Lambda function adds the two input numbers and returns their sum in the `result` field:
+
+```json
+{
+  "result": 5
+}
+```
+
+By default, the `ConnectorTool` expects the response from the Lambda function to contain a field named `response`. However, in this example the Lambda function response doesn't include a `response` field. To retrieve the result from the `result` field instead, you need to provide a `response_filter`, specifying the [JSON path](https://github.com/json-path/JsonPath) to the `result` field (`$.result`). Using the `response_filter`, the `ConnectorTool` will retrieve the result with the specified JSON path and return it in the `response` field.
+
+To configure the Lambda function workflow, create a flow agent. A flow agent runs a sequence of tools in order and returns the last tool's output. To create a flow agent, send the following register agent request, providing the connector ID from the previous step and a `response_filter`:
+
+```json
+POST /_plugins/_ml/agents/_register
+{
+  "name": "Demo agent of Lambda connector",
+  "type": "flow",
+  "description": "This is a demo agent",
+  "app_type": "demo",
+  "tools": [
+    {
+      "type": "ConnectorTool",
+      "name": "lambda_function",
+      "parameters": {
+        "connector_id": "YOUR CONNECTOR ID",
+        "response_filter": "$.result"
+      }
+    }
+  ]
+}
+```
+{% include copy-curl.html %} 
+
+For parameter descriptions, see [Register parameters](#register-parameters).
+
+OpenSearch responds with an agent ID:
+
+```json
+{
+  "agent_id": "az1XEJABXWrLmr4miAFj"
+}
+```
+
+## Step 3: Run the agent
+
+Then, run the agent by sending the following request:
+
+```json
+POST /_plugins/_ml/agents/9X7xWI0Bpc3sThaJdY9i/_execute
+{
+  "parameters": {
+    "number1": 2,
+    "number2": 3
+  }
+}
+```
+{% include copy-curl.html %} 
+
+OpenSearch returns the output of the Lambda function execution. In the output, the field name is `response`, and the `result` field contains the Lambda function result:
+
+```json
+{
+  "inference_results": [
+    {
+      "output": [
+        {
+          "name": "response",
+          "result": 5
+        }
+      ]
+    }
+  ]
+}
+```
+
+## Register parameters
+
+The following table lists all tool parameters that are available when registering an agent.
+
+Parameter | Type | Required/Optional | Description
+:--- | :--- | :--- | :---
+`connector_id` | String | Required | A connector ID of a connector configured with an `execute` action that invokes an API.
+`response_filter` | String | Optional | A [JSON path](https://github.com/json-path/JsonPath) to the response field that contains the result of invoking the API. If a `response_filter` is not specified, then the `ConnectorTool` expects the API response to be in a field named `response`.
+
+## Execute parameters
+
+When running the agent, you can define any parameter needed for the API call in the `request_body` of your connector's `execute` action. In this example, the parameters are `number1` and `number2`:
+
+```json
+"actions": [
+    {
+      "action_type": "execute",
+      "method": "POST",
+      "url": "YOUR LAMBDA FUNCTION URL",
+      "headers": {
+        "content-type": "application/json"
+      },
+      "request_body": "{ \"number1\":\"${parameters.number1}\", \"number2\":\"${parameters.number2}\" }"
+    }
+  ]
+```
diff --git a/_ml-commons-plugin/agents-tools/tools/index.md b/_ml-commons-plugin/agents-tools/tools/index.md
@@ -33,6 +33,7 @@ Each tool takes a list of parameters specific to that tool. In the preceding exa
 |:---	|:---	|
 |[`AgentTool`]({{site.url}}{{site.baseurl}}/ml-commons-plugin/agents-tools/tools/agent-tool/)	|Runs any agent. |
 |[`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. |
 |[`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. |