Starting in API version 68.0, we’ve streamlined Agentforce agent metadata types to make it easier to retrieve and deploy agents. Previously, moving an agent from sandbox to production required at least three metadata types. Plus, you had to manually add every Apex class, flow, and prompt template associated with an agent action, making sure to indicate the correct agent version. With the new AiAgentDefinition and AiAgentDefinitionVersion types, Salesforce CLI now retrieves the agent and all its dependencies automatically.
Where: This change applies to Lightning Experience in Enterprise, Performance, Unlimited, and Developer Editions with Foundations or Agentforce 1 Editions. Setup for AI agents is available on the desktop site.
When: This change is available as Winter ’27 rolls out, starting with preview sandboxes the week of August 24, 2026.
How: To use the simplified metadata types, update Salesforce CLI to the latest
version and update your package manifest to reference AiAgentDefinition
and AiAgentDefinitionVersion. To retrieve an agent and its
dependencies, run sf project retrieve start --metadata AiAgentDefinitionVersion
--root-type-with-dependencies AiAgentDefinitionVersion.
You can continue to use the previous metadata types AiAuthoringBundle,
Bot, and BotVersion by specifying API version 67.0
in your package manifest.
AiAgentDefinition and AiAgentDefinitionVersion are
supported in second-generation managed packaging (managed 2GP) only.