Guidelines for technical developers

• 1: Define and configure agent
• 2: Create a Docker image
• 3: Deployment of an agent
• 4: Errors management

1 - Define and configure agent

Define and configure agent

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")

2 - Create a Docker image

Docker image

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

3 - Deployment of an agent

Deployment of an agent 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.

4 - Errors management

Errors management

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

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