Link Search Menu Expand Document Documentation Menu

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.

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

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