Issues with Agentforce planner bundles (GenAiPlannerBundle) can sometimes appear as unknown exceptions during metadata retrieval or deployment. These issues are typically caused by inconsistencies in how Salesforce processes Agentforce metadata internally.

The problem is often first noticed during Gearset comparisons when retrieving Agentforce metadata. The behaviour can appear inconsistent depending on the API version or the method used to retrieve the metadata. For example, some planner bundles may appear while others fail with an unknown exception.

When retrieving planner bundles in Gearset, the app does not perform wildcard retrievals, even when all items are selected. Instead, metadata is retrieved in batches, which means some bundles may appear in comparisons even if others are problematic.

Salesforce may also report successful retrievals even when the operation did not fully complete as expected. For example, a deployment may succeed even though the metadata cannot later be retrieved, or a retrieval may succeed but return incomplete metadata. Signs of a partial retrieval include agents appearing in the non-bundled structure when a bundled structure is expected, or missing components such as schema files or the main agent XML metadata.

Agentforce planner bundles may appear in two different metadata structures, depending on how you created your agent. Earlier implementations defined topics and actions as separate metadata types referenced by the planner bundle. In newer implementations, topics and actions may be bundled directly within the planner bundle, with the associated schemas and action definitions stored alongside the bundle metadata. Understanding which structure is expected can help identify cases where metadata has been partially retrieved.

How to troubleshoot the issue

First, determine whether the issue affects all planner bundles or only specific ones.

Using the Salesforce CLI, attempt both of the following:

A wildcard retrieval to retrieve all planner bundles.
Named retrievals that request individual bundles explicitly.

Comparing the results of these retrieval methods can help identify inconsistent behaviour.

If the retrieval succeeds but the returned metadata appears incomplete, inspect the retrieved files for signs of partial retrieval, such as:

Agents appearing in an unexpected structural format.
Missing schema files for bundled actions.
Missing agent metadata files.

If all planner bundles retrieve correctly, the issue is likely unrelated to planner bundle metadata.

Salesforce CLI reference

sf project retrieve start -m GenAiPlannerBundle

Retrieve all planner bundles using a manifest

sf project retrieve start --manifest package.xml

<Package xmlns="http://soap.sforce.com/2006/04/metadata">
  <types>
    <members>*</members>
    <name>GenAiPlannerBundle</name>
  </types>
  <version>66.0</version>
</Package>

Retrieve a single planner bundle

sf project retrieve start -m GenAiPlannerBundle:Agent_1

<Package xmlns="http://soap.sforce.com/2006/04/metadata">
  <types>
    <members>Agent_1</members>
    <name>GenAiPlannerBundle</name>
  </types>
  <version>66.0</version>
</Package>

Retrieve multiple planner bundles

sf project retrieve start \
  -m GenAiPlannerBundle:Agent_1 \
  -m GenAiPlannerBundle:Other_Agent

<Package xmlns="http://soap.sforce.com/2006/04/metadata">
  <types>
    <members>Agent_1</members>
    <members>Other_Agent</members>
    <name>GenAiPlannerBundle</name>
  </types>
  <version>66.0</version>
</Package>

Agent metadata structure

Agentforce planner bundles may appear in two metadata structures, depending on the Agentforce version.

Non-bundled structure

Topics and actions are defined as separate metadata types.

Example structure:

genAiFunctions/
  MyAction/
    MyAction.genAiFunction
    input/schema.json
    output/schema.json

genAiPlannerBundles/
  MyAgent/
    MyAgent.genAiPlannerBundle

genAiPlugins/
  MyTopic/
    MyTopic.genAiPlugin

Example metadata:

<GenAiPlannerBundle>
  <genAiPlugins>
    <genAiPluginName>MyTopic</genAiPluginName>
  </genAiPlugins>
  <genAiFunctions>
    <genAiFunctionName>MyAction</genAiFunctionName>
  </genAiFunctions>
</GenAiPlannerBundle>

Bundled structure

Topics and actions are contained within the planner bundle.

Example structure:

genAiPlannerBundles/
  MyAgent/
    MyAgent.genAiPlannerBundle
    MyTopicAction/
      input/schema.json
      output/schema.json
      MyTopicAction.genAiFunction

Example metadata:

<GenAiPlannerBundle>
  <localTopics>
    <fullName>MyTopic</fullName>
    <localActions>
      <fullName>MyTopicAction</fullName>
    </localActions>
  </localTopics>

  <plannerActions>
    <fullName>MyAction</fullName>
  </plannerActions>
</GenAiPlannerBundle>

Identify problematic bundles

To determine which bundle is causing the failure, retrieve bundles individually or in smaller groups.

Two approaches can be used:

Individual retrieval

Retrieve each bundle separately and identify any bundle that fails or retrieves partially. This approach works well when the number of bundles is small.

Note that some bundles may only fail when retrieved alongside others.

Bisection method

For larger sets of bundles, retrieve groups of bundles and progressively narrow down the failing group.

Example workflow:

Retrieve half of the bundles.
Retrieve the other half.
Identify which group fails.
Split the failing group again.
Repeat until the problematic bundle is identified.

This approach is faster when many bundles are present and can also reveal issues triggered by multi-bundle retrieval.

For more information on this method check out our guide on How to use the bisection method to debug retrieval errors?

Attempt to repair the problematic bundle

Once the problematic bundle is identified, modifying the metadata can trigger Salesforce to reprocess the agent.

Possible approaches include, ordered from lowest to highest impact.

Minor metadata update:

Make a small change to the bundle metadata, such as modifying the <description> field. This may force Salesforce to regenerate the metadata representation.