Skip to main content
New tool CRON Expression Builder — preview next run times before you schedule Apex. Open the builder →
Diagram of an Agentforce agent migrating from Bot and BotVersion to AiAgentDefinition at API 68.0
Agentforce & AI

AiAgentDefinition: Migrate Agentforce from Bot at API 68.0

At API 68.0, Agentforce agents no longer retrieve or deploy as Bot and BotVersion, so pipelines still using those types fail. This guide maps them to AiAgentDefinition and AiAgentDefinitionVersion, then covers the manifest rewrite, dependency retrieval limits and the deploy validations that catch half-migrated pipelines.

The short answer

At API 68.0, Agentforce agents retrieve and deploy as AiAgentDefinition (the agent) and AiAgentDefinitionVersion (each version, with the planner inline), and Bot or BotVersion now return an error for them. To postpone the switch, pin a manifest's version to 67.0, where the old types still work.

Key takeaways Move every agent manifest to AiAgentDefinition at 68.0. To postpone the switch for one deploy path, pin that manifest's to 67.0, where Bot and BotVersion still work. Use the AgentName#* member form for agents still in development, so adding a version doesn't mean editing the manifest. Run --root-type-with-dependencies as a deliberate developer step and commit the result. Keep it out of CI, because it is capped at 25 requests per day and only reaches one level deep. Every 68.0 deploy should carry the AiAgentDefinition (at least on first deploy), each version and each version's AiAuthoringBundle, with no legacy BotVersion for the same agent. Handle the agent username with sfdx-project.json string replacement for drafts, and plan a new version when a committed agent needs a different user.

If your pipeline moved to API 68.0 and the agent retrieve started failing, the error is accurate. At 68.0, Bot and BotVersion belong to classic Einstein Bots only, and Agentforce agents move as AiAgentDefinition and AiAgentDefinitionVersion. Winter '27 reached production orgs in October 2026, so every org can take the new types today. The rename itself is mechanical. What fails deploys is a half-finished switch, such as a manifest that still lists BotVersion or an agent user that exists only in the source org.

What moved where at API 68.0

Up to 67.0, one agent with a single version was split across Bot (with its BotVersion files), GenAiPlannerBundle and AiAuthoringBundle. At 68.0 the agent and each of its versions get their own types, the planner folds into the version file, and the Agent Script source keeps its own bundle. The content survives the move unchanged; only names and packaging differ.

Before 68.0 At 68.0 SFDX folder Member name
Bot, agent-level settings (ClaimsTriageAgent.bot-meta.xml) AiAgentDefinition aiAgents ClaimsTriageAgent
BotVersion (v2.botVersion-meta.xml) AiAgentDefinitionVersion aiAgentDefinitionVersions ClaimsTriageAgent#2
GenAiPlannerBundle (ClaimsTriageAgent_v2) <planner> element inside the version file (merged into the version) (none)
AiAuthoringBundle (newest unsuffixed, older ones _1, _2) AiAuthoringBundle, always suffixed aiAuthoringBundles ClaimsTriageAgent_2

The definition holds the agent's type, description, context variables and other agent-level settings. Each version file holds that version's settings, conversation variables and messages, plus an inline <planner> with its subagents and actions.

Three naming changes affect anything that diffs or parses these files.

The authoring bundle name is now stable. At 67.0 and earlier, the newest bundle had no suffix, so the folder you were editing got a new name on the next retrieve after someone created a version. At 68.0 every bundle carries its version suffix from the start, and ClaimsTriageAgent_1 keeps that name after version 2 exists.

Generated suffixes on subagents and actions are gone. A name like PolicyLookup_18a40c7f2e91d3b becomes PolicyLookup. The suffixed fullName and developerName elements are removed, localDeveloperName is the name, and subagents reference actions through it. Folders inside the version use the names you gave them, such as PolicyLookup/FetchPolicyByNumber. These names stay the same across versions, so a diff between version 2 and version 3 shows what changed in behaviour without hundreds of renamed identifiers.

The version file also has welcomeMessage, errorMessage and escalationMessage elements. Each one is the first message of the Welcome, Error_Handling or Transfer_To_Agent dialog, and Salesforce builds those dialogs from them on deploy.

Writing the manifest with the # member syntax

Versions are addressed with a # delimiter. ClaimsTriageAgent#2 is one version, ClaimsTriageAgent#* is every version of that agent, and * is every version of every agent. Here is a 68.0 manifest for an agent with three versions:

<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
    <types>
        <members>ClaimsTriageAgent</members>
        <name>AiAgentDefinition</name>
    </types>
    <types>
        <members>ClaimsTriageAgent#*</members>
        <name>AiAgentDefinitionVersion</name>
    </types>
    <types>
        <members>ClaimsTriageAgent_1</members>
        <members>ClaimsTriageAgent_2</members>
        <members>ClaimsTriageAgent_3</members>
        <name>AiAuthoringBundle</name>
    </types>
    <types>
        <members>ClaimsCoverageService</members>
        <name>ApexClass</name>
    </types>
    <types>
        <members>Claims_Create_Followup_Task</members>
        <name>Flow</name>
    </types>
    <version>68.0</version>
