Aura – agents-ai

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

agent-dispatcher-api plugin

Technical description of the agent-dispatcher-api plugin

Introduction

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

Consumes components (IOC)

Name	Type	Description
configurationManager	PluginType.Service	Configuration manager
redisConnector	PluginType.Service	Redis connector
sessionService	PluginType.Service	Session service
agentsConfiguration	PluginType.Service	Agents Configuration

Provides components (IOC)

Name	Type	Description
agentDispatcherApi	PluginType.API	Agent dispatcher API

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Agents Manager API

Definition of the complete API in agents-manager

Download swagger file

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Define and configure agent

Description of the process for defining a new agent in ATRIA

Introduction

The first step for the creation of a new agent in ATRIA includes the definition of the agent. This is done by extending the BaseAgent class, in charge of creating the basic structure for all the agents to be developed and the management of its configuration.

Base class

The BaseAgent class provides the necessary functionality to initialize agent, manage configurations and interact with the agent package.

Access here the BaseAgent class in the Github repository.

The ATRIA agent-server uses this class to identify all the agents of the agent package coming from the BaseAgent.
This class promotes functionalities to initialize and build the agent.

Build agent

To build an agent it is necessary to extend this base class and, at least, extend these functionalities, according to the specific goals assigned to the agent.

get_class_ref: This method is used to get the class reference of the agent. It is used to identify the agent in the system.
build: This method is used to build the agent. It is used to set up the necessary configurations and to get everything required to initialize the agent.
__call__: This method is used to call the agent. It is used to execute the agent’s functionality.
initialize: This method is optional and used to initialize the agent. For example, it can be used to set up the agent’s state or to load any necessary data.

Configuration and information

The BaseAgent class provides a way to manage the agent’s configuration and information.

Information

The agent information is generated during the agent creation stage and can be accessed through the info field. It contains the following fields:

identifier: Unique identifier of the agent. This value corresponds to the class_ref of the agent.
name: Name of the agent. This value corresponds to the name of the agent coming from API.
deployment_name: Name of the agent deployment used to identify the agent environment that corresponds to the agent.
base_name : Base name of the agent used to identify the type agent. This value corresponds to the name of the agent class.
version : Version of the agent used to identify the version agent. This value corresponds to the version of the agent package installed.

Configuration

The agent configuration is generated during the agent creation stage from the aura-configuration-api, within the API agentBase.configuration field.

Here is an example.

 {
      "id": "XXXX-XXXX-XXXX-XXXXXXXXXXXX",
      "name": "test-agent",
      "deploymentName": "test-deployment-agent",
      "description": "A test agent",
      "communication": {
          "communicationType": "http"
      },
      "agentBase": {
          "name": "test-agent",
          "configuration": {
            "test": "test_value",
            "url": "http://localhost:8000"
          }
      }
  }

The entire content of this field is inserted into the agent under creation as a dictionary in the config field of the agent.

To obtain the configuration, access this config field as shown in the example below, where we want to obtain the test field within the agent’s configuration.
The use of the config will always be to fetch the information and not to store it between requests, as this config can be updated on the fly without the need to restart the component, so the config is read on each request.

test_value = self.config.get("test", None)

All this configuration is at agent level, but there are also configuration values at environment level. To obtain this environment configuration, use the command below:

test_value = os.getenv("TEST_ENV_VAR")

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Guidelines for technical developers

Scope: Comprehensive guidelines for the development of an agent and its integration into ATRIA

Technical developers

Introduction

ATRIA offers a framework for the development of agents to be used for the creation of experiences.

Agents can be developed both using their own tools or taking advantage of the libraries and tools that ATRIA provides. The current document will focus on the second option.

Agents development workflow

Prerequisites

Two main prerequisites are required prior to the development of an agent:

Python version: 3.13. or higher
ATRIA agents-server dependencies must be installed.

Workflow

The orderly steps for the creation and subsequent deployment of an agent are included below:

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Agents Manager API plugins

agents-manager plugins are components that provide different functionalities to agents-manager

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.

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Agents Manager Development API

Description of Agents Manager Development API. Only available in development environments.

Download swagger file

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Agents Manager architecture and components

Development architecture and technical components of the agents-manager

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.

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Agents Server architecture and components

Development architecture and technical components of the agents-server

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.

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Docker image

Description of how to create agent images, which is necessary for future deployment.

Introduction

The Docker image is the necessary component to deploy the agent in the ATRIA environment.

The image is built from the agent package and agent-server, which contains all the necessary to run the agent-server.

Build agent image

To build the agent image, it is necessary to use the docker command with the build option.

docker build -t <image_name> .

Where:

<image_name>: Name of the image to be created.
.: It indicates that the Dockerfile is in the current directory.

Dockerfile

