AI Assistant Reference
| Features marked with EE badge require Enterprise Edition. |
This page provides configuration reference for 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 architecture and concepts, see AI Assistant Concepts.
Server Configuration
Provider and global AI settings are placed in netxmsd.conf.
Runtime limits are set through server configuration variables (see Server Configuration Variables).
Global Settings
The [AI] section supports the following parameters:
| Parameter | Default | Description |
|---|---|---|
|
(auto) |
Name of the default provider.
If not set, the first provider with the |
|
|
Enable or disable the prompt injection guard. |
Provider Settings
Each provider is configured in a [AI/Provider/<name>] section.
| Parameter | Type | Default | Description |
|---|---|---|---|
|
String |
|
Provider type: |
|
String |
(varies) |
API endpoint URL.
Defaults: |
|
String |
(varies) |
Model name.
Defaults: |
|
String |
(empty) |
API authentication token.
Sent as a |
|
Number |
-1 |
Sampling temperature. Set to -1 to use the provider default. |
|
Number |
-1 |
Nucleus sampling parameter. Set to -1 to use the provider default. Values above 1 are clamped to 1.0. |
|
Boolean |
|
Verify the provider’s TLS certificate. |
|
Integer |
(auto) |
Context window size of the model, in tokens.
When not set, the server reads it from the provider API for the configured model. The OpenAI API does not report it, but many OpenAI-compatible servers do.
If no size is available, chat context usage is shown as a token count only.
For |
|
Integer |
32768 |
Maximum response size in tokens ( |
|
Integer |
180 |
HTTP request timeout in seconds. |
|
String |
|
Comma-separated list of slots this provider serves (e.g., |
Provider Slots
Slots route different types of AI requests to appropriate providers.
Assign one or more slots to each provider using the Slots parameter.
| Slot | Description |
|---|---|
|
General-purpose slot used when no specific slot is requested.
A provider becomes the default when its name matches |
|
Used for interactive chat sessions with users. |
|
Used for background AI task execution. |
|
Used for deep analysis tasks such as incident investigation. |
|
Used by workers started with the |
|
Used for quick operations where low latency is preferred over capability (e.g., prompt injection guard fallback). |
|
Used by the prompt injection guard.
If not defined, the |
A request to a slot with no assigned provider falls back to the default provider (except the prompt injection guard, which falls back to the fast slot as noted above).
Configuration Examples
Single cloud provider:
[AI/Provider/openai]
Type = openai
URL = https://api.openai.com/v1/chat/completions
Model = gpt-4o
Token = sk-your-api-key
Slots = default
Multi-provider setup with slots:
[AI/Provider/claude]
Type = anthropic
Model = claude-sonnet-4-20250514
Token = sk-ant-your-key
Slots = default,analytical
[AI/Provider/ollama-fast]
Type = ollama
Model = mistral
Slots = fast
[AI]
DefaultProvider = claude
Local-only deployment with Ollama:
[AI/Provider/local]
Type = ollama
URL = http://127.0.0.1:11434/api/chat
Model = llama3.2
ContextSize = 32768
Slots = default
Server Configuration Variables
The following server configuration variables (stored in the database, changed at runtime from the management client) control the AI subsystem:
| Variable | Default | Description |
|---|---|---|
|
30 |
Number of steps (LLM round trips with tool calls) in an interactive chat request after which the user is asked whether to continue.
Continuing grants a fresh step budget, so this is not a hard cap.
Changes take effect without server restart.
The database upgrade renames the former |
|
64 |
Maximum number of steps (LLM round trips with tool calls) per request in a non-interactive chat (AI task runs, AI operator cycles, workers, event processing, incident analysis).
Changes take effect without server restart.
The database upgrade renames the former |
|
16384 |
Maximum total size (bytes) of environment memory entries placed into AI assistant prompts. Entries beyond this size are available to the model only on request. |
|
8192 |
Maximum total size (bytes) of per-user memory entries placed into AI assistant prompts. |
|
8192 |
Maximum total size (bytes) of per-object memory entries placed into AI assistant prompts. |
|
4 |
Maximum number of workers a single |
|
600 |
Maximum time (seconds) to wait for the workers of a single |
|
1 |
Enable the AI operator subsystem (global switch for all operator instances). |
|
3 |
Number of consecutive execution failures after which an AI operator instance is disabled automatically. |
|
60 |
Minimum time (seconds) between an AI operator cycle and the next cycle started by a standing check with the wake action. Interrupts arriving sooner are queued until it elapses. |
|
10 |
Maximum execution time (seconds) of a single run of an AI operator standing check script. |
|
5 |
Number of consecutive script errors after which a standing check is disabled automatically. |
|
32 |
Maximum number of standing checks per AI operator instance. |
|
20 |
Number of standing instruction history records kept per AI operator instance. |
|
8192 |
Maximum size (bytes of UTF-8 text) of AI operator standing instructions; longer text, written by the operator or by an administrator, is truncated at a character boundary (0 for no limit). |
Expired AI messages are cleaned up at the interval given by AI.MessageCleanupInterval (default: 60 minutes).
This variable is read directly at runtime and is not visible in the Server Configuration view.
Background AI tasks run in the AI-TASKS thread pool, sized by the ThreadPool.AITasks.BaseSize (default: 4) and ThreadPool.AITasks.MaxSize (default: 16) server configuration variables.
AI operators run in the dedicated AI-OPERATOR thread pool, sized by ThreadPool.AIOperator.BaseSize (default: 4) and ThreadPool.AIOperator.MaxSize (default: 16).
Workers run in the AI-WORKERS thread pool, sized by ThreadPool.AIWorkers.BaseSize (default: 4) and ThreadPool.AIWorkers.MaxSize (default: 16).
Changes to the thread pool variables take effect after server restart.
MCP Endpoint
The mcp server module (Module=mcp in netxmsd.conf) adds the Model Context Protocol endpoint /mcp to the server’s web API listener.
Address, port, and TLS come from the [WEBAPI] section (see Enabling the API); the module has no settings of its own and does not need the webapi module.
With the default listener settings, the endpoint URL is http://127.0.0.1:8000/mcp.
For the setup procedure, see How to Connect an MCP Client.
Transport
The endpoint implements the stateless variant of the streamable HTTP transport, protocol revision 2025-06-18:
-
Each request is an HTTP
POSTwith one JSON-RPC 2.0 message andContent-Type: application/json; other content types are rejected with 415. -
Each response with a body is a single
application/jsondocument. The endpoint does not use server-sent events;GETand other methods return 405. -
No session is created, and no
Mcp-Session-Idheader is used. -
Batch requests (a JSON array) are rejected with 400 and JSON-RPC error
-32600. -
Notifications and JSON-RPC responses sent by the client are accepted with 202 and no body.
| Method | Description |
|---|---|
|
Returns the protocol revision, the server name and version, and the |
|
Returns an empty result. |
|
Lists the available tools with their input schemas and annotations. |
|
Calls a tool with the given |
|
Lists the enabled skills as prompts (name and description). |
|
Returns a skill’s prompt as a single user message. |
Other methods return JSON-RPC error -32601.
Authentication and Access Control
Every request must carry a web API authentication token in the Authorization: Bearer <token> header.
Use a persistent token (see Authentication Tokens); a token from /v1/login also works, but expires at the latest after WebAPI.AuthTokenMaxLifetime (24 hours by default).
Single-use tokens are rejected.
| HTTP status | Cause |
|---|---|
401 |
The token is missing, invalid, or expired. Deleting a user revokes all of the user’s tokens, so requests of a deleted user get 401. |
403 |
The user account is disabled, or the user does not have the Use AI assistant system access right. |
Tools run with the access rights of the user the token belongs to.
tools/list and prompts/list are not filtered by these rights: every user gets the same lists, and access checks apply when a tool runs.
Calls that reach a known, enabled tool are recorded in the audit log under the AI subsystem, with the tool name and a success flag.
A call is recorded as failed only when the tool’s result text starts with Error:; a tool that reports a failure in other words, such as Access denied, is recorded as successful.
Requests rejected before that, including calls to unknown or disabled tools, are not recorded.
Tools and Prompts
tools/list contains the global tools and the tools of all enabled skills; an MCP client does not need to load a skill before it calls one of the skill’s tools.
Tools that serve only the AI assistant are not listed (see Tools Through MCP).
Tools and skills disabled in the AI Skills & Tools view of the Configuration perspective are left out of tools/list and prompts/list, and a call to a disabled tool fails as a call to an unknown tool.
A call to an unknown tool returns JSON-RPC error -32602.
The result of tools/call carries the tool’s result text.
isError is true only when that text starts with Error:, so some failures, such as Access denied, arrive with isError: false.
Use the mcp debug tag to trace the endpoint: level 5 logs tool calls, level 6 logs every request method.
nxai Command-Line Reference
nxai [options] [message]
nxai is nxshell started under another name and accepts the same options, except -c.
Connection options:
| Option | Description |
|---|---|
|
Server hostname or URL (e.g., |
|
Username for authentication. |
|
Password.
Prefer using the |
|
Disable SSL certificate verification. |
|
Do not save the session token for reuse. |
|
Clear saved session token and exit. |
Context options (mutually exclusive):
| Option | Description |
|---|---|
|
Bind the chat session to an object by name. |
|
Bind the chat session to an object by ID. |
|
Bind the chat session to an incident. |
Display options:
| Option | Description |
|---|---|
|
Force plain text output (no colors or formatting). |
General options:
| Option | Description |
|---|---|
|
Show usage information and exit. |
|
Show version information and exit. |
Environment variables:
| Variable | Description |
|---|---|
|
Default server hostname. |
|
Default username. |
|
Password (avoids passing on command line). |
Session tokens are saved to sessions.json in the nxshell configuration directory for automatic reconnection: $XDG_CONFIG_HOME/nxshell if XDG_CONFIG_HOME is set, otherwise ~/.config/nxshell (%APPDATA%\nxshell on Windows).
Saved sessions expire after 4 hours.
Command history is stored in the history file in the same directory.
Use --clear-session to remove saved tokens.
Debug Tags
The following debug tags can be used for troubleshooting the AI subsystem:
| Tag | Description |
|---|---|
|
General AI assistant operations (chat, tool calls, incident analysis). |
|
Low-level message assembly traces (debug level 8), for both interactive and background chats. |
|
LLM provider base class (HTTP requests, response parsing). |
|
OpenAI-compatible provider operations. |
|
Anthropic provider operations. |
|
Ollama provider operations. |
|
Mistral provider operations. |
|
AI memory store (environment, per-user, and per-object entries). |
|
AI operator management and execution. |
|
Skill loading and management. |
|
Background task scheduling and execution. |
|
AI message lifecycle and cleanup. |
|
Anomaly detection profile generation. |
|
AI tools (server and agent side). |
|
Workers started by the |
|
Web API endpoints for AI chat sessions, memory, and operators. |
|
MCP endpoint requests and tool calls (see MCP Endpoint). |
|
Chat bot sessions, user mapping, and commands (see Chat Bots). |
|
Operations of the |
|
File management skill operations. |
|
SSH command execution skill operations. |
On the agent side, the ai.tools debug tag in nxagentd covers AI tools provided by agent subagents, which the AI assistant discovers and calls with the get-node-ai-tools and execute-agent-tool tools.
The aifileops subagent, which provides file search and editing tools, logs under the aifileops tag; it does not start without at least one RootFolder entry in its [aifileops] configuration section (same path[;ro][;nofollow] format as the filemgr subagent), and its file-modifying tools are available only to master servers.
The file management skill of the aiext module does not use aifileops: its requests are served by the agent’s filemgr subagent.
Enable debug output by adding the DebugTags parameter to the global section of netxmsd.conf (before any named section):
DebugTags = ai.*:6