MergenHub Envest
Home/Docs/User Manual (in-app, complete)

AI Assistant

How the assistant works: plan, stages, closing reply

The assistant opens with the AI Assistant button in the top bar or the AI Assistant row in the left menu. When you give it a job it shows not only the result but also how the job is progressing: it says up front what it will do, marks the step it is on, and at the end writes what it verified and what it could not verify. This section explains what the things you see in the chat mean.

What you see in the chat

WhatWhereWhat it tells you
Status lineBelow the reply, with a spinning iconWhat the assistant is doing right now: Thinking, Writing, Listing channels, Updating the plan… It disappears when the job is finished.
Explanation sentencesInside the replyOne sentence on entering each stage: what it will do and why ("First I am searching for the well tags; I will bind the counters to them").
Plan cardInside the reply, a box with a coloured line on its leftThe steps of the job and which one it is on. Details are below.
Step boxBelow the plan card, a collapsible box that reads "3 steps"The tools the assistant called. Clicking a row opens the Arguments the tool received and the Result it returned; it reads done if it succeeded, failed if not.
ThinkingAt the top of the reply, a collapsible blockShown if the model produces thinking (Show thinking stream in the assistant settings). Not every model does; its absence is not an error.
Approval cardInside the step boxWhen the assistant is about to change something it asks Approve / Reject. Deletion always asks.

How to read the plan card

If the job needs three or more steps the assistant writes its plan before calling the first tool. There is only one card in the chat; the same card is updated as the assistant progresses.

DisplayMeaning
Plan 2/5 in the header, and a barTwo of five steps are closed (completed and skipped steps are counted together).
Spinning ring, bold text, lightly tinted rowIn progress: the assistant is on this step now. Only one step is in progress at a time.
Ticked circle, faded textDone.
Empty circlePending: its turn has not come.
Circle with a minus sign, struck-through textSkipped: it could not be done or was no longer needed. The reason is in the closing reply.
complete on the right of the header, green lineAll steps are closed.
2 steps left on the right of the headerThe assistant stopped but the plan is not closed: either you stopped it, or the tool budget ran out, or the assistant is waiting for an answer from you. The closing reply says which.
Tip The question mark in the plan card header opens this page. Hover over a step to see the name of its state (in progress, pending, done, skipped).

Following a job from start to finish

  1. Type your request, e.g. "Build a dashboard that shows this month's water withdrawal of the wells", and press Enter.
  2. The assistant says in one sentence what it will do and writes the Plan card: e.g. "Look at the data sources", "Try the page", "Save and open", "Verify". The first step becomes in progress.
  3. At each step new tool rows are added to the step box; when the step ends it is ticked on the plan card and the next step becomes in progress.
  4. If the assistant is going to change something an approval card appears. With Approve it continues; with Reject it does not make that change; it either proposes another way or marks the step as skipped.
  5. The final reply arrives. If the plan card reads complete the job is finished; if it reads … steps left, look at the Remaining heading in the final reply.

To interrupt the job press the Stop button next to the input box. What has been done up to that moment is saved; if you type "continue", the open plan is recalled to the assistant and it carries on from the step where it stopped.

Closing reply

If it did a job, the assistant's final reply carries these headings:

HeadingWhat it contains
SummaryThe result in a sentence or two.
FindingsA table of the values read (name, value and unit, quality or status). Only when an analysis was requested.
What was doneEverything that changed, item by item. Every item written here is based on a tool result.
VerificationHow the assistant checked its work with a tool (read it back, ran it, previewed it) and what it could not verify.
RemainingThings left unfinished or that you need to do. If nothing remains this heading is absent.
Warning Do not count an item marked "could not be verified" as completed: the assistant did that thing but could not see its result (e.g. the device was offline at that moment, it could not open the screen). Check it yourself or tell the assistant "verify this now".

Getting good results

  1. Describe the result, not the steps. "Send an e-mail when the tank level drops below 20 percent" is enough; the assistant knows which tool to use.
  2. Give the names you know. If you write the channel, device, tag or counter name the assistant does not lose time searching and does not pick the wrong one.
  3. If the plan is wrong, say so at once. Press Stop and type "do not do the third step, do this instead"; the assistant renews the plan.
  4. Do not split a long job. The assistant can take many steps in one turn (Max tool steps per turn in the assistant settings). If the budget runs out it says the job is unfinished and lists what remains; typing "continue" is enough.

Frequently asked questions

QuestionAnswer
No plan card appeared.The job was short (a single question or a single tool). A plan is written only for jobs of three or more steps.
A small local model does not write a plan or leaves it half done.Writing a plan depends on the model's tool-use ability. The assistant nudges the model to continue on its own; if it still does not work, choose a stronger model.
Does writing a plan need approval, does it change anything?No. The plan is only a display; it changes nothing in the system and also works while the change permission is off.
Is the plan visible when I open an old conversation?Yes. The plan of every job stays where it was written, in its final state.
What happens to the old plan when the assistant moves on to a new job?The plan of the new job is written as a separate card; the old card stays as it is.
Is there a plan card in an external MCP client (e.g. Claude Desktop)?No. The plan card is specific to the in-app assistant; external clients use their own interface.
Limits A plan has at most 12 steps. Step titles are short; the detail is in the explanation sentences and the step box. Every tool call of the assistant that reads or changes data is written to the audit log under the "MCP" category; plan updates are not, because they change nothing in the system (the plan itself is stored in the conversation).