The Dockerfile is the file that contains the instructions to build the image.

The Dockerfile for the agent image is located in the root directory of the agent package.

It is structured in two stages:

The first stage builds the agent package
The second stage creates the final image with the necessary dependencies and configurations and run the agent-server.

FROM python:3.13-slim AS base

ADD packages/atria-agent-dummy /opt/atria-agent
WORKDIR /opt/atria-agent

RUN pip install -r dev-requirements.txt && \
    python -m build

FROM python:3.13-slim

WORKDIR /opt/atria-agent

RUN apt-get update && apt-get install gcc python3-dev -y

COPY --from=base /opt/atria-agent/dist/atria_agent_dummy-*.tar.gz .
COPY --from=base /opt/atria-agent/entrypoint.sh entrypoint.sh
COPY --from=base /opt/atria-agent/version.txt version.txt

RUN pip install atria_agent_dummy-*.tar.gz && rm atria_agent_dummy-*.tar.gz

ENV AGENT_PACKAGE_NAME=atria_agent_dummy

ENTRYPOINT ["./entrypoint.sh"]

The directory atria-agent-dummy is the agent package that contains the agents code.

The entrypoint.sh script is used to run the agent server with the necessary configurations.

#!/bin/bash

set -e

export AURA_LOGGING_MODULE_VERSION=$(cat /opt/atria-agent/version.txt)

python -m atria_agents_server

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

development-api plugin

Technical description of the development-api plugin

Introduction

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

Consumes components (IOC)

Name	Type	Description
configurationManager	PluginType.Service	Configuration manager
redisConnector	PluginType.Service	Redis connector

Provides components (IOC)

Name	Type	Description
developmentApi	PluginType.API	Endpoints to change development configuration
behaviorCache	PluginType.Service	Cache to store the configuration changes
behaviorManager	PluginType.Service	Management of changes

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Guidelines for use cases constructors

Scope: Comprehensive guidelines for the use of agents in an ATRIA experience

Use cases constructors

Index of contents

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Agent AI operational workflow

ATRIA technical operational flow corresponding to the operation of the Agents AI capability

Operational flowchart

The sequence diagram of the process executed by the agents AI capability is shown below:

@startuml
title Agent API diagram
participant Application
participant Kernel #1add4d
participant AuraGatewayApi #76bbe7
participant AgentsManager #0796f5
participant MongoDeviceRecommender #11f5cf
participant AtriaModelGateway #f58e11
participant AzureOpenAI #9476e7
Application -> Kernel: Create two-legged token with scope aura-ai-services:agents-messaging:write
Note right of Kernel: this token needs refreshing
Kernel -> Application: Response two-legged token
Application -> Kernel: Request to aura-aiservices/agents/messages with token and correlatorId (x-correlator)
Kernel -> AuraGatewayApi: Request to aiservices/agents/messages with token-info header and correlatorId
AuraGatewayApi -> AuraGatewayApi: Validate request
AuraGatewayApi -> AgentsManager: Send Request to an agent
AgentsManager -> AgentsManager: Check if the context exists && retrieves it
AgentsManager -> AgentsManager: routing to the agents
AgentsManager -> MongoDeviceRecommender: Send Request to an agent with the context
MongoDeviceRecommender -> MongoDeviceRecommender: process the Request
group Agents process
  loop XX times
    MongoDeviceRecommender -> AtriaModelGateway: Send prompt to atria-model-gateway
    AtriaModelGateway -> AzureOpenAI: Send Request to ChatCompletation endpoint
    AzureOpenAI --> AtriaModelGateway: Response from AzureOpenAI
    AtriaModelGateway -> MongoDeviceRecommender: Response prompt
    MongoDeviceRecommender -> MongoDeviceRecommender: Analyze the response
  end
end
MongoDeviceRecommender -> AgentsManager: response 200 and message
AgentsManager -> AgentsManager: Store the context
AgentsManager --> AuraGatewayApi: response 200 and message
AuraGatewayApi -> AuraGatewayApi: process response
AuraGatewayApi -> AuraGatewayApi: generate response
AuraGatewayApi -> Kernel: response 200 and message
Kernel -> Application: response 200 and message
@enduml

Agents AI operational sequence diagram

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Agent plugin

Agent plugin description for aura-configuration-api

Introduction

The agent plugin defines services associated with the management of agents in aura-configuration-api server.

All these services are defined in the agents namespace (/agents).

Servers definition

By default, the servers defined in the swagger include the base path (for v1):
/aura-services/v2/configuration.

Therefore, in order to access the services, the base path and service path must be used.

Examples:

aura-services/v2/configuration/agents
aura-services/v2/configuration/agents/{agentId}

Endpoints

