ALL ABOUT AI WITH SERVICENOW — Full Demo Master Guide

0.1 Why this part exists

Nine out of ten "ServiceNow AI doesn't work" tickets are not AI problems. They are a missing plugin, a missing role, a Now Assist feature left in inactive state, or a user whose ACLs legitimately block the data the agent is trying to read. Spend ten minutes here and the rest of the guide will not fight you.

0.2 What you need before you start

0.3 Click-path: verify what AI your instance has

1. 1. Open the plugin list: {BASE}/nav_to.do?uri=%2Fsys_plugins_list.do and search the name field for Now Assist, then AI Agent, then AI Search, then Control Tower. Note which are Active.
2. 2. Open the application list (store apps show here even when the plugin list does not): {BASE}/nav_to.do?uri=%2Fsys_store_app_list.do.
3. 3. Try the product URLs directly. These are the fastest truth test:
   Probe these four /now/assist /now/ai-agent-studio /now/ai-control-tower AI Search applications
4. 4. Check the generative AI controller properties: {BASE}/nav_to.do?uri=%2Fsys_properties_list.do%3Fsysparm_query%3Dname%2521LIKEsn_generative_ai. If the list is empty, the generative layer is not provisioned and Parts 2–5 will be read-only for you.
5. 5. Record the result in a scratch note. You will reference it in Part 12.

0.4 The {BASE} convention used in this document

Every link in this guide starts with the literal token {BASE}. Replace it once with your instance origin — for example https://dev12345.service-now.com — and every link becomes clickable. If you want them live permanently, open this file in an editor and do a single find-and-replace of {BASE}.

1.1 The mental model

ServiceNow AI is not one product. It is four layers stacked on the platform, and almost every confusion in the market comes from mixing them up. From the bottom:

1. Data layer. Your tables, CMDB, knowledge bases, attachments, plus external data reached through integrations. This is what AI is allowed to see. Workflow Data Fabric is the branding for connecting and contextualising enterprise data so AI can use it without copying it everywhere.
2. Intelligence layer. The models and retrieval. AI Search (semantic + keyword retrieval), Predictive Intelligence (classic ML: classification, similarity, clustering, regression), and the generative models reached through the Now Assist / generative AI controller — including bring-your-own-model options.
3. Action layer. Things that do work. Now Assist skills (summarise, generate, search answers), AI Agents (goal-driven, use tools, loop until done), Agentic workflows (several agents orchestrated with a trigger and a plan), and Flow Designer / Workflow Studio as the deterministic backbone that agents call into.
4. Governance layer. AI Control Tower — the inventory and control plane over everything above, including non-ServiceNow AI. This is the layer executives ask about and engineers forget.

1.2 Product-by-product, in one line each

1.3 Choosing the right tool — the decision table engineers actually need

2.1 Why start here and not at the agents

An AI Agent is a planner that calls a model. If the generative layer underneath is not configured, the agent will fail with errors that look like permission problems. Now Assist Admin is where the generative layer is turned on, skill by skill, and where you see exactly which features are consuming model calls. Configure it first and the agent work in Part 3 becomes straightforward.

2.2 Click-path: Now Assist Admin

1. 1. Open {BASE}/now/assist. If that redirects, use the filter navigator and type Now Assist Admin.
2. 2. You land on a list of applications (ITSM, CSM, HRSD, Platform/Creator…). Each application contains skills.
3. 3. Pick one application and open it. For each skill you will see: a name, a description of what it does, a state (active/inactive), and configuration such as which table and which fields it reads.
4. 4. Activate one skill to start — Incident summarisation is the classic first choice. Turning on everything at once makes cost attribution impossible later.
5. 5. Save and then open any incident form: {BASE}/nav_to.do?uri=%2Fincident_list.do → open a record with a long work-notes history → the summarise control appears in the form header or the activity area.
6. 6. Review the generative properties: {BASE}/nav_to.do?uri=%2Fsys_properties_list.do%3Fsysparm_query%3Dname%2521LIKEgenerative.

2.3 The skill anatomy — what you are actually configuring

2.4 Otto — what changed in the branding, and what it means for you

ServiceNow has consolidated its assistant experiences under the Otto name: one conversational front door across the platform instead of several separate assistant surfaces. Practically, for an implementer:

• The engine is the same stack you configure in Now Assist Admin and AI Agent Studio. Otto is the entry point users type into.
• Your Virtual Agent topics, Now Assist skills, and AI Agents are all reachable through that single surface — so topic/skill naming hygiene suddenly matters a lot, because the assistant has to choose between them.
• Nothing in Parts 3–10 of this guide changes because of the rename. Build the agents; the surface is how they get invoked.

2.5 Safe first prompts to try

3.1 What an AI Agent is, precisely

Strip the marketing away and an AI Agent is five configuration decisions:

1. Role — who it is pretending to be ("a tier-1 incident triage specialist").
2. Instructions — the operating procedure it must follow, including what it must never do.
3. Tools — the finite set of actions it may take (Part 4).
4. Data access — whose eyes it sees through: the invoking user, or a dedicated AI identity.
5. Completion criteria — how it knows it is finished, and what it hands back.

Everything else — the planning loop, the tool selection, the retries — is the platform's job. Your quality comes almost entirely from decisions 2, 3 and 4.

3.2 Click-path: open the Studio and start the agent

1. 1. Open {BASE}/now/ai-agent-studio, or type AI Agent Studio in the filter navigator and choose Create and manage.
2. 2. You see tabs for Agentic Workflows (use cases) and AI Agents (the workers). First-time instances show a Guided Setup tile — run it; it provisions the roles and default configuration you would otherwise hunt for.
3. 3. Go to the AI Agents tab → New.
4. 4. Fill the identity fields exactly as in the table below.
5. 5. Save. The agent is created in draft — it cannot be triggered by anyone yet, which is exactly what you want.

3.3 The exact field values to type

3.4 Writing instructions that actually work

Paste this as your starting template and adapt the specifics. The structure — mission, procedure, hard limits, output contract — is what matters:

MISSION
Triage one incident record and leave it better documented than you found it.

PROCEDURE
1. Read the incident: number, short_description, description, caller_id, cmdb_ci, category, priority, state.
2. Look up the caller's last 5 incidents. Note any repeat of the same symptom.
3. If cmdb_ci is set, read the CI class, operational status, and any related open incidents on that CI.
4. Decide: category, subcategory, impact, urgency, and the most likely assignment group.
5. Post ONE work note containing: your proposed values, the evidence for each, and your confidence (high/medium/low).

HARD LIMITS
- Never set state to Resolved or Closed.
- Never change caller_id, never delete anything, never email anyone.
- If confidence is low, say so and propose nothing rather than guessing.
- If the incident mentions security, payroll, or a VIP flag, stop and escalate in the work note instead of acting.
- Use only the tools provided. If a needed tool is missing, report that fact.

OUTPUT CONTRACT
Return a short structured summary: proposed_category, proposed_priority, proposed_group, confidence, evidence[].

3.5 Define Data Access — the decision that matters most

In the agent configuration there is a Define Data Access step where you pick the User Identity Type. This is not a cosmetic setting; it determines every ACL evaluation the agent makes.

1. 1. Open your agent → Define Data Access.
2. 2. For this lab choose invoking user first. Run the agent. Note what it could not see.
3. 3. Only then, if a real gap exists, switch to an AI User and add one role at a time until the gap closes.
4. 4. Record the final identity and its roles. Part 6 (Control Tower) and Part 13 (governance) both ask for it.

3.6 Test and evaluate before anyone else sees it

1. 1. In the Studio open the Test panel for your agent.
2. 2. Give it a real record: Triage INC0010001. Watch the execution trace — you should see the plan, each tool call, each tool result, and the final answer.
3. 3. Read the trace, not just the answer. The answer can be right for the wrong reason; the trace tells you whether the reasoning will generalise.
4. 4. Run the three failure cases deliberately: a record with an empty description, a record with no CI, and a record mentioning "security breach". The agent must degrade gracefully in all three.
5. 5. Use the evaluate capability to run a batch of cases and score them, so that your next instruction edit can be compared against a baseline instead of a vibe.

