name: servicenow-ai-agent-studio context: fork user-invocable: false description: Build AI Agent definitions and Agentic Workflows for ServiceNow's AI Agent Studio using the Fluent SDK. Covers AiAgent (autonomous task agents with tools, triggers, and versioned instructions) and AiAgenticWorkflow (orchestrated multi-agent team workflows). Use when creating AI-powered automation in Now Assist Panel or Virtual Agent channels, or when building agent teams that coordinate across records, schedules, or business events. Trigger this skill whenever the user mentions AI agents, AiAgent, AiAgenticWorkflow, agent tools, Now Assist Panel automation, or building AI-powered workflows in ServiceNow, even if they don't explicitly mention the AI Agent Studio.

ServiceNow AI Agent Studio — Fluent SDK

Overview

The AI Agent Studio lets you define autonomous agents that can reason over ServiceNow data, invoke tools, and complete tasks on behalf of users. Two top-level SDK objects cover this domain:

Both are imported from @servicenow/sdk/core. Requires SDK 4.4.0 or higher.

Workflow vs Single Agent Decision Tree

User Request
    |
Does it involve multiple tasks? (AND, THEN, followed by)
    | NO  -> USE SINGLE AI AGENT
    | YES
        |
    Do the tasks require DIFFERENT capability types?
    (e.g., search + summarize, fetch from table A + update table B)
        | NO  -> USE SINGLE AI AGENT (multiple tools, one agent)
        | YES -> USE AI AGENTIC WORKFLOW

Pattern Recognition:

AiAgent vs AiAgenticWorkflow

AiAgent — Core Structure

An agent definition requires five mandatory properties ($id, name, description, agentRole, securityAcl):

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

export const myAgent = AiAgent({
    $id: Now.ID['my_support_agent'],
    name: 'Support Agent',
    description: 'Assists users with common support requests',
    agentRole: 'IT support specialist',
    securityAcl: {
        $id: Now.ID['my_support_agent_acl'],
        type: 'Any authenticated user',
    },
    processingMessage: 'Analyzing your request...',
    postProcessingMessage: 'Task complete.',
    versionDetails: [
        {
            name: 'V1',
            number: 1,
            state: 'published',
            instructions: 'You are a helpful support specialist. Guide users through troubleshooting steps and escalate when needed.',
        },
    ],
})

Required Properties

Key Optional Properties

Version Management

Use versionDetails to manage agent instruction lifecycle:

versionDetails: [
    {
        name: 'V1',
        number: 1,
        state: 'draft',
        instructions: 'Initial instructions...',
    },
    {
        name: 'V2',
        number: 2,
        state: 'published',
        condition: 'priority=1',       // Optional — activates conditionally
        instructions: 'Refined instructions with more detail...',
    },
],

Version states: 'draft' (testing), 'committed', 'published' (active), or 'withdrawn'.

Tools Configuration

Tools give the agent capabilities to act in the system. Declare them in the tools array. See TOOLS-REFERENCE.md for complete tool types, CRUD operations, reference-based tools, OOB tools, and script tool patterns.

Quick overview:

tools: [
    {
        name: 'Look Up Incident',
        type: 'crud',
        executionMode: 'autopilot',
        preMessage: 'Searching for the incident...',
        postMessage: 'Incident details retrieved.',
        inputs: {
            operationName: 'lookup',
            table: 'incident',
            inputFields: [
                { name: 'number', description: 'Incident number to look up', mandatory: true, mappedToColumn: 'number' },
            ],
            queryCondition: 'number={{number}}',
            returnFields: [{ name: 'number' }, { name: 'short_description' }, { name: 'state' }],
        },
    },
]

Execution modes: 'autopilot' (agent runs automatically) or 'copilot' (human must approve).

Trigger Configuration

Agents can activate automatically based on record events or schedules. See TRIGGERS-AND-ENUMS.md for all trigger types, scheduled trigger fields, and triggerStrategy values.

