Create and Manage Agents

This article describes how to create an agent in the R-COM Gateway, configure it, assign processes, and connect it to the Agent Edgeware on the edge host. For the concepts used here (agent, Agent Edgeware, process, connection mode, Power, Monitoring, and Status), see the Introduction.

Before you start, make sure that the process templates the agent will run exist. See Process Templates.

The Manage Agents Page

Navigate to Agents > Manage Agents. The page lists all agents you can access.

Manage Agents page

Column	Description
Agent	Name of the agent.
Tags	Labels used to categorize and filter agents.
Group	The Access Group assigned to the agent. Only members of this group can view or manage it.
Description	A short description, for example the location or purpose.
Status	The last state the agent reported. See Agent Status Values.
Version	The Agent Edgeware version the agent reported. Shows Version not reported if the agent has not reported a version yet.
Actions	The chevron opens the agent. The two switches turn Power and Monitoring on or off. The delete button deletes the agent and is available only while the agent is powered off.

The page header provides:

• Refresh – Reloads the list.
• MQTT Settings – Opens the shared Agent MQTT Broker configuration. See MQTT Settings.
• Create agent – Creates a new agent. See Step 1: Create the Agent.

Find Agents

• Search – Type in the search field to find agents by name.
• Add filter – Filter by Agent, Group, Monitoring, Powered, Status, or Tags. A tag filter with several tags returns agents that have any of the selected tags.
• Views – Select New view to save the current search and filters as a view, and switch between saved views above the search field.

Agent Status Values

Status	Meaning
Unknown	The Gateway is not receiving signals from the agent, for example because the Agent Edgeware is not installed, not configured, or not reachable.
Stopped	The Agent Edgeware is installed but not running. No processes or device connections are active.
Starting	The agent is initializing, loading its configuration, and connecting to the Gateway.
Running	The agent is operational, connected to the Gateway, and sending status and logs.
Stopping	The agent is shutting down its services and disconnecting from devices and the Gateway.
Updating	The agent is receiving and applying a configuration or component update from the Gateway.
Warning	The agent is running but has detected a problem that may affect it, for example a lost device or monitoring connection. Check Agent Logs.
Error	The agent has a critical failure that prevents normal operation. Check Agent Logs and act immediately.
UpdateRequired	The configuration was changed in the Gateway but has not yet been applied to the agent.
UpdateConfirmed	The agent has applied the latest configuration and is synchronized with the Gateway.

MQTT Settings

Agents use two separate MQTT configurations. They are configured in different places and serve different purposes.

Configuration	Where to configure	Used by	Purpose
Agent MQTT Broker	Agents > Manage Agents > MQTT Settings	All agents that use the Mqtt connection mode	Exchange of status, logs, configuration, and commands between the agents and the Gateway.
UI MQTT Broker	Administration > System Config > Client Settings	The Gateway UI in the browser	Live updates of agent status on the Manage Agents page without reloading.

Agent MQTT Broker

Select MQTT Settings on the Manage Agents page. The Agent MQTT Broker dialog opens in read-only mode; select Edit to change it.

warning

Changes to the Agent MQTT Broker affect all connected agents.

Agent MQTT Broker dialog

Field	Description
Host	Hostname or IP address of the MQTT broker.
Port	Broker port, for example 1883 without TLS or 8883 with TLS.
Root topic	Topic prefix under which all agent topics are created.
Username	Username for broker authentication.
Password	Password for broker authentication.
Use TLS	Encrypts the broker connection with TLS.
Accept all certificates	Accepts any server certificate, including self-signed certificates. Use for testing only.
Keep-alive interval (seconds)	How often the agent sends keep-alive messages to the broker.
Reconnect interval (seconds)	How long the agent waits before reconnecting after a disconnect.
TLS client certificate path	Path to the client certificate on the edge host, for mutual TLS.
TLS CA certificate path	Path to the CA certificate used to verify the broker's certificate.

All agents inherit these settings. Host, Port, and Root topic are always taken from here. The other fields can be overridden per agent; see MQTT Configuration.

info

The Agent MQTT Broker is used for communication between agents and the Gateway only. Agents and the Gateway connect to it with standard MQTT over TCP, not WebSocket.

UI MQTT Broker

The Gateway UI uses this broker to show agent status changes on the Manage Agents page as they happen. Configure it under Administration > System Config > Client Settings: select MQTT configuration, then Edit. For all fields, see Client Settings: UI MQTT Broker Configuration.

The UI MQTT Broker must use WSS

The Gateway UI runs in a browser over HTTPS, so the UI MQTT Broker must be reachable over WSS (WebSocket Secure). Browsers cannot open raw MQTT connections on ports 1883 or 8883, and they block plain ws:// connections from HTTPS pages. Make sure the broker provides a WSS listener, commonly on port 8084 or 443.

If the UI MQTT Broker is not configured or not reachable, the Manage Agents page does not update by itself and shows outdated status until you reload the page. Communication between agents and the Gateway is not affected.

Step 1: Create the Agent

1. On the Manage Agents page, select Create agent.

