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; the AI subsystem fails to initialize only when no default provider can be resolved. 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 Create Background AI Tasks

Background tasks allow the AI assistant to work autonomously without user interaction. Tasks can run once or iterate over multiple executions, 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 function 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 tool of the Tools 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 tool in the Tools 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. 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 a Python application (Python 3.9 or later) included in the NetXMS source tree under src/client/nxai; install it with pip:

pip install /path/to/netxms/src/client/nxai

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; a non-default port can be included in the URL (e.g., https://netxms.local:8443) or given with --port.

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

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

/quit

Exit the chat (aliases: /exit, /q)

/clear

Clear chat history

/object <name>

Set object context for the conversation

/incident <id>

Set incident context

/status

Show current session information

Keyboard shortcuts:

Shortcut Description

Ctrl+C

Cancel the current request

Ctrl+D

Exit the chat

Up / Down

Navigate command history

Session tokens are saved in sessions.json for automatic reconnection, and command history is stored in history, both in $XDG_CONFIG_HOME/nxai if XDG_CONFIG_HOME is set, otherwise in ~/.config/nxai. See nxai Command-Line Reference for all options.

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.