Create an Agent from Your DX Project

For this step, use the same Developer Edition org that you created in Step 1.

Generate an Agent Spec

An agent spec is a YAML file that contains information about the agent, such as its role and details about your company, along with an AI-generated list of topics based on this information. Topics define the range of jobs your agent can handle.

1. In VS Code’s integrated terminal, run this Salesforce CLI command:
   

sf agent generate agent-spec

The agent plugin is just-in-time (JIT), which means that Salesforce CLI installs the plugin the first time you run one of its commands. The agent commands automatically run against your Developer Edition org, because you specified it as the default when you authorized it in the previous step. You can explicitly target the org with the --target-org flag and specify the org’s alias or username, such as:sf agent generate agent-spec --target-org agentforce

2. When prompted, select (using the arrow keys) or enter the values shown in this table:
   

When the command finishes, the generated agent spec file called agentSpec.yaml is in the specs sub-directory of your DX project. You can change these defaults with the --output-file flag, such as --output-file specs/resortManagerSpec.yaml

When run without flags, the agent generate agent-spec command is interactive and prompts you for basic information about the agent and company. You use natural language to describe these properties. You can also use flags to specify the values listed in the table. For example, you can use --type and --company-name to specify the short values, and then be prompted for the long values, such as the agent role and company description.

sf agent generate agent-spec --type customer --company-name "Coral Cloud Resorts"

The agent generate agent-spec command has other flags for specifying additional spec properties, such as the maximum number of topics to generate (default is 5), a custom prompt template, the grounding context used by the prompt template, and the conversational tone of the agent. If you want to play around with these flags, run agent generate agent-spec --help to get more information.

3. View, and optionally edit, the generated specs/agentSpec.yaml file in VS Code’s editor:
   

The top part of the YAML file lists the information you provided to the agent generate agent-spec command, along with other default properties such as max number of topics and whether to add agent conversation data to org event logs. But the topics section is the interesting part: it contains the list of topics that were AI-generated based on the information you provided. Each topic has a name and a description, both generated by AI. As a result, the topics in your new agent spec file are likely slightly different from the ones shown in the screenshot above, although the gist of the topics should be similar because you started with the same agent properties. You can edit these topics directly in the YAML file as you like, such as changing the description of a topic to better describe your particular agent, or remove a topic if you don’t think it fits.

Create an Agent

Let’s now create the agent based on the agent spec you generated in the previous step. The CLI command to create an agent does two things: It creates the agent in your org, and it syncs up the metadata associated with the agent with your local DX project.

1. In VS Code’s integrated terminal, run this Salesforce CLI command:
   

sf agent create --spec specs/agentSpec.yaml --name "Resort Manager"

The --spec flag specifies the YAML agent spec you created in the previous step. The --name flag specifies the name (label) of the new agent.

2. When prompted, accept the default API name (Resort_Manager) for your agent. The command then starts executing.
   The output of the command shows all the steps that it performs, such as parsing the agent spec file, creating the agent in the org, and then retrieving metadata that was created in the org back to the local DX project. Here’s partial sample output from the command:
   

───────── Creating Resort Manager Agent ─────────


 ✔ Parsing Agent spec 38ms
 ✔ Creating Agent in org 19.26s
 ✔ Retrieving Agent metadata 7.52s


 Elapsed Time: 26.98s


Successfully created Resort Manager in afdx-th-project@salesforce.com.


Use sf org open agent --api-name Resort_Manager -o afdx-th-project@salesforce.com to view the agent in the browser.

3. Just for fun, view some of the generated local metadata in VS Code’s editor; as always, the metadata is under the force-app directory of your DX project:
   

At a high level, an agent is made up of these main metadata components: a Bot + BotVersion + GenAiPlannerBundle. A Bot and BotVersion is just a ChatBot. But when a Bot references a GenAiPlannerBundle, additional logic is added which makes it an agent. GenAiPlannerBundle is the glue that adds AI intelligence. GenAiPlannerBundles then reference other GenAi types, such as GenAiPlugins, the agent’s topics, and GenAiFunctions, the agent’s actions.

Let's say that you want to preview what the agent looks like first, before you actually create and save it in your org. To do this, first run the agent create command with the --preview flag:

sf agent create --spec specs/agentSpec.yaml --name "Resort Manager" --preview

The command generates a local JSON file with name Resort_Manager_Preview_<timestamp>.json in your DX project. The file describes the agent that the LLM will create, including suggested actions for each topic, the instructions, and sample utterances. Then, when you're ready to actually create the agent in your org, run the same command but without the --preview flag.

Open the Agent in the Developer Edition Org’s Agentforce Builder UI

To verify that the new agent has indeed been created in your Developer Edition org, view the agent in the org’s Agentforce Builder UI.

From the integrated terminal in VS Code, run this command:

sf org open agent --api-name Resort_Manager

The Resort Manager agent opens in the Agentforce Builder UI, ready to view and update.

The agent was created with topics based on the agent spec you generated. Each topic has at least one default action, and is ready for further customization whenever you’re ready to add more actions.

Hurray! You, the excellent Coral Cloud developer, now know how to use Agentforce DX to create an agent using pro-code tools such as Salesforce CLI and VS Code.

Resources

• Trailhead: Quick Start: Build a Service Agent with Agentforce
• Trailhead: Agentforce Basics
• Salesforce Developers: Agentforce Developer Guide
• Salesforce Developers: CLI Command Reference (agent commands)
• Salesforce Developers: Salesforce DX Developer Guide
• Salesforce Developers: Salesforce CLI Setup Guide
• Salesforce Developers: Salesforce Extensions for Visual Studio Code
• Salesforce Help: Agentforce Agents