AI Playbooks New in 1.0.0
An operator asks "give me a recommendation about pump 2's condition". Without help the assistant improvises: it guesses the question is about tags, searches the namespace for "pump 2", reads whatever comes back, and may or may not think to check the alarms. It answers differently tomorrow.
A playbook is the engineer writing that procedure down once — read these tags, check these alarms, trend this, then present it like this — so every phrasing of the question gets the same complete answer.
What it is, and what it is not
A playbook is rendered into the assistant's instructions and followed by the model. It is deliberately not a pipeline: the operator's question is open-ended, and a fixed execution path cannot answer "why is it drifting" or "should I be worried".
So a playbook promises influence, not enforcement, and it is worth being blunt about that:
It cannot widen or narrow what an assistant may reach. The fences are the tag scope, the connection fence and the endpoint fence, enforced by the server on every call. → Skills & fences
An instruction in a playbook to read a tag outside the fence is not a hole — it is a step that fails. Which is why the playbook is reduced to the steps its instance can actually take before it is used, silently: an order to read something the fence will refuse cannot be recovered from, because the same instructions have just forbidden searching for an alternative.
For a question that genuinely needs a guaranteed output there is a better tool — a report template, which resolves its numbers deterministically. Playbooks are for the conversational middle.
Where the exact paths earn their place
The assistant is forbidden from guessing a tag path: it must search first and use what comes back verbatim, because a namespace may hold hundreds of thousands of tags and the obvious folder is usually the wrong one.
A playbook is the one place a path can be stated safely — an engineer picked it from the tag browser, so it is known-good. That makes the common questions both faster (no search round-trip) and more accurate (no near-miss tag).
Writing one
Playbooks are authored in the Designer and the pipeline editor, in their own pane, and saved with the project like any other resource.
| Field | What it is for |
|---|---|
| Name | What the model matches a question against. Write it like the question: Pump condition, not pump_pb_v2. |
| Asks | Alternative phrasings. The model generalises from them — two or three cover a question better than ten near-duplicates. |
| Roles | The runtime roles this procedure is for. Empty means everyone. |
| Steps | The procedure, in order. |
| Guidance | What to make of what the steps fetched, in your own words. |
| Answer as | How to present it. |
Roles are applicability, not permission
Naming a role hands that operator the procedure. It grants nothing — reach still comes from the role ceiling and the fences. So one pump screen can carry Pump condition for operators and Pump teardown for maintenance, and each person's assistant is given only the one that is theirs, instead of every procedure on the screen competing to match their question.
These are runtime roles from the project's bound user database — the same names a widget's required-roles list uses. A name no longer in that database simply never matches, which costs one procedure rather than the whole turn.
Steps
| Step | Fetches |
|---|---|
| Read tags | Exact tags, by path. Picked here, so the assistant never has to search. |
| Check alarms | What is alarming under a namespace path, right now. |
| Alarm history | What alarmed under a path over a window, and when. |
| Read relationships | The stored cause→consequence links around a tag. |
| Trend | One tag over a window, so the answer can say which way it is moving. |
| Search manuals | Look the topic up in the ingested documents, and cite it. |
| Run saved query | A saved query an engineer already wrote. Only read queries are listed. |
| Call external system | One named operation on a connected system — an ERP, a CMMS. |
| Read a file | One stored document — a spec sheet, a commissioning record, a CSV of setpoints. |
| Hand to a specialist | Give this part of the question to a saved specialist and use the answer it returns. |
| Calculate a check | A figure the server works out exactly. See below. |
Alarm history and relationships are what make root-cause questions writable. The assistant's method for those is four steps — the alarms, the timeline ordered by raise time, the stored relationships, then the trends — and until those two step kinds existed, a playbook could express only the last of them and half of the first.
Relationships are ground truth an engineer rationalized, not an inference from timing, and the assistant is told to prefer them over anything it infers, and to mark a claim they support as fact rather than likely.
Every step carries a name, never a request. A step naming a query nobody saved, an operation nobody opened, or a specialist nobody created does not become a call — it becomes a step that is refused. And a file's contents are still treated as untrusted reference data, however the file is phrased.
Binding a query's parameters
A Run saved query or Call external system step can fill each declared parameter four ways:
| Mode | Where the value comes from |
|---|---|
| Fixed | A value you chose. |
| From the question | The operator's own words, resolved through the plant vocabulary by the parameter's declared meaning. |
| Window | A relative window the server computes — date arithmetic is the one thing a model must not do. |
| Ask | Tell the assistant to ask the operator rather than guess. |
From the question is named as a resolution, not "use what the user said": passing an operator's own words into a database filter is exactly the failure the plant vocabulary exists to prevent. An exact match is the answer; a probable or ambiguous one is a question to put back to the operator.
A binding left half-filled is dropped, not sent as an empty value — a query whose filter silently disappeared returns a superset that reads exactly like the answer.
Guidance
The steps say what to read; nothing else says what it means. 1180 is not an answer — "the
setpoint is 1150, and sustained drift above it risks coating" is. That judgement is the part an
engineer knows and a model guesses at.
Guidance is free text, unlike the steps, and deliberately so: a step has to be unambiguous enough to render as a tool call, whereas this is the sentence you would say to a new colleague.
It steers the answer and grants nothing. An instruction here to go and read another tag is a silent no-op, because no fence ever sees this text. Anything to fetch is a step.
Answer as
| Option | Renders |
|---|---|
| Short answer (default) | Plain prose stating the values read and where they came from. |
| Dashboard | An inline dashboard of stats, charts and tables. |
| Root cause | A causal graph, with each claim marked fact or likely. |
Checks — the arithmetic the server does
Calculate a check is the only step the server runs rather than the model, and it exists for one reason: arithmetic is where a model's judgement is worth nothing and its reliability is worst. It eyeballs a series and does mental maths, and an alarm count it got wrong reads exactly like one it got right.
So the check is deterministic and the rest of the procedure stays adaptive. The model is handed a figure it only has to explain.
A check has named inputs and one expression:
| Input | Value |
|---|---|
| Tag value | One tag's current value |
| Trend | One tag's history over a window — the list a check averages |
| Active alarms | The alarms under a namespace path |
| Alarm history | The journal events under a path over a window |
| Saved query | A saved query's rows |
| External system | One named operation's response |
The expression is written in the same expression language the platform uses for expression tags,
with lists and maps as first-class values, the comprehension macros (has, all, exists, map,
filter) and indexing, plus the aggregations a check needs: sum, avg, min, max, count and
round.
→ Expression functions
Inputs
speed Trend Plant/Line1/Filler/Speed, the last 8 hours
trips Alarm history Plant/Line1, the last 8 hours
Expression
avg(speed) < 1150 && count(trips) > 3
The model can say a check's name and nothing else. The inputs and the expression are loaded from the saved playbook server-side, exactly as a saved query loads its SQL — so the model can neither compose a calculation nor point one at a different tag, which are the two ways a "give the model a calculator" tool goes wrong.
Every input must be deterministic. A window has to be a fixed or server-computed one, never taken from the question: "three alarms this shift" computed over the wrong six hours is indistinguishable from the right answer.
Checks need the Playbook Checks skill on the assistant and the Calculate playbook checks capability, which is off by default. Each input still needs the read capability that covers it — a check can read exactly what the assistant could have read by hand, and nothing more.
Worked example — pump condition
Name: Pump condition
Asks: how is pump 2 doing · should I be worried about P-102 · pump 2 condition
Roles: (empty — everyone)
Steps
1 Read tags Plant/Area2/PMP02/Amps
Plant/Area2/PMP02/SuctionPressure
Plant/Area2/PMP02/DischargePressure
2 Trend Plant/Area2/PMP02/Amps, the last 8 hours
3 Check alarms Plant/Area2/PMP02
4 Alarm history Plant/Area2, the last 24 hours
5 Calculate a check "drifting"
amps = Trend Plant/Area2/PMP02/Amps, last 8 hours
avg(amps) > 41.5
Guidance
Nameplate is 40 A. Above 42 A sustained means the impeller is wearing or the
discharge is partly blocked — check the strainer before scheduling anything.
Suction below 0.8 bar with normal discharge is cavitation, which is a different
fault and more urgent.
Answer as: Short answer
The operator asks "how is pump 2 doing". The assistant reads three tags it never had to search for, trends one, checks what is alarming, looks at last night's journal, is handed one exact average, and answers with the engineer's own interpretation attached.
Gotchas
- A name that reads like a filename never matches. The model matches questions against the name; write it as the question.
- Steps outside the fence vanish silently. Deliberately — naming a cut step would write an out-of-fence tag path into the assistant's instructions. If a playbook seems to be doing less than it says, check the instance's fences first.
- Guidance cannot fetch. If it says "also check the seal temperature", add a step.
- A specialist step cannot nest. A specialist reached this way cannot itself run a specialist.
- Only read queries are offered, and a mislabelled one is still refused at execution: the statement is validated, not the metadata's claim about it.