Path	Method	Description
/agents/	GET	Get all agent information
/agents/	POST	Add a new agent
/agents/{agentId}	GET	Get agent information using agent id
/agents/{agentId}	PUT	Replace agent information associated to agent id
/agents/{agentId}	PATCH	Update some fields of agent information using agent id
/agents/{agentId}	DELETE	Delete agent information using agent id

You can read the complete documentation of each service in the aura-configuration-api agent swagger file.

Retrieving information from agents

Retrieving specific fields from agent information

It is possible to get only a specific list of fields for agent information, reducing the amount of data transmitted when necessary, using the includeFields query parameter.

curl --location --request GET 'http://aura-configuration-api:8999/aura-services/v2/configuration/agents?includeFields=id,name' \
--header 'correlator: urn:uuid:c8a604ee-29f8-7cda-2979-d2ae6189c360' \
--header 'Accept: application/json' \
--header 'Authorization: XXX'

Response example:

[
    {
        "id": "ab744582-c5a6-48e1-95bb-f509bdb55512",
        "name": "agent-pid-1"
    }
]

Excluding fields in agent information

It is also possible to exclude agent information fields using the excludeFields query parameter.

curl --location --request GET 'http://aura-configuration-api:8999/aura-services/v2/configuration/agents?excludeFields=metadata,name' \
--header 'correlator: urn:uuid:c8a604ee-29f8-7cda-2979-d2ae6189c360' \
--header 'Accept: application/json' \
--header 'Authorization: APIKEY XXX'

Response example:

[
    {
        "id": "ab744582-c5a6-48e1-95bb-f509bdb55512",
        "name": "agent-pid-1"
    }
]

Database

The complete definition of the data model can be found in Agent collection section within the administration module.

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Agents Manager Dispatcher API

Description of Agents Manager Dispatcher API

Download swagger file

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Aura Agents API

Description of Aura Agents API

Download swagger file

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Agents Manager communication protocol

Description of 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

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

configuration-service plugin

Description of the configuration-service plugin

Introduction

The configuration-service plugin manages the configuration of agents.

Consumes components (IOC)

Name	Type	Description
configurationManager	PluginType.Service	Configuration manager

Provides components (IOC)

Name	Type	Description
agentsConfiguration	PluginType.Service	Agents configuration

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Deployment of an agent in ATRIA

Guidelines for the deployment of newly created agents in ATRIA

Introduction

The current document includes comprehensive guidelines that serves as the foundational framework for the deployment of customized agents within ATRIA.

To deploy an agent in the aura config provisioning it is necessary to generate the following files in the corresponding folders.

Agents Base

In this folder, it is necessary to include the agents that are available to build. To do this, a json file must be generated with the data of this new agent.

Here is an example.

{
  "id": "XXXX-XXXX-XXXX-YYYYYYYYYYYYYY",
  "name": "test-agent",
  "description": "An agent test",
  "language": "python",
  "version": "1.0.0"
}

Where:

id: Unique identifier for the agent.
name: Name of the agent.
description: Description of the agent.
language: Programming language used for the agent.
version: Version of the agent.

These fields can also be added, removed or edited from the api. Also changes made by the api directly will not be persisted between releases.

Agents Deployment

