Create and run agents

Agents run your infrastructure operations. Each agent has a prompt that defines its role and behavior, a set of tools it can invoke, and an LLM model for reasoning. You control who can run it.

Every agent belongs to exactly one agent project, which controls who can view and edit it. For information about creating and managing projects, see Agent Projects.

Before you begin

Before creating an agent, make sure you have the following:

Your admin has granted you FlowAI access in Admin Essentials. A project role alone isn’t sufficient; you need both application-level FlowAI access and a project role to use Agent Projects. For more information, see FlowAI roles.
You have at least the Editor role on the project you’ll add the agent to. Adding tools and applying decorators each require their own permissions. For details, see Required permissions for project actions.
Your admin has configured a model registry with at least one enabled model. For more information, see Model Registry.

Create an agent

Click the agent project you want to add an agent to.

Click Create Agent.

Enter a Name. The name must be unique within the project.

(Optional) Enter a Description. When another agent uses this agent as a tool, it reads the description to understand what the tool does and when to use it. The description also helps people browsing the agent list.

Enter a Prompt. Write in plain text to define the agent’s role, instructions, and constraints. You can reference input variables using {{ variableName }} syntax. For more information, see Input variables.

(Optional) Expand Add Input Variables and define your variable schema. For schema requirements and constraints, see Input variables.

Add tools. The agent can only invoke the tools you select here. For information about tool types, visibility, and selection behavior, see Tools.

You can also decorate any listed tool by clicking Decorate. Decoration is optional. For guidance on when and how to use it, see Schema decorators.

Select a Profile, then select a Model. Your LLM admin determines which profiles and models are available in Model Registry. Only one model per agent is supported.

Choose the groups that can make a trigger or workflow that uses this agent in Groups. Users with Owner or Editor role on the project automatically have run access. If you don’t add any groups, only project Owners and Editors can run the agent.

Users must have apiwrite and apiread rights for Operations Manager to run automations. Set these in Admin Essentials.

Click Save or Save and Run.

Save and Run saves the agent and immediately starts a session in Agent Sessions. If you’ve defined input variables, you must provide values for all required variables before the session starts. When the session starts, a new browser tab opens to the session detail in Agent Sessions. If the session is still initializing when the tab opens, it shows a Loading state. If the session fails to start, no tab opens and an error message appears explaining why.

Input variables

Input variables let you define placeholders in the prompt that users fill in when they run the agent. This makes the same agent reusable across different scenarios without editing the prompt each time. Reference variables in the prompt using {{ variableName }} syntax.

Variable constraints:

Supported types: string and number.
Variable name matching is case-sensitive. {{ deviceName }} and {{ DeviceName }} are two distinct references.
If you reference a variable multiple times in the prompt, you need only one schema entry.

Auto-detection - As you type {{ variableName }} in the prompt, Agent Builder automatically detects the variable and then requests that you add it to the input schema. You can then refine the generated entry: set the type, mark it required or optional, and add a default value if needed.

Bidirectional validation - Agent Builder enforces a two-way match between the schema and the prompt. Every {{ variableName }} in the prompt must have a matching entry in the schema, and every property defined in the schema must appear at least once in the prompt. If either condition is violated, Agent Builder shows an inline warning identifying the specific unresolved or unused variables. You can’t save the agent until you resolve all warnings.

Tools

Tools are Itential capabilities your agent can invoke at runtime. The agent can only invoke the tools you select here; it can’t call anything outside this set, regardless of prompt content.

Tool types

You can add the following tool types to an agent:

Tool type	Description
Agent Project	All agents in an agent project. Add an agent project to use its agents as tools, enabling multi-agent architectures.
Compliance Plan	A Configuration Manager compliance plan.
Gateway Service	A Gateway service, including MCP-backed services from FlowMCP Gateway.
JSON Form	A JSON Form.
Method (from Adapter)	An adapter method.
Method (from Application)	An application method.
Method (from Integration)	An integration method.
Resource Action	A Lifecycle Manager resource model and one of its actions.
Studio Project	All assets in a Studio project.
Template	A template.
Transformation	A JSON transformation (JST).
View	A list of manual forms.
Workflow	A Studio workflow.

