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
| What | Where | What it tells you |
|---|---|---|
| Status line | Below the reply, with a spinning icon | What the assistant is doing right now: Thinking, Writing, Listing channels, Updating the plan… It disappears when the job is finished. |
| Explanation sentences | Inside the reply | One 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 card | Inside the reply, a box with a coloured line on its left | The steps of the job and which one it is on. Details are below. |
| Step box | Below 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. |
| Thinking | At the top of the reply, a collapsible block | Shown if the model produces thinking (Show thinking stream in the assistant settings). Not every model does; its absence is not an error. |
| Approval card | Inside the step box | When 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.
| Display | Meaning |
|---|---|
| Plan 2/5 in the header, and a bar | Two of five steps are closed (completed and skipped steps are counted together). |
| Spinning ring, bold text, lightly tinted row | In progress: the assistant is on this step now. Only one step is in progress at a time. |
| Ticked circle, faded text | Done. |
| Empty circle | Pending: its turn has not come. |
| Circle with a minus sign, struck-through text | Skipped: 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 line | All steps are closed. |
| 2 steps left on the right of the header | The 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. |
Following a job from start to finish
- Type your request, e.g. "Build a dashboard that shows this month's water withdrawal of the wells", and press Enter.
- 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.
- 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.
- 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.
- 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:
| Heading | What it contains |
|---|---|
| Summary | The result in a sentence or two. |
| Findings | A table of the values read (name, value and unit, quality or status). Only when an analysis was requested. |
| What was done | Everything that changed, item by item. Every item written here is based on a tool result. |
| Verification | How the assistant checked its work with a tool (read it back, ran it, previewed it) and what it could not verify. |
| Remaining | Things left unfinished or that you need to do. If nothing remains this heading is absent. |
Getting good results
- 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.
- 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.
- 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.
- 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
| Question | Answer |
|---|---|
| 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. |
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
| Job | Required |
|---|---|
| E-mail / SMS sending server, Security, Retention, Backup settings | Root only (also through the assistant). The other settings change with the Server settings permission. |
| Exporting and importing the project package | Root 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, alias | The 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 values | The visibility rule of the Counters page; it also applies when reading through the _Counters.… and _Metrics.… tag paths. |
| AI provider and external MCP server address | If 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 tools | Writing tools |
|---|---|---|
| Tags, Connectivity, Virtual Tags, Aliases, Monitoring | Connectivity: View | Connectivity: Manage (Configuration Management scope) |
| Alarms / Alarm Management | Alarms: 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 Management | Data Logs: View | Data Logs: Manage |
| Counters / Metrics / Water management | Counter 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. |
| Reports | Reports: View (+ the View permission of every source in the report) | Reports: Manage |
| Automation | Automation: View. Validating a flow (validate_workflow): Automation: Manage. | Automation: Manage. Running by hand (run_workflow): Automation: View + Tag write and services. |
| Data Bridge | Data Bridge (both seeing and creating agents) | |
| SCADA Screens | SCADA: View | SCADA: Manage |
| Project Templates | Connectivity: View | Templates and import |
| Service Control | Tag write and services (service startup setting: Server settings) | |
| Network Diagnostics (ping / TCP / DNS / port) | Tag write and services (before, Connectivity: View was enough) | |
| Audit Log | Audit log | |
| Settings / Project Export | Server settings (section by section); installing a web certificate: Certificates; opening a firewall port: Firewall; project package: Root only | |
| Users / Permissions | Root only | |
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.
| Action | Parent permission | Tools that depend on it |
|---|---|---|
Add channelchannel.create | Connectivity: Manage | create_channel |
Edit channelchannel.edit | Connectivity: Manage | update_channel |
Delete channelchannel.delete | Connectivity: Manage | delete_channel |
Add devicedevice.create | Connectivity: Manage | create_device |
Edit devicedevice.edit | Connectivity: Manage | update_device |
Delete devicedevice.delete | Connectivity: Manage | delete_device |
Add tagtag.create | Connectivity: Manage | create_tag, create_tags, create_tag_group, browse_device_tags |
Edit tagtag.edit | Connectivity: Manage | update_tag |
Delete tagtag.delete | Connectivity: Manage | delete_tag |
Add Virtual Tagvtag.create | Connectivity: Manage | create_advanced_tag |
Edit Virtual Tagvtag.edit | Connectivity: Manage | update_advanced_tag |
Delete Virtual Tagvtag.delete | Connectivity: Manage | delete_advanced_tag |
Add Tag Shortcutalias.create | Connectivity: Manage | create_alias |
Edit Tag Shortcutalias.edit | Connectivity: Manage | update_alias |
Delete Tag Shortcutalias.delete | Connectivity: Manage | delete_alias |
Start / stop servicesservice.control | Tag write and services | control_service, set_service_autorestart |
Device diagnosticsdiag.run | Tag write and services | net_ping, net_tcp_check, net_resolve, net_local_ports |
Run a flow by handworkflow.run | Tag write and services | run_workflow |
Add screenscreen.create | SCADA: Manage | create_screen |
Edit screenscreen.edit | SCADA: Manage | update_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 screenscreen.delete | SCADA: Manage | delete_screen |
Symbol libraryscada.library | SCADA: Manage | import_symbol, update_symbol, delete_symbol, symbol_memory |
Zone treescada.zones | SCADA: Manage | add_zone, update_zone, delete_zone |
Acknowledge alarmsalarms.ack | Alarms: View | ack_alarm |
Add alarm definitionalarmdef.create | Alarms: Manage | create_alarm |
Edit alarm definitionalarmdef.edit | Alarms: Manage | update_alarm |
Delete alarm definitionalarmdef.delete | Alarms: Manage | delete_alarm |
Add log grouploggroup.create | Data Logs: Manage | create_log_group |
Edit log grouploggroup.edit | Data Logs: Manage | update_log_group |
Delete log grouploggroup.delete | Data Logs: Manage | delete_log_group |
Add countercounter.create | Counters and Metrics: Manage | create_counter |
Add metricmetric.create | Counters and Metrics: Manage | create_metric_from_formula |
Enter manual valuesinput.enter | Counters and Metrics: Manage | set_counter_period_value, set_metric_input_value |
Water setup wizardwater.setup | Water Management: Manage | setup_water_management |
Add reportreport.create | Reports: Manage | save_report (without id), save_report_page (without id) |
Edit reportreport.edit | Reports: Manage | save_report (with id), save_report_page (with id) |
Delete reportreport.delete | Reports: Manage | delete_report, delete_report_page |
Add flowworkflow.create | Automation: Manage | create_workflow |
Edit flowworkflow.edit | Automation: Manage | update_workflow |
Delete flowworkflow.delete | Automation: Manage | delete_workflow |
Enable / disable flowsworkflow.enable | Automation: Manage | set_workflow_enabled |
Add agentagent.create | Data Bridge | create_iot_agent |
Edit agentagent.edit | Data Bridge | update_iot_agent |
Delete agentagent.delete | Data Bridge | delete_iot_agent |
Install templatestemplate.install | Templates and import | apply_template |
Package templatestemplate.package | Templates and import | create_template |
Delete templatestemplate.delete | Templates and import | delete_template |
Feature groupssettings.features | Server settings | set_feature_group |
Services and resource thresholdssettings.services | Server settings | set_service_startup |
Web certificatecert.web | Certificates | set_web_cert_selfsigned, import_web_cert |
save_reportandsave_report_pageboth create and update: ifidis given "Edit report" is checked, if not "Add report". If one of the two is on, the tool appears in the list.update_settingsworks section by section: the action of every settings section that is changed is checked separately (e.g. "Branding settings" for the Branding section).get_settingsreturns 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_projectand 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).
MergenHub