Technical components

• 1: ATRIA application
• 2: Aura Gateway API
• 2.1: Architecture and components
• 2.1.1: Plugins
• 2.1.1.1: aura-generative-api plugin
• 2.1.1.2: aura-generative-process-service plugin
• 2.1.1.3: aura-nlp-resolution-api plugin
• 2.1.1.4: aura-nlp-resolution-process-service plugin
• 2.1.1.5: aura-development-api plugin
• 2.1.1.6: aura-feedback-api plugin
• 2.1.1.7: aura-agents-api plugin
• 2.1.1.8: aura-operations-api plugin
• 2.2: Operational overview
• 2.3: Environment variables
• 2.4: API definition
• 2.4.1: Aura Gateway API
• 2.4.2: Aura Gateway Core API
• 2.4.3: Aura Agents API
• 2.4.4: Aura Generative API
• 2.4.5: Aura NLP resolution API
• 2.4.6: Aura Feedback API
• 2.4.7: Aura Gateway Development API
• 2.4.8: Aura Operations API
• 3: ATRIA Model Gateway
• 3.1: Architecture and components
• 3.2: Operational overview
• 3.3: API definition
• 3.4: Environment variables
• 4: ATRIA Models Manager
• 5: AURA GenAI Libs
• 6: ATRIA RAG Server
• 6.1: Architecture and components
• 6.2: Operational overview
• 6.3: Environment variables
• 7: ATRIA RAG generate DB
• 7.1: Architecture and components
• 7.2: Operational overview
• 8: Agents Manager
• 8.1: Architecture and components
• 8.1.1: Plugins
• 8.1.1.1: agent-dispatcher-api plugin
• 8.1.1.2: Agent Deployment Plugin
• 8.1.1.3: development-api plugin
• 8.1.1.4: configuration-service plugin
• 8.1.1.5: redis-connector-service plugin
• 8.1.1.6: session-service plugin
• 8.2: Communication protocol
• 8.3: Environment variables
• 8.4: API definition
• 8.4.1: Agents Manager API
• 8.4.2: Agents Manager Development API
• 8.4.3: Agents Manager Dispatcher API
• 9: Agents Server
• 9.1: Architecture and components
• 9.2: Environment variables
• 9.3: API definition
• 10: ATRIA APIs documentation

1 - ATRIA application

ATRIA application

Introduction

Within ATRIA’s framework, an application is defined as an entity that allows the connection of a channel, service or skill with aura-gateway-api, the component in charge of managing the access to the different ATRIA capabilities.

ATRIA application

As a preliminary step for leveraging any ATRIA AI-driven capability, the use case constructor must configure an application, including different parameters:

• To indicate which specific ATRIA capabilities are utilized in the use case.
  In this framework, applications supported by ATRIA can be classified as follows:

  • Applications that make use only of the NLP as a Service capabilities
  • Applications that use Generative capabilities
  • Applications that use RAG capabilities

  The difference between Generative and RAG capabilities relies solely on the definition of the preset that is associated. But the same application can make use of one, several or all of these capabilities, combining their configuration.

• Once the capabilities are selected, to set the required fields for its operation

  For example, if we want to use Generative AI for the use case resolution, firstly, certain parameters must be set corresponding to:

  • Establishing admin accesses.

  • Setting the presets that the application can use, that is, the instructions to work with the AI model, that will be defined in the application configuration.

How to configure an application

An ATRIA application must be configured with specific parameters. For this purpose, follow the guidelines Configure an application in ATRIA, using the specific parameters for the ATRIA AI-driven technology to be used.

Example of application

This is a example of an application that makes use of NLPaaS, Generative and RAG capabilities:

    {
        "id": "8832550f-f03c-4e18-bdbe-7c6fc7adf5ff",
        "name": "app",
        "disabled": false,
        "brand": "0401",
        "nlp": {
            "channelId": "1234"
        },
        "models": {
            "level": "user",
            "presets": ["atria-rag-gpt-4", "generative-preset"]
        }
    }