</Package>

I would default to #* for agents that are still changing. You don't edit the manifest when someone adds a version, and source and target stay aligned, which matters because a mismatch blocks later deploys (more on that below). The cost is that you can't hold one version back. If you need to, name versions explicitly and accept that you'll edit the manifest every time.

On the command line, wrap the value in double quotes. Otherwise the shell treats # as the start of a comment and * as a glob:

# The # member syntax and the dependency flag need CLI 2.149.9 or later
sf update
sf project retrieve start \
  --metadata "AiAgentDefinitionVersion:ClaimsTriageAgent#*" \
  --target-org claims-dev

Without a manifest, the CLI uses sourceApiVersion from sfdx-project.json, and that has to be 68.0 for these types to resolve.

Retrieving dependencies without burning the daily cap

Without extra flags, a retrieve returns only what you name. --metadata AiAgentDefinitionVersion on its own returns every version of every agent, but no parent definitions, no authoring bundles and nothing the actions call. Adding --root-type-with-dependencies AiAgentDefinitionVersion also pulls each version's AiAgentDefinition, its AiAuthoringBundle, the flows, Apex classes and prompt templates its actions invoke, and any global subagents and actions it uses:

sf project retrieve start \
  --metadata "AiAgentDefinitionVersion:ClaimsTriageAgent#3" \
  --root-type-with-dependencies AiAgentDefinitionVersion \
  --target-org claims-dev

From API 64.0 to 67.0, dependency retrieval only worked on a whole Bot with all its versions, so being able to pull one version is a real improvement. The limits are tight, though:

  • 25 retrieve requests with dependencies per day, each capped at 100 components.
  • One level deep. If an action calls ClaimsCoverageService and that class calls ClaimsRateTable, you get only the first class.
  • Custom objects, custom fields and Data 360 dependencies aren't included, so list them yourself.

Because of the cap, keep this flag out of CI. If a build runs it on every push, parallel branches will use up the 25 requests before lunch. Run it as a developer step when an agent's action set changes, check the output, add the second-level classes and fields by hand, commit, and let the pipeline deploy from the explicit manifest.

The Move an Agent guide recommends the flag over listing flows, Apex and prompt templates yourself. Listing them explicitly gives up that convenience in exchange for a pipeline that doesn't spend the daily cap.

The compiled Agent Script in the version's agentScript folder belongs to the version itself and arrives with or without the flag.

The four validations that fail a half-migrated deploy

  1. Legacy and new types for the same agent in one deployment. A version can't be deployed alongside the matching legacy BotVersion. This usually happens when someone adds the new types to a manifest and forgets to remove the old ones.
  2. A version with no definition, or a definition with no version. If the target org doesn't already have the AiAgentDefinition, it has to be in the same deploy, and a new definition on its own fails too. The first deploy to any org needs both.
  3. An Agent Script agent deployed without its AiAuthoringBundle. The agentScript folder inside the version is compiled output and can't stand in for the source, so ship the bundle with the version.
  4. The agent user. Retrieved metadata carries the source org's agent username, and that user usually doesn't exist in the target.

For a draft agent, fix the agent user with string replacement. The username sits in the .agent file's default_agent_user property, so the replacement has to cover .agent files as well as *-meta.xml:

{
  "packageDirectories": [{ "path": "force-app", "default": true }],
  "sourceApiVersion": "68.0",
  "replacements": [
    {
      "glob": "force-app/**/*-meta.xml",
      "stringToReplace": "[email protected]",
      "replaceWithEnv": "CLAIMS_AGENT_USERNAME"
    },
    {
      "glob": "force-app/**/*.agent",
      "stringToReplace": "[email protected]",
      "replaceWithEnv": "CLAIMS_AGENT_USERNAME"
    }
  ]
}
export CLAIMS_AGENT_USERNAME="[email protected]"
sf project deploy start --manifest manifest/claims-agent.xml --target-org claims-uat

Committed agents are harder. The Move an Agent guide says string replacement can't change a committed agent's username, and a committed version can't be edited at all. The string-replacement example page says its method works for committed and uncommitted agents. Until Salesforce reconciles the two pages, treat replacement on committed agents as not yet confirmed and plan for the strict reading: create a new version with the correct user. If a draft lands without replacement, update the agent user manually before anyone runs it. Whichever user you pick needs permissions for everything the agent does, down to read access on the custom fields its actions query.

Moving an existing pipeline to 68.0

