This is the documentation for the development version. There are no official binaries for it; build it from the source code in git. Download links on these pages work only after the release. For the current release, see version 7.0.

AI Assistant How-to Guides

This page covers common tasks for the NetXMS AI assistant.

For initial setup, see Getting Started with the AI Assistant. For architecture and concepts, see AI Assistant Concepts. For configuration reference, see AI Assistant Reference.

How to Configure LLM Providers

Providers are configured in netxmsd.conf under [AI/Provider/<name>] sections. Each provider has a unique name and maps to one or more slots.

OpenAI-compatible Provider

Works with the OpenAI API and any compatible service (Azure OpenAI, vLLM, LiteLLM, etc.):

[AI/Provider/openai]
Type = openai
URL = https://api.openai.com/v1/chat/completions
Model = gpt-4o
Token = sk-your-api-key-here
Timeout = 180
Slots = default,interactive

Anthropic Provider

Connects to the Anthropic Messages API:

[AI/Provider/anthropic]
Type = anthropic
URL = https://api.anthropic.com/v1/messages
Model = claude-sonnet-4-20250514
Token = sk-ant-your-key-here
Slots = default,analytical

Ollama Provider (Local)

Runs models locally using Ollama. No API key is required for local deployments:

[AI/Provider/local-llama]
Type = ollama
URL = http://127.0.0.1:11434/api/chat
Model = llama3.2
ContextSize = 32768
Slots = fast

How to Use Provider Slots

Slots allow you to route different types of AI requests to different providers. For example, you can use a fast local model for quick responses and a more capable cloud model for deep analysis.

Assign slots to providers using the Slots parameter (comma-separated list):

[AI/Provider/gpt4]
Type = openai
Model = gpt-4o
Token = sk-your-key
Slots = default,analytical

[AI/Provider/local-fast]
Type = ollama
Model = mistral
Slots = fast

A provider becomes the default when its name matches DefaultProvider in the [AI] section or when its slot list contains default; model-dependent AI features are unavailable when no default provider can be resolved. The server’s built-in tools and script-defined tools remain available through the MCP endpoint without a provider, except the tools that serve only the AI assistant (see Tools Through MCP). See Provider Slots Reference for the complete list of available slot names.

You can optionally set the global default provider explicitly:

[AI]
DefaultProvider = gpt4

How to Set Up AI Incident Analysis

The AI assistant can automatically analyze incidents when they are created from event processing rules.

  1. Open Configuration  Event Processing Policy.

  2. Edit the rule that creates incidents.

  3. On the rule’s Incident property page, make sure Create incident on alarm creation is checked — the AI analysis options remain visible but disabled until it is.

  4. Enable Perform AI-based incident analysis to run automatic incident analysis by the AI assistant.

  5. Optionally, enable Automatically assign incident to suggested owner to let the AI assistant suggest and assign the incident to the most appropriate user based on past data and object responsibility. This option is part of the AI analysis group and requires Perform AI-based incident analysis to be enabled.

  6. Select the analysis depth:

    • Quick — fast, high-level summary.

    • Standard — balanced analysis with root cause suggestions.

    • Deep — deep analysis including topology context, event correlation, and historical incidents.

  7. Optionally, enter a custom AI prompt to guide the analysis (e.g., "Focus on network connectivity issues" or "Check for recurring patterns over the last 7 days").

To have the AI assistant comment on alarms created by a rule, enable Add AI assistant’s comment on alarm creation on the rule’s Alarm property page. The comment is added to the alarm, not the incident.

How to Analyze Events with AI Instructions

An event processing rule can send each matching event to the AI assistant with instructions, for example to analyze the event and notify someone with the result. This works for any event and does not need an alarm or an incident.

  1. Open Configuration  Event Processing Policy.

  2. Create a rule, or edit an existing one, and select the events to analyze on its Events filter page. Use the source and severity filters to keep the number of matching events low: each matching event starts a separate AI request.

  3. On the rule’s AI Instructions page, enter the instructions. Event macros are expanded, and the assistant also receives the event data and the source object. Name the notification channel and the recipient, because the result is only delivered through the assistant’s actions:

    Event %N on %n: %m
    Find the likely cause using recent events, alarms and collected data for this node.
    Send a short summary through the notification channel "Email" to [email protected]
    with the subject "AI analysis: %n".
  4. Save the event processing policy.