Applications model

Common fields

NLPaaS fields

Generative/RAG fields

2 - Aura Gateway API

Aura Gateway API

Introduction

aura-gateway-api is a server in charge of the access to the different AI cognitive capabilities provided by ATRIA.

A channel, service or skill can send a request through an application (entity that enables the communication with aura-gateway-api). After passing through Kernel for authentication and security purposes, aura-gateway-api sends this request to the corresponding AI-driven technology for providing the most accurate response.

Currently, aura-gateway-api enables the access to ATRIA capabilities.

Associated documentation

Descriptive technical documentation regarding aura-gateway-api includes:

• Architecture and components
• Operational overview
• Environment variables
• Aura Gateway API definition and Aura Gateway API Codebase

Guidelines for working with aura-gateway-api for the development of experiences, depending on the specific ATRIA capability:

• Technical guidelines

2.1 - Architecture and components

Aura Gateway API architecture and components

Technical foundations

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

aura-gateway-api server is composed by several plugins, which provide different functionalities to this component. From the different capabilities that aura-gateway-api can manage, certain plugins are used by all of them and others are specific of one capability.

A channel, service, or skill uses an application to connect with aura-gateway-api following this communication protocol.

Architecture overview

The following figure shows the main technical components of the aura-gateway-api.

ConfigurationManager

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

RedisConnector

RedisConnector is a handler connection to redis.

Kpis-handler

KpisHandler is the module responsible for writing the KPIs entities.

HTTP server

Microservice is implemented as an HTTP server (AuraGatewayServer) 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.

Plugins

Different plugins provide functionality to aura-gateway-api.

Check the available ones together with detailed information in: aura-gateway-api plugins.

2.1.1 - Plugins

Aura gateway API plugins

Introduction

aura-gateway-api 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 aura-gateway-api.

The following plugins are currently available in aura-gateway-api. From the different ATRIA capabilities that this component can manage, certain plugins are used by all or some of them and others are specific of one capability.

• aura-generative-api plugin
  This module manages request to external OpenAI APIs.

• aura-generative-process-service plugin
  This module manages the communication and data processing with external OpenAI APIs.

• aura-nlp-resolution plugin
  This module manages the request to NLP services.

• aura-nlp-resolution-process-services plugin
  This module manages the communication and data processing with external NLP services.

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

• aura-feedback-api plugin
  This module manages requests to provide feedback about the generative and RAG services behavior.

• aura-agents-api plugin
  This module manages the communication with agents.

• dapr-pubsub-service plugin This plugin allows the interaction with the Dapr PubSub Service.

• aura-operations-api plugin
  This module allows you to perform operations on now, currently launching the generateDB

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

Plugins management

aura-gateway-api 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, aura-gateway-api uses the PluginManager module (located in the modules/plugin-manager folder). This module starts as the rest of modules at the aura-gateway-api 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 aura-gateway-api 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 aura-gateway-api core environment variables, each plugin can define its own specific variables. Access the document aura-gateway-api environment variables and find them in the section corresponding to your plugin.

Plugin basic structure

Currently, aura-gateway-api 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

aura-gateway-api 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 aura-gateway-api configuration information.
• redisConnector: Module with the aura-gateway-api 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 aura-gateway-api.

2.1.1.1 - aura-generative-api plugin

aura-generative-api plugin

Introduction

The aura-generative-api plugin manages the endpoints for the communication with atria-model-gateway.

Consumes components (IOC)

Provides components (IOC)

2.1.1.2 - aura-generative-process-service plugin

aura-generative-process-service plugin

Introduction

The aura-generative-process-service plugin manages the communication with atria-model-gateway to allow applications to communicate with LLMs.

Consumes components (IOC)

Provides components (IOC)

2.1.1.3 - aura-nlp-resolution-api plugin

