Agentforce
AiAgentDefinition: deploy Agentforce metadata across orgs
Check API versions, agent versions and dependencies before moving an Agentforce build from sandbox to production.
An agent deployment can fail because the source and destination use different metadata models. Check both orgs before changing the manifest.
Salesforce’s deployment guide introduces updated agent metadata for API v68. It says both orgs must support v68 to use that model; a v68 sandbox targeting a v67 production org must use the earlier metadata approach.
Make the version choices explicit
Record the source API version, target API version, CLI version and agent version being released. Keep that information beside the deployment manifest so another engineer can reproduce the artifact.
For the v68 model, Salesforce documents AiAgentDefinition and AiAgentDefinitionVersion. The top-level definition must exist in the target or be included, and a deployed definition needs at least one version. Agent Script builds also require their AiAuthoringBundle.
Don’t combine the new version metadata with the matching legacy BotVersion in one package. Follow the guide’s manifest examples for the exact agent and versions you intend to release.
Retrieve dependencies through the supported path
The guide documents this argument for retrieving or deploying the applicable action dependencies:
--root-type-with-dependencies AiAgentDefinitionVersion
That doesn’t make every surrounding configuration automatic. Custom objects, fields and other required metadata still need deliberate inclusion.
Inspect the retrieved diff before committing. Confirm that the artifact contains the intended prompts, actions and version references, without unrelated sandbox experiments. Keep secrets and environment-specific authentication outside source-controlled metadata where the platform requires separate configuration.
Also review the target’s feature enablement and permissions. A successful metadata operation doesn’t establish that the intended user can invoke every action.
Validate behavior after deployment
Use a non-production target first. Run a small acceptance set covering a normal request, missing data, an unauthorized action and a failed dependency. Inspect the underlying record changes as well as the agent’s reply.
Confirm which version is active and how channels or clients reach it. Document the rollback decision before production release: restoring metadata, selecting an earlier version and repairing data are different operations.
If a deployment fails, preserve the precise error and artifact version. Don’t keep broadening the manifest until the error disappears without understanding which dependency was missing.
For actions that write records or call external services, include the failure-handling checks in release acceptance. The deployment is complete when the target version performs the approved workflow under the intended identity, not merely when the CLI reports success.