连接器工具

2.15 版引入

The ConnectorTool uses a 连接器 to call any REST API function. For example, you can use a ConnectorTool to call a Lambda function through its REST API interface.

步骤 1：注册具有执行操作的连接器

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 函数 URL.

要创建连接器，请发送以下请求

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 返回连接器 ID

{
  "connector_id": "Zz1XEJABXWrLmr4mewEF"
}

步骤 2：注册将运行 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 路径 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.

要配置 Lambda 函数工作流，请创建一个流智能体。流智能体按顺序运行一系列工具并返回最后一个工具的输出。要创建流智能体，请发送以下注册智能体请求，提供上一步的连接器 ID 和一个 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"
      }
    }
  ]
}

有关参数描述，请参阅注册参数。

OpenSearch 返回一个代理 ID

{
  "agent_id": "az1XEJABXWrLmr4miAFj"
}

步骤 3：运行智能体

然后，通过发送以下请求运行代理

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

OpenSearch 返回 Lambda 函数的执行输出。在输出中，字段名为 response，并且 result 字段包含 Lambda 函数的结果。

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

注册参数

下表列出了注册代理时可用的所有工具参数。

执行参数

运行智能体时，您可以在连接器 execute 操作的 request_body 中定义 API 调用所需的任何参数。在此示例中，参数为 number1 和 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}\" }"
    }
  ]