The assistant’s reply itself is not stored. To see it while testing, set the debug level for the ai.assistant tag to 4 or higher and check the server log. For the details, see AI Instructions in the rule reference.

How to Create Background AI Tasks

Background tasks allow the AI assistant to work autonomously without user interaction. A task can run once or several times, preserving state between runs.

From the chat interface:

Ask the AI assistant to create a task:

Create a background task to check the health of all core routers
every hour and notify me if any anomalies are found.

The AI assistant will use the register-ai-task tool to schedule the task.

From the management client:

  1. Open the Configuration perspective.

  2. Navigate to AI Tasks.

  3. Click New…​ to open the Create AI Task dialog.

  4. Enter a description and the prompt (instructions for the AI assistant).

Tasks appear in the task manager with their current state: Scheduled, Running, Completed, or Failed. The Explanation column shows a summary of what the task accomplished or why it failed. A task runs with the access rights of its owner; its execution fails when the owner account is disabled, deleted, or no longer has the Use AI assistant system access right.

How to Work with AI Messages

Background AI tasks communicate results through messages. Messages appear in the AI Messages view of the AI perspective.

There are three message types:

  • Informational — findings, reports, and status updates.

  • Alert — anomalies or warnings that require attention.

  • Approval Request — proposed actions that require user approval before execution.

To handle messages:

  1. Open the AI Messages view in the AI perspective.

  2. Select a message to view its content in the detail panel.

  3. For approval requests, click Approve or Reject.

Messages are automatically marked as read after 30 seconds. Informational and alert messages expire after 7 days by default; approval requests expire after 24 hours. API clients can list messages, mark them as read, and approve or reject requests through the AI message endpoints. Expired messages are cleaned up by the server.

How to Use the Command-Line Client

NetXMS provides nxai, a command-line interface for chatting with the AI assistant from a terminal. nxai is the nxshell command-line shell installed under a second name: started as nxai, it opens directly in AI assistant mode and exits when that mode is left.

nxai communicates with the server through the web API (/v1/login, /v1/ai/chat, etc.), so the server’s web API must be enabled and reachable. The --server value is treated as an https:// URL when no scheme is given; there is no separate port option — include a non-default port in the URL (e.g., https://netxms.local:8443).

Basic usage:

nxai --server netxms.example.com --user admin

With context binding:

# Bind to a specific node
nxai --server netxms.example.com --user admin --node web-server-01

# Bind to an incident
nxai --server netxms.example.com --user admin --incident 456

Non-interactive (one-shot) mode:

Pass the message as a command-line argument, or pipe it via stdin, to get a single response without starting an interactive session:

nxai --server netxms.example.com --user admin "list critical alarms"

echo "list critical alarms" | nxai --server netxms.example.com --user admin

Plain text output is enabled automatically when stdout is not a terminal. When stdin is not a terminal and the AI assistant asks a question, the question is automatically declined and a warning is printed.

Connection parameters can also be set via environment variables: NETXMS_SERVER, NETXMS_USER, NETXMS_PASSWORD.

Slash commands available during a chat session:

Command Description

/help

Show available commands

/exit

Exit the chat (alias: /quit)

/clear

Clear chat history

/incident <id>

Set incident context; without an argument, clears the current incident context

/status

Show current session information

Other shell commands are also available with the / prefix — for example, /cd <path> changes the current object, which is the conversation context, and /console show pollers runs a server debug console command.

Keyboard shortcuts:

Shortcut Description

Ctrl+C

Cancel the current request or clear the input line

Ctrl+D

Exit the chat

Up / Down

Navigate command history

Tab

Complete command names and object names

How to Connect an MCP Client