aura-nlp-resolution-api plugin

Introduction

The aura-nlp-resolution-api plugin manages the communication with NLP APIs to return a recognizer response.

Consumes components (IOC)

Provides components (IOC)

2.1.1.4 - aura-nlp-resolution-process-service plugin

aura-nlp-resolution-process-service plugin

Introduction

The aura-nlp-resolution-process-service plugin manages the communication with NLP APIs to return a recognizer response.

Consumes components (IOC)

Provides components (IOC)

2.1.1.5 - aura-development-api plugin

aura-development-api plugin

Introduction

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

Consumes components (IOC)

Provides components (IOC)

2.1.1.6 - aura-feedback-api plugin

aura-feedback-api plugin

Introduction

The aura-feedback-api plugin manages the communication with atria-model-gateway to provide feedback about the Generative and RAG services behavior.

Consumes components (IOC)

Provides components (IOC)

2.1.1.7 - aura-agents-api plugin

aura-agents-api plugin

Introduction

The aura-agents-api plugin manages the endpoints for the communication with the agents-manager.

Consumes components (IOC)

Provides components (IOC)

2.1.1.8 - aura-operations-api plugin

aura-operations-api plugin

Introduction

The aura-operations-api plugin manages the endpoints for operations related to Aura.

Consumes components (IOC)

Provides components (IOC)

2.2 - Operational overview

Aura Gateway API operational overview

Communication protocol

aura-gateway-api communication protocol is synchronous, depending on the endpoint.

A new component comes here into play: application, defined as an entity used by a channel, service or skill to connect with aura-gateway-api.

An application has a specific configuration and will be the entry point to the aura-gateway-api flow, previous pass through Kernel, meaning that the input parameters for aura-gateway-api come from the application, and no specific information regarding the channel, service or skill is required.

2.3 - Environment variables

Aura Gateway API environment variables

Introduction

aura-gateway-api environment variables can be common for all plugins or specific for each of them.

Common properties

aura-development-api plugin

aura-generative-api plugin

aura-update-me-api plugin

aura-nlp-resolution-process-services plugin

| Property | Type | Description | Modifiable by OB? | |:—————-|:—————————————————————————| | AURA_COGNITIVE_ENDPOINT | string | URL of Aura NLP API. | NO. In any case, it must be the internal k8s URL pointing to the api-gw. |

aura-feedback-api plugin

aura-agents-api plugin

aura-operations-api plugin

2.4 - API definition

API definition for Aura Gateway API

APIs index

• Aura Gateway API
  Definition of the complete API in aura-gateway-api

• Aura Gateway Core API
  Definition of the core API in aura-gateway-api that handle its operations

• Aura Gateway Agents API
  This API is exposed in Kernel to handle agents services: https://developers.baikalplatform.com/apis/aura-aiservices/

• Aura Generative API
  This API is exposed in Kernel to handle Generative and RAG services: https://developers.baikalplatform.com/apis/aura-aiservices/

• Aura NLP Resolution API
  This API is exposed in Kernel to handle NLP as a Service: https://developers.baikalplatform.com/apis/aura-aiservices/

• Aura Feedback API
  This API is exposed in Kernel to provide feedback about the behavior of Generative and RAG services: https://developers.baikalplatform.com/apis/aura-aiservices/

• Aura Gateway Update-Me API

• Aura Gateway Development API
  Only available in development environments.

• Dapr PubSub API

• Aura Operations API
  API that include a set of endpoints related to operations over Aura.

2.4.1 - Aura Gateway API

Aura Gateway API

2.4.2 - Aura Gateway Core API

Aura Gateway Core API

2.4.3 - Aura Agents API

Aura Agents API

2.4.4 - Aura Generative API

Aura Generative API

2.4.5 - Aura NLP resolution API

Aura NLP resolution API

2.4.6 - Aura Feedback API

Aura Feedback API

2.4.7 - Aura Gateway Development API

