AiAgentDefinition

Parent Type

This type extends the Metadata 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[] 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[] 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.

<?xml version="1.0" encoding="UTF-8"?>
<AiAgentDefinition xmlns="http://soap.sforce.com/2006/04/metadata">
    <agentDSLEnabled>true</agentDSLEnabled>
    <agentDescription>Answers common customer questions and escalates complex issues.</agentDescription>
    <agentType>EinsteinServiceAgent</agentType>
    <botUser>myagent.user@example.com</botUser>
    <contextVariables>
        <contextVariableMappings>
            <SObjectType>MessagingSession</SObjectType>
            <fieldName>MessagingSession.ChannelType</fieldName>
            <messageType>EmbeddedMessaging</messageType>
        </contextVariableMappings>
        <dataType>Text</dataType>
        <description>The channel the customer is messaging from.</description>
        <developerName>ChannelType</developerName>
        <includeInPrompt>false</includeInPrompt>
        <label>Channel Type</label>
    </contextVariables>
    <logPrivateConversationData>false</logPrivateConversationData>
    <richContentEnabled>true</richContentEnabled>
    <type>ExternalCopilot</type>
</AiAgentDefinition>

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.