Agentforce metadata types — Bot, BotVersion, GenAiPlannerBundle, GenAiPlugin, GenAiFunction, GenAiPromptTemplate, AiAuthoringBundle, AiEvaluationDefinition, and how they reference each other
The metadata that makes up an Agentforce agent in a DX project and how the pieces connect — the two authoring models (Agent Script in an AiAuthoringBundle with Bot and BotVersion, or the classic planner bundle with topics and actions), each type's folder, suffix and shape, the names that link them (genAiPluginName, functionName, invocationTarget), the other AI types (prompt templates, evaluations, search index config), and a manifest that moves a whole agent.
markdownreferencev283GR-6AZ4stage: buildtrust: officialservice: agentforceinterface: iacinterface: cliAgentforce metadataBotBotVersionbots folderv1.botVersion-meta.xmlGenAiPlannerBundlegenAiPlannerBundlesplannerType AiCopilot__ReActGenAiPlugin topicgenAiPluginsgenAiPluginNamecanEscalateGenAiFunction actiongenAiFunctionsinput/schema.json output/schema.jsoninvocationTargetinvocationTargetType apex flowisConfirmationRequiredprogressIndicatorMessagestandard actions EmployeeCopilot__QueryRecordsGenAiPromptTemplateGenAiPromptTemplateActvAiAuthoringBundleaiAuthoringBundles.agent filebundleType AGENTAgent ScriptAiEvaluationDefinitionaiEvaluationDefinitionsAiTestingDefinitionAiAgentDefinitionDataObjectSearchIndexConfLightningTypeBundleagent manifest package.xml--root-type-with-dependencies
Agentforce metadata types
Two ways an agent exists in source
| Model | Files | Where it comes from |
|---|---|---|
| Agent Script (the current, recommended Agentforce DX workflow) | aiAuthoringBundles/<Agent>/<Agent>.agent (the script) + <Agent>.bundle-meta.xml (<bundleType>AGENT</bundleType>), plus the published Bot / BotVersion | sf agent generate authoring-bundle, or sf project generate --template agent (reference/agentforce/agent-script.md) |
Classic (built in Agentforce Builder, or from sf agent create) | Bot + BotVersion, a GenAiPlannerBundle, GenAiPlugin topics, GenAiFunction actions | Retrieve from the org (--root-type-with-dependencies Bot) |
Agent Script calls topics subagents (subagent <name>: blocks). Classic metadata still calls them topics, as GenAiPlugin.
The types
| Type | Folder, file | What it is |
|---|---|---|
Bot (decomposed) | bots/<Agent>/<Agent>.bot-meta.xml + v1.botVersion-meta.xml | The agent and its versions |
GenAiPlannerBundle (bundle) | genAiPlannerBundles/<Agent>/<Agent>.genAiPlannerBundle | The agent's planner: plannerType (Coral Cloud: AiCopilot__ReAct), its topics (genAiPlugins/genAiPluginName) and agent-level actions (genAiFunctions/genAiFunctionName) |
GenAiPlugin | genAiPlugins/<Topic>.genAiPlugin-meta.xml | A topic: description, scope and instructions, canEscalate, and its actions (genAiFunctions/functionName) |
GenAiFunction (bundle) | genAiFunctions/<Action>/<Action>.genAiFunction-meta.xml + input/schema.json + output/schema.json | An action: invocationTarget (an Apex class, flow or prompt template API name), invocationTargetType (apex, flow…), isConfirmationRequired, progress message; the schemas describe inputs and outputs to the reasoning engine |
| Standard actions | Referenced by name, not files: EmployeeCopilot__QueryRecords, EmployeeCopilot__SummarizeRecord, EmployeeCopilot__GetRecordDetails, EmployeeCopilot__AnswerQuestionsWithKnowledge | Salesforce-provided actions |
AiAuthoringBundle (bundle) | aiAuthoringBundles/<Agent>/ | An Agent Script agent |
GenAiPromptTemplate | genAiPromptTemplates/<Name>.genAiPromptTemplate-meta.xml | A Prompt Builder template (family 6); GenAiPromptTemplateActv is its activation |
AiEvaluationDefinition | aiEvaluationDefinitions/<Name>.aiEvaluationDefinition-meta.xml | An agent test suite (reference/agentforce/agent-testing.md); AiTestingDefinition is also registered |
DataObjectSearchIndexConf | dataObjectSearchIndexConfs | A Data 360 search index configuration (reference/data360/search-indexes-and-retrievers.md) |
LightningTypeBundle | lightningTypes/<Name>/ | Custom input and output rendering for actions |
| Also registered | AiAgentDefinition, AiAgentDefinitionVersion, AIApplication, AiAgentScorerDefinition, ExternalAIModel | Newer AI types. At API 68.0+ sf agent publish retrieves an agent as AiAgentDefinition + AiAgentDefinitionVersion instead of Bot/GenAiPlugin/GenAiFunction (reference/agentforce/agent-script-actions-and-targets.md). The hub's reading: generate or retrieve them rather than hand-writing them |
How the names chain: Bot → GenAiPlannerBundle → GenAiPlugin (topic) → GenAiFunction (action) → invocationTarget (Apex class, flow, prompt template). Each link is a plain API name, so a rename breaks the chain silently until deploy time.
Moving a whole agent
Salesforce's agent project template deploys with this manifest (wildcards per type, <version> set to the project's API version):
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
<types><members>*</members><name>AiAuthoringBundle</name></types>
<types><members>*</members><name>ApexClass</name></types>
<types><members>*</members><name>Bot</name></types>
<types><members>*</members><name>BotVersion</name></types>
<types><members>*</members><name>Flow</name></types>
<types><members>*</members><name>GenAiPlannerBundle</name></types>
<types><members>*</members><name>GenAiPromptTemplate</name></types>
<types><members>*</members><name>PermissionSet</name></types>
<types><members>*</members><name>PermissionSetGroup</name></types>
<version>66.0</version>
</Package>For a classic agent, add GenAiPlugin and GenAiFunction. Deploy actions (Apex, flows, prompt templates) before, or in the same deploy as, the agent that references them.