Aura Gateway Development API

2.4.8 - Aura Operations API

Aura Operations API

3 - ATRIA Model Gateway

ATRIA Model Gateway

Introduction

atria-model-gateway is an ATRIA component in charge of managing the communication with different AI models.

Currently, this component receives a request from aura-gateway-api, together with other input data, and makes a call to the LLM/LMM Experiences Builder and use its capabilities.

atria-model-gateway is also in charge of security and privacy control and allows users to provide feedback on their experience.

If the selected AI model is RAG, then atria-model-gateway calls the atria-rag-server, which is in charge of executing the RAG chain and making the corresponding calls to the LLM models and databases.

The functional components of atria-model-gateway are described in the document LLM/LMM Experiences Builder

Associated documentation

Descriptive technical documentation regarding atria-model-gateway includes:

• Architecture and components
• Operational overview
• API definition

3.1 - Architecture and components

ATRIA Model Gateway architecture and components

Technical foundations

atria-model-gateway is responsible for managing the communication with different AI models. This component receives a request from aura-gateway-api, together with other input data, and makes a call the corresponding AI models.

If the selected AI model is RAG, then atria-model-gateway calls the atria-rag-server, which is in charge of executing the RAG chain and making the corresponding calls to the LLM models and databases.

Functional components

The functional components of atria-model-gateway are described in the document LLM/LMM Experiences Builder

Architecture overview

The following diagram schematically shows the main technical components integrated into atria-model-gateway.

A brief description of these components is included below:

Access module

Module for the management of different profiles to access atria-model-gateway.

Context module

Module in charge of the storage of a conversation history in a cache (currently, Redis is used) over a period of time, grouped by session ID. These conversations are taken into account when calling the generative LLM models.

Model manager

Module that includes the available models and presets. It is in charge of receiving the info from aura-gateway-api and calling the corresponding model.

Models

Available AI models integrated into the atria-model-gateway.

Presets

Presets are configurable entities to define the specific model to work with and certain parameters associated to it: model Id, name, description, model parameters, etc.

Constructors can use the default presets or build new ones: Go to document ATRIA configuration.

When configuring an application, all the presets that can be used for this application must be previously defined.

3.2 - Operational overview

ATRIA Model Gateway operational overview

Operational workflow

The operational flow between an application (for the communication with aura-gateway-apì), atria-model-gateway, atria-rag-server and atria-rag-generate-db is schematically shown in the following figure:

• Application

  • Constructors must configure an application for a channel, skill or service to communicate with aura-gateway-api.
  • In the application, the constructor must set the access grants for this application and all the presets that this application can use, from the ones configured in atria-model-gateway.
    
    

• atria-model-gateway It contains:

  • The different accesses that are defined here for each preset.
  • The available presets. Each of them is associated to an AI model with specific parameters.
  • The available AI models.
    
    

• atria-rag-server

  • When using RAG (Retrieval Augmented Generation), atria-rag-server is in charge of managing the requests made to the RAG model.
  • The available projects that contain information required for the execution of the RAG pipeline are included here.
    
    

• atria-rag-generate-db

  • atria-rag-generate-db is in charge of feeding the databases the RAG works with.
  • The available projects that contain the data required for reading the information sources and feed the databases are included here.

Configuration

atria-model-gateway includes a default configuration. Constructors can use it as is or they can modify it to be adapted to their requirements or business models: Go to document ATRIA configuration.

3.3 - API definition

Atria Model Gateway API definition

3.4 - Environment variables

ATRIA Model Gateway environment variables

Introduction

The atria-model-gateway depends on these environment variables to be set. None of them are modifiable by the OBs.

• The environment variables related to Redis are used to connect to the Redis database. This database is used to refresh the agent’s configuration, because every time the configuration of an agent is changed, it publishes this change in the corresponding channel so we can detect this change in order to refresh it.