Compliance Plan is the only Configuration Manager tool type. You can run Golden Configurations through the Configuration Manager API, but you can’t select them as tools.

Tool visibility

The tool catalog shows only the tools you have access to run on Itential. Visibility rules vary by tool type:

Global space Studio assets - Always visible if no auth group is set. If an auth group is set, visible only to members of that group.
Compliance Plans - Visible if you’ve got read or write access, or if no access controls are set.
Studio project assets - Visible if you’ve got Owner, Editor, or Operator role on the Studio project.
Agent assets - Visible if you’ve got Owner or Editor role on the agent project, or if a project Owner or Editor has added you to the agent’s permissions.
Adapter, application, and integration service methods - Visible if you’ve got a service-level role on the specific instance that permits the method.

If your permissions on a source project are revoked after you’ve associated a tool, Itential preserves the tool reference but flags it in the UI. You can delete the flagged tool but can’t modify it or create a decorator for it. The agent can still run with flagged tools, but resolve the flagged reference before relying on the agent in production.

Browse and select tools

Select tools individually or by Itential Studio or Agent Project:

Individual tool - Selecting an individual tool assigns it directly to the agent. The tool remains available even if someone moves it to a different project or to global scope.
Project - Selecting a Studio or Agent Project automatically selects all of its current assets. You can’t select a project without selecting all its assets. Assets added to the project after you configure the agent are included the next time you open the agent for editing. Saving the agent persists the updated selection.

To exclude a single asset from a project while keeping the rest, expand the project row and unselect the individual asset. Doing so deselects the project but keeps all other assets from that project selected. To remove a project and all its auto-selected assets, unselect the project row.

When a tool assigned to the agent no longer exists in the system, Itential marks it as missing. The agent can still run, but resolve stale references before relying on the agent in production.

If a decorator is applied to a tool, the agent sees the decorator’s tool description instead of the tool’s native description.

Tools you add take effect the next time you run the agent, not the current run.

Unavailable tools

Some Itential methods are deny-listed and can’t be added to an agent, even if you have permission to run them. Deny-listed methods perform destructive, system-level, or workflow-internal operations that aren’t appropriate for an agent to invoke directly, so they don’t appear in the tool catalog when you configure an agent.

Deny-listed methods by service

AutomationGateway (adapter): runPlaybook, dryRunPlaybook, runRole, runModule, runNornirModule, runScript, runScriptEnv, runCommand, runCollectionModule, runCollectionRole, restoreConfig, sendRequest, createDevice, createDeviceRaw, createDeviceGroup, updateDevice, updateDeviceRaw, updateDeviceGroup, deleteDevice, deleteDeviceGroup, deleteDeviceFromDeviceGroup, addDeviceToDeviceGroup, setConfig, loadConfig, connectDevice, gnmiSet, gnoiCancelReboot, gnoiClearBGPNeighbor, gnoiClearInterfaceCounters, gnoiClearLLDPInterface, gnoiClearNeighborDiscovery, gnoiClearSpanningTree, gnoiReboot, gnoiSetPackage, gnoiSwitchCPU, gnoiWakeOnLAN, createInventoryDevice, updateInventoryDevice, deleteInventoryDevice, netconfExecRpc, netmikoSendConfig, netmikoSendConfigSet, netconfSetConfig, netmikoSendCommand, netmikoSendCommandExec, applyTerraform, destroyTerraform, planTerraform, initTerraform, getTerraform, getTerraforms, refreshCollections, refreshInventory, refreshModules, refreshNornirModules, refreshPlaybooks, refreshRoles, refreshScripts

AGManager: undiscoverAll, undiscoverModules

