AI Specialists
A Specialist is a saved sub-assistant: its own instructions, its own narrower set of tools, and a declared answer shape. The assistant calls it as a single step and gets one finished answer back.
It exists because assistants get worse as you give them more tools. Selection stays reliable at roughly ten to twenty tools and degrades well before fifty. A plant that needs Tags + History + Alarms + Saved Queries to answer "should I intervene on P-101?" is carrying those tools in every conversation for one recurring question. A specialist folds them into one.
Skill, Playbook, Specialist
These three are configured in the same places and are easy to confuse. They are not the same thing.
| Skill | Playbook | Specialist | |
|---|---|---|---|
| What it is | A named bundle of tools | A written procedure | A saved sub-assistant |
| Where it runs | In the assistant's own conversation | In the assistant's own conversation | Its own separate conversation |
| Tools in the assistant's context | Adds all of them | Adds none directly | Adds exactly one |
| What comes back | — | — | One validated answer |
| Grants access? | Yes — it selects capabilities | No | No |
Choosing between the last two. Use a playbook to shape how the assistant answers. Use a specialist when the sub-question deserves its own attention and comes back as one answer.
It can never reach further than the person asking
A specialist selects from what its caller already holds. It never grants:
specialist's tools = the tools its skills name
∩ the tools the calling turn already resolved
Every lookup it makes is re-authorized on the server under the same identity, against the same tag, connection and endpoint fences as its caller. A specialist naming a tool its caller does not hold simply does not have it — the same way any unavailable tool behaves.
It also cannot nest: a specialist cannot call a specialist.
Turning it on
Three things must be true before an assistant can run one.
- Administrator —
Settings → AI Assistant, tick Ask specialists. It is off by default, like every capability over a surface that did not exist before. This is also the kill switch: turning it off withdraws every specialist everywhere, immediately. - Author — the Author AI Specialists permission, to create or edit one.
- Engineer — tick the Specialists skill on whichever assistant is to run one, then pick the specialists themselves.
If the Specialists skill is ticked but nothing is picked, the assistant is given no specialist tool at all. That is deliberate: an advertised tool with nothing behind it reads to an operator as a broken assistant rather than an unconfigured one.
Writing one
Project Browser → AI ▸ Specialists, or the same branch of the Pipeline Browser. A specialist is
stored with the project, so one definition serves every screen and pipeline that picks it.
| Field | What it is for |
|---|---|
| Name | The human label. |
| Description | Read by the model to decide when to call this specialist. Write it as an instruction, not as documentation for a colleague — this is the field authors most often get wrong. |
| How it answers | Instructions, code, or both. See below. |
| Instructions | The sub-assistant's own system prompt: what to read, in what order, how to decide. |
| What it can use | Which built-in skills it draws its tools from. At most six — one that plugs in everything has given up the only benefit it was built for. |
| What it is given | The parameters the model must supply. Each field's description is what the model reads to fill it in. |
| What it answers with | A written answer, A set of values (validated), or One of a fixed list. |
| How far it may go | Steps and tokens. The defaults are runaway guards, not tuning knobs; they should never fire on a specialist that works. |
A specialist brings the skills it needs. You do not tick those separately on the assistant that calls it — and it stays one tool in that assistant's context however many its sub-assistant uses inside.
Use the Test panel while writing. It runs the draft directly with your own permissions and shows the full trace: every tool call, in order, and the answer.
A specialist can also be saved as a draft New in 1.0.2 — testable by its author, and withheld from every assistant until it is marked available.
Answering with code New in 1.0.2
A sub-agent is a language model, and arithmetic is what a language model is least reliable at. So a specialist can carry a Python compute body and answer with a figure it did not have to derive in its head.
How it answers offers three modes:
| Mode | What runs | Cost |
|---|---|---|
| Instructions only (the default) | A sub-agent reads what it needs and answers in its own words. | A nested model conversation. |
| Instructions and compute | The server fetches the inputs and runs your code first, then the sub-agent explains the figures it produced rather than working them out. | A nested conversation, over exact numbers. |
| Compute only | The server fetches the inputs and runs your code. No model runs at all — the answer is the same every time and costs nothing to produce. | None. |
Empty is instructions-only, which is what every specialist written before this existed already was.
The rule the whole thing rests on
The model may choose the reference. It may never carry the value.
A model naming PMP-01/Speed is choosing a reference. A model that reads 1487.3 and retypes it
into a call is carrying a value, and has reintroduced the transcription error this exists to remove.
So the inputs are fetched by the server, and the code reaches nothing on its own: no system.*,
no network, no plant. Each input is re-authorized against the tool that would have fetched it by
hand — which is what makes "a compute body reads exactly what its caller could have read" true by
construction rather than by promise.
Inputs
Up to 12, each with a name that becomes a parameter of your function:
| Kind | Re-authorized against | |
|---|---|---|
| Tag value | read_tag | |
| Trend (historian) | read_historian | |
| Active alarms | read_active_alarms | |
| Alarm journal | query_alarm_journal | |
| Saved query | run_named_query | |
| External system | call_endpoint | |
| Tag relationships | read_tag_relationships | 1.0.6 |
| Manuals | search_knowledge | 1.0.6 |
| Stored file | read_file | 1.0.6 |
| Gateway variable | read_variables | 1.0.8 |
The editor names that tool on every row, because it is what decides whether the input works at all: an input naming a tool the caller does not hold reaches nothing.
The last three close the gap with a playbook's step kinds. New in 1.0.6 A compute-only specialist runs no nested conversation and therefore holds no tools at all — its only data is this list — so until they existed, a calculation over a commissioning record, a manual or a tag's stored relationships was not expressible at all, while a playbook could order the identical read in one step. Relationships are worth having as an input rather than only as a step for the same reason the whole feature exists: the links are a graph, and counting or walking a graph is exactly the arithmetic a model does badly and states confidently.
Which inputs the caller may re-aim. A tag, trend or relationships input can take its target from one of the specialist's own declared input fields, so the caller says which pump and the server resolves that into a reading — the named path still goes through the instance's tag fence before anything is read. The others take a fixed target the author pins: a namespace prefix, a saved query, an operation, a knowledge search, a file and a gateway variable are reaches the author chose, and a caller able to rewrite one would be choosing which part of the plant, the database or the document set a single call acquires.
A gateway variable New in 1.0.8 is read from the project's own variables and the global ones. One that is not set, or too large to read whole, ends the run with an error rather than computing over a missing value.
Changed in 1.0.6 The kinds on offer normally follow the ticked skills. A compute-only specialist has none by design — its reads come from this list, each re-authorized per call — so the dropdown used to fall back to the passthrough kinds and Saved query never appeared at all. A definition the server accepts and runs could not be produced in the editor. Every kind is now offered when a compute body runs, and the fence stays where it actually is: per input, per call, against whoever is asking.
The body
The signature is derived from the inputs and shown read-only above the editor — the input names are the parameters, so it changes as you edit the list:
def compute(amps, trips):
average = sum(amps) / len(amps) if amps else 0
return {
"average_amps": round(average, 1),
"trips": len(trips),
"verdict": "investigate" if average > 41.5 or len(trips) > 3 else "normal",
}
The entry point is called by name, so a body that defines something else never runs. Switching into a compute mode seeds a starter body for that reason.
Up to 40,000 bytes, roughly a thousand lines. Changed in 1.0.6 The limit is not about cost — a compute body is never sent to a model, so it costs no tokens at all. It is about design: this is one textarea, with no imports and no way to split a file, and logic that outgrows it belongs in a pipeline, which has nodes, a debug view and somewhere to put tests. Note that it counts bytes, so a character like an em-dash in a comment costs three of them.
The server checks the body as you write it and reports problems inline; a specialist whose code does not pass cannot be made available.
What compute() may return Changed in 1.0.8
One line under the editor states the rule for the current mode and answer shape:
| Answer shape | compute() returns |
|---|---|
| A written answer | Anything. A string is the answer as written; a number, true/false, list or dict is passed on as JSON. |
| One of a fixed list | A string or number that matches one of the choices — 2 matches the choice "2". |
| A set of values | A dict, one key per declared value, each one flat. |
| Instructions and compute, any shape | The figures the sub-agent should explain, in any shape. |
Returning None fails the run with a message pointing at a missing return. Before 1.0.8 a
compute-only specialist answering as text refused anything but a string — so one returning a dict,
the natural result of a calculation, saved cleanly and then failed every run.
Time limit
A calculation runs for at most the Compute specialist limit, 60 seconds by default, set by an administrator on the AI time limits card. Changed in 1.0.8 → Time limits
What the trace shows
A compute-only run makes no model calls, so its trace used to be empty — answered without reading anything, beside an answer that came entirely from what the server read. Changed in 1.0.8 A successful run now records one step per input, named by the tool it was read through; with instructions as well, those reads come before the model's own calls.
Specialists converted from playbook checks New in 1.0.8
Upgrading to 1.0.8 turns every saved playbook check into a draft compute specialist with the check's inputs, its expression kept as a comment, and a body that raises until somebody writes the calculation. It is not offered to any assistant until Available to assistants is ticked. → Playbook checks were retired
Using one
On an AI node (pipeline)
Node editor → tick the Specialists skill → the Specialists picker appears → choose.
A node runs unattended, so nothing is filtered by role. The node's own fences still apply to every lookup the specialist makes.
On an AI Chat widget (a screen)
Property panel → tick the Specialists skill → the specialists property appears → choose.
On a runtime role
Identity & Access → Roles → AI Access. When a widget has Limit to role ticked, the screen's own
picks are ignored and the role decides which specialists that operator may run.
Ids, comma separated. There is no * here — an operator is granted sub-assistants one at a time, and
an empty list means none. An operator holding several roles gets the combined set.
Not in the platform assistant
The assistant in the Designer has no per-project specialist selection and does not run them. Use the Test panel, which is the surface built for that.
What an operator sees
While a specialist is running, the chat shows "asking a specialist". Its internal steps are deliberately not streamed — it is a tool call, not an answer. The steps are recorded in the run trace, and the answer is handed back whole.
A specialist is by far the slowest thing an assistant does, often tens of seconds: it is a second model conversation, not a lookup.
When it does not work
| What you see | Why |
|---|---|
| The assistant says it has no specialists | Ask specialists is off in Settings → AI Assistant, or nothing is picked on this assistant. |
| The picker is empty | The project has no specialists yet, or none is valid. |
| A specialist is marked unfinished | Its definition fails validation, so the server skips it. Open it and see what is missing. |
| "runs with less than it was written for" | It draws on skills this assistant does not hold. It will run, with fewer tools than its author intended. |
| The answer says it was cut short | It reached its token budget, or the model profile's Max output tokens. Raise it, or narrow the instructions. |
| A compute input returns nothing | It is re-authorized against the caller's identity, not the author's. Check the tool named on that input row is one the asker holds. |
| Code that will not save | A body no mode runs is refused, and so is a compute mode with no body. |
Next
→ Skills & fences — what a specialist inherits, and what narrows it
→ Playbooks — a procedure can hand one step to a specialist