From 6e5120dd2a84a133c91678714a07baac71db570d Mon Sep 17 00:00:00 2001 From: Yaliang Wu Date: Thu, 13 Jun 2024 10:48:00 -0700 Subject: [PATCH 01/10] add connector tool Signed-off-by: Yaliang Wu --- .../agents-tools/tools/connector-tool.md | 148 ++++++++++++++++++ .../agents-tools/tools/index.md | 1 + 2 files changed, 149 insertions(+) create mode 100644 _ml-commons-plugin/agents-tools/tools/connector-tool.md diff --git a/_ml-commons-plugin/agents-tools/tools/connector-tool.md b/_ml-commons-plugin/agents-tools/tools/connector-tool.md new file mode 100644 index 0000000000..b8eed16f20 --- /dev/null +++ b/_ml-commons-plugin/agents-tools/tools/connector-tool.md @@ -0,0 +1,148 @@ +--- +layout: default +title: Connector tool +has_children: false +has_toc: false +nav_order: 20 +parent: Tools +grand_parent: Agents and tools +--- + + +# Connector tool +**Introduced 2.15** +{: .label .label-purple } + + +The `ConnectorTool` runs `execute` action in a connector. + +## Step 1: Register a connector with execute action + +`ConnectorTool` can only run `execute` action in a connector. So you need to create a connector with `execute` action. It's very similar to the `predict` action in connector. For example, create a connector to execute an AWS Lambda function with [Function URL](https://docs.aws.amazon.com/lambda/latest/dg/lambda-urls.html). +The Lambda function accepts two integer numbers and returns the sum. + +``` +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}\" }" + } + ] +} +``` +OpenSearch responds with an agent ID: + +```json +{ + "connector_id": "Zz1XEJABXWrLmr4mewEF" +} +``` + +## Step 2: Register a flow agent that will run the ConnectorTool + +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: + +Suppose the Lambda function will return such response +```json +{ + "result": 10 +} +``` +Need to set `response_filter` to retrieve the result `10` with json path `$.result`. + +```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 index information: + +```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 which has execute action. +`response_filter` | String | Optional | A json path to retrieve target result. + +## Execute parameters + +You can use any parameter defined in your connector `execute` action `request_body`. \ 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 8db522006e..0d42f0004f 100644 --- 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/) |Run execute action in connector. | |[`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. | From be603ad40ebb6b112bed8f97bd06499f3a186a42 Mon Sep 17 00:00:00 2001 From: Yaliang Wu Date: Tue, 18 Jun 2024 16:10:57 -0700 Subject: [PATCH 02/10] address comments Signed-off-by: Yaliang Wu --- _ml-commons-plugin/agents-tools/tools/connector-tool.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/_ml-commons-plugin/agents-tools/tools/connector-tool.md b/_ml-commons-plugin/agents-tools/tools/connector-tool.md index b8eed16f20..f9c6c59e14 100644 --- a/_ml-commons-plugin/agents-tools/tools/connector-tool.md +++ b/_ml-commons-plugin/agents-tools/tools/connector-tool.md @@ -18,7 +18,7 @@ The `ConnectorTool` runs `execute` action in a connector. ## Step 1: Register a connector with execute action -`ConnectorTool` can only run `execute` action in a connector. So you need to create a connector with `execute` action. It's very similar to the `predict` action in connector. For example, create a connector to execute an AWS Lambda function with [Function URL](https://docs.aws.amazon.com/lambda/latest/dg/lambda-urls.html). +`ConnectorTool` can only run `execute` action in a connector. So you need to create a [connector](https://opensearch.org/docs/latest/ml-commons-plugin/remote-models/connectors/) with `execute` action. It's very similar to the `predict` action in connector. For example, create a connector to execute an AWS Lambda function with [Function URL](https://docs.aws.amazon.com/lambda/latest/dg/lambda-urls.html). The Lambda function accepts two integer numbers and returns the sum. ``` @@ -68,7 +68,7 @@ Suppose the Lambda function will return such response "result": 10 } ``` -Need to set `response_filter` to retrieve the result `10` with json path `$.result`. +Connector tool will return of of `response` field. In this example the model raw response doesn't have `response` field, so need to set `response_filter` to retrieve the result `10` with json path `$.result`, the filtered result will be put into `response` field. ```json POST /_plugins/_ml/agents/_register From 1bc04d10719367d39575220c5c673df89bcdfae6 Mon Sep 17 00:00:00 2001 From: Fanit Kolchina Date: Wed, 19 Jun 2024 16:16:41 -0400 Subject: [PATCH 03/10] Doc review Signed-off-by: Fanit Kolchina --- .../agents-tools/tools/connector-tool.md | 50 +++++++++++++------ .../remote-models/blueprints.md | 2 +- 2 files changed, 36 insertions(+), 16 deletions(-) diff --git a/_ml-commons-plugin/agents-tools/tools/connector-tool.md b/_ml-commons-plugin/agents-tools/tools/connector-tool.md index f9c6c59e14..67ea5df04c 100644 --- a/_ml-commons-plugin/agents-tools/tools/connector-tool.md +++ b/_ml-commons-plugin/agents-tools/tools/connector-tool.md @@ -14,14 +14,17 @@ grand_parent: Agents and tools {: .label .label-purple } -The `ConnectorTool` runs `execute` action in a connector. +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 execute action +## Step 1: Register a connector with an execute action -`ConnectorTool` can only run `execute` action in a connector. So you need to create a [connector](https://opensearch.org/docs/latest/ml-commons-plugin/remote-models/connectors/) with `execute` action. It's very similar to the `predict` action in connector. For example, create a connector to execute an AWS Lambda function with [Function URL](https://docs.aws.amazon.com/lambda/latest/dg/lambda-urls.html). -The Lambda function accepts two integer numbers and returns the sum. +The `ConnectorTool` can only run an `execute` action within a connector. Before you can create a `ConnectorTool`, 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", @@ -50,7 +53,9 @@ POST _plugins/_ml/connectors/_create ] } ``` -OpenSearch responds with an agent ID: +{% include copy-curl.html %} + +OpenSearch responds with a connector ID: ```json { @@ -60,15 +65,17 @@ OpenSearch responds with an agent ID: ## Step 2: Register a flow agent that will run the ConnectorTool -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: +For this example, the Lambda function adds the two input numbers and returns their sum in the `result` field: -Suppose the Lambda function will return such response ```json { - "result": 10 + "result": 5 } ``` -Connector tool will return of of `response` field. In this example the model raw response doesn't have `response` field, so need to set `response_filter` to retrieve the result `10` with json path `$.result`, the filtered result will be put into `response` field. + +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 dot path to the `result` field (`$.result`). Using the `response_filter`, the `ConnectorTool` will retrieve the result from the `result` field of the Lambda function response and return it in the OpenSearch response. + +To configure running the Lambda function, 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 @@ -103,7 +110,6 @@ OpenSearch responds with an agent ID: ## Step 3: Run the agent - Then, run the agent by sending the following request: ```json @@ -117,7 +123,7 @@ POST /_plugins/_ml/agents/9X7xWI0Bpc3sThaJdY9i/_execute ``` {% include copy-curl.html %} -OpenSearch returns the index information: +OpenSearch returns the output of the Lambda function run. In the output, the field name is `response`, and the `result` field contains the Lambda function result: ```json { @@ -140,9 +146,23 @@ The following table lists all tool parameters that are available when registerin Parameter | Type | Required/Optional | Description :--- | :--- | :--- | :--- -`connector_id` | String | Required | A connector which has execute action. -`response_filter` | String | Optional | A json path to retrieve target result. +`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 dot path to the response field that contains the result of invoking the API. ## Execute parameters -You can use any parameter defined in your connector `execute` action `request_body`. \ No newline at end of file +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}\" }" + } + ] +``` \ No newline at end of file diff --git a/_ml-commons-plugin/remote-models/blueprints.md b/_ml-commons-plugin/remote-models/blueprints.md index 254a21b068..a3668267e3 100644 --- a/_ml-commons-plugin/remote-models/blueprints.md +++ b/_ml-commons-plugin/remote-models/blueprints.md @@ -74,7 +74,7 @@ The `actions` parameter supports the following options. | Field | Data type | Description | |:---|:---|:---| -| `action_type` | String | Required. Sets the ML Commons API operation to use upon connection. As of OpenSearch 2.9, only `predict` is supported. | +| `action_type` | String | Required. Sets the ML Commons API operation to use upon connection. Valid values are `predict` (to invoke an externally hosted model) and `execute` (to invoke any REST API function). | | `method` | String | Required. Defines the HTTP method for the API call. Supports `POST` and `GET`. | | `url` | String | Required. Sets the connection endpoint at which the action occurs. This must match the regex expression for the connection used when [adding trusted endpoints]({{site.url}}{{site.baseurl}}/ml-commons-plugin/remote-models/index#adding-trusted-endpoints). | | `headers` | JSON object | Sets the headers used inside the request or response body. Default is `ContentType: application/json`. If your third-party ML tool requires access control, define the required `credential` parameters in the `headers` parameter. | From 57df6dab49b7be6edbadb14f50c28b10abea4062 Mon Sep 17 00:00:00 2001 From: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> Date: Wed, 19 Jun 2024 18:20:49 -0400 Subject: [PATCH 04/10] Update _ml-commons-plugin/agents-tools/tools/connector-tool.md Signed-off-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> --- _ml-commons-plugin/agents-tools/tools/connector-tool.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_ml-commons-plugin/agents-tools/tools/connector-tool.md b/_ml-commons-plugin/agents-tools/tools/connector-tool.md index 67ea5df04c..ba8448e758 100644 --- a/_ml-commons-plugin/agents-tools/tools/connector-tool.md +++ b/_ml-commons-plugin/agents-tools/tools/connector-tool.md @@ -147,7 +147,7 @@ The following table lists all tool parameters that are available when registerin 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 dot path to the response field that contains the result of invoking the API. +`response_filter` | String | Optional | A JSON dot path to the response field that contains the result of invoking the API. If `response_filter` is not specified, the `ConnectorTool` expects the API response in a field named `response`. ## Execute parameters From f3f35ac0412f69078cb6c6f211301b7eb1574260 Mon Sep 17 00:00:00 2001 From: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> Date: Wed, 19 Jun 2024 18:21:19 -0400 Subject: [PATCH 05/10] Update _ml-commons-plugin/agents-tools/tools/connector-tool.md Signed-off-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> --- _ml-commons-plugin/agents-tools/tools/connector-tool.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_ml-commons-plugin/agents-tools/tools/connector-tool.md b/_ml-commons-plugin/agents-tools/tools/connector-tool.md index ba8448e758..22ffce14b0 100644 --- a/_ml-commons-plugin/agents-tools/tools/connector-tool.md +++ b/_ml-commons-plugin/agents-tools/tools/connector-tool.md @@ -147,7 +147,7 @@ The following table lists all tool parameters that are available when registerin 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 dot path to the response field that contains the result of invoking the API. If `response_filter` is not specified, the `ConnectorTool` expects the API response in a field named `response`. +`response_filter` | String | Optional | A JSON dot path to the response field that contains the result of invoking the API. If a `response_filter` is not specified, the `ConnectorTool` expects the API response in a field named `response`. ## Execute parameters From 7b0d71886ecfa1943645d005930277c4cd6e1a1d Mon Sep 17 00:00:00 2001 From: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> Date: Thu, 20 Jun 2024 09:14:19 -0400 Subject: [PATCH 06/10] Update _ml-commons-plugin/agents-tools/tools/connector-tool.md Signed-off-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> --- _ml-commons-plugin/agents-tools/tools/connector-tool.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_ml-commons-plugin/agents-tools/tools/connector-tool.md b/_ml-commons-plugin/agents-tools/tools/connector-tool.md index 22ffce14b0..5f72b58c17 100644 --- a/_ml-commons-plugin/agents-tools/tools/connector-tool.md +++ b/_ml-commons-plugin/agents-tools/tools/connector-tool.md @@ -75,7 +75,7 @@ For this example, the Lambda function adds the two input numbers and returns the 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 dot path to the `result` field (`$.result`). Using the `response_filter`, the `ConnectorTool` will retrieve the result from the `result` field of the Lambda function response and return it in the OpenSearch response. -To configure running the Lambda function, 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: +To configure running the Lambda function, 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 From d829054ba90885e61e8cbf07639d422b938339bf Mon Sep 17 00:00:00 2001 From: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> Date: Thu, 20 Jun 2024 14:41:57 -0400 Subject: [PATCH 07/10] Update _ml-commons-plugin/agents-tools/tools/connector-tool.md Co-authored-by: Yaliang Wu Signed-off-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> --- _ml-commons-plugin/agents-tools/tools/connector-tool.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_ml-commons-plugin/agents-tools/tools/connector-tool.md b/_ml-commons-plugin/agents-tools/tools/connector-tool.md index 5f72b58c17..0de5ed5380 100644 --- a/_ml-commons-plugin/agents-tools/tools/connector-tool.md +++ b/_ml-commons-plugin/agents-tools/tools/connector-tool.md @@ -73,7 +73,7 @@ For this example, the Lambda function adds the two input numbers and returns the } ``` -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 dot path to the `result` field (`$.result`). Using the `response_filter`, the `ConnectorTool` will retrieve the result from the `result` field of the Lambda function response and return it in the OpenSearch response. +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 running the Lambda function, 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`: From 313552d78cb04c1e9b714a467528cdf9415cbec0 Mon Sep 17 00:00:00 2001 From: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> Date: Thu, 20 Jun 2024 14:42:27 -0400 Subject: [PATCH 08/10] Update _ml-commons-plugin/agents-tools/tools/connector-tool.md Co-authored-by: Yaliang Wu Signed-off-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> --- _ml-commons-plugin/agents-tools/tools/connector-tool.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_ml-commons-plugin/agents-tools/tools/connector-tool.md b/_ml-commons-plugin/agents-tools/tools/connector-tool.md index 0de5ed5380..ba139dfb1d 100644 --- a/_ml-commons-plugin/agents-tools/tools/connector-tool.md +++ b/_ml-commons-plugin/agents-tools/tools/connector-tool.md @@ -147,7 +147,7 @@ The following table lists all tool parameters that are available when registerin 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 dot path to the response field that contains the result of invoking the API. If a `response_filter` is not specified, the `ConnectorTool` expects the API response in a field named `response`. +`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, the `ConnectorTool` expects the API response in a field named `response`. ## Execute parameters From b2b79dc48b46a4e0c553c0af437c6510c3df5074 Mon Sep 17 00:00:00 2001 From: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> Date: Thu, 20 Jun 2024 14:43:08 -0400 Subject: [PATCH 09/10] Update _ml-commons-plugin/remote-models/blueprints.md Signed-off-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> --- _ml-commons-plugin/remote-models/blueprints.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_ml-commons-plugin/remote-models/blueprints.md b/_ml-commons-plugin/remote-models/blueprints.md index a3668267e3..254a21b068 100644 --- a/_ml-commons-plugin/remote-models/blueprints.md +++ b/_ml-commons-plugin/remote-models/blueprints.md @@ -74,7 +74,7 @@ The `actions` parameter supports the following options. | Field | Data type | Description | |:---|:---|:---| -| `action_type` | String | Required. Sets the ML Commons API operation to use upon connection. Valid values are `predict` (to invoke an externally hosted model) and `execute` (to invoke any REST API function). | +| `action_type` | String | Required. Sets the ML Commons API operation to use upon connection. As of OpenSearch 2.9, only `predict` is supported. | | `method` | String | Required. Defines the HTTP method for the API call. Supports `POST` and `GET`. | | `url` | String | Required. Sets the connection endpoint at which the action occurs. This must match the regex expression for the connection used when [adding trusted endpoints]({{site.url}}{{site.baseurl}}/ml-commons-plugin/remote-models/index#adding-trusted-endpoints). | | `headers` | JSON object | Sets the headers used inside the request or response body. Default is `ContentType: application/json`. If your third-party ML tool requires access control, define the required `credential` parameters in the `headers` parameter. | From e82d658c13e92643da316f01d64851d058becdb4 Mon Sep 17 00:00:00 2001 From: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> Date: Thu, 20 Jun 2024 15:08:50 -0400 Subject: [PATCH 10/10] Apply suggestions from code review Co-authored-by: Nathan Bower Signed-off-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> --- _ml-commons-plugin/agents-tools/tools/connector-tool.md | 8 ++++---- _ml-commons-plugin/agents-tools/tools/index.md | 2 +- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/_ml-commons-plugin/agents-tools/tools/connector-tool.md b/_ml-commons-plugin/agents-tools/tools/connector-tool.md index ba139dfb1d..dfe4770932 100644 --- a/_ml-commons-plugin/agents-tools/tools/connector-tool.md +++ b/_ml-commons-plugin/agents-tools/tools/connector-tool.md @@ -18,7 +18,7 @@ The `ConnectorTool` uses a [connector]({{site.url}}{{site.baseurl}}/ml-commons-p ## 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`, 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. +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). @@ -75,7 +75,7 @@ For this example, the Lambda function adds the two input numbers and returns the 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 running the Lambda function, 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`: +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 @@ -123,7 +123,7 @@ POST /_plugins/_ml/agents/9X7xWI0Bpc3sThaJdY9i/_execute ``` {% include copy-curl.html %} -OpenSearch returns the output of the Lambda function run. In the output, the field name is `response`, and the `result` field contains the Lambda function result: +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 { @@ -147,7 +147,7 @@ The following table lists all tool parameters that are available when registerin 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, the `ConnectorTool` expects the API response in a field named `response`. +`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 diff --git a/_ml-commons-plugin/agents-tools/tools/index.md b/_ml-commons-plugin/agents-tools/tools/index.md index 0d42f0004f..fba47b63da 100644 --- a/_ml-commons-plugin/agents-tools/tools/index.md +++ b/_ml-commons-plugin/agents-tools/tools/index.md @@ -33,7 +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/) |Run execute action in connector. | +|[`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. |