3.7 Where the agent lives in the data model

Studio is a UI over tables. Knowing them lets you query, diff, and ship agents like any other configuration:

Table names in the sn_aia_* family can differ by release and by which store app is installed. If a URL 404s, open {BASE}/nav_to.do?uri=%2Fsys_db_object_list.do%3Fsysparm_query%3Dname%2521LIKEaia and read the actual names on your instance. Doing this once is also the fastest way to learn the real model.

4.1 The principle

A model can only reason. A tool is the bridge from reasoning to doing. Tool design is the highest-leverage engineering work in agentic AI, and the rule is counter-intuitive: fewer, better-described, narrower tools beat many flexible ones. A tool called run_query(table, encodedQuery) is powerful and will be misused; a tool called get_caller_incident_history(user_sys_id, limit) is boring and will be used correctly every time.

4.2 The four tool types you will use

4.3 Build the Script Include behind your tools

1. 1. Open {BASE}/nav_to.do?uri=%2Fsys_script_include.do%3Fsys_id%3D-1.
2. 2. Name: AIAgentTriageTools. Check Client callable = false. Accessible from: This application scope only unless you genuinely need cross-scope.
3. 3. Paste the script below, save, and note the sys_id from the URL — you will reference the class and method when you register each tool.

var AIAgentTriageTools = Class.create();
AIAgentTriageTools.prototype = {

    initialize: function () {
        this.MAX_ROWS = 20;           // hard ceiling: protects context window and cost
        this.instance = gs.getProperty('glide.servlet.uri');
    },

    /**
     * TOOL 1 — get_incident
     * Input : { number: 'INC0010001' }
     * Output: one flat object, display values only, no sys_ids the model does not need
     */
    getIncident: function (number) {
        if (!number) return { error: 'number is required' };
        var gr = new GlideRecord('incident');
        gr.addQuery('number', String(number).trim());
        gr.setLimit(1);
        gr.query();
        if (!gr.next()) return { error: 'incident not found', number: number };

        return {
            number:            gr.getDisplayValue('number'),
            short_description: gr.getDisplayValue('short_description'),
            description:       this._trim(gr.getDisplayValue('description'), 1200),
            caller:            gr.getDisplayValue('caller_id'),
            caller_sys_id:     gr.getValue('caller_id'),
            state:             gr.getDisplayValue('state'),
            priority:          gr.getDisplayValue('priority'),
            impact:            gr.getDisplayValue('impact'),
            urgency:           gr.getDisplayValue('urgency'),
            category:          gr.getDisplayValue('category'),
            subcategory:       gr.getDisplayValue('subcategory'),
            assignment_group:  gr.getDisplayValue('assignment_group'),
            assigned_to:       gr.getDisplayValue('assigned_to'),
            ci:                gr.getDisplayValue('cmdb_ci'),
            ci_sys_id:         gr.getValue('cmdb_ci'),
            business_service:  gr.getDisplayValue('business_service'),
            opened_at:         gr.getDisplayValue('opened_at'),
            reassignments:     gr.getValue('reassignment_count'),
            url:               this.instance + '/incident.do?sys_id=' + gr.getUniqueValue()
        };
    },

    /**
     * TOOL 2 — get_caller_incident_history
     * Narrow on purpose: one user, bounded count, only the fields needed to spot a repeat.
     */
    getCallerHistory: function (callerSysId, limit) {
        if (!callerSysId) return { error: 'callerSysId is required' };
        var max = Math.min(parseInt(limit || 5, 10) || 5, this.MAX_ROWS);

        var out = [];
        var gr = new GlideRecord('incident');
        gr.addQuery('caller_id', callerSysId);
        gr.orderByDesc('opened_at');
        gr.setLimit(max);
        gr.query();
        while (gr.next()) {
            out.push({
                number:            gr.getDisplayValue('number'),
                short_description: gr.getDisplayValue('short_description'),
                category:          gr.getDisplayValue('category'),
                state:             gr.getDisplayValue('state'),
                assignment_group:  gr.getDisplayValue('assignment_group'),
                opened_at:         gr.getDisplayValue('opened_at'),
                resolved_at:       gr.getDisplayValue('resolved_at')
            });
        }
        return { caller: callerSysId, count: out.length, incidents: out };
    },

    /**
     * TOOL 3 — get_ci_context
     * Gives the agent the CMDB picture: class, status, and whether the CI is already on fire.
     */
    getCiContext: function (ciSysId) {
        if (!ciSysId) return { error: 'ciSysId is required' };

        var ci = new GlideRecord('cmdb_ci');
        if (!ci.get(ciSysId)) return { error: 'CI not found', ciSysId: ciSysId };

        var openCount = 0;
        var agg = new GlideAggregate('incident');
        agg.addQuery('cmdb_ci', ciSysId);
        agg.addQuery('active', true);
        agg.addAggregate('COUNT');
        agg.query();
        if (agg.next()) openCount = parseInt(agg.getAggregate('COUNT'), 10) || 0;

        return {
            name:               ci.getDisplayValue('name'),
            ci_class:           ci.getDisplayValue('sys_class_name'),
            operational_status: ci.getDisplayValue('operational_status'),
            support_group:      ci.getDisplayValue('support_group'),
            environment:        ci.getDisplayValue('environment'),
            open_incidents:     openCount,
            url:                this.instance + '/cmdb_ci.do?sys_id=' + ciSysId
        };
    },

    /**
     * TOOL 4 — suggest_assignment_group
     * Deterministic evidence for the model: who historically resolved this category on this CI class.
     * The model decides; this tool only supplies counted facts.
     */
    suggestGroup: function (category, ciClass) {
        var agg = new GlideAggregate('incident');
        if (category) agg.addQuery('category', category);
        if (ciClass)  agg.addQuery('cmdb_ci.sys_class_name', ciClass);
        agg.addQuery('state', 'IN', '6,7');            // resolved / closed
        agg.addNotNullQuery('assignment_group');
        agg.addAggregate('COUNT', 'assignment_group');
        agg.orderByAggregate('COUNT', 'assignment_group');
        agg.query();

        var rows = [];
        while (agg.next() && rows.length < 5) {
            rows.push({
                group: agg.getDisplayValue('assignment_group'),
                resolved_count: parseInt(agg.getAggregate('COUNT', 'assignment_group'), 10)
            });
        }
        return { category: category || null, ci_class: ciClass || null, candidates: rows };
    },

    /**
     * TOOL 5 — post_triage_note
     * The ONLY write this agent can perform. Narrow write tools are how you sleep at night.
     */
    postTriageNote: function (number, noteText) {
        if (!number || !noteText) return { error: 'number and noteText are required' };

        var gr = new GlideRecord('incident');
        gr.addQuery('number', String(number).trim());
        gr.setLimit(1);
        gr.query();
        if (!gr.next()) return { error: 'incident not found', number: number };

        // Refuse to touch records the agent must never write to
        if (gr.getValue('state') === '7') return { error: 'incident is closed; no note written' };

        gr.setValue('work_notes', '[AI Triage] ' + this._trim(noteText, 4000));
        gr.update();
        return { ok: true, number: gr.getDisplayValue('number'), written_chars: noteText.length };
    },

    _trim: function (v, max) {
        v = v == null ? '' : String(v);
        return v.length > max ? v.substring(0, max) + '…' : v;
    },

    type: 'AIAgentTriageTools'
};

4.4 Register each method as a tool in AI Agent Studio

1. 1. Open {BASE}/now/ai-agent-studio → Tools → New.
2. 2. Choose type Script (or "Script tool" / "Script Include" depending on your release label).
3. 3. Fill in, for the first tool:

   Name	get_incident
   Description	Returns the full field set of one incident given its number, e.g. INC0010001. Use this first, before any other tool, to establish the facts of the record.
   Script	new AIAgentTriageTools().getIncident(inputs.number)
   Input	number · string · required · "Incident number like INC0010001"
   Output	Object — map the fields you want the agent to see