In this folder, developers must define the agent to be deployed, associated with the [Docker image version]((/docs/atria/technical-guidelines/agents-management/agents-technical-development/docker-image/) previously created.

For this purpose, generate a json file with the data of this new agent.

Here is an example.

{
   "id": "XXXX-XXXX-XXXX-XXXXXXXXXXXX",
   "name": "test-agent",
   "config": {},
   "secrets": {},
   "image": "XXXX/agent-test",
   "tag": "X.X.X"
 }

Where:

id: Unique identifier for the agent.
name: Name of the agent.
config: Assign configuration assigned to in the agent’s environment (can be empty).
secrets: Assign secrets assigned to in the agent’s environment (can be empty).
image: Docker image of the agent.
tag: Tag of the Docker image.

These fields cannot be updated from the api.

Agents

In this folder, developers must include the information regarding te agent to be deployed, together with its configuration and information.

You can display the same agent image but with different information or configuration.

Here is an example.

{
     "id": "XXXX-XXXX-XXXX-XXXXXXXXXXXX",
     "name": "test-agent",
     "deploymentName": "test-deployment-agent",
     "description": "A test agent",
     "communication": {
         "communicationType": "http"
     },
     "agentBase": {
         "name": "test-agent",
         "configuration": {}
     }
 }

Where:

id: Unique identifier for the agent.
name: Name of the agent. This value is the name we want to give to the agent and is not related to the name we have at code level. Therefore, we can deploy several different agents with the same code base.
deploymentName: Name of the deployment of the agent, this value allows grouping several agents to the same deployment name.
description: Description of the agent.
communication: Communication type of the agent, in this case it is HTTP.
agentBase: Information about the base agent, including its name and configuration.
agentBase.name: Name of the base agent, this value allows you to associate the agent with the image of the agent you want to deploy. This value is associated with the name that comes by reference with the value of the get_class_ref of the developed agent.
agentBase.configuration: Configuration parameters for the agent (can be empty).

These fields can also be added, removed or edited from the api. Also changes made by the api directly will not be persisted between releases.

Applications

For the agent to be used in ATRIA, it must be associated to an existing application.

For this purpose, within the general process for the configuration of an application, edit the field agents with the list of agents’ identifiers to be associated to the application.

Here is an example.

{
     "brand": "ZZZZ",
     "id": "YYYY-YYYY-YYYY-YYYYYYYYYYYY",
     "name": "test-agent-app",
     "agents": [
         "XXXX-XXXX-XXXX-XXXXXXXXXXXX"
     ]
}

These fields can also be added, removed or edited from the api. Also changes made by the api directly will not be persisted between releases.

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Agents server

These documents include comprehensive guidelines for the management of agents in ATRIA, intended for two profiles:

Technical developers in charge of creating agents

Use cases constructors responsible for the generation and configuration of an agent for their experience

Index of contents

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Agents Manager environment variables

List of environment variables handled by agents-manager

Properties marked in bold are mandatory.
Properties marked in italics are optional.

Introduction

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

Common properties

Property	Type	Description	Modifiable by OB?
AURA_AUTHORIZATION_HEADER	string	APIKey to use with aura-services.	NO
AURA_DEFAULT_LOCALE	string	Culture code to be used by default in the current deployment: `de-de`, `en-gb`, `es-es`, `pt-br`.	NO
AURA_DEFAULT_TIME_ZONE	string	Timezone where the service is running.	NO
AURA_ENCRYPTION_ALGORITHM	string	Encryption algorithm that will be used to validate the APIKey. By default: `aes-256-cbc`.	NO
AURA_ENCRYPTION_IV_LENGTH	number	Size for the initialization vector used by the encryption algorithm that validates the APIKey. By default: `16`.	NO
AURA_ENCRYPTION_IV_POSITION	number	Position where to insert the initialization vector in the final string with the encrypted payload. By default: `35`.	NO
AURA_ENCRYPTION_KEY	string	Encryption key or comma-separated list of encryption keys to be used in the environment. It is mainly used to decrypt the APIKeys.	NO. It would break database encrypted data and APIKey validation.
AURA_ENVIRONMENT_NAME	string	Name of the environment where the server is deployed. Used during server make-up to handle the indexes of the database properly.	NO
AURA_ENVIRONMENT_PREFIX	string	Prefix that will be used by all Redis keys when using redis-connector. By default: ``. (empty)	YES
AURA_HTTP_KEEP_ALIVE	boolean	Use of keep-alive in HTTP connections. Used in monkey-patcher. By default: `true`.	NO
AURA_HTTP_KEEP_ALIVE_MSECS	number	Number of milliseconds to keep alive HTTP connections. Used in monkey-patcher. By default: `100000`.	NO
AURA_HTTP_KEEP_MAX_SOCKETS	number	Maximum number of sockets. Used in monkey-patcher. By default: `250`.	NO
AURA_HTTP_MAX_REQUEST_SIZE	string	Maximum size in bytes of body request. Allowed values must indicate the units: 10 mb, 200 kb, etc. By default, `20mb`.	NO
AURA_LOGGING_FORMAT	string	Format to be used in monitoring logs: `json` or `dev`(more visual format). By default: `json`.	NO. Only for development, set it to `dev`.
AURA_LOGGING_LEVEL	string	Level to be used in logs, from more to less verbose: `'TRACE', 'DEBUG', 'INFO', 'WARN', 'ERROR', 'FATAL', 'OFF'`. By default: `INFO`.	NO
AURA_MAKEUP_MODE	string	It allows `dev` mode for the make-up process with the value `local`. By default: `full`.	NO
AURA_MICROSOFT_AZURE_STORAGE_ACCESS_KEY	string	Microsoft Storage password of the deployment.	NO
AURA_MICROSOFT_AZURE_STORAGE_ACCOUNT	string	Microsoft Storage account of the environment.	NO
AURA_MICROSOFT_AZURE_STORAGE_CONFIGURATION_CONTAINER	string	Aura configuration container name. By default: `aura-configuration`.	NO
AURA_HTTP_MONKEY_PATCHER_ENABLED	boolean	Flag to indicate whether Monkey Patcher is used in service or not.	NO
AURA_SERVER_PORT	number	Port to where server is listening. By default: `8990`.	NO
AURA_SERVER_REMOTE_CONTAINER_PREFIX	number	Remote container prefix. By default: `agents-manager`.	NO
AURA_SERVICE_ENVIRONMENT	string	Type of environment: `'DEV', 'PRE', 'PRO'`. By default, `DEV`. It is used during locale translation, to get the correct text reference.	NO
AURA_SHUTDOWN_GRACEFUL_TTL	number	Time in milliseconds to complete the SHUTDOWN signal and process all the messages in queue before SIGTERM. By default: `25 * 1000`.	NO
AURA_SWAGGER_FROM_REMOTE	boolean	Flag to indicate whether the swagger file is loaded from remote or not. By default: `true`.	NO
AURA_SWAGGER_LOCAL_PATH	string	Location of the swagger file generated from all loaded plugins. By default: `swagger.yaml`. Used during makeup to upload the file to remote.	NO
AURA_SWAGGER_PLUGIN_PATH	string	Location of the swagger file of every plugin. By default: `swagger.yaml`.	NO
AURA_SWAGGER_LOCAL_CORE_PATH	string	Location of server swagger base file. By default: `swagger-core.yaml`.	NO
AURA_SWAGGER_REMOTE_CONTAINER_PREFIX	string	Remote container prefix to store the swagger information. By default: `swagger`	NO
AURA_VERSION	string	Mandatory, release of Aura.	NO
AURA_HTTP_PATHS_LOG_DISABLED	string	HTTP paths separated by commas whose request would not be logged. By default `aura-configuration', 'metrics', 'healthz` Used in monkey-patcher.	NO

development-api plugin

Property	Type	Description	Modifiable by OB?
DEV_AURA_BEHAVIOR_PREFIX	string	Used in cache key prefix and in command name. By default: `gateway`.	NO in production environments. This feature could only be activated in development environments.
DEV_AURA_BEHAVIOR_CACHE_TTL	number	Maximum lifetime of behavior cache in seconds. After this time, the system will delete the message. By default: `60 * 60` (60 min).	NO in production environments. This feature could only be activated in development environments.
DEV_AURA_BEHAVIOR_COMMAND_PATTERN	string	Pattern to recognize a behavior command. By default: `gateway(:\| +)(get\|set\|unset)(:\| +)(\w+)(:\| +)?.+`	NO in production environments. This feature could only be activated in development environments.

configuration-service plugin

Property	Type	Description	Modifiable by OB?
AURA_CONFIGURATION_API_ENDPOINT	string	Configuration API URL where the server should get the configuration.	NO
AURA_AUTHORIZATION_HEADER	string	APIKey to use with aura-services.	NO
AURA_CONFIGURATION_RETRIES	number	Number of retries to get the configuration. By default: `3`.	NO, only if checked and validated with Aura Global Team.
AURA_CONFIGURATION_RETRY_DELAY	number	Delay between retries in case of error. By default: `100`.	NO, only if checked and validated with Aura Global Team.
AURA_CONFIGURATION_RETRY_FACTOR	number	Factor to multiply delay for every HTTP request retried. By default: `10`.	NO, only if checked and validated with Aura Global Team.

redis-connector-service plugin

Property	Type	Description	Modifiable by OB?
AURA_REDIS_MODE	string	Mode of Redis distribution. Values: `CLUSTER`, `SENTINEL`, `SINGLE`. By default: `SENTINEL`.	NO
AURA_REDIS_SENTINEL_INSTANCE_NAME	string	Name of the Redis instance. Used in `SENTINEL` mode.	NO
AURA_REDIS_HOSTS	string	String with a list of nodes separated by ‘,’, including host and port separated by ‘:’. For example: “localhost:port,localhost2:port2”.	NO
AURA_REDIS_DATABASE	number	Database number for `SINGLE` or `SENTINEL` mode. By default: `0`.	YES
AURA_REDIS_PASSWORD	string	String with Redis password.	YES
AURA_REDIS_USE_CONNECTION_POOL	boolean	Use pool connections for Redis. By default: `true`.	YES
AURA_REDIS_CONNECTION_POOL_MIN	number	Minimum number of connections in the pool. By default: `2`.	YES
AURA_REDIS_CONNECTION_POOL_MAX	number	Maximum number of connections in the pool. By default: `100`.	YES
AURA_REDIS_MAX_RECONNECT_RETRIES	number	Number of retries to connect to Redis. By default: `25`	YES
AURA_REDIS_MAX_RECONNECT_INTERVAL	number	Time in milliseconds to wait before reconnecting to Redis. By default: `5000`.	YES

session-service plugin

Property	Type	Description	Modifiable by OB?
AURA_SESSION_MAX_HISTORY_LENGTH	number	Maximum number of messages to keep in history. Default: `10`.	NO
AURA_SESSION_EXPIRE_TIME	number	Expire time for the conversation history in seconds. Default: `3600` (1 hour).	NO

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Agents server environment variables

List of environment variables handled by the agents-server

Introduction

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

Property	Type	Description
AGENT_PACKAGE_NAME	string	Package names containing the agents to be deployed. They must be separated by `,`.
AURA_AGENT_DEPLOYMENT_NAME	string	Deployment name, which is used to obtain the agents to be deployed at API level.
AURA_CONFIG_API_API_KEY	number	APIKey for the aura-configuration-api. This key is used to authenticate requests to the aura-configuration-api.
AURA_CONFIG_API_BASE_URL	string	Base URL for the aura-configuration-api used to make requests to this component.
AURA_LOGGING_CONFIG_PATH	string	Path to the logging configuration file. This file is used to configure the logging settings for the server.
AURA_LOGGING_MODULE_NAME	string	Name of the logging module. This name is used to identify the logging module in the logging configuration.
AURA_LOGGING_NAME	string	Name of the logging instance. This name is used to identify the logging instance in the logging configuration.
AURA_REDIS_DATABASE	number	Redis database number to be used by the server. This number is used to connect to the Redis database.
AURA_REDIS_HOSTS	string	Redis hosts to be used by the server. This is a comma-separated list of Redis host names or IP addresses.
AURA_REDIS_MODE	string	Mode of the Redis connection.
AURA_REDIS_PASSWORD	number	Ppassword for the Redis connection. This password is used to authenticate the connection to the Redis database.
AURA_REDIS_POOL_SIZE	number	Size of the Redis connection pool. This number is used to limit the number of connections to the Redis database.
AURA_REDIS_PREFIX_SUBSCRIBERS	string	Prefix for the Redis subscribers. This prefix is used to identify the subscribers in the Redis database.
AURA_REDIS_CHANNELS_SUBSCRIBERS	string	Channels (separated by ‘,’) for the Redis subscribers. Redis prefix is added to these channels at the beginning.
AURA_REDIS_P_CHANNELS_SUBSCRIBERS	string	Pattern channels (separated by ‘,’) for the Redis subscribers. Redis prefix is added to these pattern channels at the beginning.
AURA_DAPR_PUBSUB_NAME	string	DAPR pubsub component name. It is used to identify DAPR component to be used.
AURA_DAPR_PREFIX_SUBSCRIBERS	string	Prefix for the DAPR pubsub subscribers. This prefix is used to identify the subscribers in the configured database.
AURA_DAPR_TOPICS_SUBSCRIBERS	string	Topics (separated by ‘,’) for the DAPR pubsub subscribers. DAPR prefix is added to these topics at the beginning.
AURA_MODEL_GW_BASE_URL	string	Base URL for the aura-model-gateway. This URL is used to make requests to the aura-model-gateway.
AURA_MONGODB_SSL	boolean	It indicates whether to use SSL for the MongoDB connection or not. This is a boolean value that can be set to `true` or `false`.
AURA_MONGODB_URI	string	URI for the MongoDB connection. This URI is used to connect to the MongoDB database.
AURA_MONGODB_USERNAME	string	Username for the MongoDB connection. This username is used to authenticate the connection to the MongoDB database.
AURA_MONGODB_PASSWORD	string	Password for the MongoDB connection. This password is used to authenticate the connection to the MongoDB database.

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.

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Errors management

Description of the error handling available on the server for internal use of new agents in ATRIA

Introduction

The agents-server provides a set of error managers mechanisms to ensure that agents can handle errors gracefully and provide meaningful feedback to users. This is essential for maintaining the reliability and usability of the agents.

Error Managers

The agents-server provides a set of error managers that can be used to handle errors in a consistent way. These error managers are designed to be used by agents to handle errors that occur during their execution.

The error managers are:

AgentErrorManager: This error manager is used to handle errors that occur during the execution of the agent. This results in the corresponding response and error code, depending on the exception thrown at agent level.
FastApiErrorManager: This error manager is used to handle errors that occur during the execution of the FastAPI application. This results in the corresponding response and error code, depending on the exception thrown at server level.

AgentErrorManager

All these exceptions receive a message and an error code.

This manager controls the following exceptions:

AgentBaseException

This is the base exception for all agent-related exceptions. It is used to catch any other exceptions that are not explicitly handled by the other error managers. It results in a 500 Internal Server Error response. It is formed as follows:

message: String. Default value: An agent error occurred.
error_code: String. Default value: AGENT_ERROR.

AgentNotFoundException

This exception is raised when the agent is not found in the system. It results in a 404 Not Found response. It is formed as follows:

message: String. Default value: Agent not found.
error_code: String. Default value: AGENT_NOT_FOUND.

AgentConfigException

This exception is raised when there is an error in the agent configuration. It results in a 400 Bad Request response. It is formed as follows:

message: String. Default value: Agent configuration error.
error_code: String. Default value: AGENT_CONFIG_ERROR.

AgentValidationException

This exception is raised when there is a validation error in the agent’s input. It results in a 400 Bad Request response. It is formed as follows:

message: String. Default value: Agent validation failed.
error_code: String. Default value: AGENT_VALIDATION_ERROR.

AgentExecutionException

This exception is raised when there is an error during the execution of the agent. It results in a 500 Internal Server Error response. It also receives the field detail. It is formed as follows:

message: String. Default value: Agent execution failed.
error_code: String. Default value: AGENT_EXECUTION_ERROR.
detail: String. Used to provide additional information to message. Default value: empty string.

AgentExternalServiceException

This exception is raised when there is an error in the external service that the agent is trying to access. It results in a 502 Bad Gateway response. It also receives the fields service_error_code and service_name. It is formed as follows:

message: String. Default value: External service error.
error_code: String. Default value: AGENT_EXTERNAL_SERVICE_ERROR.
service_error_code: String. Used to provide additional information, adding to the message {service_error_code}`. Default value: empty string.
service_name: String. Used to provide additional information, adding to the message `Service: {service_name}. Default value: empty string.

AgentModelError

message: String. Default value: Model error.
error_code: String. Default value: AGENT_MODEL_ERROR.
service_error_code: String. Used to provide additional information, adding to the message {service_error_code}`. Default value: empty string.
service_name: String. Used to provide additional information, adding to the message `Service: {service_name}. Default value: empty string.

AgentRateLimitError

This exception is raised when the agent exceeds the rate limit for the external service it is trying to access. It results in a 429 Too Many Requests response. It also receives the fields service_error_code and service_name. It is formed as follows:

message: String. Default value: Rate limit error.
error_code: String. Default value: AGENT_RATE_LIMIT_ERROR.
service_error_code: String. Used to provide additional information, adding to the message {service_error_code}`. Default value: empty string.
service_name: String. Used to provide additional information, adding to the message `Service: {service_name}. Default value: empty string.
retry_after: String. Mandatory field that adds the value Retry-After in the response header to indicate how long the client should wait before making a new request.

Usage

This manager allows launching these exceptions internally in your new agent.

To launch one of these exceptions, use the following command:

raise AgentExecutionException(message='message error', service_error_code='ERROR CODE', detail='problem with the agent execution')

FastApiErrorManager

This manager controls the following exceptions server:

ValidationException: This exception is raised when there is a validation error in the request. It results in a 400 Bad Request response.
RequestValidationError: This exception is raised when there is a validation error in the request body. It results in a 400 Bad Request response.
ResponseValidationError: This exception is raised when there is a validation error in the response body. It results in a 400 Bad Request response.

Response Error

The error managers return a response with the following structure:

{
    "code": "NOT_FOUND",
    "message": "Agent with identifier XXXX not found.",
    "errors": [
        {
            "type": "AGENT_NOT_FOUND",
            "message": "Agent with identifier XXXX not found."
        }
    ]
}

The response contains the following fields:

code: The error code that identifies the type of error.
message: A human-readable message that describes the error.
errors: A list of errors that occurred during the execution of the agent. Each error contains the following fields:
- type: The type of error that occurred.
- message: A human-readable message that describes the error.

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

redis-connector-service plugin

Description of the redis-connector-service plugin

Introduction

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

Consumes components (IOC)

Name	Type	Description
configurationManager	PluginType.Service	Configuration manager

Provides components (IOC)

Name	Type	Description
redisConnector	PluginType.Service	Redis connector

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Aura Configuration API Agent definition

Description of Aura configuration API Agent swagger

Download swagger file

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Create and configure an agent

Guidelines for the configuration of ATRIA by use cases constructors when developing an experience by means of an agent

Introduction

An agent is a configuration entity in ATRIA that represents an integration point for external channels, services, or platforms.

Each agent defines how ATRIA communicates with and manages sessions for a specific external system, specifying connection details, session parameters, and operational metadata.

Agents are referenced by applications to enable channel or service connectivity within the platform.

Guidelines to configure an agent

1. Create a new agent

Build the agent for your use case (json file), using the available agent fields.

When the agent json file is generated, execute this command to include it:

curl --location --request POST 'https://svc-<env>.auracognitive.com/aura-services/v2/configuration/agents/' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'Authorization: APIKEY XXX' \
  --data-raw '<NEW AGENT JSON>'

1.1. Modify/update an agent

If once created, certain modifications are required, follow these instructions:

Make the required changes in the agent json file using the available agent fields.

When the agent is modified, execute this command to update it:

curl --location --request PUT 'https://svc-<env>.auracognitive.com/aura-services/v2/configuration/agents/<agentID>' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: APIKEY XXX' \
  --data '<AGENT JSON WITH MODIFICATIONS>'

1.2. Delete an agent

Execute the following command:

curl --location --request DELETE 'https://svc-<env>.auracognitive.com/aura-services/v2/configuration/agents/<agentId>' \
  --header 'Accept: application/json' \
  --header 'Authorization: APIKEY XXX'

2. Include the agent in the application

If the application for your use case does not exist, first create it following the guidelines for the configuration of an application.

Once the application is created, assign the created agent in the field agents.

If you update or delete an agent, ensure that any application referencing it is also updated accordingly.
Remember that agents must exist to be inserted in an application.

Example to update the list of agents in an application:

curl --location --request PATCH 'https://svc-<env>.auracognitive.com/aura-services/v1/applications/<applicationId>' \
  --header 'Accept: application/json' \
  --header 'Authorization: APIKEY XXX' \
  --data '{
    "id": "<applicationId>",
    "agents": [
      "<agentId1>",
      "<agentId2>"
    ]
  }'

