AiAgentDefinitionVersion | Metadata API Developer Guide

Parent Type

This type extends the Metadata metadata type and inherits its fullName field.

File Suffix and Directory Location

AiAgentDefinitionVersion components have the suffix .AiAgentDefinitionVersion and are stored in a subfolder for the agent in the AiAgentDefinitionVersion folder.

Version

AiAgentDefinitionVersion components are available in API version 68.0 and later.

Special Access Rules

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

Fields

Field Name	Description
aiAgentFieldLevelRecordAccesses	Field Type AiAgentDefinitionFieldLevelRecordAccess[] Description The field-level record access settings that define which object fields the agent can read or write.
articleAnswersGPTEnabled	Field Type boolean Description Indicates whether the agent generates answers from knowledge articles using generative AI (`true`) or not (`false`).
billingMode	Field Type AgentBillingMode (enumeration of type string) Description The billing model for the agent. Valid values are: `ActionBased` `OutcomeBased`
botDialogs	Field Type BotDialog[] Description The list of dialogs in this agent version.
citationsEnabled	Field Type boolean Description Indicates whether the agent includes citations in its responses (`true`) or not (`false`).
company	Field Type string Description Reserved for internal use.
conversationVariables	Field Type ConversationVariable[] 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	Field Type Language (enumeration of type string) Description The primary language that the agent uses in conversations.
copilotSecondaryLanguages	Field Type string Description The additional languages that the agent supports beyond the primary language.
entryDialog	Field Type string Description A reference to the first dialog that the agent presents to your customer. For example, `Welcome`.
errorMessage	Field Type string Description The message that the agent displays when it encounters an error.
escalationMessage	Field Type string Description The message that the agent displays when it escalates a conversation to a human.
genAiPlannerName	Field Type string Description The API name of the planner that powers the agent's reasoning and actions.
isScriptCompatibleAgent	Field Type boolean Description Indicates whether the agent is compatible with Agent Script (`true`) or not (`false`).
knowledgeActionEnabled	Field Type boolean Description Indicates whether the agent can use knowledge actions to answer questions (`true`) or not (`false`).
knowledgeFallbackEnabled	Field Type boolean Description Indicates whether the agent falls back to knowledge articles when no other action applies (`true`) or not (`false`).
mainMenuDialog	Field Type string Description A reference to the dialog identified as the main menu dialog. For example, `Main Menu`.
planner	Field Type AiAgentDefinitionPlanner Description The planner configuration that defines how the agent selects and runs actions.
role	Field Type string Description A description of the agent's role and purpose.
smallTalkEnabled	Field Type boolean Description Indicates whether the agent responds to small talk (`true`) or not (`false`).
staticPromptsEnabled	Field Type boolean Description Indicates whether the agent uses static prompts (`true`) or not (`false`).
status	Field Type BotStatusCode (enumeration of type string) Description The activation status of the agent. Valid values are: `Active` `Inactive`
stopRecPrompts	Field Type boolean Description Indicates whether the agent stops showing recommended prompts (`true`) or not (`false`).
surfacesEnabled	Field Type boolean Description Indicates whether the agent is available across its configured surfaces (`true`) or not (`false`).
toneType	Field Type GenAiBotToneType (enumeration of type string) Description The conversational tone that the agent uses in its responses. Valid values are: `Casual` `Formal` `Neutral`
version	Field Type int Description The version number of the agent definition.
welcomeMessage	Field Type string Description The message that the agent displays at the start of a conversation.

AiAgentDefinitionFieldLevelRecordAccess

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

Field Name	Description
accessLevel	Field Type AiAgentRecordAccessLevel (enumeration of type string) Description Required. The level of access that the agent has to the specified field. Valid values are: `ReadWrite`
field	Field Type string Description Required. The API name of the field that the access setting applies to.
object	Field Type string Description Required. The API name of the object that the access setting applies to.

AiAgentDefinitionPlanner

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

Field Name	Description
attributeMappings	Field Type GenAiPlannerAttrMapping[] Description The attribute mappings that the planner uses.
botTemplate	Field Type string Description The API name of the bot template that the planner is based on.
capabilities	Field Type string Description The capabilities available to the planner.
description	Field Type string Description A description of the planner.
genAiFunctions	Field Type GenAiPlannerFunctionDef[] Description The functions available to the planner.
genAiPlugins	Field Type GenAiPlannerFunctionDef[] Description The plugins available to the planner.
masterLabel	Field Type string Description Required. The label displayed in the Salesforce user interface.
plannerSurfaces	Field Type AiPlannerSurfaceDef[] Description The surfaces on which the planner is available.
plannerType	Field Type PlannerType (enumeration of type string) Description Required. The type of planner that powers the agent. Valid values are: `AiCopilot__AgileAppDev` `AiCopilot__ReAct` `AiCopilot__SequentialPlannerIntentClassifier` `Atlas__ConcurrentMultiAgentOrchestration` `Atlas__VoiceAgent` `BYOP__waiiplanner` `SentOS__SearchAgent`
ruleExpressionAssignments	Field Type GenAiPlannerRuleExprAsgn[] Description The rule expression assignments for the planner.
ruleExpressions	Field Type GenAiPlannerRuleExprDef[] Description The rule expressions defined for the planner.

BotDialog

Represents the dialogs in this agent version.

Field Name	Description
botDialogGroup	Field Type string Description The bot dialog group that contains this bot dialog.
botSteps	Field Type BotStep[] Description The ordered steps that make up this dialog.
description	Field Type string Description A description of the bot dialog.
developerName	Field Type string 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	Field Type boolean 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`. Available in API version 58.0 and later.
label	Field Type string Description Required. A label that identifies the dialog throughout the Salesforce user interface.
mlIntent	Field Type string Description Required. The name of the intent associated with a dialog.
mlIntentTrainingEnabled	Field Type boolean 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`. Available in API version 46.0 and later.
showInFooterMenu	Field Type boolean Description Indicates whether to show this dialog in the Bot Options menu. The default value is `false`.

ConversationVariable

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

Field Name	Description
SObjectType	Field Type string Description Specifies the SObjectType of the ID stored in a bot variable. Valid values are: `BotDefinition` `Queue`
collectionType	Field Type ConversationVariableCollectionType (enumeration of type string) Description This field defines whether a variable is designated as a List Variable. Valid value is List.
dataType	Field Type ConversationDataType (enumeration of type string) Description Required. Valid values are: `Boolean` `Currency` `Date` `DateTime` `Id` (available in API 45.0 and later.) `Object` `Number` `Text`
description	Field Type string Description A description of this variable. This value can be used by the Agentforce planner service. Available in API version 63.0 and later.
developerName	Field Type string 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	Field Type boolean 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 Available in API version 63.0 and later.
label	Field Type string Description Required. Label that identifies a variable throughout the Salesforce user interface.
visibility	Field Type ConversationVariableVisibilityType (enumeration of type string) Description Required. 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. Valid values are: `internal` `external`