Guidelines for use cases constructors

• 1: Create and configure an agent
• 2: Create and configure an agent base

1 - Create and configure an agent

Create and configure an agent

Introduction

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

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:

Communication configuration (communication)

Agent base (agentBase)

Metadata (metadata)

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": "1870fa4a-bcc4-4a7c-88fc-c0194555a076",
    "name": "device-recommender-agent",
    "communication": {
      "communicationType": "http",        
    },
    "deploymentName": "mongo-device-recommender-agent",
    "description": "An AI agent built with langgraph that provides personalized recommendations about devices by querying and analyzing data stored in a MongoDB database.",
    "agentBase": {
      "name": "device-recommender-agent",
      "configuration": {
        "conversational_agent": {
          "conversational_prompt": "Adopt the role of Aura",
          "model_params": {
            "temperature": 0.1
          },
          "model_str": "model_gw/gpt-4o-mini"
        },
        "mongo_agent": {
          "database_name": "mongo-recommender",
          "limit_query_result": 10,
          "model_params": {
            "temperature": 0.1
          },
          "model_str": "model_gw/gpt-4o-mini",                    
        }
      },          
    },
    "metadata": {
      "createdAt": "2025-07-11T09:54:33.973Z",
      "updatedAt": "2025-07-11T09:54:33.973Z",
      "version": "10.3.0"
    }
  }

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.

2 - Create and configure an agent base

Create and configure an agent base

Introduction

An agent-base is a configuration entity in ATRIA that represents an implementation code for an agent.

Agents base are referenced by agents to deploy the configuration of the agent.

Guidelines to configure an agent-base

1. Create a new agent-base

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

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

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

1.1. Modify/update an agent-base

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

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

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

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

1.2. Delete an agent-base

• Execute the following command:

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

2. Include the agent-base in the agent

Create the agents configuration, indicating de agentBase.name, as explained in the document guidelines for the configuration of an agent

Agent base fields

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

Metadata (metadata)

Example: agent-base configuration

{
  "id": "cd2b534c-16c3-4d89-a87e-ec45d3939232",
  "name": "agent-base-test",
  "description": "An AI agent built with langgraph that provides personalized recommendations about devices by querying and analyzing data stored in a MongoDB database.",
  "language": "python",
  "version": "1.0.0"
}

Note:

• The id, name, and language fields are mandatory.
• The language must be python.