4. 4. Repeat for get_caller_incident_history, get_ci_context, suggest_assignment_group, post_triage_note.
5. 5. Open your agent from Part 3 → Tools → attach all five → Save.
6. 6. Re-run the Part 3 test. The trace should now show real tool calls instead of the agent apologising that it has no data.

4.5 A Flow-based tool, for when the agent must write something real

For writes that involve approvals, notifications or integrations, do not script it — wrap it in a Flow and expose the Flow as a tool. You get the platform's error handling, retry, and a visual audit trail that auditors accept.

1. 1. Open Flow Designer: {BASE}/$flow-designer.do (list: {BASE}/nav_to.do?uri=%2Fsys_hub_flow_list.do).
2. 2. New → Subflow. Name: AI Reassign Incident With Approval.
3. 3. Inputs: incident_number (string), target_group (reference sys_user_group), justification (string).
4. 4. Steps: Look Up Record (incident by number) → Ask for Approval (approver = current assignment group manager) → If approved: Update Record (assignment_group, work_notes) → Else: Update Record (work note "AI reassignment declined").
5. 5. Outputs: result (string), approved (boolean).
6. 6. Publish, then register it in Agent Studio as a Flow tool with the description: Requests a human-approved reassignment of an incident. Use only when you are confident of the target group and have stated a justification. The human decides; you do not.

5.1 Agent vs agentic workflow

An agent is a worker. An agentic workflow (in some releases labelled a "use case") is the job: what starts it, which agents participate, what context they share, and what "done" means. You almost never deploy a bare agent — you deploy a workflow that uses one or more agents.

5.2 Click-path: create the agentic workflow

1. 1. {BASE}/now/ai-agent-studio → Agentic Workflows → New.
2. 2. Name: Incident Intake Triage. Objective: Every newly created P1–P3 incident is triaged within 5 minutes with documented evidence and a proposed assignment, without changing state.
3. 3. Add participating agents: your Incident Triage Assistant (and later the specialists from 5.4).
4. 4. Configure the trigger — see 5.3.
5. 5. Set completion criteria: the workflow is done when a triage note exists and a proposal has been produced (or an explicit "insufficient information" has been recorded).
6. 6. Save as Draft, test from the Studio, then activate.

5.3 The four ways an agentic workflow starts

For a scheduled sweep, this is the script to put in the Scheduled Script Execution — it bounds its own work, which is the difference between a nightly job and a nightly outage:

// Scheduled Script Execution: "AI Triage — stale P2 sweep"
// Run: Daily 06:00 · Active: true · Conditional: false
(function runTriageSweep() {

    var MAX_PER_RUN = 25;                       // never let a sweep run unbounded
    var picked = 0;

    var gr = new GlideRecord('incident');
    gr.addEncodedQuery('active=true^priority=2^assignment_groupISEMPTY^sys_created_onRELATIVEGT@hour@ago@24');
    gr.orderBy('sys_created_on');
    gr.setLimit(MAX_PER_RUN);
    gr.query();

    while (gr.next()) {
        try {
            // Fire an event the agentic workflow (or a Flow) subscribes to.
            gs.eventQueue('ai.triage.requested', gr, gr.getValue('number'), gs.getUserID());
            picked++;
        } catch (e) {
            gs.error('[AI triage sweep] ' + gr.getValue('number') + ' → ' + e.message);
        }
    }

    gs.info('[AI triage sweep] queued ' + picked + ' of max ' + MAX_PER_RUN);
})();

5.4 Multi-agent patterns that work in practice

6.1 What problem it solves

Within a year of adopting AI, a typical enterprise has Now Assist skills, a dozen agents, several third-party copilots, some shadow API keys, and no single answer to four questions a board will absolutely ask: what AI do we have, who approved it, what is it doing right now, and what did it return? AI Control Tower is the control plane built for exactly those four questions — and crucially it is vendor-agnostic: it inventories non-ServiceNow AI too, including models, agents, MCP servers and AI identities.

6.2 Click-path

1. 1. Open {BASE}/now/ai-control-tower. Alternatively: filter navigator → All → Workspaces → AI Control Tower.
2. 2. Start on the overview / command centre. Read the headline counts: AI assets, active deployments, pending approvals, risk items.
3. 3. Open AI Inventory. Find the agent you built in Part 3. If it is not there, trigger it once — inventory populates from real registration and usage.
4. 4. Open the record and read its attributes: owner, lifecycle state, data it touches, identity it runs as, associated risks.
5. 5. Open Governance / assessments. Run or review the assessment attached to your agent. Note which questions you cannot answer — those are your real project gaps.
6. 6. Open Runtime / monitoring. Confirm your Part 5 test run is visible with its latency and outcome.
7. 7. Open Value / ROI. Set one baseline metric now (e.g. mean time to triage) so that in 30 days you have a before-and-after instead of an anecdote.

6.3 The four functions, and what each one is for

6.4 Fill these five fields for every agent you ship

7.1 What RAG is, in one paragraph without the hype

Retrieval Augmented Generation means: do not ask the model what it remembers, give it the relevant text and ask it to answer only from that text. Four stages — ingest (collect documents), index (chunk and embed them so they are searchable by meaning), retrieve (find the few chunks that match the question), generate (answer using only those chunks, with citations). Fine-tuning changes the model; RAG changes the context. For enterprise knowledge that edits weekly, RAG is almost always the right answer.

7.2 Implementation A — AI Search + generative answers (the native path)

Admin This is the fastest, most supportable RAG on ServiceNow: the retrieval half already exists, indexed and ACL-aware. You configure sources and let the generative layer answer from them.

1. 1. Open AI Search applications: {BASE}/nav_to.do?uri=%2Fai_search_application_list.do.
2. 2. Open Indexed sources: {BASE}/nav_to.do?uri=%2Fais_datasource_list.do (label may be "Index sources"). Confirm your knowledge base is indexed and the index is current.
3. 3. Create or open a Search profile: {BASE}/nav_to.do?uri=%2Fais_search_profile_list.do. The profile is the scope: which sources, which filters, which relevancy tuning.
4. 4. Restrict the source filter to published, current articles: for kb_knowledge use workflow_state=published^active=true^valid_toONorAfterToday. This single filter removes the most common RAG quality complaint.
5. 5. Verify ACL behaviour — AI Search respects knowledge-base user criteria. Search as a non-admin test user and confirm restricted articles do not appear.
6. 6. Enable the generative answer / Q&A capability in Now Assist Admin ({BASE}/now/assist) and point it at this search profile.
7. 7. Test with a question whose answer lives in exactly one article. The response must cite that article. No citation means it is not retrieving — go back to step 2.

7.3 Implementation B — custom RAG inside ServiceNow (Script Include + your own LLM)

Developer Use this when you need full control of the prompt, want to combine knowledge with live record data, or must call a specific model endpoint. Retrieval still comes from the platform; you own the generation call.

Step 1 — create the outbound REST message for your LLM. {BASE}/nav_to.do?uri=%2Fsys_rest_message.do%3Fsys_id%3D-1

Step 2 — the RAG Script Include. {BASE}/nav_to.do?uri=%2Fsys_script_include.do%3Fsys_id%3D-1 → name RagAnswerService:

var RagAnswerService = Class.create();
RagAnswerService.prototype = {

    initialize: function (options) {
        options = options || {};
        this.topK      = options.topK      || 5;
        this.minScore  = options.minScore  || 0.70;
        this.maxChars  = options.maxChars  || 6000;   // context budget
        this.model     = options.model     || gs.getProperty('rag.llm.model', 'gpt-4o-mini');
        this.restMsg   = 'LLM Chat Completions';
        this.restFn    = 'complete';
        this.instance  = gs.getProperty('glide.servlet.uri');
    },

    /**
     * MAIN ENTRY. answer('What is the leave carry-over limit?')
     * Returns { answer, citations[], used_chunks, grounded:boolean }
     */
    answer: function (question, kbSysIds) {
        if (!question) return { error: 'question is required' };

        var chunks = this._retrieve(question, kbSysIds);
        if (!chunks.length) {
            return {
                answer: 'I could not find anything in the knowledge base that answers this. ' +
                        'Please raise a request so a human can respond.',
                citations: [], used_chunks: 0, grounded: false
            };
        }

        var ctx = this._buildContext(chunks);
        var llm = this._callLlm(this._systemPrompt(), this._userPrompt(question, ctx.text));

        if (llm.error) return { error: llm.error, citations: ctx.citations, grounded: false };

        return {
            answer:      llm.content,
            citations:   ctx.citations,
            used_chunks: chunks.length,
            grounded:    true
        };
    },

    /**
     * RETRIEVE — platform text search over published KB only.
     * Swap this body for an AI Search API call if your instance exposes it;
     * the contract (array of {title, text, number, sys_id, score}) stays the same.
     */
    _retrieve: function (question, kbSysIds) {
        var out = [];
        var gr = new GlideRecord('kb_knowledge');
        gr.addQuery('workflow_state', 'published');
        gr.addQuery('active', true);
        if (kbSysIds && kbSysIds.length) gr.addQuery('kb_knowledge_base', 'IN', kbSysIds.join(','));

        // 123TEXTQUERY321 uses the platform text index and is ACL-filtered for the current user
        gr.addEncodedQuery('123TEXTQUERY321=' + encodeURIComponent(question));
        gr.setLimit(this.topK);
        gr.query();

        while (gr.next()) {
            out.push({
                title:  gr.getDisplayValue('short_description'),
                number: gr.getDisplayValue('number'),
                sys_id: gr.getUniqueValue(),
                text:   this._stripHtml(gr.getDisplayValue('text')),
                url:    this.instance + '/kb_view.do?sys_kb_id=' + gr.getUniqueValue()
            });
        }
        return out;
    },

    /** Build a bounded, labelled context block so the model can cite by number */
    _buildContext: function (chunks) {
        var parts = [], cites = [], budget = this.maxChars;

        for (var i = 0; i < chunks.length; i++) {
            var c = chunks[i];
            var piece = '[' + (i + 1) + '] ' + c.title + ' (' + c.number + ')\n' + c.text;
            if (piece.length > budget) piece = piece.substring(0, budget);
            if (piece.length < 40) break;

            parts.push(piece);
            cites.push({ ref: i + 1, number: c.number, title: c.title, url: c.url });
            budget -= piece.length;
            if (budget <= 200) break;
        }
        return { text: parts.join('\n\n---\n\n'), citations: cites };
    },

    _systemPrompt: function () {
        return [
            'You answer employee questions using ONLY the numbered context provided.',
            'Rules:',
            '1. If the context does not contain the answer, say exactly: "Not covered in our knowledge base." Do not guess.',
            '2. Cite every factual claim with its bracket number, e.g. [2].',
            '3. Be concise: 3 sentences or a short list.',
            '4. Never invent policy numbers, dates, amounts or approver names.',
            '5. Do not mention that you were given context; just answer.'
        ].join('\n');
    },

    _userPrompt: function (question, contextText) {
        return 'CONTEXT:\n' + contextText + '\n\nQUESTION: ' + question + '\n\nANSWER:';
    },

    _callLlm: function (systemMsg, userMsg) {
        try {
            var body = {
                model: this.model,
                temperature: 0,                       // factual task → no creativity
                max_tokens: 500,
                messages: [
                    { role: 'system', content: systemMsg },
                    { role: 'user',   content: userMsg }
                ]
            };

            var r = new sn_ws.RESTMessageV2(this.restMsg, this.restFn);
            r.setRequestBody(JSON.stringify(body));
            r.setHttpTimeout(45000);

            var resp = r.execute();
            var code = resp.getStatusCode();
            var raw  = resp.getBody();

            if (code < 200 || code >= 300) {
                gs.error('[RagAnswerService] LLM HTTP ' + code + ' → ' + raw);
                return { error: 'LLM call failed with HTTP ' + code };
            }

            var parsed = JSON.parse(raw);
            var content = parsed && parsed.choices && parsed.choices[0] &&
                          parsed.choices[0].message ? parsed.choices[0].message.content : '';

            if (!content) return { error: 'LLM returned an empty completion' };
            return { content: content.trim(), usage: parsed.usage || null };

        } catch (e) {
            gs.error('[RagAnswerService] ' + e.message);
            return { error: e.message };
        }
    },

    _stripHtml: function (html) {
        if (!html) return '';
        return String(html)
            .replace(/<style[\s\S]*?<\/style>/gi, ' ')
            .replace(/<script[\s\S]*?<\/script>/gi, ' ')
            .replace(/<[^>]+>/g, ' ')
            .replace(/&nbsp;/g, ' ')
            .replace(/\s+/g, ' ')
            .trim();
    },

    type: 'RagAnswerService'
};

Step 3 — test it. Open {BASE}/$script.do (Scripts — Background) and run:

var svc = new RagAnswerService({ topK: 5, minScore: 0.7 });
var res = svc.answer('What is our annual leave carry-over limit?');
gs.info(JSON.stringify(res, null, 2));

Step 4 — expose it. Register answer() as an AI Agent tool (exactly as in Part 4.4) so any agent can ground itself in knowledge, and/or wrap it in a Scripted REST API (Part 8) so external clients can use it.

7.4 Implementation C — external vector store (when you genuinely need embeddings)

Architect Choose this only when you must: semantic recall across hundreds of thousands of documents, non-ServiceNow corpora, or cross-lingual retrieval. The cost is a second system to run and secure.

7.5 Choosing between the three

8.1 What MCP is and why it matters here

Model Context Protocol is an open standard for connecting AI clients (Cursor, Claude Desktop, agent frameworks) to tools and data through a uniform interface. Instead of every AI client implementing a bespoke ServiceNow integration, you expose ServiceNow once as an MCP server and every compliant client can use it. Conceptually it is the same tool-design discipline as Part 4 — a named tool, a typed input schema, a bounded output — but spoken over a standard protocol instead of inside the platform.

8.2 Architecture decision: where does the MCP server run?

We build the Scripted REST tool surface on ServiceNow first (because that is where the ACLs are), then a thin local MCP server that proxies to it.

8.3 Build the tool surface: Scripted REST API

1. 1. Open {BASE}/nav_to.do?uri=%2Fsys_ws_definition.do%3Fsys_id%3D-1 (Scripted REST APIs → New).
2. 2. Name: AI Tool Surface. API ID: ai_tools. Save. Your base path becomes /api/<scope>/ai_tools.
3. 3. Add resource tools/list: method GET, relative path /tools.
4. 4. Add resource tools/call: method POST, relative path /call.
5. 5. Set Requires authentication = true and require a dedicated role (create x_ai_tool_user at {BASE}/nav_to.do?uri=%2Fsys_user_role.do%3Fsys_id%3D-1).
6. 6. Paste the scripts below into the two resources.

GET /tools — the discovery endpoint. This is literally the tool catalogue your AI client reads:

(function process(request, response) {

    return {
        tools: [
            {
                name: 'get_incident',
                description: 'Return the full field set of one incident by number. Use this first to establish facts.',
                inputSchema: {
                    type: 'object',
                    properties: { number: { type: 'string', description: 'e.g. INC0010001' } },
                    required: ['number']
                }
            },
            {
                name: 'search_incidents',
                description: 'Search incidents with an encoded query. Returns at most 50 rows with key fields. Use for lists and counts, not for single records.',
                inputSchema: {
                    type: 'object',
                    properties: {
                        query: { type: 'string', description: 'ServiceNow encoded query, e.g. active=true^priority=1' },
                        limit: { type: 'integer', description: '1-50, default 10' }
                    },
                    required: ['query']
                }
            },
            {
                name: 'ask_knowledge',
                description: 'Ask a natural-language question and get a cited answer from published knowledge articles only. Returns a refusal when the knowledge base does not cover it.',
                inputSchema: {
                    type: 'object',
                    properties: { question: { type: 'string' } },
                    required: ['question']
                }
            }
        ]
    };

})(request, response);

