AIA - Assist Spike Usage Alert: OOTB Detection Mechanism (Now Assist AI Agents v6.0+)

Martin Z · 13m ago

Purpose: Technical reference for the OOTB "Assist spike usage alert" mechanism shipped with the Now Assist AI Agents application (sn_aia scope).
Audience: Engineers / Developers — Now Assist AI Agents configuration and operations.
Target version: Now Assist AI Agents v6.0 and later (Yokohama Patch 11+).

🧭 Overview

What problem does this solve?

In Now Assist deployments, anomalous spikes in agentic AI usage — sudden jumps in assist consumption against a particular Use Case or AI Agent — can signal misconfiguration, runaway workflows, prompt-loop bugs, or unexpected user behavior. Without proactive detection, these spikes can drain assist budgets, drive up costs, or degrade user experience before anyone notices.

How does the OOTB mechanism work?

The "Assist spike usage alert" is an OOTB monitoring loop shipped with the Now Assist AI Agents application (sn_aia). The flow is:

A Scheduled Job runs every 3 hours (configurable).

The Script Include AIANotificationService aggregates assist usage per (usecase, agent) over the current rolling window vs. the previous equal-length window.

If both conditions hold — an absolute floor (default: 5,000 assists, configurable) AND a relative growth threshold (default: +50%, configurable) — the event sn_aia.agent_assist_spike is fired.

An Email Notification record dispatches an HTML email to the administrator with deep-links into the affected Use Case and AI Agent.

What this article covers

This article documents each component end-to-end: the Scheduled Job, the Script Include detection algorithm, the event payload, the Email Notification record, recipient resolution behavior (which is admin-only in OOTB), verification queries, and recommended customization paths when admin-only delivery is unsuitable.

📑 Table of Contents

Overview — problem & mechanism summary

Architecture Overview

Scheduled Job

Script Include — AIANotificationService

Event — sn_aia.agent_assist_spike

Email Notification

Verification & Troubleshooting

Customization Considerations

Quick Reference — sys_id Index

Tags

1. Architecture Overview

📐 Architecture diagram — Scheduled Job → Script Include → Aggregation → Event → Email Notification

2. Scheduled Job

Field Value

Table sysauto_script

Name AIA - Assist spike usage alert

sys_id 4bda1720ffa83210f8a8ffffffffff34

Active true

Application scope Now Assist AI Agents (sn_aia)

Run as System Administrator

Run type Periodically

Run period 1970-01-01 03:00:00 → every 3 hours

Conditional false

Advanced true

Script body
var notification = new sn_aia.AIANotificationService();
notification.checkForAssistUsage();
3. Script Include — AIANotificationService

Field Value

Table sys_script_include

Name AIANotificationService

sys_id b4cdabe7ffb322102217ffffffffff05

API name sn_aia.AIANotificationService

Application scope Now Assist AI Agents (sn_aia)

Logger new sn_aia.AIAgentsLogger("AIANotificationService") (writes to syslog_app_scope, source = sn_aia)

3.1 Configuration properties (read at execution time)

All properties are stored in the sn_aia_property table (NOT sys_properties).

Property name Default Validation Purpose

alert.assist_spike_hours_to_check 3 Integer 1–24 Length of the rolling window (in hours) used for current vs. previous comparison.

📌 Note: If changed, the Scheduled Job's run_period must be updated manually to match.

alert.assist_spike_usage_threshold 5000 Positive integer Absolute floor — current-window total must exceed this to be evaluated.

alert.assist_spike_usage_percentage_threshold 0.5 0–1 (float) Relative growth threshold — current must exceed previous × (1 + threshold).

3.2 checkForAssistUsage() — detection algorithm

Step Action Source data

1 Read 3 properties (hours, abs threshold, pct threshold) with validation sn_aia_property

2 Compute the current-window start timestamp: now − hoursToCheck —

3 GlideAggregate on sn_aia_execution_plan filtered by sys_created_on >= current-window start AND gen_ai_usage_log != null, group by usecase + agent, sum gen_ai_usage_log.assists sn_aia_execution_plan JOIN gen_ai_usage_log