2. Enter the agent details:

   Field	Required	Description
   Name	Yes	A unique, descriptive name, for example Warehouse-East-01.
   Group	Yes	The Access Group whose members can view and manage the agent.
   Description	No	The agent's location, purpose, or managed devices.
   Tags	No	Labels for filtering. Type a tag and press Enter to add it.

3. Select Create agent.

Create agent dialog

The agent appears in the list with the status Unknown. This is expected: the agent stays Unknown until its Agent Edgeware is installed, configured, and connected (Step 4).

New agent in the agent list

Step 2: Configure the Agent

Select an agent in the list to open it. The agent opens next to a collapsible agent list, so you can switch between agents. Use Group by group in that list to group agents by Access Group.

Agent details

The agent header provides:

Button	Description
Edit	Edits the settings on the Overview tab.
Power on / Power off	Sets the agent's desired state. A connected agent starts or stops to match it. You must power off an agent before you can delete it.
Turn monitoring on / Turn monitoring off	Turns monitoring on or off for the agent.
Export configuration	Downloads the agent configuration as a JSON file for the Agent Edgeware. See Step 4.
Delete agent	Deletes the agent. Available only while the agent is powered off.

The agent has five tabs: Overview (settings), Processes, Endpoints, Agent Logs, and Process Logs.

Overview

On the Overview tab, select Edit to change the settings, then save your changes. Select Cancel to discard them.

General Information

Shows the agent's Status, Power, and Monitoring state, the reported Version, and whether the agent is currently connected and running. In edit mode, you can change the Name, Group, Description, and Tags.

General Settings

Select the information icon next to a setting in the Gateway to see a short description.

Setting	Description
Auto Start	Starts the agent automatically when the edge host starts. Recommended for production.
Forward Log Exceptions	Forwards unrecognized log entries to the Gateway. Forwarded entries are marked in the Error column of the logs. See Log Exceptions.
Log Buffer Size	Number of log entries the agent collects before it sends them to the Gateway in one batch. Higher values reduce the number of transmissions but use more memory.
Live Log Buffer Size	Number of live log events the agent caches before pushing them to the Gateway.
Status Heartbeat Interval (ms)	Time between two status messages from the agent. Lower values update the status faster but use more bandwidth.
Log Batch Send Interval (ms)	How often the agent sends collected log entries.
Live Log Push Interval (ms)	How often the agent pushes live log events while a live log is open.
Live Log Inactivity Timeout (s)	How long a live log stays open without activity before it stops.
Last changed	Date and time of the last configuration change (read-only).

Connection & Logging

Connection & Logging

Setting	Description
Agent Connection Mode	How the agent and the Gateway exchange status, logs, and configuration: Mqtt or ServerToAgent. The mode also determines which section follows: MQTT Configuration or REST Server to Agent. See Connection Modes.
Log To Database	Stores the agent's logs in a local database on the edge host. Useful for local troubleshooting and offline operation.
Log To File	Writes the agent's logs to local log files on the edge host.
Auto-Confirm Update	Applies configuration changes on the agent automatically, without a separate confirmation.
Host	The Gateway server URL for agent communication.
Log Display Level	The minimum log level for the agent. Entries of the selected level and more severe levels are listed; less severe entries are ignored. For example, INFO lists INFO, WARNING, ERROR, and SEVERE. Levels from most to least severe: SEVERE, ERROR, WARNING, INFO, CONFIG, FINE, FINER, FINEST.
Database Log Retention Days	Number of days logs are kept in the local database before they are deleted.
Monitoring Worker Sleep (ms)	Delay between two monitoring cycles. Lower values detect changes faster but use more CPU.
Monitoring Payload Limit (Bytes)	Maximum size of one batch of log or monitoring data sent to the Gateway.

AgentToServer is not available yet

The connection mode list also contains AgentToServer, but this mode is not yet enabled for R-COM Gateway. Use Mqtt or ServerToAgent.

MQTT Configuration

Shown when the connection mode is Mqtt.

Host, Port, and Root Topic come from the shared Agent MQTT Broker and are read-only here. All other fields can be overridden for this agent. Overrides do not affect the shared configuration or other agents.

Setting	Can be overridden	Description	Example
Host	No	Broker hostname or IP address.	mqtt.example.com
Port	No	Broker port.	8883
Root Topic	No	Topic prefix for all agent topics.	site-a/agents
Username	Yes	Username for broker authentication.	agent-user
Password	Yes	Password for broker authentication.	********
Use TLS	Yes	Encrypts the broker connection with TLS.	Enabled
Accept All Certificates	Yes	Accepts any server certificate, including self-signed certificates. Use for testing only.	Disabled
Keep-alive interval (seconds)	Yes	How often the agent sends keep-alive messages to the broker.	60
Reconnect interval (seconds)	Yes	How long the agent waits before reconnecting after a disconnect.	10
TLS Client Certificate Path	Yes	Path to the client certificate on the edge host, for mutual TLS.	/certs/mqtt-client.pfx
TLS Client Certificate Password	Yes	Password of the client certificate file, if any.	********
TLS CA Certificate Path	Yes	Path to the CA certificate used to verify the broker's certificate.	/certs/ca.crt

REST Server to Agent