An external AI application that supports the Model Context Protocol (MCP) can use the NetXMS tools through the server’s MCP endpoint. The MCP client uses its own model; the server does not need an LLM provider for this.

  1. Load the mcp module in netxmsd.conf (before any named section). Load the aitools module as well to get the operational tool set (objects, alarms, data collection, logs, and so on); without it, the endpoint offers only the server’s built-in and script-defined tools.

    Module=mcp
    Module=aitools
  2. Make the web API listener reachable from the MCP client. The endpoint uses the listener configured in the [WEBAPI] section, whose HTTP listener accepts connections on the loopback interface only by default. For a client on another host, enable the TLS listener, or put a TLS-offloading reverse proxy in front of the HTTP listener; change Address only if that proxy runs on another host (see Enabling the API).

  3. Restart the server.

  4. Create a user account for the MCP client, or select an existing one, and grant it the Use AI assistant system access right. Tools run with the access rights of this account, so give it access only to the objects the client should see and change.

  5. Issue a persistent authentication token for this account (see Authentication Tokens), and copy the token value.

  6. Check the endpoint with curl:

    curl http://127.0.0.1:8000/mcp \
      -H "Authorization: Bearer <token>" \
      -H "Content-Type: application/json" \
      -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}'

    The response lists the available tools. A 401 response means the token is missing, invalid, or expired; a 403 response means the account is disabled or does not have the Use AI assistant right.

  7. Add the server to the MCP client configuration as a remote server with the streamable HTTP transport, and pass the token in the Authorization header. Field names differ between clients; many use a layout like this:

    {
      "mcpServers": {
        "netxms": {
          "type": "http",
          "url": "https://netxms.example.com:8443/mcp",
          "headers": {
            "Authorization": "Bearer <token>"
          }
        }
      }
    }

MCP clients do not receive tools and skills disabled in Configuration  AI Skills & Tools (see How to Disable AI Skills and Tools). For the protocol details, see MCP Endpoint.

How to Disable AI Skills and Tools

The server keeps one list of disabled skills and tools. It applies to everything that uses the AI assistant: chats, background AI tasks, workers, AI operators, the QueryAIAssistant() NXSL function, and MCP clients.

Viewing the list requires the Use AI assistant or the Manage AI skills and tools system access right; changing it requires Manage AI skills and tools.

  1. Open Configuration  AI Skills & Tools. The view lists the skills and the server-wide tools of the loaded server modules, with their type, name, description, and status.

  2. Select one or more rows and click Disable or Enable on the toolbar or in the context menu.

The change takes effect immediately; a server restart is not needed.

The list shows skills and server-wide tools only. Tools that come with a skill are not listed separately. To disable such a tool, or a skill or tool of a module that is not loaded, use Add custom entry…​: enter the exact name (names are case-sensitive), then select Skill or Tool. The entry is shown as disabled with no description. To enable it again, select it and click Remove custom entry.

What a disabled item affects:

  • A disabled tool fails when called, also in a conversation, task, or worker that is already running. A chat that was started before the tool was disabled can still offer the tool to the language model, but the call is rejected. Disabled server-wide tools are left out when a chat starts, and disabled skill tools are left out when a skill is loaded.

  • A disabled skill is not listed to the AI assistant and cannot be loaded or run in a worker. A conversation that already loaded the skill keeps its instructions and tools; to block those tools, disable them by name with Add custom entry…​.

  • After enabling a tool that was left out when a chat started, clear the chat with Clear chat or start a new chat to make the tool available. A tool that comes with a skill also becomes available when the skill is loaded again. A background AI task picks up the current list at each run.

  • MCP clients get the current list with each tools/list and prompts/list request; the server does not notify connected clients of the change.

  • Tools that run on an agent are called through the execute-agent-tool tool. Disabling the name of an agent-side tool does not block it; disable execute-agent-tool instead.

  • Disabling a script-defined nxsl-* tool removes it from the AI assistant only; the script itself can still run from other places.

How to Check Context Usage

The chat view in the management client shows how much of the model’s context window the chat takes up, as a gauge and a percentage. Hover over the percentage to see the token counts. The value comes from the most recent request to the model, and the percentage changes color at 75% and again at 90%. If the window size of the model is unknown, only the token count is shown; the show ai providers server console command shows the detected size and its source, and the ContextSize provider parameter sets it explicitly.

Chat history is not shortened automatically, so when usage gets close to the limit, use the Clear chat action to start over.

How to Export a Conversation

In the management client, use the Export conversation…​ action in the chat view’s toolbar or view menu (Ctrl+Shift+E). The conversation is saved as a Markdown file containing the sender, timestamp, and text of each message.