Agent fields

The fields for the characterization of an agent are summarized below, as defined in the API swagger Aura Configuration ATRIA Agents:

Field	Type	Mandatory	Description
`id`	string	Yes	Unique identifier (UUID) for the agent.
`name`	string	Yes	Name that uniquely identifies the agent in Aura.
`description`	string	No	Description of the agent.
`communication`	object	Yes	Parameters for the configuration of the communication flow. See communication configuration.
`flowConfig`	object	No	Configuration of the agent flow.
`deploymentName`	string	No	Name of the deployment where the agent is running. If the `endpoint` field is not present in `communication`, this field will be used to route requests to the agent.
`metadata`	object	No	Document metadata (version, createdAt, updatedAt, etc). See metadata.

Communication configuration (`communication`)

Field	Type	Mandatory	Description
`communicationType`	string	Yes	Type of communication. Only `http` is currently supported.
`endpoint`	string	No	HTTP endpoint where the agent listens.
`headers`	object	No	HTTP headers associated with the agent.
`timeout`	number	No	Timeout for agent communication.
`retries`	number	No	Number of retries for communication.

Metadata (`metadata`)

Field	Type	Mandatory	Description
`version`	string	No	Configuration version when the document was created.
`createdAt`	string	No	Creation date (ISO 8601).
`updatedAt`	string	No	Last update date (ISO 8601).