4 For each (usecase, agent) group: skip if totalAssists <= assistThreshold (5000) —

5 Compute previous window: [now - 2N, now - N] and aggregate the same fields filtered by the same usecase/agent sn_aia_execution_plan JOIN gen_ai_usage_log

6 If totalAssists > previousTotalAssists × (1 + percentageThreshold): identify the latest execution plan record for the matched usecase or agent sn_aia_execution_plan

7 Fire event: gs.eventQueue('sn_aia.agent_assist_spike', latestExecutionPlanRecord, '', this.uri) sysevent

Both conditions must be met (AND):

Absolute: current window total > assist_spike_usage_threshold

Relative: current window > previous window × (1 + percentage_threshold)

3.3 Logging behavior

The logger is sn_aia.AIAgentsLogger, which wraps sn_log.GlideLogger.

Log level Where to find Filter

INFO / WARN / DEBUG / ERROR Application Logs (syslog_app_scope) source = sn_aia, Source Script = Script Include: AIAgentsLogger

⚠️ Important: The logger's source field is hardcoded to sn_aia (the scope name), NOT to the constructor argument ("AIANotificationService"). The constructor argument is used only as a message prefix.

⚠️ INFO-level logs may be suppressed depending on the verbosity setting for the sn_aia scope. To see INFO logs, raise the scope's log verbosity to Info or Debug temporarily.

3.4 Other methods in this Script Include (for reference, not invoked by this Scheduled Job)

Method Purpose Triggered by

checkForConsecutiveErrorAlerts(usecase, agent) Detect N consecutive failed executions and fire sn_aia.agent_execution_failed Business Rule on sn_aia_execution_plan

checkForConsecutiveHighLatencyAlerts(executionPlanGr) Detect N consecutive high-latency executions and fire sn_aia.agent_p95_tool_latency or sn_aia.agent_p95_llm_latency Business Rule on sn_aia_execution_plan

These are independent of the Scheduled Job and are mentioned only because they share the same Script Include and property infrastructure.

4. Event — sn_aia.agent_assist_spike

Field Value

Table sysevent_register

Event name sn_aia.agent_assist_spike

sys_id 93199b2cff683210f8a8ffffffffff71

Suffix agent_assist_spike

Description "Raised when an execution of an Agentic workflow or an AI agent has a spike on assist usage"

Fired by Scheduled job

Table reference sn_aia_execution_plan

Priority 100

Application scope Now Assist AI Agents (sn_aia)

4.1 Event payload (parameters)

The event is queued via:
gs.eventQueue('sn_aia.agent_assist_spike', latestExecutionPlanRecord, '', this.uri);
Argument Field on sysevent Value

1st: event name name sn_aia.agent_assist_spike

2nd: instance instance sys_id of the latest sn_aia_execution_plan record

3rd: parm1 parm1 Empty string ('')

