Customize an Agent Built With Agentforce DX

After you create a basic agent, customize it so that it does what you want. As always, you can use low-code builders or pro-code developer tools to develop the different parts of the agent.

The main way you customize an agent is to add more topics and actions. Sometimes you can use an existing topic or action from your development org’s reference library. But at other times, to meet your specific business needs, you must create a custom topic or action.

This table lists the various customizations you can make to your agent, the best tool to use, and where to get more information.

Customization Task	Best Tool	Related Documentation
Add a standard action from the reference library to an existing topic.	Use Agentforce Builder.	Add an Action to a Topic Standard Agent Action Reference
Create a custom action based on an Apex class, and then add it to an existing topic.	To help you code the Apex class, use VS Code with Agentforce for Developers. To add it to a topic, use Agentforce Builder.	Build Custom Actions using Apex REST. Apex Development with VS Code Salesforce Extensions Agentforce for Developers Create a Custom Action for Agents Add an Action to a Topic
Create a custom action based on an autolaunched flow, and then add it to an existing topic.	To create the flow, use Flow Builder. To add it to a topic, use Agentforce Builder.	About Flows and Flow Builder Create a Custom Action for Agents Add an Action to a Topic
Create a custom action based on a prompt template, and then add it to an existing topic.	To create the prompt template, use Prompt Builder. To add it to a topic, use Agentforce Builder.	Prompt Builder Create a Custom Action for Agents Add an Action to a Topic
Create a custom action based on an external service and then add it to an existing topic.	To create the external service, use Setup in your org. To add it to a topic, use Agentforce Builder.	Use Agentforce to Invoke External Service Actions Create a Custom Action for Agents Add an Action to a Topic
Add a topic from the asset library to your agent.	Use Agentforce Builder.	Add a Topic from the Asset Library Standard Agent Topic Reference
Create a custom topic and add it to your agent.	Use Agentforce Builder.	Create a Custom Topic
Update the agent settings.	(low-code) Use Agentforce Builder. (pro-code) To edit the agent's metadata directly in your local Salesforce DX project, use VS Code.	Manage Agent Settings (Agentforce Builder) Agent Metadata: A Shallow Dive

Whether you use pro-code or low-code tools to modify your agent, you always want to keep your development org and your Salesforce DX project synchronized. Agents are made of metadata, just like any other Salesforce customization, so you use the standard Salesforce DX CLI commands to retrieve, deploy, and delete agents.

For example, if your development org is enabled for source tracking, and you change an agent in your org, use these standard CLI commands to first check for changes and then retrieve them to your DX project.

If your development org isn’t enabled for source tracking, you must specify the specific metadata component that you want to retrieve; for example, to retrieve all Apex classes:

However, agents are a little more complex than standard metadata types because they're made up of multiple types linked together, as described in Agent Metadata: A Shallow Dive. To make it easier to deploy, retrieve, and delete agents when your org doesn’t use source tracking, use the new “pseudo” metadata type called Agent. Agent isn’t a real metadata type; it’s just a shorthand way to tell the relevant CLI commands to work on all the metadata components that make up the agent. The syntax is Agent:Agent_API_Name.

Let’s start with retrieving. Imagine you used Agentforce Builder in your development org to modify the properties of an existing agent whose API name is Resort_Manager. Your org doesn’t use source tracking. Now you want to retrieve those changes back to your DX project. Use the project retrieve start CLI command and specify the Agent pseudo metadata type with the --metadata flag. Run this command from the VS Code integrated terminal or by using a terminal (macOS, Linux) or command prompt (Windows) from your DX project:

When you use the Agent pseudo metadata type with the --metadata flag of project retrieve start, only the metadata components described in Agent Metadata: A Shallow Dive are retrieved. The command doesn't retrieve metadata for org artifacts that implement an agent action, such as a flow, prompt template, or Apex class. The same applies when deploying and deleting metadata by using the Agent pseudo metadata type.

Next let’s look at deleting. If you tried to create an agent and it was only partly created in the development org, use the delete command to clean up everything, both in your org and in your DX project. You can also use this command to delete an inactive agent in your org.

To deploy local metadata associated with the same agent back to the org, run this command:

Agents are made of metadata, just like any other Salesforce customization. But a single agent is a collection of multiple metadata components linked together. This simple graphic shows the major metadata types:

Agent metadata hierarchy

Bot: The Bot metadata type has been around for a few Salesforce releases. It’s the top-level representation of an Einstein Bot, or chatbot, which is a basic computer program that conducts a conversation via auditory or textual methods.
BotVersion: A BotVersion represents the configuration for a specific Einstein Bot version. A single Einstein Bot can have many versions, but only one version can be active.
GenAiPlannerBundle is a reasoning engine for agents. It uses a large language model (LLM) and a reasoning strategy to break down a task into smaller parts, find the best actions for each part, and use them. An agent has a single GenAiPlannerBundle component.

Bot and BotVersion components together define simple chatbots. But when you add a GenAiPlannerBundle, the chatbot becomes an agent!
GenAiPlugin: Represents an agent topic, which is a category of actions related to a particular job to be done by the agent. An agent can have multiple GenAiPlugin components.
GenAiFunction: Represents an agent action. An agent can have multiple GenAiFunction components.

There are other GenAi metadata types that can be associated with your agent, such as GenAiPromptTemplate, which represents a prompt template. This guide doesn’t dive deeply into all the metadata. It only provides a simple overview to get you started.

In your DX project, agent metadata is stored in a package directory just like other Salesforce metadata. In this screenshot of VS Code, the DX project is called agentforcedx and the agent metadata is stored in the default force-app package directory.

VS Code showing agent metadata in "force-app" package directory in the left explorer panel and an open GenAiPlannerBundle XML file in the right editor panel.