• The environment variables related to DAPR are used to connect to the DAPR components. These components are used to refresh the agent’s configuration, because every time the configuration of an agent is changed, it publishes this change in a corresponding topic, so we can detect this change in order to refresh it.

• In order to use DAPR, it is necessary to have the DAPR pubsub component configured in the DAPR configuration file, besides the DAPR environment variables.

4 - ATRIA Models Manager

ATRIA Models Manager

Introduction

atria-models-manager is a ATRIA library responsible for managing all the models that we can use in the atria-model-gw model. The objective is for the atria.model-gw to only have to import the models from this component, avoiding defining the logic of the models in the atria-model-gw. For the first version, it will only feature Perplexity’s Sonar model, in the future, we will be able to migrate the atria-model-gw models here.

It contains all the logic necessary to call an LLM. Prompt construction, query tokenization, etc. It also contains all the definitions of the exceptions that an LLM can throw.

How to use it

To use the atria-models-manager, you need to install it in your Python environment and import the model into the code.

5 - AURA GenAI Libs

AURA GenAI Libs

Introduction

aura-genai-libs is a ATRIA that contains common components for agent development, such as logs and the langchain call to the atria_model_gw service.

Includes the following modules:

• logger module, whose purpose is to implement a callback handler to log the different stages of model, chain, and tool processing within the LangChain framework, integrating it with the AURA PyTraces logging system and the ATRIA Agents context. The module is based on the use of BaseCallbackHandler (langchain_core) and logs information at different stages of the execution cycle of language models (LLM), chats, chains, and tools. Each logged event uses m_headers.

• chat_models module, which provides a custom implementation of the ChatOpenAI class from LangChain. This custom implementation is designed to facilitate the integration with the atria_model_gw service.

How to use it

To use the aura-genai-libs, you need to install it in your Python environment and import and use the module in your code.

6 - ATRIA RAG Server

ATRIA RAG Server

Introduction

atria-rag-server is an ATRIA component that manages a RAG-type server. It is called by atria-model-gateway when RAG (Retrieval Augmented Generation) is used.

atria-rag-server manages the request made to the RAG model following the predefined RAG chain (pipeline) and making continuous requests combining Generative AI technology (LLMs) with semantic and lexical searches to retrieve the required information.

Associated documentation

Descriptive technical documentation regarding atria-rag-server includes:

• Architecture and components
• Operational overview

6.1 - Architecture and components

ATRIA RAG Server architecture and components

Architecture overview

The following diagram schematically shows the main technical components integrated into atria-rag-server.

A brief description of the technical components is included below:

Project

A project contains information required for the execution of the RAG pipeline: specific models for semantic search and lexical search; path where the documents to feed the LLMs are located; allowed file extensions, etc.

Semantic search (embeddings)

Qdrant database that stores the embeddings generated through semantic search (OpenAI embeddings) technology.

Lexical search (LLMs)

Database that stores the required documentation for making lexical searching, based on keywords.

Configuration

atria-rag-server includes a default configuration. Constructors can use it as is or they can modify it to be adapted to their requirements or business models: Go to document ATRIA configuration.

6.2 - Operational overview

ATRIA RAG Server operational overview

Operational workflow

The operational flow between an application (for the communication with aura-gateway-api), atria-model-gateway, atria-rag-server and atria-rag-generate-db is schematically shown in the document atria-model-gateway: operational flow.

Configuration

atria-rag-server includes a default configuration. Constructors can use it as is or they can modify it to be adapted to their requirements or business models: Go to document ATRIA configuration.

6.3 - Environment variables

ATRIA RAG Server environment variables

Introduction

The atria-rag-server depends on these environment variables to be set. None of them are modifiable by the OBs.

• The environment variables related to Redis are used to connect to the Redis database. This database is used to refresh the agent’s configuration, because every time the configuration of an agent is changed, it publishes this change in the corresponding channel so we can detect this change in order to refresh it.