triggerConfig: [
    {
        name: 'High Priority Incident',
        channel: 'nap',
        targetTable: 'incident',
        triggerFlowDefinitionType: 'record_create',
        triggerCondition: 'priority=1',
        objectiveTemplate: 'Resolve incident ${number}',
        active: false,         // Set true to enable
    },
],

Security ACL (securityAcl)

securityAcl is mandatory on both AiAgent and AiAgenticWorkflow. Auto-generates sys_security_acl and sys_security_acl_role records.

// Any authenticated user
securityAcl: {
    $id: Now.ID['my_agent_acl'],
    type: 'Any authenticated user',
}

// Specific roles only
securityAcl: {
    $id: Now.ID['my_agent_acl'],
    type: 'Specific role',
    roles: [
        '282bf1fac6112285017366cb5f867469',  // itil role sys_id
    ]
}

Common role sys_ids: admin = 2831a114c611228501d4ea6c309d626d, itil = 282bf1fac6112285017366cb5f867469, user = b05926fa0a0a0aa7000130023e0bde98

Key distinction: securityAcl controls who can invoke the agent. runAsUser/runAs and dataAccess control which user identity the agent runs under.

Data Access Control

Set either runAsUser (agent) / runAs (workflow) or dataAccess — not both:

// Option A — fixed service account (agent)
runAsUser: 'sys_id_of_service_account',

// Option B — dynamic identity (caller's permissions, restricted to listed roles)
dataAccess: {
    roleList: ['282bf1fac6112285017366cb5f867469'],  // itil role sys_id
    description: 'Restrict to itil role',
},

AiAgenticWorkflow — Multi-Agent Teams

An agentic workflow coordinates a team of agents toward a shared goal:

import { AiAgenticWorkflow, Record } from '@servicenow/sdk/core'

const triageAgent = Record({ table: 'sn_aia_agent', $id: Now.ID['triage_agent'], data: { name: 'Triage Agent' } })
const resolutionAgent = Record({ table: 'sn_aia_agent', $id: Now.ID['resolution_agent'], data: { name: 'Resolution Agent' } })

export const reviewWorkflow = AiAgenticWorkflow({
    $id: Now.ID['incident_review_workflow'],
    name: 'Incident Review Workflow',
    description: 'Coordinates triage and resolution agents for incident management',
    securityAcl: {
        $id: Now.ID['incident_review_workflow_acl'],
        type: 'Specific role',
        roles: ['282bf1fac6112285017366cb5f867469'],
    },
    runAs: 'service_account_sys_id',
    executionMode: 'copilot',
    team: {
        $id: Now.ID['incident_review_team'],
        name: 'Incident Review Team',
        members: [triageAgent, resolutionAgent],
    },
    versions: [{ name: 'V1', number: 1, state: 'published', instructions: 'Triage then resolve incidents.' }],
})

Required Workflow Properties

Key notes:

• team.description is auto-populated from workflow description — do not set it
• Agents must be deployed before creating workflows
• Use the Record API for agent references for portability across instances
• versions (not versionDetails) for workflows

Critical Rules

Instructions Authoring

Writing principles:

• Name tools explicitly in instructions
• Add contingency gates: "DO NOT PROCEED if details are missing"
• Use "from the task" or "from the context" — NOT "from the triggering record"

Reference Files

Deployment Order

1. Create and deploy AI Agents (with securityAcl)
2. Get agent sys_ids from sn_aia_agent
3. Create and deploy workflow with securityAcl and agent sys_ids
4. Verify with run_query on sn_aia_usecase

Build Placement

AI Agent Studio artifacts belong in the Logic layer:

src/
  fluent/
    agents/
      support-agent.now.ts        ← AiAgent definition
      review-workflow.now.ts      ← AiAgenticWorkflow definition
    logic/
      script-includes/
        agent-helpers.now.ts      ← Script Includes called by agent tools