POST /call — the dispatcher. Note the explicit allow-list: anything not named here cannot be executed, by construction.

(function process(request, response) {

    var body = request.body && request.body.data ? request.body.data : {};
    var name = body.name;
    var args = body.arguments || {};

    // ---- hard allow-list: no dynamic dispatch, ever -------------------------
    var HANDLERS = {

        get_incident: function (a) {
            return new AIAgentTriageTools().getIncident(a.number);
        },

        search_incidents: function (a) {
            if (!a.query) return { error: 'query is required' };

            var limit = Math.min(parseInt(a.limit || 10, 10) || 10, 50);
            var rows = [];

            var gr = new GlideRecord('incident');
            gr.addEncodedQuery(String(a.query));         // runs as the authenticated caller → ACLs apply
            gr.orderByDesc('sys_created_on');
            gr.setLimit(limit);
            gr.query();

            while (gr.next()) {
                rows.push({
                    number:            gr.getDisplayValue('number'),
                    short_description: gr.getDisplayValue('short_description'),
                    state:             gr.getDisplayValue('state'),
                    priority:          gr.getDisplayValue('priority'),
                    assignment_group:  gr.getDisplayValue('assignment_group'),
                    assigned_to:       gr.getDisplayValue('assigned_to'),
                    opened_at:         gr.getDisplayValue('opened_at')
                });
            }
            return { count: rows.length, limit: limit, incidents: rows };
        },

        ask_knowledge: function (a) {
            return new RagAnswerService().answer(a.question);
        }
    };

    if (!name || !HANDLERS[name]) {
        response.setStatus(400);
        return { error: 'unknown tool', requested: name || null, available: Object.keys(HANDLERS) };
    }

    try {
        var started = new Date().getTime();
        var result  = HANDLERS[name](args);

        gs.info('[ai_tools] ' + name + ' by ' + gs.getUserName() +
                ' in ' + (new Date().getTime() - started) + ' ms');

        return { tool: name, result: result };

    } catch (e) {
        gs.error('[ai_tools] ' + name + ' failed: ' + e.message);
        response.setStatus(500);
        return { error: e.message, tool: name };
    }

})(request, response);

Test it from the terminal (replace <scope> with the scope shown on your API record, e.g. x_12345_ai, or global):

# discovery
curl -u 'ai.svc:PASSWORD' \
  'https://yourinstance.service-now.com/api/global/ai_tools/tools'

# call a tool
curl -u 'ai.svc:PASSWORD' -X POST \
  -H 'Content-Type: application/json' \
  -d '{"name":"search_incidents","arguments":{"query":"active=true^priority=1","limit":5}}' \
  'https://yourinstance.service-now.com/api/global/ai_tools/call'

8.4 The local MCP server (Python, ~70 lines)

Install the SDK, then create the server. It advertises the same three tools and proxies each call to the endpoint you just built — so all ACL enforcement stays on the instance where it belongs.

pip install "mcp[cli]" httpx

# servicenow_mcp.py — a minimal MCP server exposing ServiceNow tools to any MCP client
import os
import httpx
from mcp.server.fastmcp import FastMCP

SN_BASE  = os.environ["SN_INSTANCE"].rstrip("/")        # https://dev12345.service-now.com
SN_USER  = os.environ["SN_USER"]
SN_PASS  = os.environ["SN_PASSWORD"]
SN_SCOPE = os.environ.get("SN_SCOPE", "global")

API = f"{SN_BASE}/api/{SN_SCOPE}/ai_tools"

mcp = FastMCP("servicenow")


def _call(name: str, arguments: dict) -> dict:
    """Single choke point: every tool goes through the instance's allow-listed dispatcher."""
    try:
        r = httpx.post(
            f"{API}/call",
            json={"name": name, "arguments": arguments},
            auth=(SN_USER, SN_PASS),
            timeout=45.0,
        )
        r.raise_for_status()
        return r.json().get("result", {})
    except httpx.HTTPStatusError as e:
        return {"error": f"HTTP {e.response.status_code}", "detail": e.response.text[:500]}
    except Exception as e:                                  # network, timeout, parse
        return {"error": str(e)}


@mcp.tool()
def get_incident(number: str) -> dict:
    """Return the full field set of one ServiceNow incident by its number (e.g. INC0010001)."""
    return _call("get_incident", {"number": number})


@mcp.tool()
def search_incidents(query: str, limit: int = 10) -> dict:
    """Search incidents using a ServiceNow encoded query, e.g. 'active=true^priority=1'. Max 50 rows."""
    return _call("search_incidents", {"query": query, "limit": min(max(limit, 1), 50)})


@mcp.tool()
def ask_knowledge(question: str) -> dict:
    """Ask a question and get an answer cited from published ServiceNow knowledge articles only."""
    return _call("ask_knowledge", {"question": question})


if __name__ == "__main__":
    mcp.run()                                               # stdio transport

8.5 Wire it into your editor