• The environment variables related to DAPR are used to connect to the DAPR components. These components are used to refresh the agent’s configuration, because every time the configuration of an agent is changed, it publishes this change in a corresponding topic, so we can detect this change in order to refresh it.

• In order to use DAPR, it is necessary to have the DAPR pubsub component configured in the DAPR configuration file, besides the DAPR environment variables.

7 - ATRIA RAG generate DB

ATRIA RAG Generate DB

Introduction

atria-rag-generate-db is an ATRIA component that manages a RAG-type database. This component is launched when you want to feed the document database for the first time or when you want to update the database with new information. See more information about these processes in the guidelines Import documents into ATRIA.

atria-rag-generate-db is in charge of handling the information coming from different sources and feeding the databases the RAG works with.

Associated documentation

Descriptive technical documentation regarding atria-rag-generate-db includes:

• Architecture and components
• Operational overview

Launch atria-rag-generate-db

To launch atria-rag-generate-db, there are two suitable options:

Option 1

Send a request to the API for it to launch the atria-rag-generate-db. The endpoint responsible for this is:
/aura-services/v2/operations/data

curl -X POST "https://<your-atria-domain>/aura-services/v2/operations/data" \
-H "Content-Type: application/json"
-d '{
  "presetId": "<name of the project>"
}'

Option 2

Execute the following command to update the data in the environment. This command is in charge of launching the generation of the database for all the projects, but we can launch this generation for a specific project.

PROJECT='project-copilot-reduced'
kubectl patch configmap/atria-rag-generate-db-project --type merge -p "{\"data\":{\"ATRIA_PROJECT\":\"${PROJECT}\"}}" -n <namespace>
kubectl create job --from=cronjob/atria-rag-generate-db $(date +%Y%m%d%H%M%S)-atria-rag-generate-db-${PROJECT} -n <namespace>

(Change <namespace> by the specific one)

7.1 - Architecture and components

ATRIA RAG Generate DB architecture and components

Architecture overview

The following diagram schematically shows the main technical components integrated into atria-rag-generate-db.

A brief description of the technical components is included below:

Data sources

A project contains information required for the execution of the generation of the databases: specific path of documents to feed the databases, allowed file extensions, etc. It can read from different sources, this source type is defined in the extensions field.

Before the information from the documents is stored in the corresponding database, the documents are processed, e.g., they are cut up and cleaned.

Retrievers

The retrievers are in charge of reading the information from the documents and feeding the databases.

The retrievers are defined in the retrievers field of the project. Each retriever is associated with a database in order to feed or retrieve information from it.

7.2 - Operational overview

ATRIA RAG Generate DB operational overview

Operational flow

The operational flow between an application (for the communication with aura-gateway-api), atria-model-gateway, atria-rag-server and atria-rag-generate-db is schematically shown in the document atria-model-gateway: operational flow.

Configuration

atria-model-gateway includes a default configuration. Constructors can use it as is or they can modify it to be adapted to their requirements or business models: Go to document ATRIA configuration.

Data persistence feature

Now ATRIA enables data persistence in knowledge bases across releases: After the installation of a new release, all existing data in the knowledge base (currently, Qdrant) remains fully available and accessible for every ATRIA experience. Thus, information is completely independent of the deployed version.

This feature provides key advantages:

• Guaranteed continuity of ATRIA experiences.
• No need for data re-ingestion after each release.
• No need to recalculate embeddings.
• Data ingested after the installation of a release (through hot swapping) is now automatically consolidated and carried forward to subsequent releases.

Tracking and clean-up processes

atria-rag-generate-db keeps a record of the current state of documents and related configuration for data sources, so it only feeds documents that have been modified or added since the last update.

atria-rag-generate-db also cleans up any resources that are left behind and no longer used after new ones are introduced.

Preset management

Preset report

After generation-db is executed, a report is logged with the following information for each preset:

