Skip to main content
Version: 4.5.0

Function: AiAgent(config)

Creates an AI Agent definition for ServiceNow's AI Agent Studio.

Parameters​

config​

AiAgent

Properties:

  • $id (required): string | number | ExplicitKey<string>

  • agentRole (required): string Describes the agent's role or purpose in the system (e.g., 'IT Support Assistant', 'HR Onboarding Guide'). Used for categorization and discovery

  • description (required): string Brief explanation of what this agent does and when to use it. Shown in agent selection interfaces and documentation

  • name (required): string Human-readable name shown in the UI and used to identify the agent. Must be unique within the scope

  • acl (optional): string | Record<'sys_security_acl'> | Acl<unknown, AclType> Access control list that determines which users can execute this agent. Provide either a sys_id string or a Record reference to a sys_security_acl

  • active (optional): boolean Controls whether the agent is available for use. Inactive agents are hidden from selection but not deleted. Defaults to true

  • advancedMode (optional): boolean Enables advanced configuration options and features for power users. Defaults to false

  • agentConfigSysOverrides (optional): string | Record<'sn_aia_agent_config'> Reference to overrides for agent config (another agent config)

  • agentLearning (optional): boolean Allows the agent to learn from interactions and improve over time. When enabled, the agent stores feedback for training. Defaults to false

  • agentType (optional): AiAgentAgentType Specifies whether this is an internal ServiceNow agent or integrates with an external AI service. Defaults to 'internal'

  • channel (optional): AiAgentChannelType Determines where the agent is available: 'nap' (Now Assist Panel only) or 'nap_and_va' (both Now Assist and Virtual Agent). Defaults to 'nap_and_va'

  • compiledHandbook (optional): string Compiled handbook for the agent

  • condition (optional): string Condition table reference

  • contextProcessingScript (optional): string | (context: any, dependencies: any[]) => any Server-side script that transforms or enriches the context before the agent executes. Use this to add data, filter information, or prepare inputs. Can be a function or Now.include() reference

  • dataAccess (optional): DataAccessConfigType Configures which roles can access data through this agent. Required when runAsUser is not specified. Use roleList to restrict access to specific roles

  • docUrl (optional): string Link to external documentation or help content for this agent. Shown to users who need more information about capabilities and usage

  • external (optional): boolean Whether the agent is external

  • externalAgentConfiguration (optional): string | Record<'sn_aia_external_agent_configuration'> Reference to an external agent configuration

  • iconUrl (optional): string URL to a custom icon image that represents this agent in the UI. Use for visual identification and branding

  • memoryCategories (optional): AiAgentMemoryCategory[] Categories of long-term memory the agent is allowed to access. Each category maps to a ServiceNow AI Agent Memory Category record

  • parent (optional): string | Record<'sn_aia_agent'> Reference to the parent AI Agent

  • postProcessingMessage (optional): string Message shown to users after the agent finishes execution. Use to provide next steps, summarize results, or offer additional guidance

  • processingMessage (optional): string Message shown to users while the agent is working. Use to set expectations about wait time or explain what's happening

  • public (optional): boolean Controls whether the agent appears in public catalogs and can be discovered by all users. Private agents are only visible to specific roles. Defaults to false

  • recordType (optional): AiAgentRecordType Classifies the agent's lifecycle stage: 'template' (reusable pattern), 'aia_internal' (system agent), 'custom' (user-created), or 'promoted' (elevated from custom). Defaults to 'template'

  • runAsUser (optional): string | Record<'sys_user'> Specifies which user's permissions the agent uses when accessing data. Provide a sys_user sys_id or Record reference. When set, dataAccess configuration is optional

  • sourceId (optional): string | Record<'sn_aia_agent'> Reference to the source agent (for cloned agents)

  • sysDomain (optional): string Domain ID

  • tools (optional): AiAgentToolDetailsType[] Array of tools and capabilities available to the agent. Tools enable actions like web search, CRUD operations, subflow execution, and custom scripts

    • name: string Name of the tool

    • active: boolean Whether the tool is active

    • description: string Description of the tool

    • displayOutput: boolean Whether to display the tool output

    • documentStatus: ToolDocumentStatus Document status for the tool

    • executionMode: ToolExecutionMode Execution mode for the tool (autopilot or copilot)

    • m2mSysOverrides: string | Record<'sn_aia_agent_tool_m2m'> Reference to overrides for tool usage in agent (sn_aia_agent_tool_m2m)

    • maxAutoExecutions: number Maximum number of automatic executions

    • outputTransformationStrategy: OutputTransformationStrategy Strategy for transforming the tool output

    • postMessage: string Message to display after tool execution

    • postProcessingScript: string | (result: any, inputs: any, dependencies: any[]) => any Script to execute after the tool runs

    • preMessage: string Message to display before tool execution

    • preRun: boolean Whether to run this tool before other tools

    • recordType: AiAgentToolRecordType Record type for the tool (custom, promoted, or template)

    • sysOverrides: string | Record<'sn_aia_tool'> Reference to overrides for tool definition (sn_aia_tool)

    • timeout: string Timeout duration for tool execution

    • toolAttributes: object Additional attributes for the tool - structured as an object

    • transformationInstructions: string Instructions for transforming the tool output

    • type: 'topic' | 'script' | 'catalog' | 'action' | 'subflow' | 'capability' | 'crud' | 'deep_research' | 'desktop_automation' | 'file_upload' | 'knowledge_graph' | 'mcp' | 'rag' | 'topic_block' | 'web_automation'

    • widgets: (string | Record<'sn_aia_widget'>)[] Widgets associated with the tool

  • triggerConfig (optional): AiAgentTriggerConfigType[] Defines conditions and schedules for automatic agent execution. Use triggers to run agents on record changes, time schedules, or business events

    • channel: string Messaging channel for the trigger (defaults to Now Assist Panel)

    • name: string Name of the trigger

    • objectiveTemplate: string Template for the objective message (defaults to "Help me resolve ${number}")

    • active: boolean Whether the trigger is active (defaults to false)

    • businessRule: string | Record<'sys_script'> | BusinessRule<unknown> Business rule to execute when triggered

    • description: string Description of the trigger

    • domain: string Domain ID

    • enableDiscovery: boolean Whether to enable trigger discovery (defaults to false)

    • m2mSysOverrides: string | Record<'sn_aia_trigger_agent_usecase_m2m'> Reference to override the trigger-agent-usecase mapping (sn_aia_trigger_agent_usecase_m2m)

    • notificationScript: string | Record<'sys_script_client'> | ClientScriptProps<unknown, client_script_events, boolean> Client script for handling notifications

    • portal: string | Record<'now_assist_deployment_channel'> Now Assist deployment channel

    • profile: string | Record<'now_assist_deployment'> Now Assist deployment profile

    • runAs: string Field name to use for determining the run-as user

    • runAsScript: string | (context: unknown, dependencies: unknown[]) => string Script to determine which user to run as

    • runAsUser: string | Record<'sys_user'> Reference to User who runs the trigger (user sys_id or Record<'sys_user'>)

    • schedule: ScheduleConfigType Schedule configuration - used for scheduled triggers (scheduled, daily, weekly, monthly)

    • showNotifications: boolean Whether to show notifications when the trigger fires

    • sysOverrides: string | Record<'sn_aia_trigger_configuration'> Reference to another trigger configuration to override

    • targetTable: unknown Table that the trigger monitors

    • triggerCondition: string Condition script that determines when the trigger fires

    • triggerFlow: string | Record<'sys_hub_flow'> Flow to execute when triggered

    • triggerFlowDefinitionType: TriggerFlowDefinitionType Type of trigger flow definition

    • usecase: string | Record<'sn_aia_usecase'> Use case associated with this trigger

    • usecaseDiscovery: boolean Whether to enable use case discovery

  • versionDetails (optional): AiAgentVersionDetailsType[] Manages multiple versions of agent instructions. Each version can have different prompts, conditions, and states (draft/published). Enables A/B testing and gradual rollouts

    • condition: string Condition string for this version

    • instructions: string Instructions that guide the agent's behavior for this version

    • name: string Version name

    • number: number Version number

    • state: AiAgentVersionState State of the version