Winter '27 reached production in October 2026, so the 68.0 types are available in every org and nothing forces you to wait. Staying on 67.0 is now a choice you make per manifest: pin its <version> to 67.0 and Bot and BotVersion keep working for that manifest. Both orgs in a deploy still have to be on 68.0 for the new types, a rule that comes back whenever a preview sandbox runs ahead of production. If you raise sourceApiVersion before the target org is on 68.0, the target can't accept the files you retrieved. Keeping one manifest per target, each with its own <version>, lets you move paths one at a time.

To switch a path:

  1. Run sf update and confirm the CLI is 2.149.9 or later.
  2. Set the manifest <version> and sourceApiVersion to 68.0.
  3. Retrieve the agents fresh from the org instead of converting the old files by hand.
  4. Commit the switch on its own. Every agent folder and file name changes, and you want that diff kept apart from logic changes in review.
  5. Point any scripts that read GenAiPlannerBundle or suffixed names at <planner> and localDeveloperName.
  6. Add a guard so a manifest can't mix eras:
#!/usr/bin/env bash
# check-agent-manifest.sh: fail when agent types don't match the manifest API version
set -euo pipefail
manifest="${1:?usage: check-agent-manifest.sh path/to/package.xml}"

api=$(sed -n 's:.*<version>\([0-9.]*\)</version>.*:\1:p' "$manifest")
[[ -n $api ]] || { echo "ERROR: no <version> in $manifest" >&2; exit 1; }
major=${api%%.*}
has_type() { grep -q "<name>$1</name>" "$manifest"; }

if (( major >= 68 )); then
  # Bot and BotVersion stay legal at 68.0 for classic Einstein Bots; this blocks BotVersion assuming the project has no classic bots (see the allowlist note below)
  for legacy in BotVersion GenAiPlannerBundle; do
    if has_type "$legacy"; then
      echo "ERROR: $manifest is API $api but lists $legacy; use AiAgentDefinitionVersion" >&2
      exit 1
    fi
  done
  if has_type AiAgentDefinitionVersion && ! has_type AiAgentDefinition; then
    echo "WARN: versions without AiAgentDefinition; a first deploy to this org will fail" >&2
  fi
else
  if has_type AiAgentDefinition || has_type AiAgentDefinitionVersion; then
    echo "ERROR: $manifest is API $api; AiAgentDefinition types need 68.0 in both orgs" >&2
    exit 1
  fi
fi

If your org still runs classic Einstein Bots that use BotVersion, give the guard an allowlist of those bot names instead of deleting the check.

What to watch for

  • Managed packaging isn't supported for AiAgentDefinition or AiAgentDefinitionVersion. ISVs shipping agents need a different distribution plan for now.
  • After a deploy, the source and target agents must match, or later deploys are blocked. If someone creates a version directly in the target, create the matching version in source.
  • Don't hand-edit retrieved agent metadata beyond the username replacement. Salesforce warns that deploying modified agent metadata can corrupt the org.
  • Salesforce advises against keeping the compiled agentScript folder in source control. Whether excluding it through .forceignore affects deploys is not yet confirmed, so test that in a scratch org before you rely on it.
  • Check edition availability before you plan a migration: the release note lists Enterprise, Performance, Unlimited and Developer Editions with Foundations or Agentforce 1 Editions.

Originally reported by developer.salesforce.com

Frequently asked questions

Why does retrieving Bot metadata fail for Agentforce agents at API 68.0?

At 68.0, Bot and BotVersion are reserved for classic Einstein Bots, so a retrieve or deploy that targets an Agentforce agent with them returns an error pointing you to AiAgentDefinition and AiAgentDefinitionVersion. To keep using the old types, set the manifest version to 67.0.

How do I list every AiAgentDefinitionVersion for one agent in package.xml?

Use the agent name followed by #*, for example ClaimsTriageAgent#*. Use ClaimsTriageAgent#2 for a single version, or * for every version of every agent. On the command line, wrap the value in double quotes so the shell leaves # and * alone.

Do both source and target orgs need API 68.0 to deploy AiAgentDefinition?

Yes. The new types only move between orgs that are both on 68.0. Production orgs have been there since Winter '27 finished rolling out in October 2026, but the rule applies again whenever a preview sandbox runs ahead of production, and that path stays on Bot, BotVersion and GenAiPlannerBundle at 67.0 until both sides match.

Does --root-type-with-dependencies retrieve custom fields and nested Apex classes?

No. It goes one level deep, so it brings back the Apex class an action calls but not the classes that class depends on, and it skips custom objects, custom fields and Data 360 dependencies, which you list yourself. It is capped at 25 requests per day and 100 components per request.

Can AiAgentDefinition be included in a managed package?

No. The Winter '27 release note says managed packaging isn't supported for the new agent metadata types.

Newsletter

One email every Tuesday

New guides, tool updates, and the release-note changes that break things.

No spam. Unsubscribe in one click.

Comments

Loading comments...

Leave a Comment