AI Assistant Concepts

Features marked with EE badge require Enterprise Edition.

This page explains the architecture and key concepts behind the NetXMS AI assistant.

For setup instructions, see Getting Started with the AI Assistant. For task-oriented guides, see AI Assistant How-to Guides. For configuration reference, see AI Assistant Reference.

Architecture Overview

The AI subsystem consists of the following components:

LLM Providers connect the NetXMS server to language models. Each provider is configured with a model, API endpoint, and authentication credentials. Multiple providers can be active simultaneously.

Provider Slots route AI requests to appropriate providers. Different slots (e.g., default, fast, analytical) can point to different providers, allowing you to balance cost, speed, and capability.

Functions are the bridge between the AI assistant and NetXMS data. When the AI assistant needs to access live information (alarms, objects, metrics, logs), it calls registered functions that execute on the server and return results. Well over a hundred functions are available covering alarms, incidents, objects, data collection, logs, SNMP, event processing, and more.

Skills are domain-specific instruction sets that the AI assistant loads on demand. Each skill includes a specialized prompt and a set of related functions. Skills are loaded dynamically during a chat session when the AI assistant determines they are needed.

Background Tasks allow the AI assistant to work autonomously. Tasks can run once or iterate with a configurable delay, preserving state between executions through a memento mechanism.

AI Messages are the output channel for background tasks. Tasks can post informational findings, alerts, or approval requests that users review in the management client.

Skills

Skills extend the AI assistant with domain-specific knowledge and capabilities. Each skill includes a detailed prompt with instructions and reference data, plus a set of functions for data access.

Skills and functions are provided by server modules. The aitools module, available in the open-source edition, provides the skills listed below that carry no EE badge. The badged skills come from the aiext and aissh Enterprise Edition modules (see Enterprise Skills); additional skills can be provided by third-party modules. Load a module by adding Module=<name> to netxmsd.conf (before any named section).

Skill	Description
Incident Analysis	Root cause analysis, alarm correlation, incident history, topology context, and assignment recommendations.
Log Analysis	Search and correlate syslog, Windows events, SNMP traps, and NetXMS system events. Includes pattern detection and burst analysis.
Data Collection	Metric creation, threshold management, historical data analysis. Supports SNMP, agent, and script-based data origins.
Event Processing	Event template and processing policy management. Event flow analysis and action configuration.
Inventory	Hardware components, software packages, and network interface inventory. Integration with SNMP, WMI, and agent sources.
Maintenance	Maintenance mode scheduling and management. Alert suppression during maintenance windows.
Alarm Management	Alarm browsing and lifecycle operations: acknowledge, resolve, and terminate alarms.
Device Backup	Access to network device configuration backups collected by the server.
Dashboard Building	Creation and modification of dashboards and dashboard elements.
NXSL Scripting EE	Compile and execute NXSL scripts, run and browse script library scripts.
Asset Management EE	Track physical assets, manage properties, link assets to monitored objects, and audit change history.
File Management EE	Remote file operations on nodes with NetXMS agent: read, write, delete, rename, and integrity verification.
Network Topology EE	IP/MAC address location, peer discovery, route tracing, and access to ARP caches, routing tables, forwarding databases, LLDP/CDP neighbors, OSPF/VRRP/STP state, VLANs, and physical device layout.
Scheduler Management EE	Create and manage scheduled tasks for automated maintenance, script execution, and discovery operations.
Agent Operations EE	Host and agent control: reboot or shut down hosts, restart agents, start/stop/restart system services, list and execute agent actions.
Package Deployment EE	List packages, deploy packages to nodes, and monitor or cancel deployment jobs.
SSH Command Execution EE	Secure remote command execution on servers and network devices with intelligent command classification and approval workflow.

Skill

Description

Incident Analysis

Root cause analysis, alarm correlation, incident history, topology context, and assignment recommendations.

Log Analysis

Search and correlate syslog, Windows events, SNMP traps, and NetXMS system events. Includes pattern detection and burst analysis.

Data Collection

Metric creation, threshold management, historical data analysis. Supports SNMP, agent, and script-based data origins.

Event Processing

Event template and processing policy management. Event flow analysis and action configuration.

Inventory

Hardware components, software packages, and network interface inventory. Integration with SNMP, WMI, and agent sources.

Maintenance

Maintenance mode scheduling and management. Alert suppression during maintenance windows.

Alarm Management

Alarm browsing and lifecycle operations: acknowledge, resolve, and terminate alarms.