Create .cursor/mcp.json in your project (the same shape works for other MCP clients, including Claude Desktop's config file):

{
  "mcpServers": {
    "servicenow": {
      "command": "python",
      "args": ["C:/SVCProject/mcp/servicenow_mcp.py"],
      "env": {
        "SN_INSTANCE": "https://dev12345.service-now.com",
        "SN_USER": "ai.svc",
        "SN_PASSWORD": "***",
        "SN_SCOPE": "global"
      }
    }
  }
}

1. 1. Save the file and restart the editor.
2. 2. Confirm the server shows as connected and lists three tools.
3. 3. Ask in chat: "Using the servicenow tools, show me open P1 incidents and summarise the common theme."
4. 4. Watch the instance side: {BASE}/nav_to.do?uri=%2Fsyslog_list.do%3Fsysparm_query%3Dmessage%2521LIKE%255Bai_tools%255D — your gs.info lines prove exactly which tool ran, as whom, and how long it took.

8.6 ServiceNow as an MCP client

To let a platform agent use an external MCP server, bridge it: create a REST Message pointing at the MCP server's HTTP transport, wrap tools/list and tools/call in a Script Include, and register that Script Include as an AI Agent tool (Part 4). The agent then calls external MCP tools the same way it calls local ones — and every call is auditable on the instance.

9.1 When to use Python instead of staying on-platform

The honest rule: Python is excellent for pipelines and analysis; the platform is where enforcement and workflow belong. Mixing those up is how you end up re-implementing ACLs in a script.

9.2 Authentication — do it properly once

1. 1. Create a service user: {BASE}/nav_to.do?uri=%2Fsys_user.do%3Fsys_id%3D-1. Name ai.python.svc, check Web service access only, set Internal Integration User if your licensing model expects it.
2. 2. Give it the narrowest roles that work. Start with snc_read_only plus explicit table ACLs, and add write capability only when a specific step requires it.
3. 3. For OAuth (preferred over basic auth for anything beyond a lab): {BASE}/nav_to.do?uri=%2Foauth_entity_list.do → New → Create an OAuth API endpoint for external clients. Record the client ID and secret.
4. 4. Store credentials in environment variables. Never in the script, never in the repo.

# Windows PowerShell
$env:SN_INSTANCE = "https://dev12345.service-now.com"
$env:SN_USER     = "ai.python.svc"
$env:SN_PASSWORD = "***"
$env:LLM_BASE    = "https://YOUR_LLM_HOST/v1"
$env:LLM_KEY     = "***"
$env:LLM_MODEL   = "gpt-4o-mini"

# macOS / Linux
export SN_INSTANCE="https://dev12345.service-now.com"
export SN_USER="ai.python.svc"
export SN_PASSWORD="***"
export LLM_BASE="https://YOUR_LLM_HOST/v1"
export LLM_KEY="***"
export LLM_MODEL="gpt-4o-mini"

9.3 The ServiceNow client — reusable, paginated, resilient

pip install httpx tenacity python-dotenv

# sn_client.py — a small, honest ServiceNow REST client
import os
import httpx
from typing import Iterator, Optional
from tenacity import retry, stop_after_attempt, wait_exponential, retry_if_exception_type


class ServiceNowClient:
    """Thin wrapper over the Table API. Paginates, retries, and never swallows errors silently."""

    def __init__(self, instance: str = None, user: str = None, password: str = None, page_size: int = 200):
        self.base = (instance or os.environ["SN_INSTANCE"]).rstrip("/")
        self.auth = (user or os.environ["SN_USER"], password or os.environ["SN_PASSWORD"])
        self.page_size = page_size
        self.http = httpx.Client(timeout=60.0, headers={"Accept": "application/json"})

    # ---------- reads ----------------------------------------------------

    @retry(
        retry=retry_if_exception_type((httpx.TransportError, httpx.HTTPStatusError)),
        stop=stop_after_attempt(4),
        wait=wait_exponential(multiplier=1, min=2, max=20),
        reraise=True,
    )
    def _get(self, url: str, params: dict) -> dict:
        r = self.http.get(url, params=params, auth=self.auth)
        if r.status_code == 429 or r.status_code >= 500:
            r.raise_for_status()            # retryable
        if r.status_code >= 400:
            raise RuntimeError(f"ServiceNow {r.status_code}: {r.text[:400]}")
        return r.json()

    def query(
        self,
        table: str,
        encoded_query: str = "",
        fields: Optional[list] = None,
        limit: Optional[int] = None,
        display_value: str = "all",
    ) -> Iterator[dict]:
        """Yield records page by page. Never loads an unbounded result set into memory."""
        url = f"{self.base}/api/now/table/{table}"
        fetched, offset = 0, 0

        while True:
            page = self.page_size if limit is None else min(self.page_size, limit - fetched)
            if page <= 0:
                return

            params = {
                "sysparm_query": encoded_query,
                "sysparm_limit": page,
                "sysparm_offset": offset,
                "sysparm_display_value": display_value,       # 'all' gives both raw and display
                "sysparm_exclude_reference_link": "true",
            }
            if fields:
                params["sysparm_fields"] = ",".join(fields)

            rows = self._get(url, params).get("result", [])
            if not rows:
                return

            for row in rows:
                yield row

            fetched += len(rows)
            offset  += len(rows)

            if len(rows) < page or (limit is not None and fetched >= limit):
                return

    def get_by_number(self, table: str, number: str) -> Optional[dict]:
        for row in self.query(table, f"number={number}", limit=1):
            return row
        return None

    # ---------- writes ---------------------------------------------------

    def update(self, table: str, sys_id: str, payload: dict) -> dict:
        r = self.http.patch(
            f"{self.base}/api/now/table/{table}/{sys_id}",
            json=payload,
            auth=self.auth,
        )
        if r.status_code >= 400:
            raise RuntimeError(f"Update failed {r.status_code}: {r.text[:400]}")
        return r.json().get("result", {})

    def create(self, table: str, payload: dict) -> dict:
        r = self.http.post(f"{self.base}/api/now/table/{table}", json=payload, auth=self.auth)
        if r.status_code >= 400:
            raise RuntimeError(f"Create failed {r.status_code}: {r.text[:400]}")
        return r.json().get("result", {})

    def call_tool(self, tool: str, arguments: dict, scope: str = "global") -> dict:
        """Call the Part 8 allow-listed dispatcher instead of writing ad-hoc queries."""
        r = self.http.post(
            f"{self.base}/api/{scope}/ai_tools/call",
            json={"name": tool, "arguments": arguments},
            auth=self.auth,
        )
        r.raise_for_status()
        return r.json().get("result", {})

    def close(self):
        self.http.close()

9.4 The LLM client — vendor-neutral, with the two things people forget

# llm_client.py — one base URL, one key, one model. Swap the host, keep the code.
import os
import json
import httpx
from tenacity import retry, stop_after_attempt, wait_exponential


class LlmClient:
    def __init__(self, base: str = None, key: str = None, model: str = None):
        self.base  = (base or os.environ["LLM_BASE"]).rstrip("/")
        self.key   = key or os.environ["LLM_KEY"]
        self.model = model or os.environ.get("LLM_MODEL", "gpt-4o-mini")
        self.http  = httpx.Client(timeout=90.0)
        self.total_prompt_tokens = 0          # (1) people forget to track cost
        self.total_completion_tokens = 0

    @retry(stop=stop_after_attempt(3), wait=wait_exponential(min=2, max=30), reraise=True)
    def chat(self, system: str, user: str, temperature: float = 0.0, max_tokens: int = 700) -> str:
        r = self.http.post(
            f"{self.base}/chat/completions",
            headers={"Authorization": f"Bearer {self.key}", "Content-Type": "application/json"},
            json={
                "model": self.model,
                "temperature": temperature,
                "max_tokens": max_tokens,
                "messages": [
                    {"role": "system", "content": system},
                    {"role": "user", "content": user},
                ],
            },
        )
        r.raise_for_status()
        data = r.json()

        usage = data.get("usage") or {}
        self.total_prompt_tokens     += usage.get("prompt_tokens", 0)
        self.total_completion_tokens += usage.get("completion_tokens", 0)

        return data["choices"][0]["message"]["content"].strip()

    def chat_json(self, system: str, user: str, schema_hint: str) -> dict:
        """(2) people forget that models return prose when you wanted JSON. Be explicit, then validate."""
        sys_msg = (
            system
            + "\n\nReturn ONLY valid JSON matching this shape, with no markdown fence and no commentary:\n"
            + schema_hint
        )
        raw = self.chat(sys_msg, user, temperature=0.0)

        cleaned = raw.strip()
        if cleaned.startswith("```"):                      # strip a fence if the model adds one anyway
            cleaned = cleaned.split("```")[1]
            cleaned = cleaned[4:] if cleaned.lower().startswith("json") else cleaned

        try:
            return json.loads(cleaned)
        except json.JSONDecodeError:
            return {"_parse_error": True, "_raw": raw[:1000]}

    def embed(self, texts: list, model: str = None) -> list:
        """Batch embeddings for the Part 7C pipeline."""
        r = self.http.post(
            f"{self.base}/embeddings",
            headers={"Authorization": f"Bearer {self.key}", "Content-Type": "application/json"},
            json={"model": model or os.environ.get("EMBED_MODEL", "text-embedding-3-small"), "input": texts},
        )
        r.raise_for_status()
        return [item["embedding"] for item in r.json()["data"]]

    @property
    def usage_summary(self) -> dict:
        return {
            "prompt_tokens": self.total_prompt_tokens,
            "completion_tokens": self.total_completion_tokens,
            "total": self.total_prompt_tokens + self.total_completion_tokens,
        }

9.5 The complete pipeline: read incidents → analyse with an LLM → write back

This is the script to run end to end. It is deliberately conservative: dry-run by default, bounded batch, structured output, and it never touches a closed record.

# triage_pipeline.py
# Read recent unassigned incidents, ask the LLM for a structured triage, write a work note back.
# Run:  python triage_pipeline.py            (dry run — prints, writes nothing)
#       python triage_pipeline.py --apply    (writes work notes)

import sys
import json
from sn_client import ServiceNowClient
from llm_client import LlmClient

BATCH_LIMIT = 15        # bounded, always
APPLY = "--apply" in sys.argv

SYSTEM = """You are a senior ITSM triage analyst.
You classify incidents using only the information provided.
You never invent CI names, user names, or policy references.
If the description is too vague to classify, set confidence to "low" and explain what is missing."""

SCHEMA = """{
  "proposed_category": "string",
  "proposed_subcategory": "string",
  "proposed_priority": "1|2|3|4",
  "proposed_group": "string",
  "confidence": "high|medium|low",
  "reasoning": "string, max 400 chars",
  "missing_information": ["string"]
}"""


def build_user_prompt(inc: dict, history: list) -> str:
    hist = "\n".join(
        f"- {h.get('number')}: {h.get('short_description')} [{h.get('category')}] -> {h.get('assignment_group')}"
        for h in history
    ) or "- none"

    return f"""INCIDENT
number: {inc.get('number')}
short_description: {inc.get('short_description')}
description: {(inc.get('description') or '')[:1500]}
caller: {inc.get('caller_id', {}).get('display_value') if isinstance(inc.get('caller_id'), dict) else inc.get('caller_id')}
current_category: {inc.get('category')}
current_priority: {inc.get('priority')}
configuration_item: {inc.get('cmdb_ci', {}).get('display_value') if isinstance(inc.get('cmdb_ci'), dict) else inc.get('cmdb_ci')}

CALLER HISTORY (most recent first)
{hist}

Classify this incident."""


def main():
    sn  = ServiceNowClient()
    llm = LlmClient()

    query = "active=true^assignment_groupISEMPTY^sys_created_onRELATIVEGT@hour@ago@48"
    fields = ["sys_id", "number", "short_description", "description",
              "caller_id", "category", "priority", "state", "cmdb_ci"]

    processed, skipped = 0, 0

    for inc in sn.query("incident", query, fields=fields, limit=BATCH_LIMIT):
        number = inc["number"] if isinstance(inc["number"], str) else inc["number"]["value"]

        # never touch closed/resolved records, even if the query drifts
        state = inc.get("state")
        state_val = state.get("value") if isinstance(state, dict) else state
        if state_val in ("6", "7"):
            skipped += 1
            continue

        caller = inc.get("caller_id")
        caller_id = caller.get("value") if isinstance(caller, dict) else caller
        history = []
        if caller_id:
            history = list(sn.query(
                "incident",
                f"caller_id={caller_id}^number!={number}",
                fields=["number", "short_description", "category", "assignment_group"],
                limit=5,
            ))

        result = llm.chat_json(SYSTEM, build_user_prompt(inc, history), SCHEMA)

        if result.get("_parse_error"):
            print(f"[parse-error] {number}: {result['_raw'][:200]}")
            skipped += 1
            continue

        note = (
            "[AI Triage - python pipeline]\n"
            f"Proposed category: {result.get('proposed_category')} / {result.get('proposed_subcategory')}\n"
            f"Proposed priority: {result.get('proposed_priority')}\n"
            f"Proposed group:    {result.get('proposed_group')}\n"
            f"Confidence:        {result.get('confidence')}\n"
            f"Reasoning:         {result.get('reasoning')}\n"
        )
        if result.get("missing_information"):
            note += "Missing info:      " + "; ".join(result["missing_information"]) + "\n"
        note += "\nThis is a suggestion. A human decides."

        if APPLY and result.get("confidence") in ("high", "medium"):
            sys_id = inc["sys_id"] if isinstance(inc["sys_id"], str) else inc["sys_id"]["value"]
            sn.update("incident", sys_id, {"work_notes": note})
            print(f"[written] {number} ({result.get('confidence')})")
        else:
            print(f"[dry-run] {number}\n{note}\n{'-' * 60}")

        processed += 1

    print(json.dumps({
        "processed": processed,
        "skipped": skipped,
        "applied": APPLY,
        "tokens": llm.usage_summary,
    }, indent=2))

    sn.close()


if __name__ == "__main__":
    main()

9.6 Scheduling it, and the three ways to be wrong

Log every run back into the instance so the work is visible where the work lives — create u_ai_pipeline_run with fields name, started, finished, processed, skipped, tokens, status, error, and have the script create() a row at the end. Then build one report on it. That single table turns "some Python runs somewhere" into a governed, monitored integration.

10.1 What the SDK is and why it belongs in an AI guide

The ServiceNow SDK (with the Fluent TypeScript DSL) lets you define platform artefacts — tables, fields, Script Includes, business rules, roles, ACLs, records — as code in a local project, then build and deploy them to an instance. It matters for AI work for two reasons. First, agent tools are code, and code belongs in version control with reviews and diffs rather than in a Studio text area. Second, AI coding assistants are dramatically more effective against a local TypeScript project than against a browser form — which is the whole point of pairing the SDK with Cursor and an MCP server from Part 8.

10.2 Install and authenticate

# 0) prerequisites
node -v                      # Node 18+ required
npm -v

# 1) create the project folder
mkdir hr-leave-ai-sdk && cd hr-leave-ai-sdk
npm init -y

# 2) install the SDK as a dev dependency (project-local, reproducible)
npm install -D @servicenow/sdk@latest

# 3) add an authentication profile for your instance
#    This opens a browser / prompts for credentials and stores a named profile.
npx @servicenow/sdk auth --add https://dev12345.service-now.com

# 4) list the profiles you have
npx @servicenow/sdk auth --list

# 5) scaffold the project (asks for app name, scope, and the auth profile to use)
npx @servicenow/sdk init

10.3 The complete command reference

10.4 Project layout

hr-leave-ai-sdk/
├─ now.config.json              # app name, scope, version, dependencies, instance config
├─ package.json                 # scripts: build, deploy
├─ src/
│  └─ fluent/
│     ├─ index.now.ts           # entry point — imports every other definition
│     ├─ tables.now.ts          # table + field definitions
│     ├─ roles.now.ts           # roles
│     ├─ acls.now.ts            # access controls
│     ├─ script-includes.now.ts # server-side classes (your AI tools live here)
│     ├─ business-rules.now.ts  # business rules
│     └─ records.now.ts         # seeded data / configuration records
└─ dist/                        # build output (do not commit)

10.5 Build the application: AI Triage Audit, end to end

A small but genuinely useful app: a table that records every AI triage decision, a role, ACLs, the tool class from Part 4, and a business rule. This is the artefact that makes your AI auditable.

Step 1 — the table. src/fluent/tables.now.ts:

import { Table, StringColumn, ChoiceColumn, IntegerColumn,
         ReferenceColumn, GlideDateTimeColumn, BooleanColumn } from '@servicenow/sdk/core'

export const x_ai_triage_audit = Table({
  name: 'x_ai_triage_audit',
  label: 'AI Triage Audit',
  display: 'number',
  audit: true,                       // every AI decision row is itself audited
  schema: {
    number: StringColumn({
      label: 'Number', maxLength: 40, read_only: true,
    }),
    incident: ReferenceColumn({
      label: 'Incident', referenceTable: 'incident', mandatory: true,
    }),
    agent_name: StringColumn({ label: 'Agent', maxLength: 120 }),
    identity_used: StringColumn({ label: 'Identity used', maxLength: 120 }),
    proposed_category: StringColumn({ label: 'Proposed category', maxLength: 80 }),
    proposed_priority: ChoiceColumn({
      label: 'Proposed priority',
      choices: {
        '1': { label: '1 - Critical' },
        '2': { label: '2 - High' },
        '3': { label: '3 - Moderate' },
        '4': { label: '4 - Low' },
      },
    }),
    proposed_group: ReferenceColumn({
      label: 'Proposed group', referenceTable: 'sys_user_group',
    }),
    confidence: ChoiceColumn({
      label: 'Confidence',
      choices: {
        high:   { label: 'High' },
        medium: { label: 'Medium' },
        low:    { label: 'Low' },
      },
    }),
    reasoning: StringColumn({ label: 'Reasoning', maxLength: 4000 }),
    tool_calls: IntegerColumn({ label: 'Tool calls' }),
    tokens_used: IntegerColumn({ label: 'Tokens used' }),
    duration_ms: IntegerColumn({ label: 'Duration (ms)' }),
    accepted_by_human: BooleanColumn({ label: 'Accepted by human' }),
    decided_at: GlideDateTimeColumn({ label: 'Decided at' }),
  },
})

Step 2 — the role. src/fluent/roles.now.ts:

import { Role } from '@servicenow/sdk/core'

export const ai_triage_auditor = Role({
  name: 'x_ai_triage_auditor',
  description: 'Can read AI triage audit records and report on AI decision quality.',
  elevated_privilege: false,
})

Step 3 — access control. src/fluent/acls.now.ts:

import { Acl } from '@servicenow/sdk/core'

// Read: auditors and ITIL. Write: nobody interactively — the platform writes these rows.
export const audit_read = Acl({
  name: 'x_ai_triage_audit',
  operation: 'read',
  type: 'record',
  admin_overrides: true,
  active: true,
  roles: ['x_ai_triage_auditor', 'itil'],
})

export const audit_no_delete = Acl({
  name: 'x_ai_triage_audit',
  operation: 'delete',
  type: 'record',
  admin_overrides: false,          // not even admin, from the UI
  active: true,
  script: 'answer = false;',
})

Step 4 — the Script Include. src/fluent/script-includes.now.ts:

import { ScriptInclude } from '@servicenow/sdk/core'

export const AiTriageAudit = ScriptInclude({
  name: 'AiTriageAudit',
  description: 'Writes one audit row per AI triage decision. Called by agent tools and by the Python pipeline.',
  client_callable: false,
  access: 'package_private',
  active: true,
  script: `var AiTriageAudit = Class.create();
AiTriageAudit.prototype = {

    initialize: function () {
        this.table = 'x_ai_triage_audit';
    },

    /**
     * log({ incident_sys_id, agent_name, identity_used, proposed_category,
     *       proposed_priority, proposed_group, confidence, reasoning,
     *       tool_calls, tokens_used, duration_ms })
     */
    log: function (d) {
        d = d || {};
        if (!d.incident_sys_id) return { error: 'incident_sys_id is required' };

        var gr = new GlideRecord(this.table);
        gr.initialize();
        gr.setValue('incident',           d.incident_sys_id);
        gr.setValue('agent_name',         d.agent_name || 'unknown');
        gr.setValue('identity_used',      d.identity_used || gs.getUserName());
        gr.setValue('proposed_category',  d.proposed_category || '');
        gr.setValue('proposed_priority',  d.proposed_priority || '');
        gr.setValue('proposed_group',     d.proposed_group || '');
        gr.setValue('confidence',         d.confidence || 'low');
        gr.setValue('reasoning',          String(d.reasoning || '').substring(0, 4000));
        gr.setValue('tool_calls',         parseInt(d.tool_calls || 0, 10));
        gr.setValue('tokens_used',        parseInt(d.tokens_used || 0, 10));
        gr.setValue('duration_ms',        parseInt(d.duration_ms || 0, 10));
        gr.setValue('decided_at',         new GlideDateTime());

        var id = gr.insert();
        return id ? { ok: true, sys_id: id } : { error: 'insert failed' };
    },

    type: 'AiTriageAudit'
};`,
})

Step 5 — the business rule. src/fluent/business-rules.now.ts:

import { BusinessRule } from '@servicenow/sdk/core'

export const stamp_audit_number = BusinessRule({
  name: 'Stamp AI triage audit number',
  table: 'x_ai_triage_audit',
  when: 'before',
  action: ['insert'],
  order: 100,
  active: true,
  script: `(function executeRule(current, previous) {
    if (!current.number) {
        current.number = 'AIT' + new GlideDateTime().getNumericValue().toString().slice(-10);
    }
})(current, previous);`,
})

export const mark_human_decision = BusinessRule({
  name: 'Mark AI proposal accepted',
  table: 'incident',
  when: 'after',
  action: ['update'],
  order: 200,
  active: true,
  // Only run when the fields an AI proposal targets actually changed
  condition: 'current.assignment_group.changes() || current.category.changes()',
  script: `(function executeRule(current, previous) {
    var audit = new GlideRecord('x_ai_triage_audit');
    audit.addQuery('incident', current.getUniqueValue());
    audit.addQuery('accepted_by_human', false);
    audit.orderByDesc('sys_created_on');
    audit.setLimit(1);
    audit.query();

    if (audit.next()) {
        var matched = (audit.getValue('proposed_group') === current.getValue('assignment_group')) ||
                      (audit.getValue('proposed_category') === current.getValue('category'));
        if (matched) {
            audit.setValue('accepted_by_human', true);
            audit.update();
        }
    }
})(current, previous);`,
})

Step 6 — wire it all up. src/fluent/index.now.ts:

import './tables.now'
import './roles.now'
import './acls.now'
import './script-includes.now'
import './business-rules.now'
import './records.now'

Step 7 — build and deploy.

npx @servicenow/sdk build
npx @servicenow/sdk deploy --auth dev

# verify on the instance
# table:          {BASE}/x_ai_triage_audit_list.do
# app record:     {BASE}/nav_to.do?uri=%2Fsys_app_list.do
# script include: {BASE}/nav_to.do?uri=%2Fsys_script_include_list.do%3Fsysparm_query%3Dname%3DAiTriageAudit
# business rules: {BASE}/nav_to.do?uri=%2Fsys_script_list.do%3Fsysparm_query%3Dtable%3Dx_ai_triage_audit

Step 8 — close the loop with the agent. Add one line to the end of your agent's write tool (Part 4.3, postTriageNote) so every decision is audited:

new AiTriageAudit().log({
    incident_sys_id:   gr.getUniqueValue(),
    agent_name:        'Incident Triage Assistant',
    identity_used:     gs.getUserName(),
    proposed_category: proposal.category,
    proposed_priority: proposal.priority,
    proposed_group:    proposal.group_sys_id,
    confidence:        proposal.confidence,
    reasoning:         proposal.reasoning,
    tool_calls:        proposal.tool_calls,
    duration_ms:       proposal.duration_ms
});

11.1 How the screens in this guide work

Every Screen block above is drawn with CSS, not a bitmap — so it stays readable at any zoom, never goes stale, and contains no customer data. Use them as the target: capture the equivalent real screenshot from your own instance and drop it in beside the conceptual frame. That pairing — "this is the idea, this is our instance" — is what makes an internal enablement deck credible.

11.2 The capture list

Save real screenshots as PNG into HR_Leave_App/html/assets/shots-ai-full-demo/ using these exact filenames, then the markup snippet below will pick them up.

Drop a real screenshot in beside any conceptual frame with this snippet:

<figure class="shot">
  <img src="assets/shots-ai-full-demo/09-control-tower.png"
       alt="AI Control Tower command centre on our instance"
       style="display:block;width:100%;height:auto" />
  <figcaption class="shot-cap">
    <strong>Our instance — AI Control Tower.</strong> Captured 2026-10-05, 34 assets, 2 open risks.
  </figcaption>
</figure>

Run these in order. Record pass/fail. Any failure below TS-18 is a blocker; TS-19 onward are hardening checks you should still fix before production.

13.1 The seven controls that actually prevent incidents

13.2 Cost control, in order of impact

1. Narrow the trigger. Moving from "all incidents" to "P1–P3 on create" is often a 10× reduction. Nothing else comes close.
2. Cap the context. A context budget per call bounds your worst case; without it, one enormous record sets your monthly peak.
3. Right-size the model. Classification and extraction rarely need your largest model. Measure quality on the TS table before paying for capability you cannot detect.
4. Deduplicate. Do not re-summarise a record that has not changed. Store a hash or compare sys_updated_on against the last run.
5. Prefer classic ML where it fits. Predictive Intelligence categorisation costs a fraction of an LLM call and is more explainable.
6. Measure per use case. Token counts in the audit table, reported weekly. "Which agent costs what" must be a report, not an estimate.

13.3 Anti-patterns — each one is a real post-mortem

14.1 Complete URL catalog

Replace {BASE} once with your instance origin. Where a nav_to.do?uri= form is given, it opens the list inside the standard UI frame; the bare *.do form opens it standalone.

14.2 The 2–3 hour study plan

14.3 Final go-live checklist