• The preset name.
• The status of the execution (success, skipped or error).
• A descriptive message with the reason for the status.
• Date and time of the execution start.
• Date and time of the execution end.
• The configured documents for the preset

Preset availability

When a new preset is created, it is necessary to launch the database generation process by executing the atria-rag-generate-db component. This process may take several minutes to complete. Once the generation is finished, the atria-rag-generate-db component is automatically restarted.

While these processes are running, a message is shown to the user indicating that the preset is not yet available.

When both processes are finished, the preset becomes available for use.

Data migration between ATRIA releases

The data persistence feature is implemented by a migration tool between environments or releases integrated in the atria-rag-generate-db component. This tool moves the trained data from one release to another, to avoid generating preset data that has been previously created in a release.

The process for migrating data must be triggered manually by launching a command (similar to the aura-rag-generate-db job), where both source and target environments should be indicated.

After executing this command, data will be migrated from one environment to the other automatically.

The migration flow is executed as follows:

1. Process the hashes file and, for each preset we want to migrate, we will do the following steps:
   • Check that the preset from the source environment is in the config of the target environment
   • Move the trained_data files from the source environment to the respective training folder of the target environment
   • Duplicate the collections from the source environment to the target environment
   • Move the TFIDFs files from the source environment to the target environment
2. Move the hashes file from the source environment to the target environment
3. Add the new presets training files to the respective training folder in the target environment.
4. Launch atria-rag-generate-db. Only new presets will be reloaded.

Data migration flow

In the migration process described above, the following folders are generated and stored in an Azure blob storage after atria-rag-generate-db is finished:

Shared data

This folder contains the trained data shared between atria-rag-server and atria-rag-generate-db. This is used to store the files that the atria-rag-generate-db generates and then the atria-rag-server uses to be able to process the request.

At the moment, only the files generated by the TFIDF (Term Frequency–Inverse Document Frequency) exist in this folder.

This folder is used for migration, as we can take the TFIDFs of a trained preset to the blob of a specific release where that preset has not been trained and save the training afterward.

Trained data

This folder contains the files that have been used in the atria-rag-generate-db for each preset.

The folder structure is defined with a hash of the contents of all the files for each preset, to facilitate migration.

Atria RAG project hashes

This is a file containing all the information for each preset, to facilitate migration.

It contains the following information for each preset:

• config_hash: Hash of the preset configuration at the time the atria-rag-generate-db was launched.

• source_files_hash: Hash of the source files used to generate the preset. This hash should exist in one folder into the trained data folder.

• metadata: Metadata of the preset, including the date of atria-rag-generate-db launching.

• retrievers: Info that retrievers used to generate the preset. It contains the name of the Qdrant collection and the path where it holds the TFIDF files, which would correspond to the shared data.

  {
    "5905dece-433d-47f4-a78c-72366bcd1473": {
      "config_hash": "28f837d56079f30c59a419292d129bc3",
      "source_files_hash": "cda3afcd8e74ede0d23065e897d55fae",
      "metadata": {
        "date": "2025-04-01 11:25:59"
      },
      "retrievers": {
        "qdrant_collection_name": "rag-ap-eight-9100-dev-project-copilot",
        "tfidf_path_file": "project-copilot/tfidf"
      }
    }
  }
  

In addition to using this data for migration, it also speeds up the launch of the atria-rag-generate-db.

The config_hash and source_files_hash values are used to verify if, at the moment of launching the atria-rag-generate-db, something has been changed in the configuration or in the training data. If changes are detected, all the data for that preset is regenerated. Otherwise, if the preset has not changed, we will save that generation.

Launch migration process

The process to persist data between releases has to be launched manually through the execution of the following command: To run this script, we just need the output files with the environment configuration info generated by the installer in the output_install directory from the source and destination environment. With this info, run the script as shown below, using the corresponding files names for the desired environment:

  ./migrate-data --source-file ${SOURCE_ENVIRONMENT_INFO_FILE} --dest-file ${DEST_ENVIRONMENT_INFO_FILE}

