Generate an Authoring Bundle

An important step in authoring an agent from scratch in your DX project is to generate its authoring bundle. An authoring bundle defines the blueprint for an agent. Specifically, authoring bundles are metadata types (named AiAuthoringBundle) that contain the agent's Agent Script file. The Agent Script file has the extension .agent and is written using the Agent Script language. See Authoring Bundle Metadata for more details about this metadata type.

Because an agent is defined by its authoring bundle, this documentation and the Agentforce DX tools use the two terms interchangeably.

For example, the CLI command discussed in this topic uses the term authoring bundle, such as agent generate authoring-bundle. However, the equivalent VS Code command uses the term agent, such as AFDX: Create Agent.

While not required, you can first generate an agent spec YAML file which you can then specify when you generate an authoring bundle. Because the agent spec file contains your agent topics, the generated Agent Script file in the authoring bundle is more customized for your new agent. If you don't use an agent spec file, then the generated authoring bundle contains the default Agent Script boilerplate. If you're just starting on your Agent Script journey, we recommend that you use the default boilerplate. But if you're more advanced, try generating and using an agent spec YAML first. See Generate an Agent Spec File.

After you finish generating the authoring bundle, the new *.agent file contains basic Agent Script code to get you started. If you specified an agent spec file, then some of the code is generated from its list of topics.

The authoring bundle is generated in the aiAuthoringBundles/<API-name> directory of your package directory, such as force-app/main/default/aiAuthoringBundles/My_Bundle. The directory contains, for example, the My_Bundle.agent and My_Bundle.bundle-meta.xml files.

  1. In VS Code, open your Salesforce DX project and be sure you've authorized your development org.

  2. From VS Code Command Palette, run the AFDX: Create Agent command.

    You can also run this command by right-clicking the aiAuthoringBundles directory in your package directory, as long it exists in your DX project. The Agentforce DX panel also has a Create Agent button.

  3. Select the template used to generate the authoring bundle.

    • Default template (Recommended): Starts with a basic boilerplate Agent Script file.
    • From an agent spec YAML file (Advanced): This option shows up only if there's at least one agent spec YAML file in the specs directory in your DX project. If you select this option, you're then asked to select the specific agent spec YAML file you want to use.

  4. Enter the name (label) of your new authoring bundle.

    You can use spaces in the name (label).

  5. Enter the API name of the bundle. We recommend that you use the default that's displayed.

    The default value for the authoring bundle's API name is derived from the label. For example, if you entered My Bundle for the label, then its default API name is My_Bundle.

  1. In VS Code, open the integrated terminal. Be sure you've authorized your development org.

    You can also open a terminal (macOS/Linux) or command prompt (Windows) and change to your Salesforce DX project.

  2. Run this command:

  3. Select the template used to generate the authoring bundle.

    • Default template (Recommended) : Starts with a basic boilerplate Agent Script file.
    • From an agent spec YAML file (Advanced) : This option shows up only if there's at least one agent spec YAML file (with a name that ends in AgentSpec.yaml) in the specs directory in your DX project. If you select this option, you're then asked to select the specific agent spec YAML file you want to use.

  4. Enter the name (label) of your new authoring bundle.

    You can use spaces in the name (label).

  5. Enter the API name of the bundle. We recommend that you use the default that's displayed.

    The default value for the authoring bundle's API name is derived from the label. For example, if you entered My Bundle for the label, then its default API name is My_Bundle.

You can specify many of the values with flags, such as --spec, --name, and --api-name. If you haven't set a default org in your project, use the --target-org flag to specify the org's username or alias. Use the --no-spec flag to skip prompting for a template and use the default boilerplate Agent Script file instead. For example: