AiAgentDefinitionVersion

Represents a version of an Agentforce agent definition, conversation variables, planner configuration, and behavior settings. For information about retrieving and deploying an Agentforce agent, see Use Use Metadata to Move an Agent to a New Org.

The fullName is the agent’s API name, for example, MyAgent. Each version of the agent is an AiAgentDefinitionVersion component named with a version number, for example MyAgent#1 or MyAgent#2.

Parent Type 

This type extends Metadata and inherits its fields.

File Suffix and Directory Location 

AiAgentDefinitionVersion components have the suffix .aiAgentDefinitionVersion-meta.xml suffix and are stored in a subfolder for the agent in the AiAgentDefinitionVersions folder. Agent components are stored in these subfolders:

• plannerActions/
• localActions/
• agentGraph/
• agentScript/—contains a compiled copy of the script, not the Agent Script source

Version 

Introduced in API version 68.0.

Special Access Rules 

AiAgentDefinitionVersion is available only if Agents is enabled in your org.

Fields 

aiAgentFieldLevelRecordAccesses 

• Type: AiAgentDefinitionFieldLevelRecordAccess[]
• Required: No
• Description: The field-level record access settings that define which object fields the agent can read or write.

articleAnswersGPTEnabled 

• Type: boolean
• Required: No
• Description: Indicates whether the agent generates answers from knowledge articles using generative AI (true) or not (false).

billingMode 

• Type: AgentBillingMode (enumeration of type string)
• Required: No
• Description: The billing model for the agent.
• Possible values:
  • ActionBased
  • OutcomeBased

botDialogs 

• Type: BotDialog[]
• Required: No
• Description: The list of dialogs in this agent version.

This field isn’t returned when you retrieve the metadata. To set the welcome, error, and escalation messages, use welcomeMessage , errorMessage , and escalationMessage . You can’t specify this field together with any of those message fields in the same agent version.

Note

citationsEnabled 

• Type: boolean
• Required: No
• Description: Indicates whether the agent includes citations in its responses (true) or not (false).

company 

• Type: string
• Required: No
• Description: Reserved for internal use.

conversationVariables 

• Type: ConversationVariable[]
• Required: No
• Description: A container that stores a specific piece of data collected from the customer. You can use variables within dialog actions as both inputs and outputs.

copilotPrimaryLanguage 

• Type: Language (enumeration of type string)
• Required: No
• Description: The primary language that the agent uses in conversations.

copilotSecondaryLanguages 

• Type: string
• Required: No
• Description: The additional languages that the agent supports beyond the primary language.

entryDialog 

• Type: string
• Required: No
• Description: A reference to the first dialog that the agent presents to your customer.

This field isn’t returned when you retrieve the metadata. To set the welcome, error, and escalation messages, use welcomeMessage , errorMessage , and escalationMessage .

Note

errorMessage 

• Type: string
• Required: No
• Description: The message that the agent displays when it encounters an error.

escalationMessage 

• Type: string
• Required: No
• Description: The message that the agent displays when it escalates a conversation to a human.

genAiPlannerName 

• Type: string
• Required: No
• Description: The API name of the planner that powers the agent’s reasoning and actions.

This field isn’t returned when you retrieve the metadata. To set the welcome, error, and escalation messages, use welcomeMessage , errorMessage , and escalationMessage .

Note

isScriptCompatibleAgent 

• Type: boolean
• Required: No
• Description: Indicates whether the agent is compatible with Agent Script (true) or not (false).

knowledgeActionEnabled 

• Type: boolean
• Required: No
• Description: Indicates whether the agent can use knowledge actions to answer questions (true) or not (false).

knowledgeFallbackEnabled 

• Type: boolean
• Required: No
• Description: Indicates whether the agent falls back to knowledge articles when no other action applies (true) or not (false).

mainMenuDialog 

• Type: string
• Required: No
• Description: A reference to the dialog identified as the main menu dialog.This field isn’t returned when you retrieve the metadata. To set the welcome, error, and escalation messages, use welcomeMessage, errorMessage, and escalationMessage.

planner 

• Type: AiAgentDefinitionPlanner
• Required: No
• Description: The planner configuration that defines how the agent selects and runs actions.

role 

• Type: string
• Required: No
• Description: A description of the agent’s role and purpose.

smallTalkEnabled 

• Type: boolean
• Required: No
• Description: Indicates whether the agent responds to small talk (true) or not (false).

staticPromptsEnabled 

• Type: boolean
• Required: No
• Description: Indicates whether the agent uses static prompts (true) or not (false).

status 

• Type: BotStatusCode (enumeration of type string)
• Required: No
• Description: The activation status of the agent.
• Possible values:
  • Active
  • Inactive

stopRecPrompts 

• Type: boolean
• Required: No
• Description: Indicates whether the agent stops showing recommended prompts (true) or not (false).

surfacesEnabled 

• Type: boolean
• Required: No
• Description: Indicates whether the agent is available across its configured surfaces (true) or not (false).

toneType 

• Type: GenAiBotToneType (enumeration of type string)
• Required: No
• Description: The conversational tone that the agent uses in its responses.
• Possible values:
  • Casual
  • Formal
  • Neutral

version 

• Type: int
• Required: No
• Description: The version number of the agent definition.

welcomeMessage 

• Type: string
• Required: No
• Description: The message that the agent displays at the start of a conversation.

AiAgentDefinitionFieldLevelRecordAccess Type 

Represents the field-level record access settings that define which object fields the agent can read or write.

Fields 

accessLevel 

• Type: AiAgentRecordAccessLevel (enumeration of type string)

• Required: Yes

• Description: Required.

  The level of access that the agent has to the specified field.

• Possible values:

  • ReadWrite

field 

• Type: string

• Required: Yes

• Description: Required.

  The API name of the field that the access setting applies to.

object 

• Type: string

• Required: Yes

• Description: Required.

  The API name of the object that the access setting applies to.

AiAgentDefinitionPlanner Type 

Represents the planner configuration that defines how the agent selects and runs actions.

Parent Type 

This type extends Metadata and inherits its fields.

Fields 

attributeMappings 

• Type: GenAiPlannerAttrMapping[]
• Required: No
• Description: The attribute mappings that the planner uses.

botTemplate 

• Type: string
• Required: No
• Description: The API name of the bot template that the planner is based on.

capabilities 

• Type: string
• Required: No
• Description: The capabilities available to the planner.

description 

• Type: string
• Required: No
• Description: A description of the planner.

genAiFunctions 

• Type: GenAiPlannerFunctionDef[]
• Required: No
• Description: The functions available to the planner.

genAiPlugins 

• Type: GenAiPlannerFunctionDef[]
• Required: No
• Description: The plugins available to the planner.

masterLabel 

• Type: string

• Required: Yes

• Description: Required.

  The label displayed in the Salesforce user interface.

plannerSurfaces 

• Type: AiPlannerSurfaceDef[]
• Required: No
• Description: The surfaces on which the planner is available.

plannerType 

• Type: PlannerType (enumeration of type string)

• Required: Yes

• Description: Required.

  The type of planner that powers the agent.

• Possible values:

  • AiCopilot__AgileAppDev
  • AiCopilot__ReAct
  • AiCopilot__SequentialPlannerIntentClassifier
  • Atlas__ConcurrentMultiAgentOrchestration
  • Atlas__VoiceAgent
  • BYOP__waiiplanner
  • SentOS__SearchAgent

ruleExpressionAssignments 

• Type: GenAiPlannerRuleExprAsgn[]
• Required: No
• Description: The rule expression assignments for the planner.

ruleExpressions 

• Type: GenAiPlannerRuleExprDef[]
• Required: No
• Description: The rule expressions defined for the planner.

AiPlannerSurfaceDef Type 

Fields 

adaptiveResponseAllowed 

• Type: boolean
• Required: No

callRecordingAllowed 

• Type: boolean
• Required: No

outboundRouteConfigs 

• Type: AiPlannerSurfOtbdRouteDef[]
• Required: No

surface 

• Type: string
• Required: Yes

surfaceType 

• Type: SurfaceType (enumeration of type string)
• Required: Yes

AiPlannerSurfOtbdRouteDef Type 

Fields 

escalationMessage 

• Type: string
• Required: No

outboundRouteName 

• Type: string
• Required: Yes

outboundRouteType 

• Type: OutboundRouteType (enumeration of type string)
• Required: Yes

BotDialog Type 

Represents the dialogs in this agent version. This metadata type isn’t returned during a retrieve operation. You can’t deploy both dialogs and the messages (welcomeMessage, errorMessage, or escalationMessage) in the same deploy. We recommend using messages instead of dialogs.

Fields 

botDialogGroup 

• Type: string
• Required: No
• Description: The bot dialog group that contains this bot dialog.

botSteps 

• Type: BotStep[]
• Required: No
• Description: The ordered steps that make up this dialog.

description 

• Type: string
• Required: No
• Description: A description of the bot dialog.

developerName 

• Type: string

• Required: Yes

• Description: Required.

  This unique name prevents conflicts with other dialogs associated with the same bot version. This name can contain only underscores and alphanumeric characters. It must begin with a letter, not include spaces, not end with an underscore, and not contain two consecutive underscores.

Only users with View DeveloperName OR View Setup and Configuration permission can view, group, sort, and filter this field.

Note

isPlaceholderDialog 

• Type: boolean
• Required: No
• Description: In a bot block, indicates whether a dialog is a placeholder (true) or not (false). In a bot template or bot version not associated with a bot block, this field is read-only and the value is false.

label 

• Type: string

• Required: Yes

• Description: Required.

  A label that identifies the dialog throughout the Salesforce user interface.

mlIntent 

• Type: string

• Required: No

• Description: Required.

  The name of the intent associated with a dialog.

mlIntentTrainingEnabled 

• Type: boolean
• Required: No
• Description: Indicates whether Einstein is turned on to train an intent model for the dialog intent (true) or turned off for the exact match option (false). The default value is false.

showInFooterMenu 

• Type: boolean
• Required: No
• Description: Indicates whether to show this dialog in the Bot Options menu. The default value is false.

ConversationVariable Type 

Represents a specific piece of data collected from the customer. You can use variables within dialog actions as both inputs and outputs.

This metadata type supports the wildcard character * (asterisk) in the package.xml manifest file. For information about using the manifest file, see Deploying and Retrieving Metadata with the Zip File.

Fields 

collectionType 

• Type: ConversationVariableCollectionType (enumeration of type string)
• Required: No
• Description: This field defines whether a variable is designated as a List Variable. Valid value is List.

dataType 

• Type: ConversationDataType (enumeration of type string)
• Required: Yes
• Description: Required.
• Possible values:
  • Boolean
  • Currency
  • Date
  • DateTime
  • Id
  • Object
  • Number
  • Text

description 

• Type: string
• Required: No
• Description: A description of this variable. This value can be used by the Agentforce planner service.

developerName 

• Type: string

• Required: Yes

• Description: Required.

  This name can contain only underscores and alphanumeric characters and must be unique in your org. It must begin with a letter, not include spaces, not end with an underscore, and not contain two consecutive underscores. Only users with View DeveloperName OR View Setup and Configuration permission can view, group, sort, and filter this field.

includeInPrompt 

• Type: boolean
• Required: No
• Description: Indicates whether the variable is injected into the prompt sent to the Agentforce model. If true, the variable appears in the Included Fields section of the UI.

The default variables Id , EndUserId , and EndUserLanguage always appear in the Included Fields section of the UI, regardless of their value of includeInPrompt . We recommend that you don’t change the value of includeInPrompt for these default variables, as changing the value can prevent your agent from accessing important session data.

Note

label 

• Type: string

• Required: Yes

• Description: Required.

  Label that identifies a variable throughout the Salesforce user interface.

SObjectType 

• Type: string (enumeration of type string)
• Required: No
• Description: Specifies the SObjectType of the ID stored in a bot variable.
• Possible values:
  • BotDefinition
  • Queue

visibility 

• Type: ConversationVariableVisibilityType (enumeration of type string)
• Required: No
• Description: Determines which components can set this variable. If the visibility is internal, the variable can only be set by action outputs. If the visibility is external, the variable can also be set by the API.
• Possible values:
  • internal
  • external

GenAiLocalPlugin Type 

Represents a custom agent topic.

Fields 

aiPluginUtterances 

• Type: AiPluginUtteranceDef[]
• Required: No

canEscalate 

• Type: boolean
• Required: No

description 

• Type: string
• Required: Yes
• Description: A description of this component. The description should explain the component’s purpose and behavior so that administrators and developers understand when to use it.

genAiFunctions 

• Type: GenAiPluginFunctionDef[]
• Required: No

genAiPluginInstructions 

• Type: GenAiPluginInstructionDef[]
• Required: No

language 

• Type: string
• Required: Yes

localDeveloperName 

• Type: string
• Required: No

masterLabel 

• Type: string
• Required: Yes
• Description: The master label for this component. This display value is the internal label that isn’t translated.

name 

• Type: string
• Required: Yes

pluginType 

• Type: PluginType (enumeration of type string)
• Required: Yes

scope 

• Type: string
• Required: No

GenAiPlannerAttrMapping Type 

Represents an attribute mapping, which enables you to map the output of one action attribute to the input of another attribute. This mapping enables you to propagate sensitive data safely without relying on untrusted user input.

Fields 

attributeName 

• Type: string
• Required: Yes

attributeType 

• Type: AttributeType (enumeration of type string)
• Required: Yes

constantValue 

• Type: string
• Required: No

mappingTargetName 

• Type: string
• Required: No

mappingType 

• Type: AttributeMappingType (enumeration of type string)
• Required: Yes

GenAiPlannerFunctionDef Type 

Represents an agent topic or action definition.

Fields 

genAiCustomizedPlugin 

• Type: GenAiLocalPlugin
• Required: No

genAiFunctionName 

• Type: string
• Required: No

genAiPluginName 

• Type: string
• Required: No

GenAiPlannerRuleExprAsgn Type 

Represents a rule-expression assignment to either a topic or an action.

Fields 

ruleExpressionName 

• Type: string
• Required: Yes

targetName 

• Type: string
• Required: Yes

targetType 

• Type: string
• Required: Yes

GenAiPlannerRuleExprCondition Type 

Represents a condition for a rule expression.

Fields 

leftOperand 

• Type: string
• Required: Yes

leftOperandType 

• Type: GenAiAgentVariableType (enumeration of type string)
• Required: Yes

operator 

• Type: GenAiRuleExpressionOperator
• Required: Yes

rightOperandValue 

• Type: string
• Required: No

GenAiPlannerRuleExprDef Type 

Represents a rule expression, which conditionally locks or unlocks topics and actions based on defined security criteria.

Fields 

conditions 

• Type: GenAiPlannerRuleExprCondition[]
• Required: No

expression 

• Type: string
• Required: No

expressionLabel 

• Type: string
• Required: Yes

expressionName 

• Type: string
• Required: Yes

expressionType 

• Type: ExpressionType (enumeration of type string)
• Required: No