Device Backup

Access to network device configuration backups collected by the server.

Dashboard Building

Creation and modification of dashboards and dashboard elements.

NXSL Scripting EE

Compile and execute NXSL scripts, run and browse script library scripts.

Asset Management EE

Track physical assets, manage properties, link assets to monitored objects, and audit change history.

File Management EE

Remote file operations on nodes with NetXMS agent: read, write, delete, rename, and integrity verification.

Network Topology EE

IP/MAC address location, peer discovery, route tracing, and access to ARP caches, routing tables, forwarding databases, LLDP/CDP neighbors, OSPF/VRRP/STP state, VLANs, and physical device layout.

Scheduler Management EE

Create and manage scheduled tasks for automated maintenance, script execution, and discovery operations.

Agent Operations EE

Host and agent control: reboot or shut down hosts, restart agents, start/stop/restart system services, list and execute agent actions.

Package Deployment EE

List packages, deploy packages to nodes, and monitor or cancel deployment jobs.

SSH Command Execution EE

Secure remote command execution on servers and network devices with intelligent command classification and approval workflow.

The AI assistant loads skills automatically based on the conversation context. You can also request a specific skill explicitly:

Load the log analysis skill and search syslog for authentication
failures in the last 24 hours.

Enterprise Skills

The following skills are available exclusively in the NetXMS Enterprise Edition. They are loaded from the aiext and aissh server modules and require a valid Enterprise Edition license.

Load the modules in netxmsd.conf:

Module = aiext
Module = aissh

Modules are mandatory by default — without a valid Enterprise Edition license, a server with these modules listed will refuse to start. The aissh module also requires a database schema upgrade (nxdbmgr upgrade) after being added.

In addition to the skills below, the aiext module registers always-available functions for reading agent metrics and tables and listing processes on managed nodes.

NXSL Scripting

The NXSL scripting skill allows the AI assistant to compile and execute NXSL (NetXMS Scripting Language) scripts. It supports both ad-hoc script execution and running scripts from the server script library.

The AI assistant can:

Compile NXSL scripts to check for syntax errors before execution.
Execute arbitrary NXSL scripts on the server.
Run existing scripts from the script library.
Browse and inspect scripts stored in the library.

The skill has no write access to the script library — it cannot create, modify, or delete library scripts.

Asset Management

The asset management skill provides the AI assistant with the ability to track physical assets, manage their properties, and link them to monitored objects.

The AI assistant can:

List and search assets by name, serial number, MAC address, or any custom property.
View complete asset details and individual property values.
Set, update, and delete asset properties with schema validation.
Link and unlink assets to monitored objects (nodes, sensors, access points, mobile devices, chassis, and racks).
Inspect the asset attribute schema including data types, constraints, and enumeration values.
Review the full change log for compliance auditing.

File Management

The file management skill enables remote file operations on nodes that have the NetXMS agent installed.

The AI assistant can:

List directory contents on remote nodes.
Read text files (100 KB by default; larger reads up to 1 MB on request).
Write and overwrite text files (up to 1 MB).
Delete files and directories.
Create directories.
Get file metadata including MD5 and SHA256 checksums.
Rename files.

All operations are restricted to the RootFolder paths configured for the agent’s filemgr subagent and enforce user access rights.

Network Topology

The network topology skill provides access to the server’s network topology data.

The AI assistant can:

Find which device owns a specific IP or MAC address and where it connects to the network.
List all directly connected peers (neighbors) of a node.
Trace the full network path between any two nodes, showing every hop and intermediate device.
Read a node’s ARP cache, routing table, and MAC forwarding database (FDB).
Read LLDP/CDP neighbor tables, OSPF, VRRP, and STP state, and VLAN configuration.
Inspect the physical device layout (chassis, modules, port positions).

Most functions accept filters and result limits (500 entries by default, up to 5000).

Agent Operations

The agent operations skill gives the AI assistant control over hosts and agents — subject to the approval workflow:

Reboot or shut down monitored hosts.
Restart NetXMS agents.
Start, stop, and restart system services.
List and execute agent actions defined in agent configuration.

Package Deployment

The package deployment skill works with the server’s package manager:

List packages available on the server.
Deploy packages to nodes.
Monitor and cancel deployment jobs.

Scheduler Management

The scheduler management skill allows the AI assistant to create, modify, and monitor scheduled tasks.

Supported task types include:

