--- schema_version: "1" id: fa9096d3ccd6024effb48a7dedbd2f6e5da977566d16c69ffb2406a50fbcc4dc title: AiAgentDefinition collection: legacydeveloper version: current locale: en-us portal_url: https://docs.salesforce.com/legacydeveloper/current/en-us/api_meta/meta_aiagentdefinition.md canonical_url: https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/meta_aiagentdefinition.htm source_site: developer.salesforce.com content_type: documentation content_hash: 25cc820ba752d4d6594af888f677746a0f4aa2f2265cbae6f449b0e1ae91f4f8 description: Represents an Agentforce agent and the settings that apply to all its versions, such as its type and its context variables. Each version of the agent is a separate AiAgentDefinitionVersion component. For information about retrieving and deploying an Agentforce agent, see Use Use Metadata to Move an Agent to a New Org. --- # AiAgentDefinition Represents an Agentforce agent and the settings that apply to all its versions, such as its type and its context variables. Each version of the agent is a separate AiAgentDefinitionVersion component. 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 AiAgentDefinition components have the suffix .aiAgentDefinition and are stored in the aiAgents folder. For example, aiAgents/MyAgent.aiAgentDefinition. ## Version AiAgentDefinition components are available in API version 68.0 and later. ## Special Access Rules AiAgentDefinition is available only if Agents is enabled in your org. ## Fields | Field Name | Description | | --- | --- | | agentDescription | Field Type string Description A description of the agent. | | agentDSLEnabled | Field Type boolean Description Indicates whether the agent is defined using Agent Script (true) or not (false). When you deploy a new agent with this field set to true, include the agent's AiAuthoringBundle in the deployment unless the target org already has it. | | agentType | Field Type string Description The type of agent, for example, EinsteinServiceAgent. Required when type is InternalCopilot or ExternalCopilot\`. For InternalCopilot agents, you can't change this value after the agent is created.Valid values are: - AgentforceEmployeeAgent - Analytics - AppDevAgent - BankingServiceAgent - BuyerAgent - CustomAgent - EinsteinSDR - EinsteinServiceAgent - Employee - ExperienceBuilder - FieldServiceAgent - GoalBasedAgent - GuidedShoppingAgent - LightningAppBuilder - ProspectingAgent - SalesCanvasAgent - SalesDealAgent - SalesEinsteinCoach - ScaleAgent - ServicePlanner - Setup - ShopperAgent - ThirdPartyA2AAgent | | botUser | Field Type string Description The username of the user that the agent runs as. Use the username, not the user's name or ID. The user must be an active standard user with access to the agent. Not supported when agentType is Employee or AgentforceEmployeeAgent. | | contextVariables | Field Type [ConversationContextVariable\[\]](#ConversationContextVariable) Description The context variables that store data available to the agent during a conversation. | | logPrivateConversationData | Field Type boolean Description Indicates whether private conversation data is logged (true) or not (false). | | richContentEnabled | Field Type boolean Description Indicates whether the agent supports rich content in its responses (true) or not (false). | | type | Field Type string Description The configuration type of the agent. Always set this field. If you omit this field when you create an agent, the agent gets type Bot and is retrieved as a Bot component, not an AiAgentDefinition component. You can't change the type after the agent is created. Valid values are: - AgentforceOrchestrator - Bot - ExternalCopilot—An external-facing agent. For example, an Agentforce Service agent. - InternalCopilot—An internal-facing agent. For example, an Agentforce Employee agent. | ## ConversationContextVariable Represents the context variable that stores data available to the agent during a conversation. | Field Name | Description | | --- | --- | | contextVariableMappings | Field Type [ConversationContextVariableMapping\[\]](#ConversationContextVariableMapping) Description The mappings that associate the context variable with a source field. | | 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 context variable. This value may 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 context variable is injected into the prompt sent to the Agentforce model (true) or not (false). | | label | Field Type string Description Required. Label that identifies a context variable throughout the Salesforce user interface. | | SObjectType | Field Type string Description Specifies the SObjectType of the ID stored in the context variable. | ## ConversationContextVariableMapping Represents the variable that associates the context variable with a source field. | Field Name | Description | | --- | --- | | fieldName | Field Type string Description Required. The name of the field mapped to the context variable. | | messageType | Field Type MessageType (enumeration of type string) Description Required. The type of message that the mapping applies to. Valid values are: - Alexa - AppleBusinessChat - Custom - Email - EmbeddedMessaging - Facebook - GoogleChat - GoogleHome - InternalCopilot - Line - MsCopilot - Omega - Phone - PstnVoice - Rcs - SipVoice - Slack - Text - Voice - VoiceIntegrationPilot - WebChat - WeChat - WhatsApp - WhatsAppVoice | | SObjectType | Field Type string Description Required. Specifies the SObjectType of the ID used in the context variable mapping. | ## Declarative Metadata Sample Definition Here's an example of an AiAgentDefinition component. true Answers common customer questions and escalates complex issues. EinsteinServiceAgent myagent.user@example.com MessagingSession MessagingSession.ChannelType EmbeddedMessaging Text The channel the customer is messaging from. ChannelType false false true ExternalCopilot ## 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)").