W-21785024: edit help

messages/agent.preview.start.md

@@ -8,9 +8,12 @@ This command outputs a session ID that you then use with the "agent preview send
 
 Identify the agent you want to start previewing with either the --authoring-bundle flag to specify a local authoring bundle's API name or --api-name to specify an activated published agent's API name. To find either API name, navigate to your package directory in your DX project. The API name of an authoring bundle is the same as its directory name under the "aiAuthoringBundles" metadata directory. Similarly, the published agent's API name is the same as its directory name under the "Bots" metadata directory.
 
-You must explicitly specify the preview execution mode using one of these flags: --use-live-actions: Executes real Apex classes, flows, and other actions in the org. --simulate-actions: Uses AI to simulate action execution without calling real implementations.
+When starting a preview session with --authoring-bundle, you must explicitly specify the execution mode using one of these flags:
 
-Published agents always use live actions regardless of which flag is specified.
+- --use-live-actions: Executes real Apex classes, flows, and other actions in the org. This surfaces compile and validation errors during preview.
+- --simulate-actions: Uses AI to simulate action execution without calling real implementations.
+
+Published agents, which you specify with the --api-name, always use live actions.
 
 # flags.api-name.summary
 
@@ -22,26 +25,26 @@ API name of the authoring bundle metadata component that contains the agent's Ag
 
 # flags.use-live-actions.summary
 
-Execute real actions in the org (Apex classes, flows, etc.).
+Execute real actions in the org, such as Apex classes and flows. When previewing using an authoring bundle, you must specify either this flag or --simulate-actions.
 
 # flags.simulate-actions.summary
 
-Use AI to simulate action execution instead of calling real actions.
+Use AI to simulate action execution instead of calling real actions. When previewing using an authoring bundle, you must specify either this flag or --use-live-actions.
 
 # output.sessionId
 
 Session ID: %s
 
 # examples
 
-- Start a programmatic agent preview session by specifying an authoring bundle. Use the org with alias "my-dev-org":
+- Start a programmatic agent preview session by specifying an authoring bundle; use simulated actions. Use the org with alias "my-dev-org":
 
   <%= config.bin %> <%= command.id %> --authoring-bundle My_Agent_Bundle --target-org my-dev-org --simulate-actions
 
 - Similar to previous example but use live actions and the default org:
 
   <%= config.bin %> <%= command.id %> --authoring-bundle My_Agent_Bundle --use-live-actions
 
-- Start a preview session with an activated published agent:
+- Start a preview session with an activated published agent in your default org (always uses live actions):
 
   <%= config.bin %> <%= command.id %> --api-name My_Published_Agent

src/commands/agent/preview/start.ts

@@ -38,39 +38,43 @@ export default class AgentPreviewStart extends SfCommand<AgentPreviewStartResult
     'api-name': Flags.string({
       summary: messages.getMessage('flags.api-name.summary'),
       char: 'n',
-      exactlyOne: ['api-name', 'authoring-bundle'],
+      exclusive: ['authoring-bundle'],
     }),
     'authoring-bundle': Flags.string({
       summary: messages.getMessage('flags.authoring-bundle.summary'),
-      exactlyOne: ['api-name', 'authoring-bundle'],
+      exclusive: ['api-name'],
     }),
     'use-live-actions': Flags.boolean({
       summary: messages.getMessage('flags.use-live-actions.summary'),
-      exactlyOne: ['use-live-actions', 'simulate-actions'],
+      exclusive: ['simulate-actions'],
+      dependsOn: ['authoring-bundle'],
     }),
     'simulate-actions': Flags.boolean({
       summary: messages.getMessage('flags.simulate-actions.summary'),
-      exactlyOne: ['use-live-actions', 'simulate-actions'],
+      exclusive: ['use-live-actions'],
+      dependsOn: ['authoring-bundle'],
     }),
   };
 
   public async run(): Promise<AgentPreviewStartResult> {
     const { flags } = await this.parse(AgentPreviewStart);
     const conn = flags['target-org'].getConnection(flags['api-version']);
     const useLiveActions = flags['use-live-actions'];
+    const simulateActions = flags['simulate-actions'];
 
     const agent = flags['authoring-bundle']
       ? await Agent.init({ connection: conn, project: this.project!, aabName: flags['authoring-bundle'] })
       : await Agent.init({ connection: conn, project: this.project!, apiNameOrId: flags['api-name']! });
 
-    // Set mode based on which flag was specified
+    // Set mode for authoring bundles based on which flag was specified
     if (agent instanceof ScriptAgent) {
       agent.preview.setMockMode(useLiveActions ? 'Live Test' : 'Mock');
     }
 
-    if (flags['simulate-actions'] && agent instanceof ProductionAgent) {
+    // Warn if mode flags are used with published agents (they have no effect)
+    if (agent instanceof ProductionAgent && (useLiveActions || simulateActions)) {
       void Lifecycle.getInstance().emitWarning(
-        'Published agents always use real actions; --simulate-actions has no effect for published agents.'
+        'Published agents always use real actions; --use-live-actions and --simulate-actions have no effect for published agents.'
       );
     }
 

test/nuts/z3.agent.preview.nut.ts

@@ -45,7 +45,7 @@ describe('agent preview', function () {
 
   it('should fail when api-name does not exist in org', async () => {
     const invalidApiName = 'NonExistent_Agent_12345';
-    execCmd(`agent preview start --api-name ${invalidApiName} --use-live-actions --target-org ${getUsername()}`, {
+    execCmd(`agent preview start --api-name ${invalidApiName} --target-org ${getUsername()}`, {
       ensureExitCode: 1,
     });
   });
@@ -127,9 +127,7 @@ describe('agent preview', function () {
       const targetOrg = getUsername();
 
       const startResult = execCmd<AgentPreviewStartResult>(
-        `agent preview start --api-name ${
-          publishedAgent!.DeveloperName
-        } --use-live-actions --target-org ${targetOrg} --json`
+        `agent preview start --api-name ${publishedAgent!.DeveloperName} --target-org ${targetOrg} --json`
       ).jsonOutput?.result;
       expect(startResult?.sessionId).to.be.a('string');
       const sessionId = startResult!.sessionId;