Agents Manager

• 1: Architecture and components
• 1.1: Plugins
• 1.1.1: agent-dispatcher-api plugin
• 1.1.2: Agent Deployment Plugin
• 1.1.3: development-api plugin
• 1.1.4: configuration-service plugin
• 1.1.5: redis-connector-service plugin
• 1.1.6: session-service plugin
• 2: Communication protocol
• 3: Environment variables
• 4: API definition
• 4.1: Agents Manager API
• 4.2: Agents Manager Development API
• 4.3: Agents Manager Dispatcher API

1 - Architecture and components

Agents Manager architecture and components

Technical foundations

agents-manager is mainly a web server built on Typescript using nodejs as engine. It is api-first designed, using OpenAPI v3 to provide the API definition and openapi-backend to handle swagger specification.

agents-manager server is composed by several plugins, which provide different functionalities to this component.

A channel, service, or skill uses an application to connect with agents-manager following this communication protocol.

Architecture overview

The following figure shows the main technical components of the agents-manager, which are described below.

agents-manager components

ConfigurationManager

ConfigurationManager is a handler for configuration, obtained through a configuration file or environment variables.

RedisConnector

RedisConnector is a handler connection to Redis.

HTTP server

Microservice is implemented as an HTTP server (AuraServer) that exposes an API to receive the request to be validated.

Middlewares

The route published in the API definition file is handled by a controller but, before a request lands on its controller, it goes through a series of middlewares that provides some common steps needed by all the controllers of the server such as: request validation, common parameters extraction, logging, metrics initialization, etc.

Controllers and Services

agents-manager is composed of plugins, which provide functionality and uses specific modules from aura-configuration-api.

Check the available plugins together with detailed information in: agents-manager plugins.

1.1 - Plugins

Agents Manager API plugins

Introduction

agents-manager is composed of plugins, which provide functionality to this component. Plugins work independently, the same way as a service in microservices oriented architecture: isolated, self-contained and without affecting other existing functionalities in the system.

From the different types of plugins, only Api plugins are available in agents-manager.

The following plugins are currently available in agents-manager. Certain plugins are used by all or some of the other plugins and others are specific for one capability.

• agent-dispatcher-api plugin
  This plugin manages request to Agent Dispatcher API.

• development-api plugin
  This plugin manages configuration in development environments. Only available in development environments.

• configuration-service plugin
  This plugin manages requests to Agent Configuration.

• redis-connector-service plugin
  This plugin manages requests to Redis.

• session-service plugin
  This plugin manages the sessions.

• agent-deployment plugin, that provides deployment functionalities for agents within the agents-manager. Plugin currently deactivated.

Discover detailed information regarding the available plugins in the left index.

Plugins management

agents-manager uses the @architect/architect library for the management of plugins, so it is the architect library that is responsible for managing the dependencies injection in each module.

To create the architect application, agents-manager uses the PluginManager module (located in the modules/plugin-manager folder). This module starts as the rest of modules at the agents-manager start-up.

The PluginManager performs the following tasks:

• It starts the architect application with the plugins defined in plugin-config.json file, located at the root of the agents-manager component.
• It adds the core modules to the IOC context. See the section plugins modules.
• It stores the information of each module defined in the plugins.

Apart from the agents-manager core environment variables, each plugin can define its own specific variables. Access the document agents-manager environment variables and find them in the section corresponding to your plugin.

Plugin basic structure

Currently, agents-manager uses @architect/architect library for plugins management.

A basic plugin must define at least:

• A package.json file defining the library, like any other JavaScript library, with a plugin section defining which modules it consumes and supplies.
• A source code file that defines the modules that it supplies (index.ts for example).

The structure of this basic plugin is as follows:

session-api
├── index.ts
└── package.json

Plugins modules

agents-manager currently adds one module that can be used by the different plugins. To use it, it is only necessary to add the package.json dependencies on plugin.consumes (like any other module/component).

• configurationManager: Module with the agents-manager configuration information.
• redisConnector: Module with the agents-manager Redis connection.