Shown when the connection mode is ServerToAgent. The Gateway calls the agent's REST API to retrieve its status and to send configuration and commands.

Setting	Description	Example
API URL	Base URL of the agent's REST API. The Gateway must be able to reach this URL. This is the same setting as Agent API URL on the Endpoints tab.	http://edge-host-01:8080
Authentication Type	Authentication method for the agent's API.	None
User	API user, required only if authentication is enabled.	–
Password	API password, required only if authentication is enabled.	–
Agent check-in interval (ms)	How often the Gateway calls the agent to retrieve its status.	150000

Step 3: Add Processes

A process runs one version of a process template on the agent. One agent can run several processes, and one template can be used by many agents.

1. Open the agent and select the Processes tab.

2. Select Add process.

   

   Processes tab

3. Enter a Process name.

4. Select the Process template and the Template version.

5. Turn on Auto start with the agent if the process should start whenever the agent starts.

6. Select Create.

   

   Add process dialog

The Processes tab lists the agent's processes with their Template, Version, Status, and Running since values.

Process actions

Action	Description
Switch	Starts or stops the process.
Logs	Opens the process's logs.
Open	Opens the process details. See Manage a Process.
Edit	Changes the process name, template, version, auto start, and variables.
Delete	Removes the process from the agent.

Manage a Process

Open a process to view and change its details.

Manage Process page

The page shows the process's template and version (select Open to open the template), the agent, Running since, Last changed, and Changed by. The header provides Refresh, Edit, and Start or Stop, depending on whether the process is running.

The page has three tabs:

• Variables – The template's variables with their type and value for this process. To change them, select Edit, enter the values, and select Update. Values set here apply to this process only and do not change the template.

• Components – The template's components as they run on the agent, with their type and last reported status. Select Refresh components to retrieve the latest status, or turn on Show live log to follow the components' log output as it happens.

  

  Process components

• Log – The process's log entries. See Process Logs.

  Screenshot placeholder

  Replace with: the Log tab of a process showing the filters (log levels, message, component, from/to) with translated labels and some log entries.

  File name: docs/agents/img/agent_process_log_tab.png

Endpoints

The Endpoints tab lists the HTTP routes the agent serves under its Agent API URL.

Endpoints tab

Column	Description
Endpoint name	Name of the route, for example getStatus.
Method	HTTP method of the route, for example GET.
Agent authentication	Shows whether the route requires the agent's API authentication.
Full URL	The complete URL of the route: the Agent API URL followed by the endpoint name.

The Agent API URL is the same setting as API URL in REST Server to Agent. Select Edit to change it; a change on either tab applies to both.

Step 4: Connect the Agent Edgeware

Creating the agent in the Gateway does not install anything on the edge host. To connect the agent:

1. Install the Agent Edgeware on the edge host. See Edgeware Installation.

2. Export the configuration. In the agent header, select Export configuration. The Gateway downloads a JSON file with the agent's connection settings, processes, and parameters.

   

   Export configuration

3. Apply the configuration to the Agent Edgeware, using one of these options:

   • Agent API (Swagger): Open http://<edge-host>:<port>/swagger/index.html, where <port> is the agent's API port (for Docker installations, the RCOM_HOST_PORT value). Open the setConfig operation, replace the example JSON with the exported file's content, and select Execute.
   • Configuration file (Windows): Open C:\ProgramData\RCOM\Gateway Agent\AgentConfig, replace the content of the configuration file with the exported JSON, and save it.

4. Start the Agent Edgeware, if it is not already running, and make sure the agent is powered on in the Gateway (Power on in the agent header).

5. Check the status in the Gateway. On the Manage Agents page, the agent's status changes from Unknown to Starting and then to Running. While the agent downloads its configuration or components, it can show Updating. In ServerToAgent mode, the change can take up to one Agent check-in interval.

If Auto Start is enabled, the agent starts again automatically after the edge host restarts.

Logs

Each agent has two log views:

• Agent Logs – Activity of the agent itself, such as status changes, power and monitoring changes, configuration updates, and connection events.
• Process Logs – Activity of the agent's processes and their components, such as device reads and web requests.

For filters, downloads, and log exceptions, see Log Monitoring.

Troubleshooting

Problem	What to check
The status stays Unknown.	Check that the Agent Edgeware is running on the edge host and that the exported configuration was applied. Check the network access required by the connection mode: for Mqtt, the edge host must reach the Agent MQTT Broker; for ServerToAgent, the Gateway must reach the agent's API URL. On the edge host, check the local logs (Log To File or Log To Database) or, for Docker installations, docker compose logs.
The Manage Agents page does not show status changes until you reload it.	The UI MQTT Broker is not configured or not reachable over WSS. See UI MQTT Broker.
The status is Warning or Error.	Open Agent Logs and filter by WARNING, ERROR, and SEVERE.
The status is UpdateRequired.	The configuration was changed in the Gateway but not yet applied on the agent. A configuration push or an agent restart is needed. To apply changes automatically, enable Auto-Confirm Update.
The agent cannot be deleted.	Power the agent off first.

Related Articles

• R-COM Agents: Introduction
• Process Templates

• Edgeware Installation

• Log Monitoring