Connector tool

Introduced 0.5.0

The ConnectorTool invokes an external service through a configured connector. The tool is created with a connector_id, and when it runs, it forwards its execute parameters to that connector's action and returns the response. Use it to let an agent call an external API or service as one step in a workflow.

Step 1: Create a connector

Before registering the tool, create a connector to the external service. The following example creates a connector that calls an external service; substitute your own endpoint, credentials, and request body:

POST /_plugins/_ml/connectors/_create
{
  "name": "External service connector",
  "description": "A connector to an external service",
  "version": 1,
  "protocol": "http",
  "parameters": {
    "endpoint": "api.example.com"
  },
  "credential": {
    "api_key": "<api_key>"
  },
  "actions": [
    {
      "action_type": "predict",
      "method": "POST",
      "url": "https://api.example.com/v1/query",
      "headers": {
        "Authorization": "Bearer ${credential.api_key}"
      },
      "request_body": "{ \"query\": \"${parameters.input}\" }"
    }
  ]
}

The response contains the connector ID:

{
  "connector_id": "a1eMb4kBJ1eYAeTMAljY"
}

Step 2: Register a flow agent that will run the ConnectorTool

A flow agent runs a sequence of tools in order and returns the last tool's output. Provide the connector_id from the previous step:

POST /_plugins/_ml/agents/_register
{
  "name": "Test_Agent_For_Connector_tool",
  "type": "flow",
  "description": "this is a test agent for the ConnectorTool",
  "tools": [
    {
      "type": "ConnectorTool",
      "name": "DemoConnectorTool",
      "parameters": {
        "connector_id": "a1eMb4kBJ1eYAeTMAljY"
      }
    }
  ]
}

For parameter descriptions, see Register parameters.

Lucenia responds with an agent ID:

{
  "agent_id": "9X7xWI0Bpc3sThaJdY9i"
}

Step 3: Run the agent

Run the agent, providing any parameters that the connector's action expects. These parameters are forwarded to the connector:

POST /_plugins/_ml/agents/9X7xWI0Bpc3sThaJdY9i/_execute
{
  "parameters": {
    "input": "What is the weather in Seattle today?"
  }
}

Lucenia returns the response from the external service.

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	The ID of the connector that the tool invokes.

Execute parameters

Any parameters you provide when running the agent are forwarded to the connector's action as substitution variables (for example, ${parameters.input}). The required parameters depend on how the connector's request_body is defined.