A plugin can provide one or more plugin modules and each plugin module can be of a different type. Each type of module is intended to add a specific functionality to agents-manager.

1.1.1 - agent-dispatcher-api plugin

agent-dispatcher-api plugin

Introduction

agent-dispatcher-api plugin manages and dispatches the requests to the agent API.

Consumes components (IOC)

Provides components (IOC)

1.1.2 - Agent Deployment Plugin

Agent Deployment Plugin

Introduction

The agent-deployment plugin is designed to manage the deployment of agents in a flexible and scalable manner. It allows multiple agents to be deployed within a single microservice, and the same agent can be deployed with different configurations across different microservices or within the same microservice.

Plugin Management

The agent-deployment plugin uses the @architect/architect library for managing dependencies and plugin lifecycle. The PluginManager module, located in the modules/plugin-manager folder, is responsible for initializing the plugin at the start-up of the agents-manager.

The PluginManager performs the following tasks:

• Initializes the architect application with the plugins defined in the plugin-config.json file, located at the root of the agents-manager component.
• Adds core modules to the IOC context. See the section plugin modules.
• Stores information about each module defined in the plugins.

Plugin Basic Structure

A basic plugin must define at least:

• A package.json file defining the library, with a plugin section specifying which modules it consumes and supplies.
• A source code file that defines the modules it supplies (index.ts for example).

The structure of this basic plugin is as follows:

agent-deployment-plugin
├── index.ts
└── package.json

Example index.ts

import { PluginType, registerPlugin } from '@telefonica/agents-manager-common';
import { Services } from './deployment-consume-services';

export = registerPlugin([
    {
        type: PluginType.Service,
        name: 'agentDeploymentService',
        instance: {
            deployAgent(agentConfig) {
                // Implementation for deploying an agent
            }
        },
        services: Services
    }
]);

Example package.json

{
    "name": "@telefonica/agent-deployment-plugin",
    "version": "1.0.0",
    "main": "index.js",
    "private": true,
    "plugin": {
        "consumes": [
            "configurationManager"
        ],
        "provides": [
            "agentDeploymentService"
        ]
    }
}

Plugin Modules

The agent-deployment plugin can utilize the following modules provided by the agents-manager:

• configurationManager: Module with the agents-manager configuration information.
• redisConnector: Module with the agents-manager Redis connection.

A plugin can provide one or more plugin modules, and each plugin module can be of a different type. Each type of module is intended to add specific functionality to the agents-manager.

1.1.3 - development-api plugin

development-api plugin

Introduction

The development-api plugin manages the configuration in development environments. Only available in development environments.

Consumes components (IOC)

Provides components (IOC)

1.1.4 - configuration-service plugin

configuration-service plugin

Introduction

The configuration-service plugin manages the configuration of agents.

Consumes components (IOC)

Provides components (IOC)

1.1.5 - redis-connector-service plugin

redis-connector-service plugin

Introduction

The redis-connector-service plugin manages requests to Redis.

Consumes components (IOC)

Provides components (IOC)

1.1.6 - session-service plugin

session-service plugin

Introduction

The session-service plugin manages the sessions.

Consumes components (IOC)

Provides components (IOC)

2 - Communication protocol

Agents Manager communication protocol

Communication protocol

The agents-manager uses a synchronous communication protocol, although the specific behavior may vary depending on the endpoint. The following diagram illustrates the protocol:

agents-manager communication protocol

3 - Environment variables

Agents Manager environment variables

Introduction

agents-manager environment variables can be common for all plugins or specific for each of them.

Common properties

development-api plugin

configuration-service plugin

redis-connector-service plugin

session-service plugin

4 - API definition

API definition for Agents Manager

APIs index

• Agents Manager API

• Agents Manager Development API
  Only available in development environments.

• Agents Manager Dispatcher API

• Dapr PubSub API

4.1 - Agents Manager API

Agents Manager API

4.2 - Agents Manager Development API

Agents Manager Development API

4.3 - Agents Manager Dispatcher API

Agents Manager Dispatcher API