AiAgentDefinition Metadata Type in SFDX

Architectural Overview#

In Salesforce Agentforce, an autonomous agent is more than a prompt—it is a governed identity with a defined role, channel bindings, security context, and reasoning engine. The AiAgentDefinition metadata type represents the top-level header definition of an AI agent in Agent Builder.

Architecturally, AiAgentDefinition separates the persistent identity of the agent (its API name, agent classification such as Service Agent or Employee Agent, and company context) from its versioned implementation (AiAgentDefinitionVersion) and reasoning bundle (GenAiPlannerBundle).

SFDX Directory & File Suffix#

Key Metadata Fields#

Declarative XML & package.xml Examples#

Sample .aiAgentDefinition-meta.xml#

<?xml version="1.0" encoding="UTF-8"?>
<AiAgentDefinition xmlns="http://soap.sforce.com/2006/04/metadata">
    <agentType>ServiceAgent</agentType>
    <companyDescription>Global B2B industrial equipment manufacturer providing 24/7 order and warranty support.</companyDescription>
    <description>Autonomous service agent handling order status inquiries, RMA initiation, and shipment tracking.</description>
    <masterLabel>Enterprise Order Support Agent</masterLabel>
    <roleDescription>You are a helpful, concise B2B Customer Support Specialist assisting verified account contacts with orders and returns.</roleDescription>
</AiAgentDefinition>

Sample package.xml Manifest#

<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
    <types>
        <members>Enterprise_Order_Support_Agent</members>
        <name>AiAgentDefinition</name>
    </types>
    <version>68.0</version>
</Package>

SFDX CLI Retrieval & Deployment#

Retrieve and deploy AiAgentDefinition components using the Salesforce CLI:

# Retrieve all AI Agent Definitions in the org
sf project retrieve start --metadata "AiAgentDefinition:*"

# Deploy a specific AI Agent Definition
sf project deploy start --metadata "AiAgentDefinition:Enterprise_Order_Support_Agent"

Senior Architect Best Practices & Gotchas#

• Least-Privilege Execution Context: Service Agents execute under a dedicated Einstein Agent User license. Provision a tailored PermissionSet granting access only to the objects, fields, Apex classes, and Flows required by the agent’s GenAiFunction actions.
• Keep Role & Company Descriptions Crisp: The roleDescription and companyDescription fields are injected into the planner’s system prompt on every turn. Avoid bloated paragraphs that consume context window tokens; keep instructions specific and conflict-free with topic-level instructions in GenAiPlugin.
• Full Bundle Promotion: Always retrieve and deploy AiAgentDefinition, AiAgentDefinitionVersion, and GenAiPlannerBundle together so version pointers remain synchronized across sandboxes.

Frequently asked questions

What is the role of AiAgentDefinition in Agentforce architecture?

AiAgentDefinition is the top-level metadata container for an Agentforce agent, storing its master label, agent type, system persona description, and associated versions.

Where are AiAgentDefinition files stored in an SFDX project?

They are stored in force-app/main/default/aiAgentDefinitions with the .aiAgentDefinition-meta.xml file suffix.

How does AiAgentDefinition relate to AiAgentDefinitionVersion and GenAiPlannerBundle?

AiAgentDefinition acts as the parent header, while AiAgentDefinitionVersion captures specific versioned snapshots that link to the underlying GenAiPlannerBundle reasoning engine.

Can I deploy an AiAgentDefinition with a hardcoded production username?

Avoid hardcoding environment-specific usernames across sandboxes; use SFDX string replacements or environment-specific variables for the execution user field.