Example: Minimal agent configuration

{
  "id": "b1e2c3d4-5678-1234-9abc-def012345678",
  "name": "example-agent",
  "communication": {
    "communicationType": "http",
    "endpoint": "https://agent.example.com/webhook"
  }
}

Example: Full agent configuration

{
  "id": "b1e2c3d4-5678-1234-9abc-def012345678",
  "name": "example-agent",
  "description": "Agent for integration with Example Service",
  "communication": {
    "communicationType": "http",
    "endpoint": "https://agent.example.com/webhook",
    "headers": {
      "Authorization": "Bearer <token>"
    },
    "timeout": 30,
    "retries": 3
  },
  "flowConfig": {},
  "deploymentName": "example-deployment",
  "metadata": {
    "version": "1.0.0",
    "createdAt": "2024-05-30T10:00:00Z",
    "updatedAt": "2024-05-30T12:00:00Z"
  }
}

Note:

The id, name, and communication fields are mandatory.

The communicationType must be http.

If an agent is deleted, applications referencing it will be updated.

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

session-service plugin

Technical description of the session-service plugin

Introduction

The session-service plugin manages the sessions.

Consumes components (IOC)

Name	Type	Description
configurationManager	PluginType.Service	Configuration manager
redisConnector	PluginType.Service	Redis connector

Provides components (IOC)

Name	Type	Description
sessionService	PluginType.Service	Management of sessions

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Agents Manager

Descriptive technical documentation regarding agents-manager, the server in charge of managing and orchestrating access to the different agents within the ATRIA ecosystem

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:

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

API definition for Agents Manager

Description of API swaggers for agents-manager component

APIs index

Agents Manager API
Agents Manager Development API
Only available in development environments.
Agents Manager Dispatcher API
Dapr PubSub API

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Agents Server

Descriptive documentation regarding the component 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:

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

aura-agents-api plugin

Description of the aura-agents-api plugin

Introduction

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

Consumes components (IOC)

Name	Type	Description
configurationManager	PluginType.Service	Configuration manager
applicationConfiguration	PluginType.Service	Configuration of applications
agentsConfiguration	PluginType.Service	Configuration of agents

Provides components (IOC)

Name	Type	Description
agentsApi	PluginType.API	Endpoints for the communication with agents APIs
agentsManagerClient	PluginType.Service	Client of agents-manager

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Agents Server API definition

Description of Agents Server configuration API swagger

This is an internal AURA API.

Download swagger file