Merge pull request #261 from salesforcecli/js/edit-nga-messages

@W-20161222@ update help for NGA beta and mark NGA commands as "beta"

Author: WillieRuemmele

messages/agent.create.md

@@ -4,6 +4,8 @@ Create an agent in your org using a local agent spec file.
 
 # description
 
+NOTE: This command creates an agent that doesn't use Agent Script as its blueprint. We generally don't recommend you use this workflow to create an agent. Rather, use the "agent generate|validate|publish authoring-bundle" commands to author agents that use the Agent Script language. See "Author an Agent" (https://developer.salesforce.com/docs/einstein/genai/guide/agent-dx-nga-author-agent.html) for details.
+
 To run this command, you must have an agent spec file, which is a YAML file that define the agent properties and contains a list of AI-generated topics. Topics define the range of jobs the agent can handle. Use the "agent generate agent-spec" CLI command to generate an agent spec file. Then specify the file to this command using the --spec flag, along with the name (label) of the new agent with the --name flag. If you don't specify any of the required flags, the command prompts you.
 
 When this command completes, your org contains the new agent, which you can then edit and customize in the Agent Builder UI. The new agent's topics are the same as the ones listed in the agent spec file. The agent might also have some AI-generated actions, or you can add them. This command also retrieves all the metadata files associated with the new agent to your local Salesforce DX project.

messages/agent.generate.agent-spec.md

@@ -4,15 +4,15 @@ Generate an agent spec, which is a YAML file that captures what an agent can do.
 
 # description
 
-The first step in creating an agent in your org with Salesforce CLI is to generate an agent spec using this command. An agent spec is a YAML-formatted file that contains information about the agent, such as its role and company description, and then an AI-generated list of topics based on this information. Topics define the range of jobs your agent can handle.
+An agent spec is a YAML-formatted file that contains basic information about the agent, such as its role, company description, and an AI-generated list of topics based on this information. Topics define the range of jobs your agent can handle.
 
 Use flags, such as --role and --company-description, to provide details about your company and the role that the agent plays in your company. If you prefer, you can also be prompted for the basic information; use --full-interview to be prompted for all required and optional properties. Upon command execution, the large language model (LLM) associated with your org uses the provided information to generate a list of topics for the agent. Because the LLM uses the company and role information to generate the topics, we recommend that you provide accurate, complete, and specific details so the LLM generates the best and most relevant topics. Once generated, you can edit the spec file; for example, you can remove topics that don't apply or change a topic's description.
 
 You can also iterate the spec generation process by using the --spec flag to pass an existing agent spec file to this command, and then using the --role, --company-description, etc, flags to refine your agent properties. Iteratively improving the description of your agent allows the LLM to generate progressively better topics.
 
 You can also specify other agent properties, such as a custom prompt template, how to ground the prompt template to add context to the agent's prompts, the tone of the prompts, and the username of a user in the org to assign to the agent.
 
-When your agent spec is ready, you then create the agent in your org by running the "agent create" CLI command and specifying the spec with the --spec flag.
+When your agent spec is ready, generate an authoring bundle from it by passing the spec file to the --spec flag of the "agent generate authoring-bundle" CLI command. An authoring bundle is a metadata type that contains an Agent Script file, which is the blueprint for an agent. (While not recommended, you can also use the agent spec file to immediately create an agent with the "agent create" command. We don't recommend this workflow because these types of agents don't use Agent Script, and are thus less flexible and more difficult to maintain.)
 
 # flags.type.summary
 

messages/agent.generate.authoring-bundle.md

@@ -1,12 +1,18 @@
 # summary
 
-Generate a local authoring bundle from an existing agent spec YAML file.
+Generate an authoring bundle from an existing agent spec YAML file.
 
 # description
 
-Authoring bundles are metadata types that represent the next-gen Salesforce agents. Their exact metadata name is AiAuthoringBundle and they consist of a standard "\*-meta.xml" metadata file and an agent file (with extension ".agent") that fully describes the next-gen agent. Use this command to generate an authoring bundle based on an agent spec YAML file, which you create with the "agent create agent-spec" command.
+Authoring bundles are metadata components that contain an agent's Agent Script file. The Agent Script file is the agent's blueprint; it fully describes what the agent can do using the Agent Script language.
 
-By default, authoring bundles are generated in the force-app/main/default/aiAuthoringBundles/<api-name> directory. Use the --output-dir to generate them elsewhere.
+Use this command to generate a new authoring bundle based on an agent spec YAML file, which you create with the "agent generate agent-spec" command. The agent spec YAML file is a high-level description of the agent; it describes its essence rather than exactly what it can do.
+
+The metadata type for authoring bundles is aiAuthoringBundle, which consist of a standard "<bundle-name>.bundle-meta.xml" metadata file and the Agent Script file (with extension ".agent"). When you run this command, the new authoring bundle is generated in the force-app/main/default/aiAuthoringBundles/<bundle-name> directory. Use the --output-dir flag to generate them elsewhere.
+
+After you generate the initial authoring bundle, vibe code (modify using natural language) the Agent Script file so your agent behaves exactly as you want. The generated Agent Script file is just a first draft of your agent! Then publish the agent to your org with the "agent publish authoring-bundle" command.
+
+This command requires an org because it uses it to access an LLM for generating the Agent Script file.
 
 # flags.spec.summary
 
@@ -30,13 +36,13 @@ API name of the new authoring bundle
 
 # examples
 
-- Generate an authoring bundle from the "specs/agentSpec.yaml" agent spec YAML file and give it the label "My Authoring Bundle":
+- Generate an authoring bundle from the "specs/agentSpec.yaml" agent spec YAML file and give it the label "My Authoring Bundle"; use your default org:
 
-  <%= config.bin %> <%= command.id %> --spec-file specs/agentSpec.yaml --name "My Authoring Bundle"
+  <%= config.bin %> <%= command.id %> --spec specs/agentSpec.yaml --name "My Authoring Bundle"
 
-- Same as previous example, but generate the files in the other-package-dir/main/default/aiAuthoringBundles directory:
+- Same as previous example, but generate the files in the "other-package-dir/main/default" package directory; use the org with alias "my-dev-org":
 
-  <%= config.bin %> <%= command.id %> --spec-file specs/agentSpec.yaml --name "My Authoring Bundle" --output-dir other-package-dir/main/default/aiAuthoringBundles
+  <%= config.bin %> <%= command.id %> --spec specs/agentSpec.yaml --name "My Authoring Bundle" --output-dir other-package-dir/main/default --target-org my-dev-org
 
 # error.no-spec-file
 
@@ -48,4 +54,4 @@ The specified file is not a valid agent spec YAML file.
 
 # error.failed-to-create-agent
 
-Failed to create a next-gen agent from the agent spec YAML file.
+Failed to create an authoring bundle from the agent spec YAML file.

messages/agent.publish.authoring-bundle.md

@@ -1,20 +1,20 @@
 # summary
 
-Publish an authoring bundle to your org, which results in a new next-gen agent.
+Publish an authoring bundle to your org, which results in a new or updated agent.
 
 # description
 
-When you publish an authoring bundle to your org, a number of things happen. First, this command validates that the agent file (with extension ".agent") successfully compiles. Then the authoring bundle metadata component is deployed to the org, and all associated metadata components, such as the Bot, BotVersion, and GenAiXXX components, are either created or updated. The org then creates a new next-gen agent based on the deployed authoring bundle and associated metadata. Finally, all the metadata associated with the new agent is retrieved back to your local DX project.
+An authoring bundle is a metadata type (named aiAuthoringBundle) that provides the blueprint for an agent. The metadata type contains two files: the standard metatada XML file and an Agent Script file (extension ".agent") that fully describes the agent using the Agent Script language.
 
-Authoring bundles are metadata types that represent the next-gen Salesforce agents. Their exact metadata name is AiAuthoringBundle and they consist of a standard "\*-meta.xml" metadata file and an agent file (with extension ".agent") that fully describes the next-gen agent.
+When you publish an authoring bundle to your org, a number of things happen. First, this command validates that the Agent Script file successfully compiles. If there are compilation errors, the command exits and you must fix the Agent Script file to continue. Once the Agent Script file compiles, then the authoring bundle metadata component is deployed to the org, and all associated agent metadata components, such as the Bot, BotVersion, and GenAiXXX components, are either created or updated. The org then either creates a new agent based on the deployed authoring bundle, or creates a new version of the agent if it already existed. Finally, all the new or changed metadata components associated with the new agent are retrieved back to your local DX project.
 
-This command requires the API name of the authoring bundle; if you don't provide it with the --api-name flag, the command prompts you for it.
+This command uses the API name of the authoring bundle. If you don't provide an API name with the --api-name flag, the command searches the current DX project and outputs a list of authoring bundles that it found for you to choose from.
 
 # examples
 
-- Publish an authoring bundle with API name MyAuthoringBundle to the org with alias "my-org", resulting in a new agent named "My Fab Agent"::
+- Publish an authoring bundle with API name MyAuthoringBundle to the org with alias "my-org":
 
-  <%= config.bin %> <%= command.id %> --api-name MyAuthoringbundle --agent-name "My Fab Agent" --target-org my-org
+  <%= config.bin %> <%= command.id %> --api-name MyAuthoringbundle --target-org my-org
 
 # flags.api-name.summary
 
@@ -24,10 +24,6 @@ API name of the authoring bundle you want to publish.
 
 API name of the authoring bundle to publish
 
-# flags.agent-name.summary
-
-Name for the new agent that is created from the published authoring bundle.
-
 # error.missingRequiredFlags
 
 Required flag(s) missing: %s.
@@ -43,8 +39,8 @@ Failed to publish agent with the following errors:
 
 # error.agentNotFound
 
-Could not find a .bundle-meta.xml file with API name '%s' in the project.
+Couldn't find a ".bundle-meta.xml" file with API name '%s' in the DX project.
 
 # error.agentNotFoundAction
 
-Check that the API name is correct and that the .agent file exists in your project directory.
+Check that the API name is correct and that the ".agent" file exists in your DX project directory.

messages/agent.validate.authoring-bundle.md

@@ -1,18 +1,18 @@
 # summary
 
-Validate a local authoring bundle to ensure it compiles successfully and can be used to create a next-gen agent.
+Validate an authoring bundle to ensure its Agent Script file compiles successfully and can be used to publish an agent.
 
 # description
 
-Authoring bundles are metadata types that represent the next-gen Salesforce agents. Their exact metadata name is AiAuthoringBundle and they consist of a standard "\*-meta.xml" metadata file and an agent file (with extension ".agent") that fully describes the next-gen agent. Generate a local authoring bundle with the "agent generate authoring-bundle" command.
+An authoring bundle is a metadata type (named aiAuthoringBundle) that provides the blueprint for an agent. The metadata type contains two files: the standard metatada XML file and an Agent Script file (extension ".agent") that fully describes the agent using the Agent Script language.
 
-This command validates that the agent file (with extension ".agent") that's part of the authoring bundle compiles without errors and can later be used to successfully create a next-gen agent.
+This command validates that the Agent Script file in the authoring bundle compiles without errors so that you can later publish the bundle to your org. Use this command while you vibe code (modify with natural language) the Agent Script file to ensure that it's always valid. If the validation fails, the command outputs the list of syntax errors, a brief description of the error, and the location in the Agent Script file where the error occurred.
 
-This command requires the API name of the authoring bundle; if you don't provide it with the --api-name flag, the command prompts you for it.
+This command uses the API name of the authoring bundle. If you don't provide an API name with the --api-name flag, the command searches the current DX project and outputs a list of authoring bundles that it found for you to choose from.
 
 # examples
 
-- Validate a local authoring bundle with API name MyAuthoringBundle:
+- Validate an authoring bundle with API name MyAuthoringBundle:
 
   <%= config.bin %> <%= command.id %> --api-name MyAuthoringBundle
 
@@ -34,13 +34,13 @@ Invalid authoring bundle path. Provide a valid directory path to the authoring b
 
 # error.compilationFailed
 
-Compilation of the agent file failed with the following errors:
+Compilation of the Agent Script file failed with the following errors:
 %s
 
 # error.agentNotFound
 
-Could not find a .bundle-meta.xml file with API name '%s' in the project.
+Couldn't find a ".bundle-meta.xml" file with API name '%s' in the DX project.
 
 # error.agentNotFoundAction
 
-Check that the API name is correct and that the ".agent" file exists in your project directory.
+Check that the API name is correct and that the ".agent" file exists in your DX project directory.

src/commands/agent/generate/authoring-bundle.ts

@@ -38,6 +38,7 @@ export default class AgentGenerateAuthoringBundle extends SfCommand<AgentGenerat
   public static readonly description = messages.getMessage('description');
   public static readonly examples = messages.getMessages('examples');
   public static readonly requiresProject = true;
+  public static state = 'beta';
 
   public static readonly flags = {
     'target-org': Flags.requiredOrg(),

src/commands/agent/publish/authoring-bundle.ts

@@ -39,6 +39,7 @@ export default class AgentPublishAuthoringBundle extends SfCommand<AgentPublishA
   public static readonly description = messages.getMessage('description');
   public static readonly examples = messages.getMessages('examples');
   public static readonly requiresProject = true;
+  public static state = 'beta';
 
   public static readonly flags = {
     'target-org': Flags.requiredOrg(),

src/commands/agent/validate/authoring-bundle.ts

@@ -36,6 +36,7 @@ export default class AgentValidateAuthoringBundle extends SfCommand<AgentValidat
   public static readonly description = messages.getMessage('description');
   public static readonly examples = messages.getMessages('examples');
   public static readonly requiresProject = true;
+  public static state = 'beta';
 
   public static readonly flags = {
     'target-org': Flags.requiredOrg(),