AI Agent for CMMS Operations
FactVerse AI Agent can help maintenance teams read connected work-order, asset, inspection, sensor, document, and provider data. It should support reviewed decisions: summarize evidence, explain differences, draft recommendations, and prepare handover notes.
Use this guide after CMMS data integration, status mapping, and service-account scopes are ready.
Agent Workflow
Prerequisites
| Requirement | Why it matters |
|---|---|
| Reviewed source data | Agent output depends on current work-order, asset, status, and attachment data |
| Service identity | Agent tools need scoped access to read context and draft actions |
| Review gate | Operational actions need an accountable reviewer |
| Source citation | The answer should show the evidence used for the recommendation |
| Write boundary | Draft, handoff, write-back, and closeout actions need separate permission |
| Feedback path | Accepted and rejected recommendations should feed future workflow improvement |
Source Data Inputs
| Input | Use |
|---|---|
| Work-order history | Summaries, repeated failure review, backlog analysis, and closeout comparison |
| Asset and location context | Equipment identity, site context, system relationship, and digital twin link |
| Inspection findings | Field evidence, checklist results, issue reports, and recurring observations |
| Sensor and alarm events | Condition context for triage and maintenance recommendation |
| ECM documents | SOPs, manuals, photos, service reports, and evidence packages |
| Provider sync state | Explains differences between FactVerse and downstream CMMS states |
| Permission and scope metadata | Controls what the Agent can read, draft, or request |
Supported Tasks
| Task | Example output |
|---|---|
| Asset history summary | Recent work orders, alerts, inspection findings, repeated failures, and open risks |
| Shift handover | High-priority work, blocked work, overdue tasks, new requests, and unresolved exceptions |
| Provider status comparison | Explanation of source status, common status, sync freshness, and owner action |
| Maintenance recommendation draft | Suggested field check, priority, evidence, and work-order draft fields |
| Closeout evidence review | Missing photos, reports, root-cause fields, or follow-up notes |
| Duplicate work-order review | Candidate duplicate records with shared asset, time window, and description similarity |
Governed CMMS Tool Slice
The CMMS tool slice separates read actions, low-risk intake actions, and work-order write actions. The runtime catalog exposes only the tools bound to the tenant's enabled Agent configuration, so a customer deployment can give one Agent read-only access while giving another Agent a reviewed write path.
| Tool | Action | Risk posture | Required permission | Execution behavior |
|---|---|---|---|---|
cmms_query_backlog | Summarize work-order backlog, priority mix, and SLA breach counts | Read-only | cmms.read | Executes immediately after scope and tenant checks |
cmms_query_equipment | List CMMS equipment or assets, optionally by site | Read-only | cmms.read | Executes immediately after scope and tenant checks |
cmms_query_work_orders | List work orders by status, equipment, and page window | Read-only | cmms.read | Executes immediately after scope and tenant checks |
cmms_suggest_technician | Suggest available technicians by required skill | Read-only suggestion | cmms.read | Does not assign work; returns candidates for review |
cmms_create_work_request | File an intake report or work request | Audited intake write | workorders.create | Can execute after review policy allows the request path |
cmms_create_work_order | Create a work order against an equipment asset | Reviewed write | workorders.create | Requires confirmation before the write is executed |
cmms_assign_work_order | Dispatch a work order to a technician or crew | Reviewed write | workorders.assign | Requires confirmation before the write is executed |
cmms_close_work_order | Complete a work order | Reviewed terminal write | workorders.complete | Requires confirmation before the write is executed |
Agent tools should enforce permissions inside the tool path, not only at the UI or controller layer. A read-capable Agent key should not be able to create, assign, or close maintenance work unless the customer has deliberately granted the write scope and review process.
When to Use the CMMS Assistant
Choose the surface that matches the work:
| Need | Recommended surface |
|---|---|
| Ask a question across work orders, equipment, and provider records; prepare one reviewed action | CMMS Assistant |
| Review a queue repeatedly, compare many records, apply filters, or open a known record | CMMS dashboard and operational views |
| Exchange records on a schedule or at system volume | CMMS APIs, connectors, and provider integrations |
The Assistant is useful when the operator knows the operational question but not the exact record or filter path. Use the dashboard for queue management and the integration interfaces for system-to-system synchronization.
Use the CMMS Assistant
The Assistant starts with five visible cards: Work Request, Backlog, Work Orders, Equipment, and Close Work Order. Selecting a card sends its example request, or the user can type a request directly. Technician suggestions, work-order creation, and assignment can also be requested in conversation when the capability is enabled and the user has the required permission. The five cards remain the fixed starting choices.
- Open CMMS Assistant from the CMMS navigation.
- Select a starter card or describe the task in plain language.
- Check the recognized intent, response, evidence, and result cards.
- If the Assistant asks for clarification, provide the missing asset, work-order number, site, status, or other required context.
- If confirmation is required, review the proposed action, target record, evidence, and blockers before selecting Confirm and Dispatch. Select Cancel to leave the operating record unchanged.
- After a successful write, use the returned work-order ID and audit reference to continue in the operational view or review the action history.
Understand the Result
| Assistant element | What it means |
|---|---|
| Intent | The task the Assistant recognized, such as backlog review, equipment lookup, work-order creation, assignment, or closeout |
| Response | The answer, summary, explanation, or proposed action |
| Gate verdict | Whether the request can proceed, needs confirmation, or is blocked |
| Clarification prompt | Information the Assistant still needs before it can continue |
| Evidence and result cards | Work-order, equipment, inspection, alarm, document, and provider records used for the answer |
| Confirmation controls | The explicit choice to approve or cancel a pending write action |
| Work-order ID and service target | The created work-order reference and response target when those values are returned |
| Blockers | Permission, data, policy, or workflow conditions that prevented the next step |
| Audit reference | The run or action record used for later review; depending on the deployment, it can appear in the action history rather than the chat response |
The platform resolves the acting user from the authenticated session or service identity, so no separate user ID entry is needed. Confirmation reuses the same action attempt so a retry does not create a second work order for the same confirmed request.
In multi-provider environments, the Assistant can summarize across normalized records while preserving the source provider and common status. Any handoff or write-back still follows the configured provider ownership, permission, confirmation, and synchronization rules.
Runtime Calling Model
CMMS tools follow the same governed Agent invocation pattern as other FactVerse Agent modules:
- The tenant Agent configuration binds a named Agent to a selected set of CMMS tools.
- The tool catalog lists only the tools bound to the current tenant's Agent configuration.
- A tool call is checked against the Agent's maximum allowed risk level, the tool permission, and the tenant boundary.
- Read-only calls execute and return evidence.
- Intake writes and work-order writes create an audit trail; higher-risk work-order writes require a confirmation step before the action changes the work-order system.
- The call path carries an idempotency key so a retry of the same logical action can be deduplicated by the runtime.
This model is important when CMMS is used above multiple downstream providers. The Agent can summarize and draft across providers, while every action still has a clear permission, reviewer, audit record, and provider handoff result.
Recommended Tool Pattern
- Read the work-order record and source status.
- Read asset identity, location, and related equipment context.
- Read recent work orders, inspections, alarms, and sensor evidence.
- Read relevant ECM documents when a procedure or service report is needed.
- Generate a summary or draft with cited evidence.
- Route draft output to an operator review state.
- Record the final decision and feedback.
Review Gates
| Action | Required review |
|---|---|
| Read-only summary | Confirm source freshness and evidence scope |
| Recommendation draft | Confirm asset identity, safety context, priority, and owner |
| Work-order draft | Confirm provider ownership, status mapping, SLA, and assignment |
| Provider handoff | Confirm target provider, required fields, and source-system response |
| Write-back | Confirm approved field list, retry behavior, and rollback procedure |
| Closeout support | Confirm evidence, root cause, action taken, and final status |
Expected Output
An Agent-assisted CMMS workflow should produce:
- answer or draft tied to source records;
- cited work-order, asset, inspection, sensor, and document evidence;
- clear owner for review and approval;
- action boundary for read, draft, handoff, or write-back;
- recorded feedback after the reviewer accepts, edits, or rejects the output.
Validation Checklist
- Agent answers show the source records used.
- The Agent can explain provider status and common status separately.
- Draft actions remain reviewable before they affect provider workflows.
- Rejected recommendations capture the reason.
- Operator corrections are stored with the workflow record.
- Service account scopes match the intended action level.
Troubleshooting
| Symptom | Check |
|---|---|
| Agent misses recent work | Connector freshness, work-order filter, source status mapping, and sync state |
| Recommendation cites the wrong asset | MDM alias mapping, equipment bridge, and retired asset rule |
| Agent cannot create a draft | Action scope, review gate, tenant enablement, and provider ownership rule |
| Summary conflicts with dashboard | Dataset version, status mapping version, cached context, and sync time |
| Closeout review lacks evidence | ECM links, attachment sync, file permissions, and required evidence policy |