Where:

• source-file: Source environment info file where the data is stored.
• dest-file: Target environment info file where the data is going to be migrated.

8 - Agents Manager

Agents Manager

Introduction

agents-manager is a server in charge of managing and orchestrating access to the different agents within the AURA ecosystem.

The main purpose of agents-manager is to facilitate orchestration between the different agents registered in ATRIA, also to enrich the conversation by managing the message history, before sending the requests to the agent responsible for their processing.

Associated documentation

Descriptive technical documentation regarding agents-manager includes:

• Architecture and components
• Communication protocol
• Environment variables
• Agents Manager API definition and Agents Manager Codebase

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

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

8.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)

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

8.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)

8.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)

8.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)

8.1.1.6 - session-service plugin

session-service plugin

Introduction

The session-service plugin manages the sessions.

Consumes components (IOC)

Provides components (IOC)

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

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

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

8.4.1 - Agents Manager API

Agents Manager API

8.4.2 - Agents Manager Development API

Agents Manager Development API

8.4.3 - Agents Manager Dispatcher API

Agents Manager Dispatcher API

9 - Agents Server

Agents Server

Introduction

The agents-server component is a microservice that provides the capability to create server API and manage agents. It is responsible for executing the agent’s tasks.

To launch the agents-server component, you need install the agents package you prefer to use and deploy the server using this agents package.

Associated documentation

Descriptive technical documentation regarding agents-server includes:

• Architecture and components
• Environment variables
• Agents Manager API definition

9.1 - Architecture and components

Agents Server architecture and components

Technical foundations

The agents-server component will start a server that listens for incoming requests and executes the agent’s tasks based on the received input.

The server can be configured to use an agent by specifying the agent package name.

This server creates a REST API that can be used to interact with different agents. The API allows sending requests to the agent and receiving responses.

Within the agents-server, the agents package component enables information processing tasks to be performed and acted upon to achieve specific objectives. This information can come from a database and respond to the user’s request based on that acquired information.

Architecture overview

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

agents-server components

HTTP server

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

Config Api Handler

The agents-server uses the aura-configuration-api to get the configuration of the agent. This handler is responsible for retrieving the configuration of the agent from the aura-configuration-api and providing it to the server.

ConfigurationManager

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

Agents Package

The server is configured to use the agent of a specific agent package name. This package contains the agent’s code and its dependencies. The server will load the agent package and use it to execute the agent’s tasks.

Event Subscribers

Event subscribers are implementations for managing event registration and handling in the agents-server. They allow the server to listen for events and trigger actions based on those events.

Redis Async Subscriber

RedisAsyncSubscriber is a handler for subscribing to Redis channels asynchronously. It allows the server to receive messages from Redis and process them in real time.

DAPR Async Subscriber

DaprAsyncSubscriber is a handler for subscribing to DAPR topics asynchronously. It allows the server to receive messages from DAPR and process them in real time.

9.2 - Environment variables

Agents server environment variables

Introduction

The agents-server depends on these environment variables to be set. None of them are modifiable by the OBs.

• The environment variables related to Redis are used to connect to the Redis database. This database is used to refresh the agent’s configuration, because every time the configuration of an agent is changed, it publishes this change in the corresponding channel so we can detect this change in order to refresh it.

• The environment variables related to DAPR are used to connect to the DAPR components. These components are used to refresh the agent’s configuration, because every time the configuration of an agent is changed, it publishes this change in a corresponding topic, so we can detect this change in order to refresh it.

• In order to use DAPR, it is necessary to have the DAPR pubsub component configured in the DAPR configuration file, besides the DAPR environment variables.

9.3 - API definition

Agents Server API definition

10 - ATRIA APIs documentation

ATRIA APIs documentation

ATRIA APIs index

• aura-gateway-api API definition

• atria-model-gateway API definition