Permission, approval and connection rules (assistant and MCP)

The assistant and the MCP server work with the permissions of the person using them: you cannot have the assistant or an MCP token do something you cannot do in the interface. As of 3.10.0 this rule is identical to the interface in every tool.

Who can do what

JobRequired
E-mail / SMS sending server, Security, Retention, Backup settingsRoot only (also through the assistant). The other settings change with the Server settings permission.
Exporting and importing the project packageRoot only (preview included). Installing, packaging and deleting a template continue with the Templates and import permission and follow resource access; a template does not carry server settings, data sources or branding.
Screen, zone, alarm, data log group, virtual tag, aliasThe related permission + access to that resource. A user with restricted resource access cannot see or change through the assistant what they cannot see otherwise.
Reading the settings (get_settings)Section by section, as in the interface: only the sections you can change arrive filled.
Counter and metric valuesThe visibility rule of the Counters page; it also applies when reading through the _Counters.… and _Metrics.… tag paths.
AI provider and external MCP server addressIf the address changes the saved key is not kept; it is entered again. Only Root changes the name, address and key of an external MCP server.

Which permission the tools need (3.10.1)

The tools match the rows of the permission window one to one. If the owner of the token does not have the permission, the tool does not appear in the list at all.

Tool group (MCP scope)Reading toolsWriting tools
Tags, Connectivity, Virtual Tags, Aliases, MonitoringConnectivity: ViewConnectivity: Manage (Configuration Management scope)
Alarms / Alarm ManagementAlarms: View (before, Connectivity: View was enough)Creating, changing, deleting a definition: Alarms: Manage. Acknowledging (ack_alarm): Alarms: View and the "Acknowledge alarms" action.
Historian / Data Logger ManagementData Logs: ViewData Logs: Manage
Counters / Metrics / Water managementCounter and metric tools: Counters and Metrics: View. Water tools: Water Management: View. Counter tracking list tools: Reports: View.Counters and Metrics: Manage. The water setup wizard also needs Water Management: Manage; turning a feature group on or off needs Server settings.
ReportsReports: View (+ the View permission of every source in the report)Reports: Manage
AutomationAutomation: View. Validating a flow (validate_workflow): Automation: Manage.Automation: Manage. Running by hand (run_workflow): Automation: View + Tag write and services.
Data BridgeData Bridge (both seeing and creating agents)
SCADA ScreensSCADA: ViewSCADA: Manage
Project TemplatesConnectivity: ViewTemplates and import
Service ControlTag write and services (service startup setting: Server settings)
Network Diagnostics (ping / TCP / DNS / port)Tag write and services (before, Connectivity: View was enough)
Audit LogAudit log
Settings / Project ExportServer settings (section by section); installing a web certificate: Certificates; opening a firewall port: Firewall; project package: Root only
Users / PermissionsRoot only
After upgrading If a token has the "Network Diagnostics", "Alarms" or "Data Bridge" scope selected and its owner does not have the permission above, these tools drop out of the list in the client. The fix: give the owner the permission. Tools that save a definition (Virtual Tag, flow, data bridge agent, log group) apply the same rule as the interface: every tag the definition refers to must be open to the owner, and a definition that writes to a tag also needs Tag write and services.

Which action the tools depend on (3.10.1)

If an action inside a permission is turned off for the user (and their group), the tool that depends on that action does not appear in the list: the assistant does not see the tool at all, and it is not in the tool list of an external MCP client either. If the tool is called anyway it does not run; the reply says that the action has been turned off for you (the server writes this message in Turkish) and carries the key of the action. The mapping is the same table as the REST API: a job whose button is not shown in the interface cannot be done by the assistant either.

