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. ]