--- schema_version: "1" id: f465e81a0e745bc40a36654ef8380ba1838e81f755e6f69aec4c747326309adf title: AiAgentDefinitionVersion collection: legacydeveloper version: current locale: en-us portal_url: https://docs.salesforce.com/legacydeveloper/current/en-us/api_meta/meta_aiagentdefinitionversion.md canonical_url: https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/meta_aiagentdefinitionversion.htm source_site: developer.salesforce.com content_type: documentation content_hash: d7829777ff5ace142ccfc00077fc3aa21fd6f5904519e4c35117ddc81d752ffa description: 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. --- # 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](https://developer.salesforce.com/docs/ai/agentforce/guide/agent-dx-deploy-metadata.html). ## Parent Type This type extends the [Metadata](https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/metadata.htm "The base class for all metadata types. You can’t edit this object. A component is an instance of a metadata type.") metadata type and inherits its fullName field. 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. ## 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 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. ## Usage This type extends the [Metadata](https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/metadata.htm "The base class for all metadata types. You can’t edit this object. A component is an instance of a metadata type.") metadata type and inherits its fullName field. ## Fields | Field Name | Description | | --- | --- | | aiAgentFieldLevelRecordAccesses | Field Type [AiAgentDefinitionFieldLevelRecordAccess\[\]](#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\[\]](#BotDialog) Description The list of dialogs in this agent version. ![Note](https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/images/icon_note.png) #### Note 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. | | 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\[\]](#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. ![Note](https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/images/icon_note.png) #### Note This field isn't returned when you retrieve the metadata. To set the welcome, error, and escalation messages, use welcomeMessage, errorMessage, and escalationMessage. | | 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. ![Note](https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/images/icon_note.png) #### Note This field isn't returned when you retrieve the metadata. To set the welcome, error, and escalation messages, use welcomeMessage, errorMessage, and escalationMessage. | | 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. ![Note](https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/images/icon_note.png) #### Note This field isn't returned when you retrieve the metadata. To set the welcome, error, and escalation messages, use welcomeMessage, errorMessage, and escalationMessage. | | planner | Field Type [AiAgentDefinitionPlanner](#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. 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. | 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. ![Note](https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/images/icon_note.png) #### Note Only users with View DeveloperName OR View Setup and Configuration permission can view, group, sort, and filter this field. | | 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. | | 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. | | 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 - Object - Number - Text | | description | Field Type string Description A description of this variable. This value can be used by the Agentforce planner service. | | 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. ![Note](https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/images/icon_note.png) #### Note 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. | | 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 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 | ## Wildcard Support in the Manifest File 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](https://developer.salesforce.com/docs/atlas.en-us.264.0.api_meta.meta/api_meta/file_based_zip_file.htm "HTML (New Window)").