> For the complete documentation index, see [llms.txt](https://docs.flopsar.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.flopsar.com/7/administrator-guide/ai-assistant.md). # AI Assistant The AI Assistant is an optional, administrator-controlled feature. Analysts use it from the Workstation to turn recorded JVM performance data into a structured diagnosis. The model never talks to the database or to agents on its own: the **Flopsar server** builds every prompt, calls the model, and — when you allow it — executes tools **as the asking user**. Configure it from **Administration → AI Assistant**. This page is the reference for every control on that screen: what it does, the default, and the allowed range. Data that can leave your infrastructure, least-privilege combinations, sealed secrets, TLS risks, `llm.log`, and the audit actions are on the Security page: [AI Assistant](/7/security/ai-assistant.md). {% hint style="info" %} **Screenshot placeholder:** Workstation → Administration → AI Assistant. Cards in order: Enable assistant, Token usage, Provider, Behaviour, Data access, Proxy, TLS. Header buttons: Test Connection, Save. {% endhint %} Analysts open the chat from **Analytics → AI Assistant**, from **AI Analysis** on a Data Analysis result, or from the **AI Assistant** tab on a method execution tree or aggregated call tree. That workflow is described in the [user guide](/7/user-guide/observing-and-diagnosing/ai-assistant.md). ## Who can open this page | Permission | Effect | | -------------------- | --------------------------------------------------------------------------------------------------- | | **View AI settings** | Open **Administration → AI Assistant** and read the current configuration. Secrets are never shown. | | **Edit AI settings** | Change any setting, save it, test the provider, list models, and reset the token counter. | | **Use AI assistant** | Open the analyst chat and **AI Analysis**. Does **not** grant access to this administration page. | | **View data** | Required in addition to **Use AI assistant**. | | **Owner** | Implicitly holds every permission above. | A user with only **View AI settings** sees every field as read-only: toggles become status tags, and **Test Connection** / **Save** / **Reset counter** are hidden. Granting **Use AI assistant** without also enabling the assistant on this page does nothing useful: the chat APIs reject the request with *the AI assistant is disabled*. Granting **Edit AI settings** without **View AI settings** is enough to open the page (the route accepts either permission), but in practice you give both to administrators. Settings take effect as soon as **Save** succeeds. Analysts do not need to sign in again. Role changes still follow the usual session-token rule: a permission you add or remove on a role applies the next time that user's token is issued (at most 12 hours). See [Managing Roles](/7/administrator-guide/managing-roles.md). Which permissions to combine with the data-access toggles is in [AI Assistant](/7/security/ai-assistant.md#authorization). ## Before you enable it 1. Confirm the server host can open HTTPS (or HTTP, for a local model) to the intended Base URL. If the host has no default route, configure **Proxy** on this page or run the model locally. `localhost` in the Base URL means the **server machine**, not the operator's laptop. 2. Create or obtain an API key if the provider requires one. Local servers usually do not. 3. Decide the **data-access** policy *before* the first production question: tools on or off, call parameters on or off, live agent queries on or off. The defaults are: tools **on**, call parameters **off**, live agent queries **off**. Review the Security page before turning the sensitive toggles on. 4. Grant **Use AI assistant** (and **View data**) only to roles that should see the chat. 5. Click **Test Connection** on unsaved form values, then **Save**. Test does not persist the form. A license file may list an **AI Assistant** capability on **Configuration → License**. Configuration and use of the assistant are still controlled by the toggle and permissions on this page. Flopsar speaks the **OpenAI Chat Completions** protocol (`POST …/chat/completions` and `GET …/models`). Any endpoint that implements that surface can be selected, as long as the Base URL points at the OpenAI-compatible path (usually a URL ending in `/v1`). ## Saving, testing, and unsaved values The header has two actions, both visible only with **Edit AI settings**: * **Save** writes the form to the server database and applies it immediately (HTTP client, proxy, TLS, tool policy, and `logs/llm.log` switch included). The API key and proxy password fields are then cleared in the browser; the server keeps the stored secrets. A success toast reads *AI assistant configuration has been updated.* * **Test Connection** does **not** save. It uses the values currently on the form. An empty **API Key** or **Proxy password** means “use the secret already stored.” The test is a short, non-streaming chat (`Reply with the single word: ok`, 16-token cap) followed by a second request that declares a dummy `ping` tool. Connect timeout is 15 seconds; the whole probe must finish within 30 seconds. Possible test outcomes: | Result | Meaning | | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | *Connection successful* | The model answered and the endpoint accepted a `tools` declaration. Safe to turn **Let the assistant query data** on. | | *Connected, but tools are not supported* | Chat works; tool calling does not (HTTP 4xx on the probe). Turn **Let the assistant query data** off, or pick a model that implements OpenAI tool calling. OpenAI, Anthropic, Gemini, DeepSeek, and Moonshot generally do; many small local models do not unless the server is started with tools enabled. | | *Connection failed* | No route, TLS failure, rejected key, wrong token-limit field, or the model name is unknown. The provider's error message is shown. | Listing models (the refresh button next to **Model**) is also unsaved: it calls `GET {Base URL}/models` with the form's key, TLS, and proxy. If the provider returns an empty list, type the model id yourself. Changing the **Provider** dropdown applies that vendor's preset Base URL and **clears** the selected model, so you do not accidentally send a previous vendor's model name to a new endpoint. ## Enable assistant **Default: off.** This master switch shows or hides the analyst entry points — the **Analytics → AI Assistant** item, the **AI Analysis** button on Data Analysis, and the **AI Assistant** tab on a call stack or aggregated tree — for users who have **Use AI assistant**. When it is off, those APIs refuse the request even if the user has permission and the provider is fully configured. Turning it on does **not** by itself send data to a model. Traffic starts when an analyst submits a question (or the grounded view auto-starts an analysis). You can save a complete provider configuration with the assistant still disabled, then enable it when the policy review is done. ## Token usage This card is informational. It is **not** a quota and it does **not** stop conversations. | Field | Meaning | | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Counting since** | When the current total started: first server start after this counter existed, or the last **Reset counter**. Shown in the browser's locale. | | **Total tokens (in + out)** | Sum of prompt tokens and completion tokens reported by the provider, across **every** user and **every** conversation (including tool rounds). Formatted with US grouping (for example `1,234`). | Only replies whose provider payload includes a `usage` object are counted. Streaming requests ask the provider for usage (`stream_options.include_usage`). If a vendor omits usage, that reply is skipped and the total under-counts. Reasoning tokens, when the provider reports them, are included in the completion/total figures the vendor sends; Flopsar does not invent a second counter for them. **Reset counter** (Edit AI settings only) sets the total back to zero and moves **Counting since** to now. It applies to all users. Confirm in the dialog before it runs. Resetting does **not** change provider billing; it only clears Flopsar's local meter. The reset is audited; see [AI Assistant](/7/security/ai-assistant.md#audit-trail). The meter cannot be written through the ordinary Save payload. Reloading the page refreshes it. ## Provider Pick where the server sends `chat/completions` requests. Every call is made from the Flopsar server, not from the analyst's browser. ### Provider presets Selecting a preset fills **Base URL**. You can still edit the URL afterward (for a regional endpoint, a company gateway, or a different port). | Preset | Default Base URL | API key typically required | | -------------------------- | --------------------------------------------------------- | -------------------------- | | OpenAI | `https://api.openai.com/v1` | Yes | | Anthropic | `https://api.anthropic.com/v1` | Yes | | Google Gemini | `https://generativelanguage.googleapis.com/v1beta/openai` | Yes | | DeepSeek | `https://api.deepseek.com/v1` | Yes | | Moonshot | `https://api.moonshot.ai/v1` | Yes | | Groq | `https://api.groq.com/openai/v1` | Yes | | OpenRouter | `https://openrouter.ai/api/v1` | Yes | | Ollama | `http://localhost:11434/v1` | No | | vLLM | `http://localhost:8000/v1` | No | | Custom (OpenAI-compatible) | empty — you must type one | Depends on the server | **Custom** is the right choice for LM Studio, LiteLLM, Azure OpenAI (when exposed as an OpenAI-compatible base), an internal reverse proxy, or any other `/v1` endpoint. The URL must start with `http://` or `https://`. There is no trailing-slash requirement; the server joins `chat/completions` and `models` itself. ### Base URL Resolved only on the server. Must be non-empty and `http` or `https` before a conversation or a test can run. Wrong host, DNS, or firewall on the **server** is the usual cause of *failed to reach the model provider (no route from the server, check HTTPS\_PROXY and firewall rules)*. ### API Key Sent as `Authorization: Bearer …` when non-empty. Local models that do not check a key can leave this blank. The key is **never returned** by the API. The page only shows whether a key is already stored (*A key is stored and encrypted. Leave empty to keep it unchanged.*) or not (*No key stored. Local models usually do not need one.*). On Save: * leave the field empty → the stored key is unchanged; * paste a new value → it replaces the stored key; * there is no “clear the key” control in the form. How the key is sealed at rest, and what happens if the master key is rotated, is on [AI Assistant](/7/security/ai-assistant.md#secrets-at-rest-and-in-transit). ### Model The model id as the provider names it (for example `gpt-4.1`, `kimi-k2-instruct`, `llama3.1:70b`). The dropdown is editable: you may pick from the refreshed list or type. After a provider change the previous id is cleared on purpose. If **Test Connection** or chat returns an error that the model is unknown, refresh the list or copy the id from the vendor's catalog. The Flopsar server does not download models. ## Behaviour The Workstation labels this card **Behaviour** (British spelling). The documentation uses that on-screen title so you can find it; the rest of this page is written in American English. {% hint style="info" %} The analyst instruction sent to the model is fixed in the server and cannot be changed from the interface. Expertise and language below only select **which built-in variant** of that instruction is used; they do not let you paste a custom system prompt. {% endhint %} ### Max tokens **Default: 20000. Allowed range in the form: 256–32000.** This is the generation cap sent to the provider, in the field named by **Token limit field**. It is **not** a cap on the size of the prompt (view data + tool results). On reasoning models the same number also covers hidden reasoning tokens, so a low value can truncate the visible answer after the model has “spent” the budget thinking. If answers stop mid-sentence, raise this value and confirm you picked the token-limit field that vendor requires. ### Temperature and Temperature field **Default temperature: 0.3. Allowed range when sending a value: 0–2, step 0.1.** **Temperature field** controls whether that number is sent at all: | Temperature field (on screen) | What the request contains | | ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------- | | **Send configured value** | `temperature` = the number in **Temperature**. The number field is enabled. | | **Always send 1 (Kimi / some reasoning models)** | `temperature` = `1`, ignoring the number. Use this when the vendor rejects any other value (Kimi K2/K3 and similar). | | **Omit field (provider default)** | The JSON has no `temperature` key. The vendor uses its default. | Most chat models accept 0–2. A lower value makes answers more deterministic, which is usually what you want for incident analysis. If **Test Connection** fails with an error about temperature, switch to **Always send 1** or **Omit field**. ### Token limit field | On-screen option | JSON field sent | Use when | | ---------------------------------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------- | | **max\_tokens (most providers)** | `max_tokens` | Anthropic-compatible, Gemini's OpenAI path, DeepSeek, Moonshot, Groq, Ollama, vLLM, and classic OpenAI chat models. | | **max\_completion\_tokens (OpenAI o-series, GPT-5)** | `max_completion_tokens` | OpenAI reasoning models that reject `max_tokens` with HTTP 400. | The two fields are mutually exclusive in the request. A mismatch is a common cause of a failed test against OpenAI reasoning models or, conversely, against a local server that does not implement `max_completion_tokens`. **Test Connection** uses the same field you selected, so a green test means the limit field is accepted. ### Default answer level **Default: Medium.** This is the expertise assumed of the **reader**, not a measure of model quality. It changes the built-in instruction, and therefore the tone and vocabulary of answers, for every user who has not picked a different level in the assistant window. | Level (on screen) | Built-in intent | | ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | **Simple - limited technical background** | Support and operations. Explains what the numbers mean, avoids JVM internals, phrases next steps as things to check or to hand to development. | | **Medium - engineer who reads metrics** | Default. Interprets latency and errors without reteaching percentiles; still explains less common measures once. | | **Advanced - performance engineer** | Skips definitions. Reasons about GC, locking, thread state, off-CPU time, pools, and remote calls when the data supports it. | Each analyst may override this per conversation (Simple / Medium / Advanced / Server default). The override is stored in **that browser**, not in the server configuration, and does not require **Edit AI settings**. The server default remains what new browsers and the **Server default** choice use. ### Answer language **Default: empty. Maximum 32 characters. Single line; control characters are rejected.** Type the language **name in English** (`Polish`, `German`, `Brazilian Portuguese`). That string is copied into the system prompt: the model is told to write the whole answer in that language, while leaving class, method, exception, and parameter names exactly as recorded. An empty field means the model chooses. In practice that is English. Identifiers are never translated even when the field is set. This is not a locale setting for the Workstation UI, and it is not a list of language codes. Do not paste extra instructions into this field; they would sit in the system prompt. ### Max tool rounds **Default: 8. Allowed range: 2–20.** Disabled in the form when **Let the assistant query data** is off. One “round” is one request/response with the provider. While tools are enabled, the model may call tools, the server executes them, and the model is asked again with the results. The **last** round of a question is always sent **without** tool declarations, so the model must write a final answer from what it already gathered. If it still tries to call tools or returns empty, the server adds an explicit “stop calling tools and answer now” turn. Higher values allow deeper chains (summary → latency grid → hotspots → call tree → parameters) and cost more provider tokens. Two is the minimum: one tool-capable turn plus a final answer turn. Values outside 2–20 are clamped on save. This limit is **per user question**, not per day. ### Stream read timeout **Default: 120 seconds. Allowed range: 30–3600.** Idle time **between** chunks of the model's streaming response, not a limit on the whole answer. A local reasoning model that thinks for three minutes before the first token needs a value above 180. A public API that stalls for 30 seconds between tokens will be aborted at the value you set. Connect timeout for a new TCP/TLS session is a separate, non-configurable 15 seconds. Tool execution on the Flopsar side is capped at 60 seconds per tool call so a stuck agent query cannot freeze the conversation indefinitely. If analysts see *the model stream broke* or *timed out* on a local model, raise this setting, **Save**, and retry. The HTTP client is rebuilt on save, so the new timeout applies to the next question. ## Data access This card is the policy boundary for **what the model is allowed to fetch**. Generation limits live under Behaviour; this card is about data. What each combination discloses to the provider is on [AI Assistant](/7/security/ai-assistant.md#what-leaves-your-infrastructure). ### Let the assistant query data **Default: on.** When **off**: * Tool declarations are not sent. The model cannot list applications, pull another time range, open a different call, or query an agent. * A conversation opened from Data Analysis, a call stack, or an aggregated tree still receives the **server-built snapshot of that view** in the first message. That is the only telemetry in the prompt. * **Analytics → AI Assistant** (free-form) has **no** view snapshot — only timezone/clock metadata. With tools off, that workspace cannot fetch metrics and is not useful. Leave tools on if you want the free-form page to work. When **on**: * The model receives OpenAI tool declarations and may call them (`tool_choice` is `auto`). * Every tool call is executed **as the asking user**: banned applications apply; missing permissions return an error string to the model rather than data. * The provider **must** accept tool declarations. Use **Test Connection**. If it does not, turn this off or change models. Call parameters and live agent queries are nested under this switch: they cannot be turned on in the form unless tools are on, and they have no effect while tools are off. ### Allow call parameters **Default: off.** Requires tools on. When on, the model may be offered `get_call_parameters`, which reads recorded argument blobs the same way **View parameters** does in the Workstation. The asking user **still** needs **View parameters**. If the user lacks it, the tool is still declared (so the model knows it exists) but execution is refused. When this setting is off, the tool is **not declared at all**. Grounded call-stack analysis includes root-method arguments in the view snapshot only under the same combined rule (this setting **and** **View parameters**). Keep this off unless a specific investigation needs argument values. Data-masking patterns that already applied at ingest still apply — the assistant sees stored (masked) values, not a bypass. ### Allow live agent queries **Default: off.** Requires tools on. When on, and the asking user has **Query agents**, the model may run the same live queries as **Instances → Query**: * JVM system properties (`get_jvm_properties`) * loaded packages (`get_jvm_packages`) * process command line (`get_jvm_command_line`) * heap histogram (`get_jvm_heap`) * thread dump (`get_jvm_thread_dump`) * agent diagnostic logs (`get_agent_logs`) * last Java error text (`get_agent_java_error`) A heap histogram or a thread dump can pause the target application. Do not enable this in production unless that pause is acceptable and **Query agents** is already trusted for those operators in the Workstation. See [AI Assistant](/7/security/ai-assistant.md). When this setting is off, those tools are not declared. Listing online agents (`list_online_agents`) and reading buffered agent status or host metrics (`get_agent_status`, `get_agent_sysmetrics`) remain available whenever tools are on and the user has **Query agents**, because they do not trigger a dump. ### Log model requests **Default: off.** When on, every `POST /chat/completions` the server sends is appended to `/logs/llm.log`. The switch applies immediately on Save, including to conversations already in flight. Treat the file as sensitive and turn it off when you no longer need it. Format, rotation, and what is excluded from the file are on [AI Assistant](/7/security/ai-assistant.md#request-log-llmlog). ## Proxy Applies **only** to assistant traffic (model HTTP). It does not change agent ingestion, Workstation HTTPS, OTLP, or LDAP. | Field | Meaning | | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Proxy address** | HTTP or HTTPS proxy, for example `http://proxy.corp:3128`. **SOCKS is not supported.** Empty = follow the server process environment (`HTTPS_PROXY` / `HTTP_PROXY` and `NO_PROXY`). | | **Bypass hosts** | Comma-separated list, same syntax as `NO_PROXY` (for example `localhost,127.0.0.1,.internal.corp`). Use this when the proxy is set but a local model must be reached directly. | | **Proxy user** / **Proxy password** | Basic authentication. Leave both empty if the proxy does not need credentials. | Password handling matches the API key: never returned; empty field on Save means “keep the stored password.” **Clearing the user name** also removes the stored password, because a password with no user is rejected. A password without a user name is invalid and Save fails. After a successful Save the HTTP client is rebuilt with the new proxy; you do not restart the server. ## TLS Used when the Base URL is `https://`. | Control | Meaning | | --------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | | **Skip certificate verification** | **Default: off.** Insecure; use only while troubleshooting. | | **CA certificate (PEM)** | Extra CA (or chain) pasted in PEM (`-----BEGIN CERTIFICATE-----` …). Added to the host trust store, not used instead of it. | If verification is not skipped and the field is empty, only the host's standard CAs are trusted — the usual public-provider case. These TLS controls do **not** affect the Workstation's own certificate, agent PSK crypto, LDAP `skip_verify`, or OTLP. Why skip-verify is unsafe, and when to paste a CA, is on [AI Assistant](/7/security/ai-assistant.md#tls-to-the-provider). ## What the model can call when tools are on Tools are filtered **per question** from the asking user's permissions and from this page. The assistant never receives a tool the policy forbids. **Always declared while tools are on** (still scoped by banned applications): | Tool | Purpose | | -------------------------------------------------- | ----------------------------------------------------------------------------- | | `list_applications` | Applications the user may see | | `search_symbols` | Exact class, method, and thread names as agents reported them | | `get_analytics_summary` | Percentiles, volume, instances, top exceptions | | `get_latency_grid` | Latency heat map (time × duration) | | `get_hotspots` | Top methods by count, off-CPU, or exceptions | | `get_call_tree` | Aggregated execution tree | | `find_calls` | Individual `call_id` rows (no argument values) | | `get_call_stack` | One traced stack; arguments only if call parameters are allowed for that user | | `get_exception_stacktrace` | Stored stack trace text (refused without **View parameters**) | | `list_data_masks` | Masking pattern names | | `list_online_agents` | Currently connected JVM instances | | `render_finding`, `render_chart`, `render_mermaid` | UI-only figures in the conversation; not extra telemetry | **Declared only with extra rights or settings:** | Tool | Requires | | ------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- | | `get_call_parameters` | **Allow call parameters** (execution also needs **View parameters**) | | `get_jvm_properties`, `get_jvm_packages`, `get_jvm_command_line`, `get_jvm_heap`, `get_jvm_thread_dump`, `get_agent_logs`, `get_agent_java_error` | **Allow live agent queries** and **Query agents** | | `get_agent_status`, `get_agent_sysmetrics` | **Query agents** (not the live-query toggle) | | `list_plugins` | **View plugins** | | `get_plugin_source` | **View plugins source** | | `list_profiles`, `get_profile` | **View profiles** | | `get_license` | **View license** | Empty or refused tool results are returned to the model as text. The model is instructed not to invent metrics to fill the gap. ## Defaults (factory) These are the values of a server that has never saved this form (and the values the UI shows before the first successful load of stored settings): | Setting | Default | | ---------------------------- | ---------------------------------------- | | Enable assistant | Off | | Provider | OpenAI (`https://api.openai.com/v1`) | | Model | Empty (must be set before test or chat) | | API key | None | | Max tokens | 20000 | | Token limit field | `max_tokens` | | Temperature | 0.3 | | Temperature field | Send configured value | | Default answer level | Medium | | Answer language | Empty (model decides; typically English) | | Let the assistant query data | On | | Allow call parameters | Off | | Allow live agent queries | Off | | Max tool rounds | 8 | | Stream read timeout | 120 s | | Log model requests | Off | | Proxy / TLS extras | Empty / verification on | Settings live in the server **database** (configuration keys), not in `settings.toml`. ## Troubleshooting | Symptom | What to check | | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Page is 403 | Role lacks **View AI settings** and **Edit AI settings**. | | Chat says the assistant is disabled | **Enable assistant** is off, or **Save** was never clicked after turning it on. | | Chat says you are not allowed | Role lacks **Use AI assistant** or **View data**. | | *no route from the server* | Firewall, DNS, or proxy on the **server** host; `localhost` pointing at the wrong machine; SOCKS proxy (unsupported). | | HTTP 400 about `max_tokens` / `max_completion_tokens` | Switch **Token limit field**. | | HTTP 400 about `temperature` | Use **Always send 1** or **Omit field**. | | Test succeeds but tools fail in chat | Model accepted the probe but is poor at tool calling; try another model or lower **Max tool rounds** after confirming **Test Connection** reports tools supported. | | Answers truncated | Raise **Max tokens**; on reasoning models the budget includes hidden tokens. | | Stream stalls then errors | Raise **Stream read timeout** for slow local models. | | Free-form page answers with no data | **Let the assistant query data** is off. | | Model never sees arguments | **Allow call parameters** off, tools off, or user lacks **View parameters**. | | Dump/histogram never offered | **Allow live agent queries** off, or user lacks **Query agents**. | | *Failed to decrypt the AI API key* in server log | Master key changed or is wrong; paste the API key again and Save. See [AI Assistant](/7/security/ai-assistant.md#secrets-at-rest-and-in-transit). | | Token total stays at zero | Provider does not return `usage` on the stream; billing still happens on the vendor side. | ## Related pages * Analyst workflow: [AI Assistant](/7/user-guide/observing-and-diagnosing/ai-assistant.md) * Security (data leaving, RBAC, secrets, TLS, audit): [AI Assistant](/7/security/ai-assistant.md) * Roles: [Managing Roles](/7/administrator-guide/managing-roles.md)