Recurring tasks using cron-style schedule expressions (e.g., 0 2 * * * for daily at 2:00 AM).
One-time tasks with a specific execution time in ISO format, Unix timestamp, or relative notation (e.g., +30m).

SSH Command Execution

The SSH skill provides secure remote command execution on servers and network devices monitored by NetXMS. It features an intelligent command classification system that categorizes every command before execution.

Command classification:

Read-only — diagnostic and information-gathering commands that execute immediately without approval. This includes commands such as ps, df, show interfaces, display version, and most other read-only operations.
Write — commands that modify system configuration or state. These require explicit user approval before execution. Examples include service restarts, package management, file modifications, and configuration changes on network devices.
Dangerous — destructive commands that are always blocked, in any form. On Linux this includes every rm, rmdir, shred, dd, userdel, reboot, poweroff, and similar commands — not only catastrophic invocations; on network devices, commands such as erase startup-config or request system zeroize.
Unknown — commands that match no known pattern are treated as write commands and require approval.

Classification is platform-aware and applies device-specific patterns for Linux, Cisco IOS, Cisco NX-OS, Juniper JunOS, Huawei VRP, MikroTik RouterOS, and Extreme EXOS, with a generic fallback.

Execution modes:

Command channel mode — uses the SSH exec channel with full shell processing. Pipes, redirects, environment variables, and command chaining all work correctly.
Interactive mode — handles CLI interfaces with prompt detection, pagination control, and command echo removal.

The mode is selected by node capability, not by platform: the server probes SSH exec-channel support during configuration polls and uses interactive mode when the exec channel is unavailable. Interactive mode can also be forced with the skill’s prefer_interactive argument, which overrides the capability-based selection. Multi-line commands always use interactive mode (executed line by line) and fail if the node does not support an interactive channel.

Approval workflow:

When a write command requires approval, the workflow depends on the session type:

In an interactive chat session, the AI assistant asks the user for confirmation directly in the chat.
In a background task, the AI assistant creates an approval request that the user reviews in the AI Messages view of the AI perspective.

All SSH command executions are logged to an audit table with the timestamp, user, target node, command, classification, approval status, and result.

Function Calling

The AI assistant uses function calling to interact with the NetXMS server in real time. When it determines that it needs live data or wants to perform an action, it invokes one or more registered functions. The results are fed back to the LLM for interpretation. In the management client, function calls appear as progress indicators in the chat, showing what data the AI assistant is accessing.

Approval Workflow

For potentially impactful actions, the AI assistant can request user approval before proceeding. This applies to both interactive chat sessions and background tasks.

In interactive chat, the AI assistant presents confirmation dialogs with Approve/Reject, Yes/No, or Confirm/Cancel buttons depending on the context. It can also ask multiple-choice questions, which the user answers by selecting one of the offered options. Confirmation requests that are not answered time out after 300 seconds.

In background tasks, the AI assistant sends approval request messages to designated users. The approval request includes a description of the proposed action and spawns a follow-up task if approved.

Background Task Execution Model

Background AI tasks can run multiple iterations, preserving state between executions so the assistant can track progress and compare findings over time.

Object AI Data

AI tasks can store custom key-value data on NetXMS objects using the object AI data storage. This allows tasks to persist findings, baselines, and analysis results directly on the objects they relate to.

For example, a background task monitoring router health could store a performance baseline on each router object and compare against it in subsequent executions.

AI Operators

AI operators are persistent, named AI assistant instances managed in the Configuration perspective under AI Operators. Each operator carries its own model slot setting, so it can target any configured provider slot, and operator queries run on the dedicated AIOperator thread pool. They can be retrieved from NXSL scripts with GetAIOperator() and GetAIOperators() to run AI queries as part of server automation. Debug output for operators is available under the ai.operator debug tag.

NXSL Integration

Four NXSL functions are available for integrating AI capabilities into scripts:

QueryAIAssistant(prompt, context): Sends a prompt to the AI assistant synchronously and returns the response as a string. The optional context parameter accepts a NetXMS object (e.g., a Node) that provides additional context for the query. Returns NULL on failure.
RegisterAITask(description, prompt): Registers a background AI task for asynchronous execution. Returns an integer task ID that can be used for tracking. Requires the Manage AI tasks system access right; returns null if the caller does not have it.
GetAIOperator(id): Returns the AI operator with the given numeric ID, or null if not found. Requires the Manage AI operators system access right.
GetAIOperators(): Returns an array of all configured AI operators. Requires the Manage AI operators system access right; returns an empty array if the caller does not have it.