You're viewing version 2.17 of the OpenSearch documentation. This version is no longer maintained. For the latest version, see the current documentation. For information about OpenSearch version maintenance, see Release Schedule and Maintenance Policy.

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:

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 a connector ID:

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

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

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

For parameter descriptions, see Register parameters.

OpenSearch responds with an agent ID:

{
  "agent_id": "az1XEJABXWrLmr4miAFj"
}

Step 3: Run the agent

Then, run the agent by sending the following request:

POST /_plugins/_ml/agents/9X7xWI0Bpc3sThaJdY9i/_execute
{
  "parameters": {
    "number1": 2,
    "number2": 3
  }
}

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:

{
  "inference_results": [
    {
      "output": [
        {
          "name": "response",
          "result": 5
        }
      ]
    }
  ]
}

Register parameters

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

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:

"actions": [
    {
      "action_type": "execute",
      "method": "POST",
      "url": "YOUR LAMBDA FUNCTION URL",
      "headers": {
        "content-type": "application/json"
      },
      "request_body": "{ \"number1\":\"${parameters.number1}\", \"number2\":\"${parameters.number2}\" }"
    }
  ]