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
In the current implementation, Temperature and TopP are parsed as integers — fractional values such as 0.7 are truncated to 0. Leave these parameters unset to use the provider defaults.

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.

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. 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 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

/quit

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

/clear

Clear chat history

/object <name>

Set object context for the conversation; without an argument, clears the current object context

/incident <id>

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

/status

Show current session information

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 slash commands

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.