4th: parm2 parm2 glide.servlet.uri (instance URL, e.g., https://<your-instance>.service-now.com/)

(auto) event creator user gs.getUserID() at the time of eventQueue call = the Scheduled Job's run_as user = System Administrator (admin)

4.2 Important behavior — event creator

⚠️ Because the Scheduled Job's run_as is set to System Administrator, sysevent.user = admin in OOTB.

This is consequential for the Notification's "Send to event creator" recipient resolution (see §5.3).

4.3 Historical note — change from initial implementation

Earlier implementation (prior to v6.0) passed the recipient explicitly:
// Old behavior (initial implementation)
gs.eventQueue('sn_aia.agent_assist_spike', latestExecutionPlanRecord, userId, this.uri);
// where userId = sys_user.sys_id of the agent/usecase creator
The current implementation passes an empty string for parm1. The recipient is now resolved via "Send to event creator" instead of event.parm1. This means alerts now go to the Scheduled Job's run_as user (admin), not the agent/workflow author.

5. Email Notification

5.1 Notification record (sysevent_email_action)

Field Value

Name [name] AI Agent assist spike

sys_id 21e917acff683210f8a8ffffffffff8b

Active [active] true

Type [type] Email

Send when [generation_type] event

Event name [event_name] sn_aia.agent_assist_spike

Table [collection] Execution Plan [sn_aia_execution_plan]

Item [item] event.parm1 (legacy reference — currently empty)

Send to event creator [send_self] true

Force delivery [force_delivery] false

Content type [content_type] text/html

Template [template] [AIA] AI Agent assist spike (505a53ecff683210f8a8ffffffffffc3)

Application scope [sys_scope] Now Assist AI Agents (sn_aia)

5.2 Recipient resolution (OOTB)

Setting Value Effective recipient

Send to event creator [send_self] true sysevent.user = Scheduled Job's run_as = System Administrator (admin)

Recipient users (empty in OOTB) —

Recipient groups (empty in OOTB) —

Recipient fields (empty in OOTB) —

⚠️ In OOTB, the alert email is delivered only to the admin user (the email address registered on the System Administrator user record). It is NOT sent to the AI Agent / Workflow author.

5.3 Email template (sysevent_email_template)

Field Value

Name [name] [AIA] AI Agent assist spike

sys_id 505a53ecff683210f8a8ffffffffffc3

Subject [subject] Spike in AI agent assist usage

Email layout [email_layout] Employee notification layout

Content type [content_type] text/html

Application scope [sys_scope] Now Assist AI Agents (sn_aia)

5.4 Email body (HTML)

The body uses these variables resolved against the sn_aia_execution_plan record:

Variable Resolves to

${event.parm2} Instance URL (from glide.servlet.uri)

${usecase.sys_id} Linked usecase's sys_id (from execution plan)

${usecase.sys_name} Linked usecase's display name

${agent.sys_id} Linked agent's sys_id (from execution plan)

${agent.sys_name} Linked agent's display name

Rendered content (paraphrased for clarity):

An assist usage spike has been detected on an agentic solution.

Agentic workflow: link to /now/agent-studio/usecase-guided-setup/{usecase.sys_id}/params/steps/details

AI Agent: link to /now/agent-studio/agent-setup/{agent.sys_id}

Edit the agentic workflow or AI agent directly, or open the AI Agents Analytics dashboard to view assist trends.

6. Verification & Troubleshooting

6.1 Confirm Scheduled Job execution

What to check Where

Scheduled Job ran /syslog_app_scope_list.do?sysparm_query=source=sn_aia^messageLIKEChecking%20for%20assist%20usage^ORDERBYDESCsys_created_on

Next run time /sys_trigger_list.do?sysparm_query=name=AIA - Assist spike usage alert

Manually execute now Open Scheduled Job record → "Execute Now" UI Action

6.2 Confirm Event was fired

What to check Where

Event records /sysevent_list.do?sysparm_query=name=sn_aia.agent_assist_spike^ORDERBYDESCsys_created_on

Fields to inspect state (processed / ready / error), user (event creator), instance (execution plan sys_id), parm1 (empty), parm2 (instance URL)

6.3 Confirm Email was sent

What to check Table / Nav

Sent / Outbox / Skipped /sys_email_list.do?sysparm_query=subject=Spike in AI agent assist usage^ORDERBYDESCsys_created_on

Email type field meanings sent / send-ready (Outbox) / send-ignored (Skipped) / send-failed (Failed)

Notification evaluation log /sys_email_log_list.do?sysparm_query=notificationLIKEAI Agent assist spike^ORDERBYDESCsys_created_on

7. Customization Considerations

When OOTB behavior (admin-only recipient) is unsuitable, three options exist:

Option Change point Pros Cons

Change Scheduled Job's run_as sysauto_script.run_as field Minimal change; alters event creator The chosen user's ACL governs all aggregate queries; choose carefully

Add explicit recipients to the Notification sysevent_email_action "Who will receive" tab — populate Recipient Users / Groups Multi-recipient support; OOTB logic untouched Decide whether to keep Send to event creator checked

Override the Script Include in a custom Update Set Modify gs.eventQueue to pass a recipient via parm1, and update the Notification to consume event.parm1 Restores per-author notification Diverges from OOTB — upgrade impact must be reviewed

8. Quick Reference — sys_id Index

OOTB record sys_ids are stable across instances (shipped with the plugin):

Component sys_id

Scheduled Job 4bda1720ffa83210f8a8ffffffffff34

Script Include (AIANotificationService) b4cdabe7ffb322102217ffffffffff05

Script Include (AIAgentsLogger) 9f1f99e27f7c1210035737e0fc8665bf

Event registration 93199b2cff683210f8a8ffffffffff71

Notification 21e917acff683210f8a8ffffffffff8b

Email template 505a53ecff683210f8a8ffffffffffc3

Property records (sn_aia_property)

Property sys_id

alert.assist_spike_hours_to_check 431f899dff64f210f8a8ffffffffffaa

alert.assist_spike_usage_threshold 029f4191ffa4f210f8a8ffffffffff54

alert.assist_spike_usage_percentage_threshold 507f4151ffa4f210f8a8ffffffffffb4

🏷️ Tags

#AssistSpike #AssistUsage #NowAssistAIAgents #AIANotificationService #sn_aia #OOTB #AIAgentMonitoring

AIA - Assist Spike Usage Alert: OOTB Detection Mechanism (Now Assist AI Agents v6.0+)

🧭 Overview

What problem does this solve?

How does the OOTB mechanism work?

What this article covers

📑 Table of Contents

1. Architecture Overview

2. Scheduled Job

Script body

3. Script Include — `AIANotificationService`

3.1 Configuration properties (read at execution time)

3.2 `checkForAssistUsage()` — detection algorithm

3.3 Logging behavior

3.4 Other methods in this Script Include (for reference, not invoked by this Scheduled Job)

4. Event — `sn_aia.agent_assist_spike`

4.1 Event payload (parameters)

4.2 Important behavior — event creator

4.3 Historical note — change from initial implementation

5. Email Notification

5.1 Notification record (`sysevent_email_action`)

5.2 Recipient resolution (OOTB)

5.3 Email template (`sysevent_email_template`)

5.4 Email body (HTML)

6. Verification & Troubleshooting

6.1 Confirm Scheduled Job execution

6.2 Confirm Event was fired

6.3 Confirm Email was sent

7. Customization Considerations

8. Quick Reference — sys_id Index

Property records (`sn_aia_property`)

🏷️ Tags

Field	Value
Table	`sysauto_script`
Name	`AIA - Assist spike usage alert`
sys_id	`4bda1720ffa83210f8a8ffffffffff34`
Active	`true`
Application scope	Now Assist AI Agents (`sn_aia`)
Run as	System Administrator
Run type	Periodically
Run period	`1970-01-01 03:00:00` → every 3 hours
Conditional	`false`
Advanced	`true`

Field	Value
Table	`sys_script_include`
Name	`AIANotificationService`
sys_id	`b4cdabe7ffb322102217ffffffffff05`
API name	`sn_aia.AIANotificationService`
Application scope	Now Assist AI Agents (`sn_aia`)
Logger	`new sn_aia.AIAgentsLogger("AIANotificationService")` (writes to `syslog_app_scope`, `source = sn_aia`)

Property name	Default	Validation	Purpose
`alert.assist_spike_hours_to_check`	`3`	Integer 1–24	Length of the rolling window (in hours) used for current vs. previous comparison. 📌 Note: If changed, the Scheduled Job's `run_period` must be updated manually to match.
`alert.assist_spike_usage_threshold`	`5000`	Positive integer	Absolute floor — current-window total must exceed this to be evaluated.
`alert.assist_spike_usage_percentage_threshold`	`0.5`	0–1 (float)	Relative growth threshold — current must exceed `previous × (1 + threshold)`.

Step	Action	Source data
1	Read 3 properties (hours, abs threshold, pct threshold) with validation	`sn_aia_property`
2	Compute the current-window start timestamp: now − hoursToCheck	—
3	`GlideAggregate` on `sn_aia_execution_plan` filtered by `sys_created_on >= current-window start` AND `gen_ai_usage_log != null`, group by `usecase` + `agent`, sum `gen_ai_usage_log.assists`	`sn_aia_execution_plan` JOIN `gen_ai_usage_log`
4	For each `(usecase, agent)` group: skip if `totalAssists <= assistThreshold` (5000)	—
5	Compute previous window: `[now - 2N, now - N]` and aggregate the same fields filtered by the same `usecase`/`agent`	`sn_aia_execution_plan` JOIN `gen_ai_usage_log`
6	If `totalAssists > previousTotalAssists × (1 + percentageThreshold)`: identify the latest execution plan record for the matched usecase or agent	`sn_aia_execution_plan`
7	Fire event: `gs.eventQueue('sn_aia.agent_assist_spike', latestExecutionPlanRecord, '', this.uri)`	`sysevent`

Method	Purpose	Triggered by
`checkForConsecutiveErrorAlerts(usecase, agent)`	Detect N consecutive failed executions and fire `sn_aia.agent_execution_failed`	Business Rule on `sn_aia_execution_plan`
`checkForConsecutiveHighLatencyAlerts(executionPlanGr)`	Detect N consecutive high-latency executions and fire `sn_aia.agent_p95_tool_latency` or `sn_aia.agent_p95_llm_latency`	Business Rule on `sn_aia_execution_plan`

Field	Value
Table	`sysevent_register`
Event name	`sn_aia.agent_assist_spike`
sys_id	`93199b2cff683210f8a8ffffffffff71`
Suffix	`agent_assist_spike`
Description	"Raised when an execution of an Agentic workflow or an AI agent has a spike on assist usage"
Fired by	Scheduled job
Table reference	`sn_aia_execution_plan`
Priority	`100`
Application scope	Now Assist AI Agents (`sn_aia`)

Argument	Field on `sysevent`	Value
1st: event name	`name`	`sn_aia.agent_assist_spike`
2nd: instance	`instance`	sys_id of the latest `sn_aia_execution_plan` record
3rd: parm1	`parm1`	Empty string (`''`)
4th: parm2	`parm2`	`glide.servlet.uri` (instance URL, e.g., `https://<your-instance>.service-now.com/`)
(auto) event creator	`user`	`gs.getUserID()` at the time of `eventQueue` call = the Scheduled Job's `run_as` user = System Administrator (admin)

Field	Value
Name [`name`]	`AI Agent assist spike`
sys_id	`21e917acff683210f8a8ffffffffff8b`
Active [`active`]	`true`
Type [`type`]	Email
Send when [`generation_type`]	`event`
Event name [`event_name`]	`sn_aia.agent_assist_spike`
Table [`collection`]	Execution Plan [`sn_aia_execution_plan`]
Item [`item`]	`event.parm1` (legacy reference — currently empty)
Send to event creator [`send_self`]	`true`
Force delivery [`force_delivery`]	`false`
Content type [`content_type`]	`text/html`
Template [`template`]	`[AIA] AI Agent assist spike` (`505a53ecff683210f8a8ffffffffffc3`)
Application scope [`sys_scope`]	Now Assist AI Agents (`sn_aia`)

Setting	Value	Effective recipient
Send to event creator [`send_self`]	`true`	`sysevent.user` = Scheduled Job's `run_as` = System Administrator (admin)
Recipient users	(empty in OOTB)	—
Recipient groups	(empty in OOTB)	—
Recipient fields	(empty in OOTB)	—

Field	Value
Name [`name`]	`[AIA] AI Agent assist spike`
sys_id	`505a53ecff683210f8a8ffffffffffc3`
Subject [`subject`]	`Spike in AI agent assist usage`
Email layout [`email_layout`]	`Employee notification layout`
Content type [`content_type`]	text/html
Application scope [`sys_scope`]	Now Assist AI Agents (`sn_aia`)

Variable	Resolves to
`${event.parm2}`	Instance URL (from `glide.servlet.uri`)
`${usecase.sys_id}`	Linked usecase's sys_id (from execution plan)
`${usecase.sys_name}`	Linked usecase's display name
`${agent.sys_id}`	Linked agent's sys_id (from execution plan)
`${agent.sys_name}`	Linked agent's display name

What to check	Where
Scheduled Job ran	`/syslog_app_scope_list.do?sysparm_query=source=sn_aia^messageLIKEChecking%20for%20assist%20usage^ORDERBYDESCsys_created_on`
Next run time	`/sys_trigger_list.do?sysparm_query=name=AIA - Assist spike usage alert`
Manually execute now	Open Scheduled Job record → "Execute Now" UI Action

What to check	Where
Event records	`/sysevent_list.do?sysparm_query=name=sn_aia.agent_assist_spike^ORDERBYDESCsys_created_on`
Fields to inspect	`state` (`processed` / `ready` / `error`), `user` (event creator), `instance` (execution plan sys_id), `parm1` (empty), `parm2` (instance URL)

What to check	Table / Nav
Sent / Outbox / Skipped	`/sys_email_list.do?sysparm_query=subject=Spike in AI agent assist usage^ORDERBYDESCsys_created_on`
Email type field meanings	`sent` / `send-ready` (Outbox) / `send-ignored` (Skipped) / `send-failed` (Failed)
Notification evaluation log	`/sys_email_log_list.do?sysparm_query=notificationLIKEAI Agent assist spike^ORDERBYDESCsys_created_on`

Option	Change point	Pros	Cons
Change Scheduled Job's `run_as`	`sysauto_script.run_as` field	Minimal change; alters event creator	The chosen user's ACL governs all aggregate queries; choose carefully
Add explicit recipients to the Notification	`sysevent_email_action` "Who will receive" tab — populate Recipient Users / Groups	Multi-recipient support; OOTB logic untouched	Decide whether to keep `Send to event creator` checked
Override the Script Include in a custom Update Set	Modify `gs.eventQueue` to pass a recipient via `parm1`, and update the Notification to consume `event.parm1`	Restores per-author notification	Diverges from OOTB — upgrade impact must be reviewed

Component	sys_id
Scheduled Job	`4bda1720ffa83210f8a8ffffffffff34`
Script Include (AIANotificationService)	`b4cdabe7ffb322102217ffffffffff05`
Script Include (AIAgentsLogger)	`9f1f99e27f7c1210035737e0fc8665bf`
Event registration	`93199b2cff683210f8a8ffffffffff71`
Notification	`21e917acff683210f8a8ffffffffff8b`
Email template	`505a53ecff683210f8a8ffffffffffc3`

Property	sys_id
`alert.assist_spike_hours_to_check`	`431f899dff64f210f8a8ffffffffffaa`
`alert.assist_spike_usage_threshold`	`029f4191ffa4f210f8a8ffffffffff54`
`alert.assist_spike_usage_percentage_threshold`	`507f4151ffa4f210f8a8ffffffffffb4`

AIA - Assist Spike Usage Alert: OOTB Detection Mechanism (Now Assist AI Agents v6.0+)

🧭 Overview

What problem does this solve?

How does the OOTB mechanism work?

What this article covers

📑 Table of Contents

1. Architecture Overview

2. Scheduled Job

Script body

3. Script Include — AIANotificationService

3.1 Configuration properties (read at execution time)

3.2 checkForAssistUsage() — detection algorithm

3.3 Logging behavior

3.4 Other methods in this Script Include (for reference, not invoked by this Scheduled Job)

4. Event — sn_aia.agent_assist_spike

4.1 Event payload (parameters)

4.2 Important behavior — event creator

4.3 Historical note — change from initial implementation

5. Email Notification

5.1 Notification record (sysevent_email_action)

5.2 Recipient resolution (OOTB)

5.3 Email template (sysevent_email_template)

5.4 Email body (HTML)

6. Verification & Troubleshooting

6.1 Confirm Scheduled Job execution

6.2 Confirm Event was fired

6.3 Confirm Email was sent

7. Customization Considerations

8. Quick Reference — sys_id Index

Property records (sn_aia_property)

🏷️ Tags

3. Script Include — `AIANotificationService`

3.2 `checkForAssistUsage()` — detection algorithm

4. Event — `sn_aia.agent_assist_spike`

5.1 Notification record (`sysevent_email_action`)

5.3 Email template (`sysevent_email_template`)

Property records (`sn_aia_property`)