Customize an Agent with Agentforce DX

After you’ve created a basic agent, customize it so 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 asset library. But other times you must create a custom topic or action to implement your specific business need.

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

Customization	Best Tool	More Information
Add an action from the action library to an existing topic.	Agent Builder.	Add an Action to a Topic Standard Agent Action Reference
Create a custom action based on an Apex class, and add it to an existing topic.	VS Code, with Agentforce for Developers to help you code the Apex class. Agent Builder to add it to a topic.	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.	Flow Builder to create the flow. Agent Builder to add it to a topic.	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.	Prompt Builder to create the prompt template. Agent Builder to add it to a topic.	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.	Setup in your org to create the external service. Agent Builder to add it to a topic.	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.	Agent Builder.	Add a Topic from the Asset Library Standard Agent Topic Reference
Create a custom topic and add it to your agent.	Agent Builder	Create a Custom Topic
Update the agent settings.	(low-code) Agent Builder. (pro-code) VS Code to edit the agent’s metadata directly in your local Salesforce DX project.	Manage Agent Settings (Agent 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 you want to retrieve; for example, to retrieve all Apex classes:

However, agents are a little more complex than standard metadata types because they are 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 Agent 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 VS Code’s integrated terminal or 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 metadata for org artifacts that implement an agent action, such as a flow, prompt template, or Apex class, isn’t retrieved. The same applies when deploying and deleting 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 simply 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.
GenAiPlanner 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 GenAiPlanner.

Bots and BotVersions together define simple chatbots. But when you add a GenAiPlanner, 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 GenAiPlugins.
GenAiFunction: Represents an agent action. An agent can have multiple GenAiFunctions.

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 just 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 GenAiPlanner XML file in the right editor panel.