ActionParent permissionTools that depend on it
Add channel
channel.create
Connectivity: Managecreate_channel
Edit channel
channel.edit
Connectivity: Manageupdate_channel
Delete channel
channel.delete
Connectivity: Managedelete_channel
Add device
device.create
Connectivity: Managecreate_device
Edit device
device.edit
Connectivity: Manageupdate_device
Delete device
device.delete
Connectivity: Managedelete_device
Add tag
tag.create
Connectivity: Managecreate_tag, create_tags, create_tag_group, browse_device_tags
Edit tag
tag.edit
Connectivity: Manageupdate_tag
Delete tag
tag.delete
Connectivity: Managedelete_tag
Add Virtual Tag
vtag.create
Connectivity: Managecreate_advanced_tag
Edit Virtual Tag
vtag.edit
Connectivity: Manageupdate_advanced_tag
Delete Virtual Tag
vtag.delete
Connectivity: Managedelete_advanced_tag
Add Tag Shortcut
alias.create
Connectivity: Managecreate_alias
Edit Tag Shortcut
alias.edit
Connectivity: Manageupdate_alias
Delete Tag Shortcut
alias.delete
Connectivity: Managedelete_alias
Start / stop services
service.control
Tag write and servicescontrol_service, set_service_autorestart
Device diagnostics
diag.run
Tag write and servicesnet_ping, net_tcp_check, net_resolve, net_local_ports
Run a flow by hand
workflow.run
Tag write and servicesrun_workflow
Add screen
screen.create
SCADA: Managecreate_screen
Edit screen
screen.edit
SCADA: Manageupdate_screen, add_widget, add_widgets, draw_svg, update_widget, delete_widget, draw_pipe, connect_widgets, build_scene, build_unit_grid, build_tank_scene, build_flow_scene, build_well_scene, add_macro, set_animation, place_on_pipe
Delete screen
screen.delete
SCADA: Managedelete_screen
Symbol library
scada.library
SCADA: Manageimport_symbol, update_symbol, delete_symbol, symbol_memory
Zone tree
scada.zones
SCADA: Manageadd_zone, update_zone, delete_zone
Acknowledge alarms
alarms.ack
Alarms: Viewack_alarm
Add alarm definition
alarmdef.create
Alarms: Managecreate_alarm
Edit alarm definition
alarmdef.edit
Alarms: Manageupdate_alarm
Delete alarm definition
alarmdef.delete
Alarms: Managedelete_alarm
Add log group
loggroup.create
Data Logs: Managecreate_log_group
Edit log group
loggroup.edit
Data Logs: Manageupdate_log_group
Delete log group
loggroup.delete
Data Logs: Managedelete_log_group
Add counter
counter.create
Counters and Metrics: Managecreate_counter
Add metric
metric.create
Counters and Metrics: Managecreate_metric_from_formula
Enter manual values
input.enter
Counters and Metrics: Manageset_counter_period_value, set_metric_input_value
Water setup wizard
water.setup
Water Management: Managesetup_water_management
Add report
report.create
Reports: Managesave_report (without id), save_report_page (without id)
Edit report
report.edit
Reports: Managesave_report (with id), save_report_page (with id)
Delete report
report.delete
Reports: Managedelete_report, delete_report_page
Add flow
workflow.create
Automation: Managecreate_workflow
Edit flow
workflow.edit
Automation: Manageupdate_workflow
Delete flow
workflow.delete
Automation: Managedelete_workflow
Enable / disable flows
workflow.enable
Automation: Manageset_workflow_enabled
Add agent
agent.create
Data Bridgecreate_iot_agent
Edit agent
agent.edit
Data Bridgeupdate_iot_agent
Delete agent
agent.delete
Data Bridgedelete_iot_agent
Install templates
template.install
Templates and importapply_template
Package templates
template.package
Templates and importcreate_template
Delete templates
template.delete
Templates and importdelete_template
Feature groups
settings.features
Server settingsset_feature_group
Services and resource thresholds
settings.services
Server settingsset_service_startup
Web certificate
cert.web
Certificatesset_web_cert_selfsigned, import_web_cert
  • save_report and save_report_page both create and update: if id is given "Edit report" is checked, if not "Add report". If one of the two is on, the tool appears in the list.
  • update_settings works section by section: the action of every settings section that is changed is checked separately (e.g. "Branding settings" for the Branding section). get_settings returns a section whose action is turned off empty.
  • The network diagnostics tools (net_ping, net_tcp_check, net_resolve, net_local_ports) belong to the "Device diagnostics" action.
  • Writing tools that do not depend on an action: import_project and the user tools (Root only), open_firewall_ports (the Firewall permission itself).
  • Reading tools have no action: the View permission of the module is enough.
  • Assistant settings. If the "AI provider" action is off, the Providers and MCP tabs do not appear in the assistant settings; if "Assistant skills" is off, the Skills tab does not appear and the assistant's skill saving tool does not work; if "Extra instructions" is off, the extra instructions field is read-only. Talking to the assistant is the AI assistant permission; it has no actions.

Operations that need approval

Before the assistant changes something it shows an approval card. The following operations are asked every time, even in "apply without asking" mode, and cannot be allowed permanently: deleting, changing a server setting, stopping / restarting a service, opening a firewall port, changing a user's permissions, applying a project import, exporting with credentials, changing the period value of a measured counter, saving a skill. While the assistant's change permission is off no writing tool runs (macro, animation, place-on-line and well scene tools included).

MCP token

  • Scopes are separate for reading and writing. The "Counters / Metrics / Water management" and "Reports" scopes only read; for setting up, entering values, saving and deleting you select the write scopes separately. A token cannot exceed its owner's permissions.
  • HTTPS only from outside the local network. A token can be used over unencrypted HTTP from the same computer or from the local network; an unencrypted request coming from the internet is rejected (turn on HTTPS in Settings).
  • Clients that connect with OAuth (such as Claude) must use PKCE (S256); the consent page shows the address the permission will go to.
  • When a user is deleted their tokens and data access keys are deleted too; the token of a disabled user does not work.
  • Tokens are deleted when the password changes. When the owner's password is changed or reset the MCP tokens are closed; create a new token for the client (see Passwords and sessions).
Note The chat view does not load images at remote addresses by itself; it shows them as links. Images you attach to the chat are shown as before.