Create and run agents

Platform 6.5+

Agents run your infrastructure operations. Each agent has a prompt that defines its role and behavior, skills it can load when a task needs them, 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. Admins typically grant this alongside your other Agent Projects permissions; see Grant FlowAI access.
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. Admins typically assign these once, up front. For details, see Access control below.
Your admin has configured a model registry with at least one enabled model. For more information, see Model Registry.

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.

Every action also requires agent-projects:read to open the application. The permissions below are the agent-project-service permissions each action needs.

Action	Application permission(s)	Minimum project role	Notes
Create an agent	`agent-project-service:read`, `agent-project-service:create`	Editor
Edit an agent	`agent-project-service:read`, `agent-project-service:update`	Editor
Clone an agent	`agent-project-service:read`, `agent-project-service:create`	Editor	Creates a new agent in the same project.
Delete an agent	`agent-project-service:read`, `agent-project-service:delete`	Editor
Run an agent	`agent-project-service:read`	Viewer, plus run access to the agent	Owners and Editors have automatic run access.

Adding tools, decorators, and skills 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.
Add a skill - Requires agent-skills:read and read access to the skill itself. Skill access is set on each skill and is separate from project roles. For details, see Access control in Manage skills.

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. For the permissions to grant, see Agent Projects in Grant FlowAI access.

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.

If you paste the same domain knowledge into more than one agent’s prompt, consider putting it in a skill instead. For more information, see Agent skills.

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

(Optional) In the Skills step, add skills. The agent loads a skill only when a task needs it. For details, see Add a skill to an agent.

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:

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.
Each input variable is required by default. You can mark it optional. For more information, see Required and optional input variables.

Data types

Platform 6.7.0+

Each input variable has a Data Type. You can pass structured data, such as a list of target devices or the details of a single device, without flattening it into text for the agent to rebuild. Select one or more of the following data types:

Data type	Accepts
`string`	Text.
`number`	Any numeric value, including decimals such as `3.5`.
`boolean`	`true` or `false`.
`object`	A JSON object. You can define the keys it expects.
`array`	A JSON array. You can define the type of item it contains.
`null`	A `null` value.

Agents you created before Platform 6.7.0 keep their string and number input variables, and their behavior doesn’t change.

Accept more than one data type

A single input variable can accept more than one data type. This is useful when the data you receive doesn’t always arrive in the same shape. For example, an upstream system might return an object when it finds a match and null when it doesn’t.

When you add a variable, Agent Builder selects string automatically. To accept other types, select them in the Data Type control. To allow more than one type, select additional types. The selected types appear comma-separated, and the label stays Data Type. A value is valid if it matches any one of the selected types.

Required and optional input variables

Every input variable is required by default, which means a user must provide a value before the agent runs. To let the agent run without a value for an input variable, mark the input variable optional. This setting is separate from the data type and applies to the whole input variable.

When no value is provided for an optional input variable, the agent receives an empty string for that variable. This is true regardless of the data type you select. If the prompt depends on the input variable, write the prompt so the agent handles an empty value, for example by telling it what to do when the value is empty.

Object keys also have a required or optional setting. A required key is enforced only when a value is provided for its object input variable.

Describe an input variable

Each input variable has one description, which you can leave empty. If the input variable accepts more than one data type, the description applies to every type. Each object key also has its own description. Array items don’t have a description.

Set rules for each data type

Rules limit the values an input variable accepts. Calls and runs with values that break a rule are rejected before they reach the agent. Rules apply to top-level input variables only, and each data type has its own rules. If an input variable accepts more than one data type, set rules separately for each type. Empty rules aren’t saved.

Data type	Rule	Description
`string`	Min Length	The fewest characters the value can have.
`string`	Max Length	The most characters the value can have.
`string`	Restricted Format	Requires the value to match one format: email, date, date-time, time, IPv4, or IPv6. You can’t enter a custom format or pattern.
`number`	Min Value	The lowest value allowed.
`number`	Max Value	The highest value allowed.
`number`	Integer Only	Accepts whole numbers only, such as `3`. Without this rule, `number` accepts any numeric value, including decimals such as `3.5`.
`object`	Keys	The keys the object expects. For more information, see Define object keys.
`array`	Item	The data type every item in the array must match. For more information, see Define array items.
`boolean`	None
`null`	None

A minimum can’t be greater than its maximum. Agent Builder shows an error and you can’t save the agent until you correct it.

If you deselect a data type that has rules, Agent Builder flags each rule for that type as an error. Select the data type again or remove each flagged rule before you save.

Define object keys

When object is one of an input variable’s data types, you can add keys that describe what the object contains. Each key has the following settings:

Name - Unique within the object.
Data type - One or more data types. A key typed as object accepts any object, and a key typed as array accepts any array.
Description - Optional.
Optional - Whether the key can be left out. Keys are required by default.

You can define keys one level below the top-level input variable. A key can’t have its own keys or rules.

Define array items

When array is one of an input variable’s data types, you set one item definition that every item in the array must match. You set only the item’s data type. An item typed as object accepts any object, and an item typed as array accepts any array. Items don’t have a description, an optional setting, or rules.

Provide values when you run the agent

When you run an agent from Agent Builder, each input variable appears according to its data type:

string - A text field.
number - A field that validates the value as you type.
boolean - True and False options.
object and array - A JSON value field.
null - A note that null is passed. You don’t enter a value.

If an input variable accepts more than one data type, select the data type to use for that run, and the field changes to match.

Call an agent with structured data

External systems that invoke an agent through the API and agents that call another agent as a tool can send object, array, and boolean values directly. No string encoding is needed. For an input variable that accepts more than one data type, the value can match any one of its types. A call is rejected with a validation error that identifies the input variable if the value doesn’t match any of the input variable’s data types.

Auto-detection and validation

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 by selecting its data type or types.

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.

The tool types you see depend on the products and applications installed in your environment, so you might not see every type listed here.

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. For information about working with schemas, see Configure decorator schemas.

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

To 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. For common edits like setting a default value, restricting allowed values, or limiting which fields the agent can use, see Configure a decorator’s JSON schema.

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

You can’t modify an existing decorator. Instead, you must clone it. To clone a decorator:

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.

Your schema changes take effect only after you select Save Decorator. Exiting without saving discards them.

Saving creates a decorator, but doesn’t apply it. Assign the new decorator to the tool so the agent can use it. When you assign a decorator, it deactivates whichever one was previously active for that tool.

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. If the original agent uses a skill you can’t read, that skill is unresolved on the clone, and the clone can’t run until you remove it.

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.