Merge pull request #278 from salesforcecli/jshackell-sfdc-patch-1

W-20424458: edit NGA cli command help

Author: WillieRuemmele

messages/agent.generate.authoring-bundle.md

@@ -8,23 +8,23 @@ Authoring bundles are metadata components that contain an agent's Agent Script f
 
 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.
+The metadata type for authoring bundles is aiAuthoringBundle, which consist of a standard "<bundle-api-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-api-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.
+After you generate the initial authoring bundle, code the Agent Script file so your agent behaves exactly as you want. The Agent Script file generated by this command is just a first draft of your agent! Interactively test the agent by conversing with it using the "agent preview" command. 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
 
-Path to the agent spec YAML file.
+Path to the agent spec YAML file; if not specified, the command provides a list that you can choose from.
 
 # flags.output-dir.summary
 
 Directory where the authoring bundle files are generated.
 
 # flags.name.summary
 
-Name (label) of the authoring bundle.
+Name (label) of the authoring bundle; if not specified, you're prompted for the name.
 
 # flags.api-name.summary
 
@@ -36,11 +36,15 @@ API name of the new authoring bundle
 
 # examples
 
+- Generate an authoring bundle by being prompted for all required values, such as the agent spec YAML file, the bundle name, and the API name; use your default org:
+
+  <%= config.bin %> <%= command.id %>
+
 - 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 specs/agentSpec.yaml --name "My Authoring Bundle"
 
-- 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":
+- Similar to previous example, but generate the authoring bundle files in the "other-package-dir/main/default" package directory; use the org with alias "my-dev-org":
 
   <%= config.bin %> <%= command.id %> --spec specs/agentSpec.yaml --name "My Authoring Bundle" --output-dir other-package-dir/main/default --target-org my-dev-org
 

messages/agent.preview.md

@@ -1,49 +1,54 @@
 # summary
 
-Interact with an active agent to preview how the agent responds to your statements, questions, and commands (utterances).
+Interact with an agent to preview how it responds to your statements, questions, and commands (utterances).
 
 # description
 
-Use this command to have a natural language conversation with an active agent in your org, as if you were an actual user. The interface is simple: in the "Start typing..." prompt, enter a statement, question, or command; when you're done, enter Return. Your utterance is posted on the right along with a timestamp. The agent then responds on the left. To exit the conversation, hit ESC or Control+C.
+Use this command to have a natural language conversation with an agent while you code its Agent Script file. Previewing an agent works like an initial test to make sure it responds to your utterances as you expect. For example, you can test that the agent uses a particular topic when asked a question, and then whether it invokes the correct action associated with that topic. This command is the CLI-equivalent of the Preview panel in your org's Agentforce Builder UI.
 
-This command is useful to test if the agent responds to your utterances as you expect. For example, you can test that the agent uses a particular topic when asked a question, and then whether it invokes the correct action associated with that topic. This command is the CLI-equivalent of the Conversation Preview panel in your org's Agent Builder UI.
+This command uses the agent's local authoring bundle, which contains its Agent Script file. You can let the command provide a list of authoring bundles (labeled "(Agent Script)") to choose from or use the --authoring-bundle flag to specify a bundle's API name.
 
-When the session concludes, the command asks if you want to save the API responses and chat transcripts. By default, the files are saved to the "./temp/agent-preview" directory. Specify a new default directory by setting the environment variable "SF_AGENT_PREVIEW_OUTPUT_DIR" to the directory. Or you can pass the directory to the --output-dir flag.
+You can use these two modes when previewing an agent from its Agent Script file:
 
-Find the agent's API name in its Agent Details page of your org's Agentforce Studio UI in Setup. If your agent is currently deactivated, use the "agent activate" CLI command to activate it.
+- Simulated mode (Default): Uses only the Agent Script file to converse, and it simulates (mocks) all the actions. Use this mode if none of the Apex classes, flows, and prompt templates that implement your actions are available yet. The LLM uses the information about topics in the Agent Script file to simulate what the action does or how it responds.
+- Live mode: Uses the actual Apex classes, flows, and prompt templates in your development org in the agent preview. If you've changed the Apex classe, flows, or prompt templates in your local DX project, then you must deploy them to your development org if you want to use them in your live preview. You can use the Apex Replay Debugger to debug your Apex classes when using live mode.
 
-IMPORTANT: Before you use this command, you must complete a number of configuration steps in your org and your DX project. For example, you must first create the link to a client connected app using the "org login web --client-app" CLI command to then get the value of the --client-app flag of this command. The examples in this help assume you've completed the steps. See "Preview an Agent" in the "Agentforce Developer Guide" for complete documentation: https://developer.salesforce.com/docs/einstein/genai/guide/agent-dx-preview.html.
+The interface is simple: in the "Start typing..." prompt, enter a statement, question, or command; when you're done, enter Return. Your utterance is posted on the right along with a timestamp. The agent then responds on the left. To exit the conversation, hit ESC or Control+C.
+
+When the session concludes, the command asks if you want to save the API responses and chat transcripts. By default, the files are saved to the "./temp/agent-preview" directory. Specify a new default directory with the --output-dir flag.
+
+NOTE: You can also use this command to connect to a published and active agent, which are labeled "(Published)" if you let this command provide the list of agents to preview. That use case, however, requires additional security and configuration in both your org and your DX project. The examples in this help are for previewing an agent from its Agent Script file in your DX project and require only simple authorization of your org, such as with the "org login web" command. The --client-app and --api-name flags are used only for previewing published and active agents, they don't apply to Agent Script agents. See "Connect to a Published Agent" in the "Agentforce Developer Guide" for complete documentation: https://developer.salesforce.com/docs/einstein/genai/guide/agent-dx-preview.html.
 
 # flags.api-name.summary
 
