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.

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.

This type extends Metadata and inherits its fields.

AiAgentDefinition components have the suffix .aiAgentDefinition and are stored in the aiAgents folder. For example, aiAgents/MyAgent.aiAgentDefinition.

Introduced in API version 68.0.

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

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

• Type: boolean
• Required: No
• 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.

• Type: GenAiAgentType (enumeration of type string)
• Required: No
• 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:
• Possible values:
  • AgentforceEmployeeAgent
  • Analytics
  • AppDevAgent
  • BankingServiceAgent
  • BuyerAgent
  • CustomAgent
  • EinsteinSDR
  • EinsteinServiceAgent
  • Employee
  • ExperienceBuilder
  • FieldServiceAgent
  • GoalBasedAgent
  • GuidedShoppingAgent
  • LightningAppBuilder
  • ProspectingAgent
  • SalesCanvasAgent
  • SalesDealAgent
  • SalesEinsteinCoach
  • ScaleAgent
  • ServicePlanner
  • Setup
  • ShopperAgent
  • ThirdPartyA2AAgent

• Type: string
• Required: No
• 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.

• Type: ConversationContextVariable[]
• Required: No
• Description: The context variables that store data available to the agent during a conversation.

• Type: boolean
• Required: No
• Description: Indicates whether private conversation data is logged (true) or not (false).

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

• Type: BotType (enumeration of type string)
• Required: No
• 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.
• Possible values:
  • AgentforceOrchestrator
  • Bot
  • ExternalCopilot — An external-facing agent. For example, an Agentforce Service agent.
  • InternalCopilot — An internal-facing agent. For example, an Agentforce Employee agent.

Represents the context variable that stores data available to the agent during a conversation.

• Type: ConversationContextVariableMapping[]
• Required: No
• Description: The mappings that associate the context variable with a source field.

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

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

• 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.

• Type: boolean
• Required: No
• Description: Indicates whether the context variable is injected into the prompt sent to the Agentforce model (true) or not (false).

• Type: string

• Required: Yes

• Description: Required.

  Label that identifies a context variable throughout the Salesforce user interface.

• Type: string
• Required: No
• Description: Specifies the SObjectType of the ID stored in the context variable.

Represents the variable that associates the context variable with a source field.

• Type: string

• Required: Yes

• Description: Required.

  The name of the field mapped to the context variable.

• Type: MessageType (enumeration of type string)

• Required: Yes

• Description: Required.

  The type of message that the mapping applies to.

• Possible values:

  • Alexa
  • AppleBusinessChat
  • Custom
  • Email
  • EmbeddedMessaging
  • Facebook
  • GoogleChat
  • GoogleHome
  • InternalCopilot
  • Line
  • MsCopilot
  • Omega
  • Phone
  • PstnVoice
  • Rcs
  • SipVoice
  • Slack
  • Text
  • Voice
  • VoiceIntegrationPilot
  • WebChat
  • WeChat
  • WhatsApp
  • WhatsAppVoice

• Type: string

• Required: Yes

• Description: Required.

  Specifies the SObjectType of the ID used in the context variable mapping.

Here’s an example of an AiAgentDefinition component.

1<?xml version="1.0" encoding="UTF-8"?>
2<AiAgentDefinition xmlns="http://soap.sforce.com/2006/04/metadata">
3    <agentDSLEnabled>true</agentDSLEnabled>
4    <agentDescription>Answers common customer questions and escalates complex issues.</agentDescription>
5    <agentType>EinsteinServiceAgent</agentType>
6    <botUser>myagent.user@example.com</botUser>
7    <contextVariables>
8        <contextVariableMappings>
9            <SObjectType>MessagingSession</SObjectType>
10            <fieldName>MessagingSession.ChannelType</fieldName>
11            <messageType>EmbeddedMessaging</messageType>
12        </contextVariableMappings>
13        <dataType>Text</dataType>
14        <description>The channel the customer is messaging from.</description>
15        <developerName>ChannelType</developerName>
16        <includeInPrompt>false</includeInPrompt>
17        <label>Channel Type</label>
18    </contextVariables>
19    <logPrivateConversationData>false</logPrivateConversationData>
20    <richContentEnabled>true</richContentEnabled>
21    <type>ExternalCopilot</type>
22</AiAgentDefinition>

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.