AgentSessionManager: runAgent

ConfigurationManager: adapterProxy, renderJinja2, runAdapterTask, runTaskInstance, runAutoRemediation, advancedAutoRemediation, runComplianceForDevice, runComplianceForDeviceGroup, runComplianceForNode, runComplianceForTree, createTaskInstance, updateTaskInstance, deleteTaskInstances, createDeviceGroup, updateDeviceGroups, deleteDeviceGroups, removeDevicesFromGroup, createConfigParser, updateConfigParser, deleteConfigParser, deleteConfigParsers, importParsers, createGoldenConfigTree, updateGoldenConfigTree, deleteGoldenConfigTree, deleteGoldenConfigTrees, importGoldenConfigTree, updateGoldenConfigTreeVersion, updateJSONConfigRules, createGoldenConfigNode, updateGoldenConfigNode, deleteGoldenConfigNode, addGroupsToNode, addTasksToNode, addDevicesToNode, removeGroupsFromNode, removeTasksFromNode, removeDevicesFromNode, deleteVariables, createConfigSpec, updateConfigSpec, updateNodeConfig, createJSONSpec, updateJSONSpec, createDeviceTemplate, updateDeviceTemplate, deleteDeviceTemplates, importDeviceTemplates, createCompliancePlan, updateCompliancePlan, deleteCompliancePlans, importCompliancePlan, addNodesToCompliancePlan, removeNodesFromCompliancePlan, updateCompliancePlanInstance, updateDeviceBackupById, deleteDeviceBackups, deleteOSTypeCache, deletePins

GatewayManager: runCode

InventoryManager: createInventory, deleteInventory, populateInventory, clearInventory, createInventoryAction, deleteInventoryAction

JsonForms: createForm, deleteForms, importForms

LifecycleManager: runAction, createManualInstanceGroup, updateManualInstanceGroup, deleteInstanceGroup, createResourceModel, updateResourceModel, deleteResourceModel, updateResourceInstance

MOP: RunCommand, RunCommandTemplate, passThru, reattempt, runAnalyticsTemplate, runAnalyticsTemplateDevices

OperationsManager: createAutomation, cloneAutomation, updateAutomation, deleteAutomation, importAutomations, createTrigger, updateTrigger, deleteTrigger, deleteTriggersByActionId, importTriggers, runEndpointTriggerWithPost, runManualTrigger

TemplateBuilder: applyTemplate, applyTemplates, renderJinja2ContextWithCast, renderJinja2TemplateWithCast, renderJinjaTemplate

WorkFlowEngine: arrayConcat, arrayIncludes, arrayIndexOf, arrayLastIndexOf, arrayLength, arrayPop, arrayPush, arrayShift, arraySlice, arrayToLocaleString, arrayToString, copyWithin, fill, isArray, join, map, reverse, sort, unshift, numberToString, parseInt, assign, keys, objectHasOwnProperty, objectToString, setObjectKey, values, charAt, charCodeAt, codePointAt, endsWith, localeCompare, match, normalize, padEnd, padStart, parse, repeat, replace, search, split, startsWith, stringConcat, stringIncludes, stringIndexOf, stringLastIndexOf, stringLength, stringSlice, stringValueOf, substring, toLocaleLowerCase, toLocaleUpperCase, toLowerCase, toUpperCase, trim, trimEnd, trimStart, addDuration, calculateTimeDiff, convertEpochToObject, convertTimeFormat, convertTimeToEpoch, convertTimezone, extractField, getTime, getTimeByTimezone, asciiToBase64, base64ToAscii, csvStringToJson, excelToJson, FlattenJSONFormInput, makeData, restCall, stub, childJob, deepmerge, delay, evaluation, eventListenerJob, forEach, merge, modify, newVariable, pop, push, query, shift, transformation, updateJobDescription, validateJsonSchema

Schema decorators

Decorators let you override two things the agent uses to understand a tool:

Tool description - tells the agent when to use the tool. This comes from the tool’s description in its source system, for example, an integration method’s description. A well-written description has a large impact on how reliably the agent selects the right tool.
Schema - tells the agent how to use the tool: what input parameters to pass, their types, and which are required. This comes from the tool’s input definition in its source system. Override the schema when the native definition is incomplete or ambiguous, for example, when an integration method doesn’t fully document its request parameters.

Changes apply only to this agent and don’t affect the tool’s original definition or how other agents see it. A decorator applied in one agent can be reused in others. Decorator names must be unique within the environment. You can apply one decorator to a tool per agent.

You can only decorate tools you have permission to run. For the permissions decorators require, see Access control.

When to decorate - Start with the tool description. If the agent is consistently choosing the wrong tool or using it incorrectly, override the schema next. You don’t need to fill out both fields; use whichever is appropriate.

Once you save a decorator, you can’t edit it. To modify a decorator, clone it and edit the clone. You can only delete decorators via the API.

Create a decorator

In the tools table, click Decorate. The Decorate Tool dialog opens.

Click Create Decorator.

Enter a Name. The name must be unique per tool.

(Optional) Enter a Description. This identifies the decorator in lists and helps distinguish it from others.

(Optional) Edit the Override Tool Description. The tool’s current description pre-fills this field. Changes here affect how the agent reasons about when and how to use the tool.

(Optional) Edit the Schema. The schema and JSON editors work together: use Infer JSON to generate a JSON example from your schema, or Infer Schema to generate a schema from a JSON example.

Click Save Decorator. Once saved, you can’t edit the decorator.

Itential checks that your schema is valid JSON, but doesn’t verify that it accurately describes the tool’s inputs and outputs. Test your decorator before relying on it in production.

Clone a decorator

To modify a decorator, clone it:

From the decorator view, click Edit Decorator on the decorator that you’d like to clone.

Choose the decorator.

Edit the name, description, tool description, or schema as needed. The clone opens pre-filled with the original’s values.

Click Clone Decorator.

Click Save Changes, or Cancel to discard.

For information about promoting decorators across environments, see Promote decorators.

View agents

The agent list shows all agents in the project with their description and current launch status. Agents that can’t launch include a details indicator explaining the specific issue, such as unresolved tool or model profile references. Use the status filter to quickly find agents that need attention.

You can clone or delete an agent from this list. For a description of each status, see Agent readiness.

Clone an agent

Cloning creates a new agent with all properties of the original, except the name, which must be unique within the project. A cloned agent must meet agent readiness before it can run. For information, see Agent readiness.

Delete an agent

Deleting an agent permanently removes it and all its configurations. This action can’t be undone.

To delete an agent, you need both of the following:

Owner or Editor role on the agent project.
The delete permission for agent projects: agent-project-service:delete (on-prem) or agents:delete (cloud). Your admin sets this in Admin Essentials (on-prem) or Cloud Hub (cloud).

To delete, open the agent list and select Delete from the agent’s action menu.

Access control

Each agent action requires both an application-level permission and a project role; neither is sufficient on its own. An admin assigns these permissions in Admin Essentials → Authorization on-prem, or through Cloud Hub role management on cloud.

This section covers agent-level actions. For project-level actions, see Required permissions for project actions.

Adding tools and decorators depends on more than these roles:

Add a tool - You can add only tools you have access to. A tool is selectable when you or one of your groups has been granted access to it and the tool’s application is available in your environment. Application availability is set by subscription tier on cloud and by installation on-prem.
Apply or create a decorator - Requires decorator authoring permission: decorator:create on-prem or tool-decorators:write on cloud. Viewing the available decorators requires decorator read permission: decorator:read on-prem or tool-decorators:read on cloud.

To let groups beyond Owners and Editors run an agent, add them in the agent’s Groups. For the full list of permissions, see FlowAI roles.