-API name of the agent you want to interact with.
+API name of the published and active agent you want to interact with.
 
 # flags.authoring-bundle.summary
 
-Preview a next-gen agent by specifying the API name of the authoring bundle metadata component that implements it.
+API name of the authoring bundle metadata component that contains the agent's Agent Script file.
 
 # flags.client-app.summary
 
-Name of the linked client app to use for the agent connection.
+Name of the linked client app to use for the connection to the published and active agent.
 
 # flags.output-dir.summary
 
 Directory where conversation transcripts are saved.
 
 # flags.use-live-actions.summary
 
-Use real actions in the org; if not specified, preview uses AI to mock actions. 
+Use real actions in the org; if not specified, preview uses AI to simulate (mock) actions.
 
 # flags.apex-debug.summary
 
 Enable Apex debug logging during the agent preview conversation.
 
 # examples
 
-- Interact with an agent with API name Resort_Manager in the org with alias "my-org" and the linked "agent-app" connected app:
+- Preview an agent in simulated mode by choosing from a list of authoring bundles provided by the command; use the org with alias "my-dev-org":
 
-  <%= config.bin %> <%= command.id %> --api-name Resort_Manager --target-org my-org --client-app agent-app
+  <%= config.bin %> <%= command.id %> --target-org my-dev-org
 
-- Same as the preceding example, but this time save the conversation transcripts to the "./transcripts/my-preview" directory rather than the default "./temp/agent-preview":
+- Preview an agent in live mode by choosing from a list of authoring bundles. Save the conversation transcripts to the "./transcripts/my-preview" directory, enable the Apex debug logs, and use your default org:
 
-  <%= config.bin %> <%= command.id %> --api-name Resort_Manager --target-org my-org --client-app agent-app --output-dir transcripts/my-preview
+  <%= config.bin %> <%= command.id %> --use-live-actions --apex-debug --output-dir transcripts/my-preview

messages/agent.publish.authoring-bundle.md

@@ -1,24 +1,28 @@
 # summary
 
-Publish an authoring bundle to your org, which results in a new or updated agent.
+Publish an authoring bundle to your org, which results in a new agent or a new version of an existing agent.
 
 # description
 
 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.
 
-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.
+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. All associated agent metadata components, such as the Bot, BotVersion, and GenAiXXX components, are either created or updated in the org. Finally, all the new or changed metadata components associated with the new agent are retrieved back to your local DX project.
 
-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.
+This command uses the API name of the authoring bundle.
 
 # examples
 
-- Publish an authoring bundle with API name MyAuthoringBundle to the org with alias "my-org":
+- Publish an authoring bundle by being prompted for its API name; use your default org:
 
-  <%= config.bin %> <%= command.id %> --api-name MyAuthoringbundle --target-org my-org
+  <%= config.bin %> <%= command.id %>
+
+- Publish an authoring bundle with API name MyAuthoringBundle to the org with alias "my-dev-org":
+
+  <%= config.bin %> <%= command.id %> --api-name MyAuthoringbundle --target-org my-dev-org
 
 # flags.api-name.summary
 
-API name of the authoring bundle you want to publish.
+API name of the authoring bundle you want to publish; if not specified, the command provides a list that you can choose from.
 
 # flags.api-name.prompt
 
@@ -30,7 +34,7 @@ Required flag(s) missing: %s.
 
 # error.invalidBundlePath
 
-Invalid bundle path. Provide a valid directory path to an authoring bundle.
+Invalid authoring bundle path. Provide a valid directory path to an authoring bundle.
 
 # error.publishFailed
 

messages/agent.validate.authoring-bundle.md

@@ -6,19 +6,23 @@ Validate an authoring bundle to ensure its Agent Script file compiles successful
 
 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 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 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 code the Agent Script file to ensure that it's 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 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 an authoring bundle with API name MyAuthoringBundle:
+- Validate an authoring bundle by being prompted for its API name; use your default org:
 
-  <%= config.bin %> <%= command.id %> --api-name MyAuthoringBundle
+  <%= config.bin %> <%= command.id %>
+
+- Validate an authoring bundle with API name MyAuthoringBundle; use the org with alias "my-dev-org":
+
+  <%= config.bin %> <%= command.id %> --api-name MyAuthoringBundle --target-org my-dev-org
 
 # flags.api-name.summary
 
-API name of the authoring bundle you want to validate.
+API name of the authoring bundle you want to validate; if not specified, the command provides a list that you can choose from.
 
 # flags.api-name.prompt