Connector tool

Introduced 2.15

The ConnectorTool uses a connector 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.

To create a connector, send the following request:

  1. POST _plugins/_ml/connectors/_create
  2. {
  3.   "name": "Lambda connector of simple calculator",
  4.   "description": "Demo connector of lambda function",
  5.   "version": 1,
  6.   "protocol": "aws_sigv4",
  7.   "parameters": {
  8.     "region": "YOUR AWS REGION",
  9.     "service_name": "lambda"
  10.   },
  11.   "credential": {
  12.     "access_key": "YOUR ACCESS KEY",
  13.     "secret_key": "YOUR SECRET KEY",
  14.     "session_token": "YOUR SESSION TOKEN"
  15.   },
  16.   "actions": [
  17.     {
  18.       "action_type": "execute",
  19.       "method": "POST",
  20.       "url": "YOUR LAMBDA FUNCTION URL",
  21.       "headers": {
  22.         "content-type": "application/json"
  23.       },
  24.       "request_body": "{ \"number1\":\"${parameters.number1}\", \"number2\":\"${parameters.number2}\" }"
  25.     }
  26.   ]
  27. }

copy

OpenSearch responds with a connector ID:

  1. {
  2.   "connector_id": "Zz1XEJABXWrLmr4mewEF"
  3. }

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:

  1. {
  2.   "result": 5
  3. }

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 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:

  1. POST /_plugins/_ml/agents/_register
  2. {
  3.   "name": "Demo agent of Lambda connector",
  4.   "type": "flow",
  5.   "description": "This is a demo agent",
  6.   "app_type": "demo",
  7.   "tools": [
  8.     {
  9.       "type": "ConnectorTool",
  10.       "name": "lambda_function",
  11.       "parameters": {
  12.         "connector_id": "YOUR CONNECTOR ID",
  13.         "response_filter": "$.result"
  14.       }
  15.     }
  16.   ]
  17. }

copy

For parameter descriptions, see Register parameters.

OpenSearch responds with an agent ID:

  1. {
  2.   "agent_id": "az1XEJABXWrLmr4miAFj"
  3. }

Step 3: Run the agent

Then, run the agent by sending the following request:

  1. POST /_plugins/_ml/agents/9X7xWI0Bpc3sThaJdY9i/_execute
  2. {
  3.   "parameters": {
  4.     "number1": 2,
  5.     "number2": 3
  6.   }
  7. }

copy

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:

  1. {
  2.   "inference_results": [
  3.     {
  4.       "output": [
  5.         {
  6.           "name": "response",
  7.           "result": 5
  8.         }
  9.       ]
  10.     }
  11.   ]
  12. }

Register parameters

The following table lists all tool parameters that are available when registering an agent.

ParameterTypeRequired/OptionalDescription
connector_idStringRequiredA connector ID of a connector configured with an execute action that invokes an API.
response_filterStringOptionalA JSON path 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:

  1. "actions": [
  2.     {
  3.       "action_type": "execute",
  4.       "method": "POST",
  5.       "url": "YOUR LAMBDA FUNCTION URL",
  6.       "headers": {
  7.         "content-type": "application/json"
  8.       },
  9.       "request_body": "{ \"number1\":\"${parameters.number1}\", \"number2\":\"${parameters.number2}\" }"
  10.     }
  11.   ]