Develop and Package Agent Templates Using Scratch Orgs

At a high-level, agents are distributed by ISVs as agent templates. To package an agent template you first create and test an agent in a namespaced scratch org, retrieve the agent to your Salesforce DX project, generate an agent template from the agent using Salesforce CLI, and finally package the agent template.

If you’re packaging an agent template in October 2025 or later, follow the workaround instructions for packaging agent templates. Due to a known issue with packaging local actions and topics, you must package agent templates using the workaround instructions at this time.

Important

Workflow for Agent Template Development

Six squares of text showing the agent template workflow

Agent and Agent Template Metadata

To package an agent template it helps to first understand the metadata types that make up an agent and an agent template.

Agents are defined by these major metadata types.

Bot
BotVersion
GenAiPlannerBundle

The GenAiPlannerBundle type in turn defines the agent's topics and actions. The agent generate template Salesforce CLI command brings together the metadata files for these three types and generates a BotTemplate file for a specific agent (Bot and BotVersion). You then use the BotTemplate file, and the GenAiPlannerBundle file, to package the agent template in a managed package.

Compare the MD types for agent MD with the agent template MD types

Create an Agent

Create and test your agent.

From Setup in your scratch org, enter Agents in the Quick Find box, and select Agentforce Agents. Then locate and enable the Agentforce setting and refresh the page.

Click New Agent, and then select an agent type.
Follow the guided setup steps, and then click Create.

For more guidance, see the documentation for the agent type you chose. For details about creating an agent, see Set Up Your Agent.

Agentforce-enabled scratch orgs have access to the Agentforce Testing Center. For more detailed information on testing your agents directly in your DX project, see Test an Agent with Agentforce DX in the Agentforce Developer Guide.

Set Up Your Salesforce DX Project and Scratch Org

To set up a Salesforce DX project and scratch org, you must already have a namespace and scratch org ready to use.

For guidance on obtaining a namespace or an Agentforce-enabled scratch org, see Get Access to Scratch Orgs with Agentforce Enabled.

To package BotTemplate metadata, you must first enable Einstein Chatbot in your Dev Hub org. You must also specify this metadata in your project-scratch-def.json file.

Note

If you’re using an existing Salesforce DX project that contains Apex classes, flows, or prompt templates for your agent, deploy them to the scratch org.
1sf project deploy start --source-dir force-app --target-org MyNamespacedScratchOrg
Open the scratch org.
1sf org open

Develop Your Agentforce Package

After you have built and tested your agent, you are ready to start packaging it.

Retrieve the relevant metadata into your Salesforce DX project.

1sf project retrieve start --metadata Agent:My_Awesome_Agent –-target-org MyNamespacedScratchOrg

Create an agent template metadata source file.

In this example, we are generating an agent template from a Bot metadata file in your DX project that corresponds to the My_Awesome_Agent agent. A single Bot can have multiple BotVersions. Use the --agent-version flag to specify the version.
1sf agent generate template --agent-file force-app/main/default/bots/My_Awesome_Agent/My_Awesome_Agent.bot-meta.xml --agent-version 1
For more details on the agent generate template command, see the Salesforce CLI Reference Guide.

Deploy the agent template metadata source file to your scratch org.

1sf project deploy start  --source-dir force-app --target-org MyNamespacedScratchOrg

When you're satisfied with your agent template, remove the following metadata from your package directory.
1. The GenAiPlannerBundle file that was part of your original agent. This file was used to create a new, separate GenAiPlannerBundle file for your agent template and is not necessary to package. Remove the GenAiPlannerBundle file that does not have “Template” in the name.
2. The Bot and BotVersion. Removing these metadata types prevents errors during packaging, since agents aren’t packageable.
To package prompt templates, you must assign permissions in the sfdx-project.json file. See Packaging Considerations for Prompt Templates.
Note
After you’ve tested your agent, create a new package version that contains the template and all dependencies. Possible dependencies include: topics, actions, Apex classes, flows, and prompt templates.
1sf package version create --package "Agentforce App" --installation-key “HIF83kS8kS7C” --definition-file config/project-scratch-def.json --code-coverage --wait 10

After a subscriber installs your package in their Agentforce-enabled org, they can use the Agentforce UI to create an agent from your template.

User interface with ISV Agent Template tile

Second-Generation Managed Packaging Developer Guide

Develop and Package Agent Templates Using Scratch Orgs

Agent and Agent Template Metadata

Create an Agent

Set Up Your Salesforce DX Project and Scratch Org

Develop Your Agentforce Package

See Also