Examples​

Agent with Custom CRUD Tool​

import { AiAgent } from "@servicenow/sdk/core";

/**
 * @title Agent with Custom CRUD Tool
 */
AiAgent({
  $id: Now.ID["crud_agent"],
  name: "CRUD Agent",
  description: "Agent with CRUD operations",
  agentRole: "Data manager",
  acl: "",
  versionDetails: [
    {
      name: "V1",
      number: 1,
      state: "published",
      instructions: "Manage records in the database...",
    },
  ],
  tools: [
    {
      name: "Save Record",
      type: "crud",
      recordType: "custom",
      executionMode: "autopilot",
      inputs: {
        operationName: "create",
        table: "x_my_app_table",
        inputFields: [
          {
            name: "title",
            description: "Record title",
            mandatory: true,
            mappedToColumn: "title",
          },
        ],
      },
    },
  ],
});

Agent with out of the box Web Search Tool​

import { AiAgent } from "@servicenow/sdk/core";

/**
 * @title Agent with out of the box Web Search Tool
 */
AiAgent({
  $id: Now.ID["simple_agent"],
  name: "Simple Agent",
  description: "Simple agent with web search",
  agentRole: "Research assistant",
  acl: "",
  versionDetails: [
    {
      name: "V1",
      number: 1,
      state: "published",
      instructions: "Search the web for information...",
    },
  ],
  tools: [
    {
      name: "Web Search",
      type: "web_automation",
      executionMode: "autopilot",
      displayOutput: true,
    },
  ],
});

Agent with record-based trigger​

import { AiAgent } from "@servicenow/sdk/core";

/**
 * @title Agent with record-based trigger
 */
AiAgent({
  $id: Now.ID["triggered_agent"],
  name: "Triggered Agent",
  description: "Agent with record trigger",
  agentRole: "Incident handler",
  acl: "",
  versionDetails: [
    { name: "V1", number: 1, state: "published", instructions: "..." },
  ],
  triggerConfig: [
    {
      name: "Record Trigger",
      channel: "now_assist_panel",
      objectiveTemplate: "Process incident ${number}",
      targetTable: "incident",
      triggerFlowDefinitionType: "record_create",
      triggerCondition: "priority=1",
    },
  ],
});

Basic AiAgent Example​

A minimal AI Agent definition with the required fields:

import { AiAgent } from "@servicenow/sdk/core";

/**
 * @title Basic AiAgent Example
 *
 * @description A minimal AI Agent definition with the required fields:
 * name, description, agentRole, and acl.
 */
AiAgent({
  name: "Basic Support Agent",
  description:
    "A simple AI agent that assists users with common support questions",
  agentRole: "Customer support specialist",
  acl: "",
  versionDetails: [
    {
      name: "V1",
      number: 1,
      state: "published",
      instructions:
        "You are a helpful support agent. Answer common questions and guide users through standard workflows.",
    },
  ],
});