@salesforce/plugin-agent 2.2.4 → 2.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -2233,16 +2233,15 @@
2233
2233
  "update:mcp:agent"
2234
2234
  ]
2235
2235
  },
2236
- "agent:preview:end": {
2236
+ "agent:publish:authoring-bundle": {
2237
2237
  "aliases": [],
2238
2238
  "args": {},
2239
- "description": "You must have previously started a programmatic agent preview session with the \"agent preview start\" command to then use this command to end it. This command also displays the local directory where the session trace files are stored.\n\nThe original \"agent preview start\" command outputs a session ID which you then use with the --session-id flag of this command to end the session. You don't have to specify the --session-id flag if an agent has only one active preview session. You must also use either the --authoring-bundle or --api-name flag to specify the API name of the authoring bundle or the published agent, respectively. 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.\n\nUse the --all flag to end all active preview sessions at once. You can combine --all with --api-name or --authoring-bundle to end only sessions for a specific agent, or use --all on its own to end every session across all agents in the project.",
2239
+ "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.\n\nWhen 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 it's published to the org, which in turn creates new associated metadata (Bot, BotVersion, GenAiX), or new versions of the metadata if the agent already exists. The new or updated metadata is retrieved back to your DX project; specify the --skip-retrieve flag to skip this step. Finally, the authoring bundle metadata (AiAuthoringBundle) is deployed to your org.\n\nThis command uses the API name of the authoring bundle.",
2240
2240
  "examples": [
2241
- "End a preview session of a published agent by specifying its session ID and API name; use the default org:\n<%= config.bin %> <%= command.id %> --session-id <SESSION_ID> --api-name My_Published_Agent",
2242
- "Similar to previous example, but don't specify a session ID; you get an error if the published agent has more than one active session. Use the org with alias \"my-dev-org\":\n<%= config.bin %> <%= command.id %> --api-name My_Published_Agent --target-org my-dev-org",
2243
- "End a preview session of an agent using its authoring bundle API name; you get an error if the agent has more than one active session.\n<%= config.bin %> <%= command.id %> --authoring-bundle My_Local_Agent",
2244
- "End all active preview sessions for a specific agent without prompting:\n<%= config.bin %> <%= command.id %> --all --authoring-bundle My_Local_Agent --target-org <target_org> --no-prompt",
2245
- "End all active preview sessions across every agent in the local session cache for an org:\n<%= config.bin %> <%= command.id %> --all --target-org <target_org>"
2241
+ "Publish an authoring bundle by being prompted for its API name; use your default org:\n<%= config.bin %> <%= command.id %>",
2242
+ "Publish an authoring bundle with API name MyAuthoringBundle to the org with alias \"my-dev-org\":\n<%= config.bin %> <%= command.id %> --api-name MyAuthoringbundle --target-org my-dev-org",
2243
+ "Publish with verbose output to see all retrieved and deployed metadata components:\n<%= config.bin %> <%= command.id %> --api-name MyAuthoringbundle --verbose",
2244
+ "Publish with concise output showing only essential information:\n<%= config.bin %> <%= command.id %> --api-name MyAuthoringbundle --concise"
2246
2245
  ],
2247
2246
  "flags": {
2248
2247
  "json": {
@@ -2277,129 +2276,106 @@
2277
2276
  "multiple": false,
2278
2277
  "type": "option"
2279
2278
  },
2280
- "session-id": {
2281
- "exclusive": [
2282
- "all"
2283
- ],
2284
- "name": "session-id",
2285
- "required": false,
2286
- "summary": "Session ID outputted by \"agent preview start\". Not required when the agent has exactly one active session. Run \"agent preview sessions\" to see the list of all sessions.",
2287
- "hasDynamicHelp": false,
2288
- "multiple": false,
2289
- "type": "option"
2290
- },
2291
2279
  "api-name": {
2292
2280
  "char": "n",
2293
- "exclusive": [
2294
- "authoring-bundle"
2295
- ],
2296
2281
  "name": "api-name",
2297
- "summary": "API name of the activated published agent you want to preview.",
2282
+ "summary": "API name of the authoring bundle you want to publish; if not specified, the command provides a list that you can choose from.",
2298
2283
  "hasDynamicHelp": false,
2299
2284
  "multiple": false,
2300
2285
  "type": "option"
2301
2286
  },
2302
- "authoring-bundle": {
2303
- "exclusive": [
2304
- "api-name"
2305
- ],
2306
- "name": "authoring-bundle",
2307
- "summary": "API name of the authoring bundle metadata component that contains the agent's Agent Script file.",
2287
+ "skip-retrieve": {
2288
+ "name": "skip-retrieve",
2289
+ "summary": "Don't retrieve the metadata associated with the agent to your DX project.",
2290
+ "allowNo": false,
2291
+ "type": "boolean"
2292
+ },
2293
+ "source-type": {
2294
+ "name": "source-type",
2295
+ "summary": "Where the agent came from. Use \"Bot\" when the agent was converted from an Einstein Bot. Applied on the first publish only.",
2308
2296
  "hasDynamicHelp": false,
2309
2297
  "multiple": false,
2298
+ "options": [
2299
+ "Bot"
2300
+ ],
2310
2301
  "type": "option"
2311
2302
  },
2312
- "all": {
2303
+ "verbose": {
2304
+ "char": "v",
2313
2305
  "exclusive": [
2314
- "session-id"
2306
+ "concise"
2315
2307
  ],
2316
- "name": "all",
2317
- "summary": "End all active preview sessions. Combine with --api-name or --authoring-bundle to limit to a specific agent, or use with only --target-org to end sessions for all agents found in the local session cache. Requires --target-org.",
2308
+ "name": "verbose",
2309
+ "summary": "Display detailed output showing all metadata components retrieved and deployed during the publish process.",
2318
2310
  "allowNo": false,
2319
2311
  "type": "boolean"
2320
2312
  },
2321
- "no-prompt": {
2322
- "char": "p",
2323
- "name": "no-prompt",
2324
- "summary": "Don't prompt for confirmation before ending sessions. Has an effect only when used with --all.",
2313
+ "concise": {
2314
+ "exclusive": [
2315
+ "verbose"
2316
+ ],
2317
+ "name": "concise",
2318
+ "summary": "Display minimal output with only essential information about the publish operation.",
2325
2319
  "allowNo": false,
2326
2320
  "type": "boolean"
2327
2321
  }
2328
2322
  },
2329
2323
  "hasDynamicHelp": true,
2330
2324
  "hiddenAliases": [],
2331
- "id": "agent:preview:end",
2325
+ "id": "agent:publish:authoring-bundle",
2332
2326
  "pluginAlias": "@salesforce/plugin-agent",
2333
2327
  "pluginName": "@salesforce/plugin-agent",
2334
2328
  "pluginType": "core",
2335
2329
  "strict": true,
2336
- "summary": "End an existing programmatic agent preview session and get trace location.",
2330
+ "summary": "Publish an authoring bundle to your org, which results in a new agent or a new version of an existing agent.",
2337
2331
  "enableJsonFlag": true,
2338
2332
  "requiresProject": true,
2339
- "envVariablesSection": {
2340
- "header": "ENVIRONMENT VARIABLES",
2341
- "body": [
2342
- {
2343
- "name": "SF_TARGET_ORG",
2344
- "description": "Username or alias of your default org. Overrides the target-org configuration variable."
2345
- }
2346
- ]
2347
- },
2348
2333
  "errorCodes": {
2349
2334
  "header": "ERROR CODES",
2350
2335
  "body": [
2351
2336
  {
2352
2337
  "name": "Succeeded (0)",
2353
- "description": "Preview session ended successfully and traces saved."
2354
- },
2355
- {
2356
- "name": "ExactlyOneRequired (2)",
2357
- "description": "Neither --api-name nor --authoring-bundle was provided (required when --all is not set)."
2358
- },
2359
- {
2360
- "name": "NotFound (2)",
2361
- "description": "Agent not found, or no preview session exists for this agent."
2362
- },
2363
- {
2364
- "name": "PreviewEndFailed (4)",
2365
- "description": "Failed to end the preview session."
2366
- },
2367
- {
2368
- "name": "PreviewEndPartialFailure (68)",
2369
- "description": "With --all, one or more sessions failed to end while others succeeded."
2338
+ "description": "Agent published successfully without errors."
2370
2339
  },
2371
2340
  {
2372
- "name": "SessionAmbiguous (5)",
2373
- "description": "Multiple preview sessions found; specify --session-id to choose one."
2341
+ "name": "Failed (1)",
2342
+ "description": "Compilation errors found in the Agent Script file."
2374
2343
  }
2375
2344
  ]
2376
2345
  },
2346
+ "FLAGGABLE_PROMPTS": {
2347
+ "api-name": {
2348
+ "message": "API name of the authoring bundle you want to publish; if not specified, the command provides a list that you can choose from.",
2349
+ "promptMessage": "API name of the authoring bundle to publish"
2350
+ }
2351
+ },
2377
2352
  "isESM": true,
2378
2353
  "relativePath": [
2379
2354
  "lib",
2380
2355
  "commands",
2381
2356
  "agent",
2382
- "preview",
2383
- "end.js"
2357
+ "publish",
2358
+ "authoring-bundle.js"
2384
2359
  ],
2385
2360
  "aliasPermutations": [],
2386
2361
  "permutations": [
2387
- "agent:preview:end",
2388
- "preview:agent:end",
2389
- "preview:end:agent",
2390
- "agent:end:preview",
2391
- "end:agent:preview",
2392
- "end:preview:agent"
2362
+ "agent:publish:authoring-bundle",
2363
+ "publish:agent:authoring-bundle",
2364
+ "publish:authoring-bundle:agent",
2365
+ "agent:authoring-bundle:publish",
2366
+ "authoring-bundle:agent:publish",
2367
+ "authoring-bundle:publish:agent"
2393
2368
  ]
2394
2369
  },
2395
- "agent:preview:send": {
2370
+ "agent:test:create": {
2396
2371
  "aliases": [],
2397
2372
  "args": {},
2398
- "description": "You must have previously started a programmatic agent preview session with the \"agent preview start\" command to then use this command to send the agent a message (utterance). This command then displays the agent's response.\n\nThe original \"agent preview start\" command outputs a session ID which you then use with the --session-id flag of this command to send a message. You don't have to specify the --session-id flag if an agent has only one active preview session. You must also use either the --authoring-bundle or --api-name flag to specify the API name of the authoring bundle or the published agent, respecitvely. 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.",
2373
+ "description": "To run this command, you must have an agent test spec file, which is a YAML file that lists the test cases for testing a specific agent. Use the \"agent generate test-spec\" CLI command to generate a test spec file. Then specify the file to this command with the --spec flag, or run this command with no flags to be prompted.\n\nWhen this command completes, your org contains the new agent test, which you can view and edit using the Testing Center UI (legacy) or Agentforce Studio (NGT). This command also retrieves the metadata component associated with the new test to your local Salesforce DX project and displays its filename. By default, the legacy AiEvaluationDefinition is created; use --test-runner agentforce-studio to author an AiTestingDefinition (NGT) instead.\n\nAfter you've created the test in the org, use the \"agent test run\" command to run it.",
2399
2374
  "examples": [
2400
- "Send a message to an activated published agent using its API name and session ID; use the default org:\n<%= config.bin %> <%= command.id %> --utterance \"What can you help me with?\" --api-name My_Published_Agent --session-id <SESSION_ID>",
2401
- "Similar to previous example, but don't specify a session ID; you get an error if the agent has more than one active session. Use the org with alias \"my-dev-org\":\n<%= config.bin %> <%= command.id %> --utterance \"What can you help me with?\" --api-name My_Published_Agent --target-org my-dev-org",
2402
- "Send a message to an agent using its authoring bundle API name; you get an error if the agent has more than one active session:\n<%= config.bin %> <%= command.id %> --utterance \"what can you help me with?\" --authoring-bundle My_Local_Agent"
2375
+ "Create an agent test interactively and be prompted for the test spec and API name of the test in the org; use the default org:\n<%= config.bin %> <%= command.id %>",
2376
+ "Create an agent test and use flags to specify all required information; if a test with same API name already exists in the org, overwrite it without confirmation. Use the org with alias \"my-org\":\n<%= config.bin %> <%= command.id %> --spec specs/Resort_Manager-testSpec.yaml --api-name Resort_Manager_Test --force-overwrite --target-org my-org",
2377
+ "Preview what the agent test metadata (AiEvaluationDefinition) looks like without deploying it to your default org:\n<%= config.bin %> <%= command.id %> --spec specs/Resort_Manager-testSpec.yaml --api-name Resort_Manager_Test --preview",
2378
+ "Author an Agentforce Studio (NGT) test from an NGT-shaped YAML; writes an AiTestingDefinition metadata file:\n<%= config.bin %> <%= command.id %> --spec specs/ReturnsCheckout.ngt.yaml --api-name Returns_Checkout --test-runner agentforce-studio --target-org my-org"
2403
2379
  ],
2404
2380
  "flags": {
2405
2381
  "json": {
@@ -2417,6 +2393,20 @@
2417
2393
  "multiple": false,
2418
2394
  "type": "option"
2419
2395
  },
2396
+ "api-name": {
2397
+ "name": "api-name",
2398
+ "summary": "API name of the new test; the API name must not exist in the org.",
2399
+ "hasDynamicHelp": false,
2400
+ "multiple": false,
2401
+ "type": "option"
2402
+ },
2403
+ "spec": {
2404
+ "name": "spec",
2405
+ "summary": "Path to the test spec YAML file.",
2406
+ "hasDynamicHelp": false,
2407
+ "multiple": false,
2408
+ "type": "option"
2409
+ },
2420
2410
  "target-org": {
2421
2411
  "char": "o",
2422
2412
  "name": "target-org",
@@ -2434,49 +2424,40 @@
2434
2424
  "multiple": false,
2435
2425
  "type": "option"
2436
2426
  },
2437
- "session-id": {
2438
- "name": "session-id",
2439
- "required": false,
2440
- "summary": "Session ID outputted by \"agent preview start\". Not required when the agent has exactly one active session. Run \"agent preview sessions\" to see list of all sessions.",
2441
- "hasDynamicHelp": false,
2442
- "multiple": false,
2443
- "type": "option"
2444
- },
2445
- "utterance": {
2446
- "char": "u",
2447
- "name": "utterance",
2448
- "required": true,
2449
- "summary": "Utterance to send to the agent, enclosed in double quotes.",
2450
- "hasDynamicHelp": false,
2451
- "multiple": false,
2452
- "type": "option"
2427
+ "preview": {
2428
+ "name": "preview",
2429
+ "summary": "Preview the test metadata file without deploying to your org.",
2430
+ "allowNo": false,
2431
+ "type": "boolean"
2453
2432
  },
2454
- "api-name": {
2455
- "char": "n",
2456
- "name": "api-name",
2457
- "summary": "API name of the activated published agent you want to preview.",
2458
- "hasDynamicHelp": false,
2459
- "multiple": false,
2460
- "type": "option"
2433
+ "force-overwrite": {
2434
+ "name": "force-overwrite",
2435
+ "summary": "Don't prompt for confirmation when overwriting an existing test (based on API name) in your org.",
2436
+ "allowNo": false,
2437
+ "type": "boolean"
2461
2438
  },
2462
- "authoring-bundle": {
2463
- "name": "authoring-bundle",
2464
- "summary": "API name of the authoring bundle metadata component that contains the agent's Agent Script file.",
2439
+ "test-runner": {
2440
+ "description": "By default, the command automatically detects which test runner to use based on the test definition metadata type in your org. Use this flag to explicitly specify the runner type. 'agentforce-studio' uses AiTestingDefinition metadata. 'testing-center' uses AiEvaluationDefinition metadata.",
2441
+ "name": "test-runner",
2442
+ "summary": "Explicitly specify which test runner to use (agentforce-studio or testing-center).",
2465
2443
  "hasDynamicHelp": false,
2466
2444
  "multiple": false,
2445
+ "options": [
2446
+ "agentforce-studio",
2447
+ "testing-center"
2448
+ ],
2467
2449
  "type": "option"
2468
2450
  }
2469
2451
  },
2470
2452
  "hasDynamicHelp": true,
2471
2453
  "hiddenAliases": [],
2472
- "id": "agent:preview:send",
2454
+ "id": "agent:test:create",
2473
2455
  "pluginAlias": "@salesforce/plugin-agent",
2474
2456
  "pluginName": "@salesforce/plugin-agent",
2475
2457
  "pluginType": "core",
2476
2458
  "strict": true,
2477
- "summary": "Send a message to an existing agent preview session.",
2459
+ "summary": "Create an agent test in your org using a local test spec YAML file.",
2478
2460
  "enableJsonFlag": true,
2479
- "requiresProject": true,
2480
2461
  "envVariablesSection": {
2481
2462
  "header": "ENVIRONMENT VARIABLES",
2482
2463
  "body": [
@@ -2491,19 +2472,19 @@
2491
2472
  "body": [
2492
2473
  {
2493
2474
  "name": "Succeeded (0)",
2494
- "description": "Message sent successfully and agent response received."
2475
+ "description": "Test created and deployed successfully."
2495
2476
  },
2496
2477
  {
2497
- "name": "NotFound (2)",
2498
- "description": "Agent not found, or no preview session exists for this agent."
2478
+ "name": "Failed (1)",
2479
+ "description": "Test validation errors or metadata format issues."
2499
2480
  },
2500
2481
  {
2501
- "name": "PreviewSendFailed (4)",
2502
- "description": "Failed to send message or receive response from the preview session."
2482
+ "name": "NotFound (2)",
2483
+ "description": "Test spec file not found or org connection failed."
2503
2484
  },
2504
2485
  {
2505
- "name": "SessionAmbiguous (5)",
2506
- "description": "Multiple preview sessions found; specify --session-id to choose one."
2486
+ "name": "DeploymentFailed (4)",
2487
+ "description": "Deployment failed due to API or network errors."
2507
2488
  }
2508
2489
  ]
2509
2490
  },
@@ -2512,25 +2493,26 @@
2512
2493
  "lib",
2513
2494
  "commands",
2514
2495
  "agent",
2515
- "preview",
2516
- "send.js"
2496
+ "test",
2497
+ "create.js"
2517
2498
  ],
2518
2499
  "aliasPermutations": [],
2519
2500
  "permutations": [
2520
- "agent:preview:send",
2521
- "preview:agent:send",
2522
- "preview:send:agent",
2523
- "agent:send:preview",
2524
- "send:agent:preview",
2525
- "send:preview:agent"
2501
+ "agent:test:create",
2502
+ "test:agent:create",
2503
+ "test:create:agent",
2504
+ "agent:create:test",
2505
+ "create:agent:test",
2506
+ "create:test:agent"
2526
2507
  ]
2527
2508
  },
2528
- "agent:preview:sessions": {
2509
+ "agent:test:list": {
2529
2510
  "aliases": [],
2530
2511
  "args": {},
2531
- "description": "This command lists the agent preview sessions that were started with the \"agent preview start\" command and are still in the local cache. Use this command to discover specific session IDs that you can pass to the \"agent preview send\" or \"agent preview end\" commands with the --session-id flag.\n\nProgrammatic agent preview sessions can be started for both published activated agents and by using an agent's local authoring bundle, which contains its Agent Script file. In this command's output table, the Agent column contains either the API name of the authoring bundle or the published agent, whichever was used when starting the session. In the table, if the same API name has multiple rows with different session IDs, then it means that you previously started multiple preview sessions with the associated agent.",
2512
+ "description": "The command outputs a table with the name (API name) of each test along with its unique ID, type ('agentforce-studio' or 'testing-center'), and the date it was created in the org.",
2532
2513
  "examples": [
2533
- "List all cached agent preview sessions:\n<%= config.bin %> <%= command.id %>"
2514
+ "List the agent tests in your default org:\n<%= config.bin %> <%= command.id %>",
2515
+ "List the agent tests in an org with alias \"my-org\"\"\n<%= config.bin %> <%= command.id %> --target-org my-org"
2534
2516
  ],
2535
2517
  "flags": {
2536
2518
  "json": {
@@ -2547,24 +2529,53 @@
2547
2529
  "hasDynamicHelp": false,
2548
2530
  "multiple": false,
2549
2531
  "type": "option"
2532
+ },
2533
+ "target-org": {
2534
+ "char": "o",
2535
+ "name": "target-org",
2536
+ "noCacheDefault": true,
2537
+ "required": true,
2538
+ "summary": "Username or alias of the target org. Not required if the `target-org` configuration variable is already set.",
2539
+ "hasDynamicHelp": true,
2540
+ "multiple": false,
2541
+ "type": "option"
2542
+ },
2543
+ "api-version": {
2544
+ "description": "Override the api version used for api requests made by this command",
2545
+ "name": "api-version",
2546
+ "hasDynamicHelp": false,
2547
+ "multiple": false,
2548
+ "type": "option"
2550
2549
  }
2551
2550
  },
2552
- "hasDynamicHelp": false,
2551
+ "hasDynamicHelp": true,
2553
2552
  "hiddenAliases": [],
2554
- "id": "agent:preview:sessions",
2553
+ "id": "agent:test:list",
2555
2554
  "pluginAlias": "@salesforce/plugin-agent",
2556
2555
  "pluginName": "@salesforce/plugin-agent",
2557
2556
  "pluginType": "core",
2558
2557
  "strict": true,
2559
- "summary": "List all known programmatic agent preview sessions.",
2558
+ "summary": "List the available agent tests in your org.",
2560
2559
  "enableJsonFlag": true,
2561
- "requiresProject": true,
2560
+ "envVariablesSection": {
2561
+ "header": "ENVIRONMENT VARIABLES",
2562
+ "body": [
2563
+ {
2564
+ "name": "SF_TARGET_ORG",
2565
+ "description": "Username or alias of your default org. Overrides the target-org configuration variable."
2566
+ }
2567
+ ]
2568
+ },
2562
2569
  "errorCodes": {
2563
2570
  "header": "ERROR CODES",
2564
2571
  "body": [
2565
2572
  {
2566
2573
  "name": "Succeeded (0)",
2567
- "description": "Sessions listed successfully (or empty list if no active sessions)."
2574
+ "description": "Agent tests listed successfully."
2575
+ },
2576
+ {
2577
+ "name": "Failed (4)",
2578
+ "description": "Failed to retrieve agent tests due to API or network errors."
2568
2579
  }
2569
2580
  ]
2570
2581
  },
@@ -2573,27 +2584,27 @@
2573
2584
  "lib",
2574
2585
  "commands",
2575
2586
  "agent",
2576
- "preview",
2577
- "sessions.js"
2587
+ "test",
2588
+ "list.js"
2578
2589
  ],
2579
2590
  "aliasPermutations": [],
2580
2591
  "permutations": [
2581
- "agent:preview:sessions",
2582
- "preview:agent:sessions",
2583
- "preview:sessions:agent",
2584
- "agent:sessions:preview",
2585
- "sessions:agent:preview",
2586
- "sessions:preview:agent"
2592
+ "agent:test:list",
2593
+ "test:agent:list",
2594
+ "test:list:agent",
2595
+ "agent:list:test",
2596
+ "list:agent:test",
2597
+ "list:test:agent"
2587
2598
  ]
2588
2599
  },
2589
- "agent:preview:start": {
2600
+ "agent:test:results": {
2590
2601
  "aliases": [],
2591
2602
  "args": {},
2592
- "description": "This command outputs a session ID that you then use with the \"agent preview send\" command to send an utterance to the agent. Use the \"agent preview sessions\" command to list all active sessions and the \"agent preview end\" command to end a specific session.\n\nIdentify 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.\n\nWhen starting a preview session with --authoring-bundle, you must explicitly specify the execution mode using one of these flags:\n\n- --use-live-actions: Executes real Apex classes, flows, and other actions in the org. This surfaces compile and validation errors during preview.\n- --simulate-actions: Uses AI to simulate action execution without calling real implementations.\n\nPublished agents (--api-name) always use live actions. The mode flags are optional and have no effect for published agents.",
2603
+ "description": "This command requires a job ID, which the original \"agent test run\" command displays when it completes. You can also use the --use-most-recent flag to see results for the most recently run agent test.\n\nBy default, this command outputs test results in human-readable tables for each test case. The tables show whether the test case passed, the expected and actual values, the test score, how long the test took, and more. Use the --result-format to display the test results in JSON or Junit format. Use the --output-dir flag to write the results to a file rather than to the terminal.",
2593
2604
  "examples": [
2594
- "Start a programmatic agent preview session by specifying an authoring bundle; use simulated actions. Use the org with alias \"my-dev-org\":\n<%= config.bin %> <%= command.id %> --authoring-bundle My_Agent_Bundle --target-org my-dev-org --simulate-actions",
2595
- "Similar to previous example but use live actions and the default org:\n<%= config.bin %> <%= command.id %> --authoring-bundle My_Agent_Bundle --use-live-actions",
2596
- "Start a preview session with an activated published agent (always uses live actions):\n<%= config.bin %> <%= command.id %> --api-name My_Published_Agent"
2605
+ "Get the results of an agent test run in your default org using its job ID:\n<%= config.bin %> <%= command.id %> --job-id 4KBfake0000003F4AQ",
2606
+ "Get the results of the most recently run agent test in an org with alias \"my-org\":\n<%= config.bin %> <%= command.id %> --use-most-recent --target-org my-org",
2607
+ "Get the results of the most recently run agent test in your default org, and write the JSON-formatted results into a directory called \"test-results\":\n<%= config.bin %> <%= command.id %> --use-most-recent --output-dir ./test-results --result-format json"
2597
2608
  ],
2598
2609
  "flags": {
2599
2610
  "json": {
@@ -2628,78 +2639,67 @@
2628
2639
  "multiple": false,
2629
2640
  "type": "option"
2630
2641
  },
2631
- "api-name": {
2632
- "char": "n",
2633
- "name": "api-name",
2634
- "summary": "API name of the activated published agent you want to preview.",
2642
+ "job-id": {
2643
+ "char": "i",
2644
+ "name": "job-id",
2645
+ "required": true,
2646
+ "summary": "Job ID of the completed agent test run.",
2635
2647
  "hasDynamicHelp": false,
2636
2648
  "multiple": false,
2637
2649
  "type": "option"
2638
2650
  },
2639
- "authoring-bundle": {
2640
- "name": "authoring-bundle",
2641
- "summary": "API name of the authoring bundle metadata component that contains the agent's Agent Script file.",
2651
+ "result-format": {
2652
+ "name": "result-format",
2653
+ "summary": "Format of the agent test run results.",
2654
+ "default": "human",
2642
2655
  "hasDynamicHelp": false,
2643
2656
  "multiple": false,
2644
- "type": "option"
2645
- },
2646
- "use-live-actions": {
2647
- "exclusive": [
2648
- "simulate-actions"
2649
- ],
2650
- "name": "use-live-actions",
2651
- "summary": "Execute real actions in the org (Apex classes, flows, etc.). Required with --authoring-bundle.",
2652
- "allowNo": false,
2653
- "type": "boolean"
2654
- },
2655
- "simulate-actions": {
2656
- "exclusive": [
2657
- "use-live-actions"
2657
+ "options": [
2658
+ "json",
2659
+ "human",
2660
+ "junit",
2661
+ "tap"
2658
2662
  ],
2659
- "name": "simulate-actions",
2660
- "summary": "Use AI to simulate action execution instead of calling real actions. Required with --authoring-bundle.",
2661
- "allowNo": false,
2662
- "type": "boolean"
2663
- },
2664
- "context-variables": {
2665
- "description": "Sets variables on the agent preview session, mirroring what the in-org Agentforce Builder UI does when you override variables before sending a message. Specify this flag multiple times or use comma-separated values. Two namespaces are supported, distinguished by the name shape. Names pass through to the runtime verbatim — the CLI doesn't transform them.\n\nLinked context variables use the \"$Context.\" prefix. These map to externally-provided fields that the runtime resolves (declared in the bundle's globalConfiguration.contextVariables) and are read by live actions and topic-routing expressions via $Context.Name. Example: $Context.MyLinkedVar=some-value.\n\nState variables use the bare developerName, no prefix. These seed mutable agent state declared in agentVersion.stateVariables. Example: MyStateVar=some-value.\n\nBoth namespaces can be mixed in one value. Example: --context-variables '$Context.MyLinkedVar=foo,MyStateVar=bar'.\n\nTips: (1) Quote the whole value in single quotes so $Context isn't shell-expanded. (2) Names are sent verbatim — a bare name is treated as a state variable, not a linked context variable, so live actions that bind via $Context.Name will see null. (3) Type is always Text; to send a typed variable, use --context-variables-json.",
2666
- "name": "context-variables",
2667
- "summary": "Session variables for the agent preview session, in the form Name=Value.",
2668
- "delimiter": ",",
2669
- "hasDynamicHelp": false,
2670
- "multiple": true,
2671
2663
  "type": "option"
2672
2664
  },
2673
- "context-variables-json": {
2674
- "description": "Sets typed variables on the agent preview session. Use this instead of --context-variables when a variable is not Text, for example a boolean-gated route (available when @variables.myFlag == True) that needs a real Boolean, or a Number, Object, List, or Json value.\n\nThe value is a JSON array of objects, each with a \"name\", a \"type\", and an optional \"value\". The \"type\" is one of Text, Date, DateTime, Money, Ref, Boolean, Number, Object, List, or Json. The JSON type of \"value\" must match \"type\": Boolean takes a boolean, Number takes a number, the string types take a string, Object and List take an array, and Json takes an object.\n\nExample: --context-variables-json '[{\"name\":\"probeGate\",\"type\":\"Boolean\",\"value\":true},{\"name\":\"retryCount\",\"type\":\"Number\",\"value\":3}]'.\n\nYou can pass both --context-variables and --context-variables-json in the same command. When the same variable name appears in both, the --context-variables-json value wins.\n\nTip: names follow the same rules as --context-variables. Use the \"$Context.\" prefix for linked context variables, and a bare name for state variables.",
2675
- "name": "context-variables-json",
2676
- "summary": "Typed session variables for the agent preview session, as a JSON array.",
2665
+ "output-dir": {
2666
+ "char": "d",
2667
+ "description": "If the agent test run completes, write the results to the specified directory. If the test is still running, the test results aren't written.",
2668
+ "name": "output-dir",
2669
+ "summary": "Directory to write the agent test results into.",
2677
2670
  "hasDynamicHelp": false,
2678
2671
  "multiple": false,
2679
2672
  "type": "option"
2680
2673
  },
2681
- "agent-json": {
2682
- "dependsOn": [
2683
- "authoring-bundle"
2684
- ],
2685
- "hidden": true,
2686
- "name": "agent-json",
2687
- "summary": "Path to a pre-compiled AgentJSON file to use instead of compiling the Agent Script file. Intended for internal use and testing.",
2674
+ "test-runner": {
2675
+ "description": "By default, the command automatically detects which test runner to use based on the test definition metadata type in your org. Use this flag to explicitly specify the runner type. 'agentforce-studio' uses AiTestingDefinition metadata. 'testing-center' uses AiEvaluationDefinition metadata.",
2676
+ "name": "test-runner",
2677
+ "summary": "Explicitly specify which test runner to use (agentforce-studio or testing-center).",
2688
2678
  "hasDynamicHelp": false,
2689
2679
  "multiple": false,
2680
+ "options": [
2681
+ "agentforce-studio",
2682
+ "testing-center"
2683
+ ],
2690
2684
  "type": "option"
2685
+ },
2686
+ "verbose": {
2687
+ "description": "When enabled, includes detailed generated data (such as invoked actions) in the human-readable test results output. This is useful for debugging test failures and understanding what actions were actually invoked during the test run.\n\nThe generated data is in JSON format and includes the Apex classes or Flows that were invoked, the Salesforce objects that were touched, and so on. Use the JSON structure of this information to build the test case JSONPath expression when using custom evaluations.",
2688
+ "name": "verbose",
2689
+ "summary": "Show generated data in the test results output.",
2690
+ "allowNo": false,
2691
+ "type": "boolean"
2691
2692
  }
2692
2693
  },
2693
2694
  "hasDynamicHelp": true,
2694
2695
  "hiddenAliases": [],
2695
- "id": "agent:preview:start",
2696
+ "id": "agent:test:results",
2696
2697
  "pluginAlias": "@salesforce/plugin-agent",
2697
2698
  "pluginName": "@salesforce/plugin-agent",
2698
2699
  "pluginType": "core",
2699
2700
  "strict": true,
2700
- "summary": "Start a programmatic agent preview session.",
2701
+ "summary": "Get the results of a completed agent test run.",
2701
2702
  "enableJsonFlag": true,
2702
- "requiresProject": true,
2703
2703
  "envVariablesSection": {
2704
2704
  "header": "ENVIRONMENT VARIABLES",
2705
2705
  "body": [
@@ -2714,23 +2714,15 @@
2714
2714
  "body": [
2715
2715
  {
2716
2716
  "name": "Succeeded (0)",
2717
- "description": "Preview session started successfully."
2718
- },
2719
- {
2720
- "name": "Failed (1)",
2721
- "description": "Agent Script compilation failed (syntax errors in the script)."
2717
+ "description": "Results retrieved successfully. Test results (passed/failed) are in the output."
2722
2718
  },
2723
2719
  {
2724
2720
  "name": "NotFound (2)",
2725
- "description": "Agent not found, or compilation API returned HTTP 404 (endpoint may not be available in your org or region)."
2726
- },
2727
- {
2728
- "name": "ServerError (3)",
2729
- "description": "Compilation API returned HTTP 500 (server error during compilation)."
2721
+ "description": "Job ID not found or invalid."
2730
2722
  },
2731
2723
  {
2732
- "name": "PreviewStartFailed (4)",
2733
- "description": "Preview session failed to start due to API or network errors."
2724
+ "name": "Failed (4)",
2725
+ "description": "Failed to retrieve results due to API or network errors."
2734
2726
  }
2735
2727
  ]
2736
2728
  },
@@ -2739,28 +2731,27 @@
2739
2731
  "lib",
2740
2732
  "commands",
2741
2733
  "agent",
2742
- "preview",
2743
- "start.js"
2734
+ "test",
2735
+ "results.js"
2744
2736
  ],
2745
2737
  "aliasPermutations": [],
2746
2738
  "permutations": [
2747
- "agent:preview:start",
2748
- "preview:agent:start",
2749
- "preview:start:agent",
2750
- "agent:start:preview",
2751
- "start:agent:preview",
2752
- "start:preview:agent"
2739
+ "agent:test:results",
2740
+ "test:agent:results",
2741
+ "test:results:agent",
2742
+ "agent:results:test",
2743
+ "results:agent:test",
2744
+ "results:test:agent"
2753
2745
  ]
2754
2746
  },
2755
- "agent:publish:authoring-bundle": {
2747
+ "agent:test:resume": {
2756
2748
  "aliases": [],
2757
2749
  "args": {},
2758
- "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.\n\nWhen 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 it's published to the org, which in turn creates new associated metadata (Bot, BotVersion, GenAiX), or new versions of the metadata if the agent already exists. The new or updated metadata is retrieved back to your DX project; specify the --skip-retrieve flag to skip this step. Finally, the authoring bundle metadata (AiAuthoringBundle) is deployed to your org.\n\nThis command uses the API name of the authoring bundle.",
2750
+ "description": "This command requires a job ID, which the original \"agent test run\" command displays when it completes. You can also use the --use-most-recent flag to see results for the most recently run agent test.\n\nUse the --wait flag to specify the number of minutes for this command to wait for the agent test to complete; if the test completes by the end of the wait time, the command displays the test results. If not, the CLI returns control of the terminal to you, and you must run \"agent test resume\" again.\n\nBy default, this command outputs test results in human-readable tables for each test case. The tables show whether the test case passed, the expected and actual values, the test score, how long the test took, and more. Use the --result-format to display the test results in JSON or Junit format. Use the --output-dir flag to write the results to a file rather than to the terminal.",
2759
2751
  "examples": [
2760
- "Publish an authoring bundle by being prompted for its API name; use your default org:\n<%= config.bin %> <%= command.id %>",
2761
- "Publish an authoring bundle with API name MyAuthoringBundle to the org with alias \"my-dev-org\":\n<%= config.bin %> <%= command.id %> --api-name MyAuthoringbundle --target-org my-dev-org",
2762
- "Publish with verbose output to see all retrieved and deployed metadata components:\n<%= config.bin %> <%= command.id %> --api-name MyAuthoringbundle --verbose",
2763
- "Publish with concise output showing only essential information:\n<%= config.bin %> <%= command.id %> --api-name MyAuthoringbundle --concise"
2752
+ "Resume an agent test in your default org using a job ID:\n<%= config.bin %> <%= command.id %> --job-id 4KBfake0000003F4AQ",
2753
+ "Resume the most recently-run agent test in an org with alias \"my-org\" org; wait 10 minutes for the tests to finish:\n<%= config.bin %> <%= command.id %> --use-most-recent --wait 10 --target-org my-org",
2754
+ "Resume the most recent agent test in your default org, and write the JSON-formatted results into a directory called \"test-results\":\n<%= config.bin %> <%= command.id %> --use-most-recent --output-dir ./test-results --result-format json"
2764
2755
  ],
2765
2756
  "flags": {
2766
2757
  "json": {
@@ -2795,98 +2786,141 @@
2795
2786
  "multiple": false,
2796
2787
  "type": "option"
2797
2788
  },
2798
- "api-name": {
2799
- "char": "n",
2800
- "name": "api-name",
2801
- "summary": "API name of the authoring bundle you want to publish; if not specified, the command provides a list that you can choose from.",
2789
+ "job-id": {
2790
+ "char": "i",
2791
+ "name": "job-id",
2792
+ "summary": "Job ID of the original agent test run.",
2802
2793
  "hasDynamicHelp": false,
2803
2794
  "multiple": false,
2804
2795
  "type": "option"
2805
2796
  },
2806
- "skip-retrieve": {
2807
- "name": "skip-retrieve",
2808
- "summary": "Don't retrieve the metadata associated with the agent to your DX project.",
2797
+ "use-most-recent": {
2798
+ "char": "r",
2799
+ "name": "use-most-recent",
2800
+ "summary": "Use the job ID of the most recent agent test run.",
2809
2801
  "allowNo": false,
2810
2802
  "type": "boolean"
2811
2803
  },
2812
- "verbose": {
2813
- "char": "v",
2814
- "exclusive": [
2815
- "concise"
2804
+ "wait": {
2805
+ "char": "w",
2806
+ "name": "wait",
2807
+ "summary": "Number of minutes to wait for the command to complete and display results to the terminal window.",
2808
+ "default": "5 minutes",
2809
+ "hasDynamicHelp": true,
2810
+ "multiple": false,
2811
+ "type": "option"
2812
+ },
2813
+ "result-format": {
2814
+ "name": "result-format",
2815
+ "summary": "Format of the agent test run results.",
2816
+ "default": "human",
2817
+ "hasDynamicHelp": false,
2818
+ "multiple": false,
2819
+ "options": [
2820
+ "json",
2821
+ "human",
2822
+ "junit",
2823
+ "tap"
2816
2824
  ],
2817
- "name": "verbose",
2818
- "summary": "Display detailed output showing all metadata components retrieved and deployed during the publish process.",
2819
- "allowNo": false,
2820
- "type": "boolean"
2825
+ "type": "option"
2821
2826
  },
2822
- "concise": {
2823
- "exclusive": [
2824
- "verbose"
2827
+ "output-dir": {
2828
+ "char": "d",
2829
+ "description": "If the agent test run completes, write the results to the specified directory. If the test is still running, the test results aren't written.",
2830
+ "name": "output-dir",
2831
+ "summary": "Directory to write the agent test results into.",
2832
+ "hasDynamicHelp": false,
2833
+ "multiple": false,
2834
+ "type": "option"
2835
+ },
2836
+ "test-runner": {
2837
+ "description": "By default, the command automatically detects which test runner to use based on the test definition metadata type in your org. Use this flag to explicitly specify the runner type. 'agentforce-studio' uses AiTestingDefinition metadata. 'testing-center' uses AiEvaluationDefinition metadata.",
2838
+ "name": "test-runner",
2839
+ "summary": "Explicitly specify which test runner to use (agentforce-studio or testing-center).",
2840
+ "hasDynamicHelp": false,
2841
+ "multiple": false,
2842
+ "options": [
2843
+ "agentforce-studio",
2844
+ "testing-center"
2825
2845
  ],
2826
- "name": "concise",
2827
- "summary": "Display minimal output with only essential information about the publish operation.",
2846
+ "type": "option"
2847
+ },
2848
+ "verbose": {
2849
+ "description": "When enabled, includes detailed generated data (such as invoked actions) in the human-readable test results output. This is useful for debugging test failures and understanding what actions were actually invoked during the test run.\n\nThe generated data is in JSON format and includes the Apex classes or Flows that were invoked, the Salesforce objects that were touched, and so on. Use the JSON structure of this information to build the test case JSONPath expression when using custom evaluations.",
2850
+ "name": "verbose",
2851
+ "summary": "Show generated data in the test results output.",
2828
2852
  "allowNo": false,
2829
2853
  "type": "boolean"
2830
2854
  }
2831
2855
  },
2832
2856
  "hasDynamicHelp": true,
2833
2857
  "hiddenAliases": [],
2834
- "id": "agent:publish:authoring-bundle",
2858
+ "id": "agent:test:resume",
2835
2859
  "pluginAlias": "@salesforce/plugin-agent",
2836
2860
  "pluginName": "@salesforce/plugin-agent",
2837
2861
  "pluginType": "core",
2838
2862
  "strict": true,
2839
- "summary": "Publish an authoring bundle to your org, which results in a new agent or a new version of an existing agent.",
2863
+ "summary": "Resume an agent test that you previously started in your org so you can view the test results.",
2840
2864
  "enableJsonFlag": true,
2841
- "requiresProject": true,
2865
+ "envVariablesSection": {
2866
+ "header": "ENVIRONMENT VARIABLES",
2867
+ "body": [
2868
+ {
2869
+ "name": "SF_TARGET_ORG",
2870
+ "description": "Username or alias of your default org. Overrides the target-org configuration variable."
2871
+ }
2872
+ ]
2873
+ },
2842
2874
  "errorCodes": {
2843
2875
  "header": "ERROR CODES",
2844
2876
  "body": [
2845
2877
  {
2846
2878
  "name": "Succeeded (0)",
2847
- "description": "Agent published successfully without errors."
2879
+ "description": "Test completed successfully (with test results in the output)."
2848
2880
  },
2849
2881
  {
2850
2882
  "name": "Failed (1)",
2851
- "description": "Compilation errors found in the Agent Script file."
2883
+ "description": "Tests encountered execution errors (test cases with ERROR status)."
2884
+ },
2885
+ {
2886
+ "name": "NotFound (2)",
2887
+ "description": "Job ID not found or invalid."
2888
+ },
2889
+ {
2890
+ "name": "OperationFailed (4)",
2891
+ "description": "Failed to poll test due to API or network errors."
2852
2892
  }
2853
2893
  ]
2854
2894
  },
2855
- "FLAGGABLE_PROMPTS": {
2856
- "api-name": {
2857
- "message": "API name of the authoring bundle you want to publish; if not specified, the command provides a list that you can choose from.",
2858
- "promptMessage": "API name of the authoring bundle to publish"
2859
- }
2860
- },
2861
2895
  "isESM": true,
2862
2896
  "relativePath": [
2863
2897
  "lib",
2864
2898
  "commands",
2865
2899
  "agent",
2866
- "publish",
2867
- "authoring-bundle.js"
2900
+ "test",
2901
+ "resume.js"
2868
2902
  ],
2869
2903
  "aliasPermutations": [],
2870
2904
  "permutations": [
2871
- "agent:publish:authoring-bundle",
2872
- "publish:agent:authoring-bundle",
2873
- "publish:authoring-bundle:agent",
2874
- "agent:authoring-bundle:publish",
2875
- "authoring-bundle:agent:publish",
2876
- "authoring-bundle:publish:agent"
2905
+ "agent:test:resume",
2906
+ "test:agent:resume",
2907
+ "test:resume:agent",
2908
+ "agent:resume:test",
2909
+ "resume:agent:test",
2910
+ "resume:test:agent"
2877
2911
  ]
2878
2912
  },
2879
- "agent:trace:delete": {
2913
+ "agent:test:run-eval": {
2880
2914
  "aliases": [],
2881
2915
  "args": {},
2882
- "description": "When you run an agent preview conversation (either interactive or programmatic), trace files are automatically recorded and saved in your local DX project. Use this command to delete some or all of the trace files.\n\nBy default, this command shows a preview of what will be deleted and prompts for confirmation. Use --no-prompt to skip confirmation.\n\nWithout filters, this comamnd deletes all trace files for all agents and sessions. Use flags to narrow the scope: filter by agent API name (--agent), by session (--session-id), or by age (--older-than).",
2916
+ "description": "Specify the tests you want to run with one of these inputs to the --spec flag:\n\n- YAML test spec generated by the `agent generate test-spec` CLI command\n- JSON payload\n\nWhen you provide a YAML test spec, this command automatically translates test cases into internal state-based evaluation framework calls and infers the agent name from the test spec's `subjectName` field. As a result, you can use the same test spec with both the `agent test run` and `agent test run-eval` commands. YAML test specs also support context variables, which allow you to inject contextual data (such as CaseId or RoutableId) into agent sessions for testing with different contexts.\n\nWhen you provide a JSON payload, it's sent directly to the evaluation framework with optional normalization. The normalizer auto-corrects common field name mistakes, converts shorthand references to JSONPath, and injects defaults. Use `--no-normalize` to disable this auto-normalization. JSON payloads can also include context_variables on agent.create_session steps for the same contextual testing capabilities as when you use a YAML test spec.\n\nThis command supports more than 8 evaluator types, including subagent routing assertions, action invocation checks, string/numeric assertions, semantic similarity scoring, and LLM-based quality ratings.",
2883
2917
  "examples": [
2884
- "Delete all traces for all agents and sessions; prompt for confirmation:\n<%= config.bin %> <%= command.id %>",
2885
- "Delete all traces for a specific agent:\n<%= config.bin %> <%= command.id %> --agent My_Agent",
2886
- "Delete traces from a specific session:\n<%= config.bin %> <%= command.id %> --session-id <SESSION_ID>",
2887
- "Delete traces older than 7 days:\n<%= config.bin %> <%= command.id %> --older-than 7d",
2888
- "Delete traces older than 24 hours for a specific agent; don't prompt for confirmation:\n<%= config.bin %> <%= command.id %> --agent My_Agent --older-than 24h --no-prompt",
2889
- "Delete all traces for all agents and sessions; don't prompt for confirmation:\n<%= config.bin %> <%= command.id %> --no-prompt"
2918
+ "Run tests using a YAML test spec on the org with alias \"my-org\":\n<%= config.bin %> <%= command.id %> --spec specs/my-agent-testSpec.yaml --target-org my-org",
2919
+ "Run tests using a YAML spec with explicit agent name override; use your default org:\n<%= config.bin %> <%= command.id %> --spec specs/my-agent-testSpec.yaml --api-name My_Agent",
2920
+ "Run tests using a JSON payload:\n<%= config.bin %> <%= command.id %> --spec specs/eval-payload.json --target-org my-org",
2921
+ "Run tests and output results in JUnit format; useful for continuous integration and deployment (CI/CD):\n<%= config.bin %> <%= command.id %> --spec specs/my-agent-testSpec.yaml --target-org my-org --result-format junit",
2922
+ "Run tests with contextVariables to inject contextual data into agent sessions (add contextVariables to test cases in your YAML spec):\n<%= config.bin %> <%= command.id %> --spec specs/agent-with-context.yaml --target-org my-org",
2923
+ "Pipe JSON payload from stdin (--spec flag is automatically populated from stdin):\n$ echo '{\"tests\":[...]}' | <%= config.bin %> <%= command.id %> --spec --target-org my-org"
2890
2924
  ],
2891
2925
  "flags": {
2892
2926
  "json": {
@@ -2904,141 +2938,106 @@
2904
2938
  "multiple": false,
2905
2939
  "type": "option"
2906
2940
  },
2907
- "agent": {
2908
- "char": "a",
2909
- "name": "agent",
2910
- "summary": "API name of the agent used to filter the list of trace files you want to delete. Matches against the API name used when starting the session, either an authoring bundle or a published agent API name.",
2911
- "hasDynamicHelp": false,
2941
+ "target-org": {
2942
+ "char": "o",
2943
+ "name": "target-org",
2944
+ "noCacheDefault": true,
2945
+ "required": true,
2946
+ "summary": "Username or alias of the target org. Not required if the `target-org` configuration variable is already set.",
2947
+ "hasDynamicHelp": true,
2912
2948
  "multiple": false,
2913
2949
  "type": "option"
2914
2950
  },
2915
- "session-id": {
2916
- "name": "session-id",
2917
- "summary": "Session ID used to filter the list of trace files you want to delete. Use the \"agent preview sessions\" CLI command to list all known agent preview sessions along with their session IDs.",
2951
+ "api-version": {
2952
+ "description": "Override the api version used for api requests made by this command",
2953
+ "name": "api-version",
2918
2954
  "hasDynamicHelp": false,
2919
2955
  "multiple": false,
2920
2956
  "type": "option"
2921
2957
  },
2922
- "older-than": {
2923
- "name": "older-than",
2924
- "summary": "Duration used to filter the list of trace files; only files older than the duration are deleted. Accepts a number followed by a unit: m/minutes, h/hours, d/days, w/weeks. Examples: 7d, 24h, 2w.",
2958
+ "spec": {
2959
+ "char": "s",
2960
+ "name": "spec",
2961
+ "required": true,
2962
+ "summary": "Path to test spec file (YAML or JSON). Supports reading from stdin when piping content.",
2925
2963
  "hasDynamicHelp": false,
2926
2964
  "multiple": false,
2927
2965
  "type": "option"
2928
2966
  },
2929
- "no-prompt": {
2930
- "name": "no-prompt",
2931
- "summary": "Skip the confirmation prompt and delete immediately.",
2932
- "allowNo": false,
2933
- "type": "boolean"
2934
- }
2935
- },
2936
- "hasDynamicHelp": false,
2937
- "hiddenAliases": [],
2938
- "id": "agent:trace:delete",
2939
- "pluginAlias": "@salesforce/plugin-agent",
2940
- "pluginName": "@salesforce/plugin-agent",
2941
- "pluginType": "core",
2942
- "strict": true,
2943
- "summary": "Delete trace files from an agent preview session.",
2944
- "enableJsonFlag": true,
2945
- "requiresProject": true,
2946
- "errorCodes": {
2947
- "header": "ERROR CODES",
2948
- "body": [
2949
- {
2950
- "name": "Succeeded (0)",
2951
- "description": "Traces deleted successfully (or no traces matched)."
2952
- }
2953
- ]
2954
- },
2955
- "isESM": true,
2956
- "relativePath": [
2957
- "lib",
2958
- "commands",
2959
- "agent",
2960
- "trace",
2961
- "delete.js"
2962
- ],
2963
- "aliasPermutations": [],
2964
- "permutations": [
2965
- "agent:trace:delete",
2966
- "trace:agent:delete",
2967
- "trace:delete:agent",
2968
- "agent:delete:trace",
2969
- "delete:agent:trace",
2970
- "delete:trace:agent"
2971
- ]
2972
- },
2973
- "agent:trace:list": {
2974
- "aliases": [],
2975
- "args": {},
2976
- "description": "When you run an agent preview conversation (either interactive or programmatic), trace files are automatically recorded and saved in your local DX project. By default, this command lists all trace files for all agents and all of their sessions. Use flags to narrow results: filter by agent name (--agent), by session (--session-id), or by date (--since).\n\nEach row in the output corresponds to one trace file, which in turn corresponds to one agent session. The Agent column shows the authoring bundle or API name used when starting the session.",
2977
- "examples": [
2978
- "List all trace files for all agents and sessions:\n<%= config.bin %> <%= command.id %>",
2979
- "List all trace files for a specific agent:\n<%= config.bin %> <%= command.id %> --agent My_Agent",
2980
- "List trace files for a specific session:\n<%= config.bin %> <%= command.id %> --session-id <SESSION_ID>",
2981
- "List trace files recorded on or after April 20, 2026 (date-only, interpreted as UTC midnight):\n<%= config.bin %> <%= command.id %> --since 2026-04-20",
2982
- "List trace files recorded on or after a specific UTC time:\n<%= config.bin %> <%= command.id %> --since 2026-04-20T14:00:00Z",
2983
- "Filter by agent and date together:\n<%= config.bin %> <%= command.id %> --agent My_Agent --since 2026-04-20",
2984
- "Return results as JSON:\n<%= config.bin %> <%= command.id %> --json"
2985
- ],
2986
- "flags": {
2987
- "json": {
2988
- "description": "Format output as json.",
2989
- "helpGroup": "GLOBAL",
2990
- "name": "json",
2991
- "allowNo": false,
2992
- "type": "boolean"
2993
- },
2994
- "flags-dir": {
2995
- "helpGroup": "GLOBAL",
2996
- "name": "flags-dir",
2997
- "summary": "Import flag values from a directory.",
2967
+ "api-name": {
2968
+ "char": "n",
2969
+ "name": "api-name",
2970
+ "summary": "Agent API name (also called DeveloperName) used to resolve agent_id and agent_version_id. Auto-inferred from the YAML spec's subjectName.",
2998
2971
  "hasDynamicHelp": false,
2999
2972
  "multiple": false,
3000
2973
  "type": "option"
3001
2974
  },
3002
- "session-id": {
3003
- "name": "session-id",
3004
- "summary": "Session ID used to filter the list of trace files. Use the \"agent preview sessions\" CLI command to list all known agent preview sessions along with their session IDs.",
2975
+ "result-format": {
2976
+ "name": "result-format",
2977
+ "summary": "Format of the agent test run results.",
2978
+ "default": "human",
3005
2979
  "hasDynamicHelp": false,
3006
2980
  "multiple": false,
2981
+ "options": [
2982
+ "json",
2983
+ "human",
2984
+ "junit",
2985
+ "tap"
2986
+ ],
3007
2987
  "type": "option"
3008
2988
  },
3009
- "agent": {
3010
- "char": "a",
3011
- "name": "agent",
3012
- "summary": "API name of the agent used to filter the list of available trace files. Matches against the API name used when starting the session, either an authoring bundle or a published agent API name.",
2989
+ "batch-size": {
2990
+ "name": "batch-size",
2991
+ "summary": "Number of tests per API request (max 5).",
2992
+ "default": 5,
3013
2993
  "hasDynamicHelp": false,
3014
2994
  "multiple": false,
3015
2995
  "type": "option"
3016
2996
  },
3017
- "since": {
3018
- "description": "Accepts ISO 8601 format: date-only (2026-04-20), date-time (2026-04-20T14:00:00Z), or date-time with milliseconds (2026-04-20T14:00:00.000Z). The \"Recorded At\" values shown in the table output are valid inputs.",
3019
- "name": "since",
3020
- "summary": "Date used to filter the list of trace files; only those recorded on or after the date are listed.",
3021
- "hasDynamicHelp": false,
3022
- "multiple": false,
3023
- "type": "option"
2997
+ "no-normalize": {
2998
+ "name": "no-normalize",
2999
+ "summary": "Disable auto-normalization of field names and shorthand references.",
3000
+ "allowNo": false,
3001
+ "type": "boolean"
3024
3002
  }
3025
3003
  },
3026
- "hasDynamicHelp": false,
3004
+ "hasDynamicHelp": true,
3027
3005
  "hiddenAliases": [],
3028
- "id": "agent:trace:list",
3006
+ "id": "agent:test:run-eval",
3029
3007
  "pluginAlias": "@salesforce/plugin-agent",
3030
3008
  "pluginName": "@salesforce/plugin-agent",
3031
3009
  "pluginType": "core",
3010
+ "state": "beta",
3032
3011
  "strict": true,
3033
- "summary": "List the available trace files that were recorded during all agent preview sessions.",
3012
+ "summary": "Run rich evaluation tests against an Agentforce agent.",
3034
3013
  "enableJsonFlag": true,
3035
- "requiresProject": true,
3014
+ "envVariablesSection": {
3015
+ "header": "ENVIRONMENT VARIABLES",
3016
+ "body": [
3017
+ {
3018
+ "name": "SF_TARGET_ORG",
3019
+ "description": "Username or alias of your default org. Overrides the target-org configuration variable."
3020
+ }
3021
+ ]
3022
+ },
3036
3023
  "errorCodes": {
3037
3024
  "header": "ERROR CODES",
3038
3025
  "body": [
3039
3026
  {
3040
3027
  "name": "Succeeded (0)",
3041
- "description": "Trace files listed successfully (or empty list if none found)."
3028
+ "description": "Tests completed successfully. Test results (passed/failed) are in the JSON output."
3029
+ },
3030
+ {
3031
+ "name": "Failed (1)",
3032
+ "description": "Tests encountered execution errors (tests couldn't run properly)."
3033
+ },
3034
+ {
3035
+ "name": "NotFound (2)",
3036
+ "description": "Agent not found, spec file not found, or invalid agent name."
3037
+ },
3038
+ {
3039
+ "name": "OperationFailed (4)",
3040
+ "description": "Failed to execute tests due to API or network errors."
3042
3041
  }
3043
3042
  ]
3044
3043
  },
@@ -3047,131 +3046,27 @@
3047
3046
  "lib",
3048
3047
  "commands",
3049
3048
  "agent",
3050
- "trace",
3051
- "list.js"
3052
- ],
3053
- "aliasPermutations": [],
3054
- "permutations": [
3055
- "agent:trace:list",
3056
- "trace:agent:list",
3057
- "trace:list:agent",
3058
- "agent:list:trace",
3059
- "list:agent:trace",
3060
- "list:trace:agent"
3061
- ]
3062
- },
3063
- "agent:trace:read": {
3064
- "aliases": [],
3065
- "args": {},
3066
- "description": "When you run an agent preview conversation (either interactive or programmatic), trace files are automatically recorded and saved in your local DX project. Each turn (utterance or response) of a conversation creates trace data. Use this command to view trace data for a specific preview session, so you can then analyze the trace data to observe, monitor, investigate, and troubleshoot agent events and behavior.\n\nUse the --format flag to specify one of these formats of the outputted trace data:\n\n- summary (Default): A per-turn narrative showing topic routing, actions executed, and the agent's response. Use this to quickly understand what happened in a preview session.\n- detail: Diagnostic drill-down into a specific dimension. Filters output to only the trace steps relevant to that dimension, minimizing noise.\n- raw: Unprocessed trace JSON. Use this as a fallback when the trace schema has changed or you need to perform custom analysis.\n\nIf you specify \"--format detail\", you must also specify a dimension with the --dimension flag. Dimensions are a way to slice and analyze the agent execution trace from a specific angle or concern. Instead of looking at the raw sequence of everything that happened, each dimension filters and organizes the trace data to answer a specific type of question. These are the available dimensions and the information they provide:\n\n- actions: The actions the agent executed. Includes action name, input parameters, output, and latency. Use this dimension to understand what the agent actually did when answering an utterance in the preview session.\n- grounding: The reasoning steps used by the LLM. Use this dimension to see how the agent \"thought\" about the problem - the AI reasoning that determined which actions to take.\n- routing: How the agent navigated between subagents. Use this dimension to understand conversation flow - when and why the agent switched between different subagents or contexts during the conversation.\n- errors: Aggregates all errors during the session. Use this dimension to quickly identify and debug issues across all steps.",
3067
- "examples": [
3068
- "Show a session trace summary for all turns in the session with the specified ID:\n<%= config.bin %> <%= command.id %> --session-id <SESSION_ID>",
3069
- "Show a trace summary for the second turn (utterance or response) of the conversation:\n<%= config.bin %> <%= command.id %> --session-id <SESSION_ID> --turn 2",
3070
- "Drill into action execution across all turns:\n<%= config.bin %> <%= command.id %> --session-id <SESSION_ID> --format detail --dimension actions",
3071
- "Drill into routing decisions for the first turn of the conversation:\n<%= config.bin %> <%= command.id %> --session-id <SESSION_ID> --format detail --dimension routing --turn 1",
3072
- "Show all errors across the session:\n<%= config.bin %> <%= command.id %> --session-id <SESSION_ID> --format detail --dimension errors",
3073
- "Output raw trace JSON for custom parsing:\n<%= config.bin %> <%= command.id %> --session-id <SESSION_ID> --format raw",
3074
- "Return results as JSON:\n<%= config.bin %> <%= command.id %> --session-id <SESSION_ID> --json"
3075
- ],
3076
- "flags": {
3077
- "json": {
3078
- "description": "Format output as json.",
3079
- "helpGroup": "GLOBAL",
3080
- "name": "json",
3081
- "allowNo": false,
3082
- "type": "boolean"
3083
- },
3084
- "flags-dir": {
3085
- "helpGroup": "GLOBAL",
3086
- "name": "flags-dir",
3087
- "summary": "Import flag values from a directory.",
3088
- "hasDynamicHelp": false,
3089
- "multiple": false,
3090
- "type": "option"
3091
- },
3092
- "session-id": {
3093
- "char": "s",
3094
- "name": "session-id",
3095
- "required": true,
3096
- "summary": "Session ID to read traces for. Use the \"agent preview sessions\" CLI command to list all known agent preview sessions along with their session IDs",
3097
- "hasDynamicHelp": false,
3098
- "multiple": false,
3099
- "type": "option"
3100
- },
3101
- "format": {
3102
- "char": "f",
3103
- "name": "format",
3104
- "summary": "Output format of the trace data; specifies the level of detail you want in the trace files.",
3105
- "default": "summary",
3106
- "hasDynamicHelp": false,
3107
- "multiple": false,
3108
- "options": [
3109
- "summary",
3110
- "detail",
3111
- "raw"
3112
- ],
3113
- "type": "option"
3114
- },
3115
- "dimension": {
3116
- "char": "d",
3117
- "name": "dimension",
3118
- "summary": "Dimension to drill into when using \"--format detail\"; used to filter and organize the trace data to answer a specific type of question.",
3119
- "hasDynamicHelp": false,
3120
- "multiple": false,
3121
- "options": [
3122
- "actions",
3123
- "grounding",
3124
- "routing",
3125
- "errors"
3126
- ],
3127
- "type": "option"
3128
- },
3129
- "turn": {
3130
- "char": "t",
3131
- "name": "turn",
3132
- "summary": "Turn number for which you want trace data. A turn is a single utterance or response in a conversation, starting with 1.",
3133
- "hasDynamicHelp": false,
3134
- "multiple": false,
3135
- "type": "option"
3136
- }
3137
- },
3138
- "hasDynamicHelp": false,
3139
- "hiddenAliases": [],
3140
- "id": "agent:trace:read",
3141
- "pluginAlias": "@salesforce/plugin-agent",
3142
- "pluginName": "@salesforce/plugin-agent",
3143
- "pluginType": "core",
3144
- "strict": true,
3145
- "summary": "Read trace files from an agent preview session.",
3146
- "enableJsonFlag": true,
3147
- "requiresProject": true,
3148
- "isESM": true,
3149
- "relativePath": [
3150
- "lib",
3151
- "commands",
3152
- "agent",
3153
- "trace",
3154
- "read.js"
3049
+ "test",
3050
+ "run-eval.js"
3155
3051
  ],
3156
3052
  "aliasPermutations": [],
3157
3053
  "permutations": [
3158
- "agent:trace:read",
3159
- "trace:agent:read",
3160
- "trace:read:agent",
3161
- "agent:read:trace",
3162
- "read:agent:trace",
3163
- "read:trace:agent"
3054
+ "agent:test:run-eval",
3055
+ "test:agent:run-eval",
3056
+ "test:run-eval:agent",
3057
+ "agent:run-eval:test",
3058
+ "run-eval:agent:test",
3059
+ "run-eval:test:agent"
3164
3060
  ]
3165
3061
  },
3166
- "agent:test:create": {
3062
+ "agent:test:run": {
3167
3063
  "aliases": [],
3168
3064
  "args": {},
3169
- "description": "To run this command, you must have an agent test spec file, which is a YAML file that lists the test cases for testing a specific agent. Use the \"agent generate test-spec\" CLI command to generate a test spec file. Then specify the file to this command with the --spec flag, or run this command with no flags to be prompted.\n\nWhen this command completes, your org contains the new agent test, which you can view and edit using the Testing Center UI (legacy) or Agentforce Studio (NGT). This command also retrieves the metadata component associated with the new test to your local Salesforce DX project and displays its filename. By default, the legacy AiEvaluationDefinition is created; use --test-runner agentforce-studio to author an AiTestingDefinition (NGT) instead.\n\nAfter you've created the test in the org, use the \"agent test run\" command to run it.",
3065
+ "description": "Use the --api-name flag to specify the name of the agent test you want to run. Use the output of the \"agent test list\" command to get the names of all the available agent tests in your org.\n\nBy default, this command starts the agent test in your org, but it doesn't wait for the test to finish. Instead, it displays the \"agent test resume\" command, with a job ID, that you execute to see the results of the test run, and then returns control of the terminal window to you. Use the --wait flag to specify the number of minutes for the command to wait for the agent test to complete; if the test completes by the end of the wait time, the command displays the test results. If not, run \"agent test resume\".\n\nBy default, this command outputs test results in human-readable tables for each test case, if the test completes in time. The tables show whether the test case passed, the expected and actual values, the test score, how long the test took, and more. Use the --result-format to display the test results in JSON or Junit format. Use the --output-dir flag to write the results to a file rather than to the terminal.",
3170
3066
  "examples": [
3171
- "Create an agent test interactively and be prompted for the test spec and API name of the test in the org; use the default org:\n<%= config.bin %> <%= command.id %>",
3172
- "Create an agent test and use flags to specify all required information; if a test with same API name already exists in the org, overwrite it without confirmation. Use the org with alias \"my-org\":\n<%= config.bin %> <%= command.id %> --spec specs/Resort_Manager-testSpec.yaml --api-name Resort_Manager_Test --force-overwrite --target-org my-org",
3173
- "Preview what the agent test metadata (AiEvaluationDefinition) looks like without deploying it to your default org:\n<%= config.bin %> <%= command.id %> --spec specs/Resort_Manager-testSpec.yaml --api-name Resort_Manager_Test --preview",
3174
- "Author an Agentforce Studio (NGT) test from an NGT-shaped YAML; writes an AiTestingDefinition metadata file:\n<%= config.bin %> <%= command.id %> --spec specs/ReturnsCheckout.ngt.yaml --api-name Returns_Checkout --test-runner agentforce-studio --target-org my-org"
3067
+ "Start an agent test called Resort_Manager_Test for an agent in your default org, don't wait for the test to finish:\n<%= config.bin %> <%= command.id %> --api-name Resort_Manager_Test",
3068
+ "Start an agent test for an agent in an org with alias \"my-org\" and wait for 10 minutes for the test to finish:\n<%= config.bin %> <%= command.id %> --api-name Resort_Manager_Test --wait 10 --target-org my-org",
3069
+ "Start an agent test and write the JSON-formatted results into a directory called \"test-results\":\n<%= config.bin %> <%= command.id %> --api-name Resort_Manager_Test --wait 10 --output-dir ./test-results --result-format json"
3175
3070
  ],
3176
3071
  "flags": {
3177
3072
  "json": {
@@ -3189,20 +3084,6 @@
3189
3084
  "multiple": false,
3190
3085
  "type": "option"
3191
3086
  },
3192
- "api-name": {
3193
- "name": "api-name",
3194
- "summary": "API name of the new test; the API name must not exist in the org.",
3195
- "hasDynamicHelp": false,
3196
- "multiple": false,
3197
- "type": "option"
3198
- },
3199
- "spec": {
3200
- "name": "spec",
3201
- "summary": "Path to the test spec YAML file.",
3202
- "hasDynamicHelp": false,
3203
- "multiple": false,
3204
- "type": "option"
3205
- },
3206
3087
  "target-org": {
3207
3088
  "char": "o",
3208
3089
  "name": "target-org",
@@ -3220,17 +3101,44 @@
3220
3101
  "multiple": false,
3221
3102
  "type": "option"
3222
3103
  },
3223
- "preview": {
3224
- "name": "preview",
3225
- "summary": "Preview the test metadata file without deploying to your org.",
3226
- "allowNo": false,
3227
- "type": "boolean"
3104
+ "api-name": {
3105
+ "char": "n",
3106
+ "name": "api-name",
3107
+ "summary": "API name of the agent test to run; corresponds to the name of the AiEvaluationDefinition metadata component that implements the agent test.",
3108
+ "hasDynamicHelp": false,
3109
+ "multiple": false,
3110
+ "type": "option"
3228
3111
  },
3229
- "force-overwrite": {
3230
- "name": "force-overwrite",
3231
- "summary": "Don't prompt for confirmation when overwriting an existing test (based on API name) in your org.",
3232
- "allowNo": false,
3233
- "type": "boolean"
3112
+ "wait": {
3113
+ "char": "w",
3114
+ "name": "wait",
3115
+ "summary": "Number of minutes to wait for the command to complete and display results to the terminal window.",
3116
+ "hasDynamicHelp": true,
3117
+ "multiple": false,
3118
+ "type": "option"
3119
+ },
3120
+ "result-format": {
3121
+ "name": "result-format",
3122
+ "summary": "Format of the agent test run results.",
3123
+ "default": "human",
3124
+ "hasDynamicHelp": false,
3125
+ "multiple": false,
3126
+ "options": [
3127
+ "json",
3128
+ "human",
3129
+ "junit",
3130
+ "tap"
3131
+ ],
3132
+ "type": "option"
3133
+ },
3134
+ "output-dir": {
3135
+ "char": "d",
3136
+ "description": "If the agent test run completes, write the results to the specified directory. If the test is still running, the test results aren't written.",
3137
+ "name": "output-dir",
3138
+ "summary": "Directory to write the agent test results into.",
3139
+ "hasDynamicHelp": false,
3140
+ "multiple": false,
3141
+ "type": "option"
3234
3142
  },
3235
3143
  "test-runner": {
3236
3144
  "description": "By default, the command automatically detects which test runner to use based on the test definition metadata type in your org. Use this flag to explicitly specify the runner type. 'agentforce-studio' uses AiTestingDefinition metadata. 'testing-center' uses AiEvaluationDefinition metadata.",
@@ -3243,16 +3151,23 @@
3243
3151
  "testing-center"
3244
3152
  ],
3245
3153
  "type": "option"
3154
+ },
3155
+ "verbose": {
3156
+ "description": "When enabled, includes detailed generated data (such as invoked actions) in the human-readable test results output. This is useful for debugging test failures and understanding what actions were actually invoked during the test run.\n\nThe generated data is in JSON format and includes the Apex classes or Flows that were invoked, the Salesforce objects that were touched, and so on. Use the JSON structure of this information to build the test case JSONPath expression when using custom evaluations.",
3157
+ "name": "verbose",
3158
+ "summary": "Show generated data in the test results output.",
3159
+ "allowNo": false,
3160
+ "type": "boolean"
3246
3161
  }
3247
3162
  },
3248
3163
  "hasDynamicHelp": true,
3249
3164
  "hiddenAliases": [],
3250
- "id": "agent:test:create",
3165
+ "id": "agent:test:run",
3251
3166
  "pluginAlias": "@salesforce/plugin-agent",
3252
3167
  "pluginName": "@salesforce/plugin-agent",
3253
3168
  "pluginType": "core",
3254
3169
  "strict": true,
3255
- "summary": "Create an agent test in your org using a local test spec YAML file.",
3170
+ "summary": "Start an agent test in your org.",
3256
3171
  "enableJsonFlag": true,
3257
3172
  "envVariablesSection": {
3258
3173
  "header": "ENVIRONMENT VARIABLES",
@@ -3268,19 +3183,19 @@
3268
3183
  "body": [
3269
3184
  {
3270
3185
  "name": "Succeeded (0)",
3271
- "description": "Test created and deployed successfully."
3186
+ "description": "Test started successfully (without --wait), or test completed successfully (with --wait)."
3272
3187
  },
3273
3188
  {
3274
3189
  "name": "Failed (1)",
3275
- "description": "Test validation errors or metadata format issues."
3190
+ "description": "Tests encountered execution errors (test cases with ERROR status when using --wait)."
3276
3191
  },
3277
3192
  {
3278
3193
  "name": "NotFound (2)",
3279
- "description": "Test spec file not found or org connection failed."
3194
+ "description": "Test definition not found or invalid test name."
3280
3195
  },
3281
3196
  {
3282
- "name": "DeploymentFailed (4)",
3283
- "description": "Deployment failed due to API or network errors."
3197
+ "name": "OperationFailed (4)",
3198
+ "description": "Failed to start or poll test due to API or network errors."
3284
3199
  }
3285
3200
  ]
3286
3201
  },
@@ -3290,25 +3205,29 @@
3290
3205
  "commands",
3291
3206
  "agent",
3292
3207
  "test",
3293
- "create.js"
3208
+ "run.js"
3294
3209
  ],
3295
3210
  "aliasPermutations": [],
3296
3211
  "permutations": [
3297
- "agent:test:create",
3298
- "test:agent:create",
3299
- "test:create:agent",
3300
- "agent:create:test",
3301
- "create:agent:test",
3302
- "create:test:agent"
3212
+ "agent:test:run",
3213
+ "test:agent:run",
3214
+ "test:run:agent",
3215
+ "agent:run:test",
3216
+ "run:agent:test",
3217
+ "run:test:agent"
3303
3218
  ]
3304
3219
  },
3305
- "agent:test:list": {
3220
+ "agent:trace:delete": {
3306
3221
  "aliases": [],
3307
3222
  "args": {},
3308
- "description": "The command outputs a table with the name (API name) of each test along with its unique ID, type ('agentforce-studio' or 'testing-center'), and the date it was created in the org.",
3223
+ "description": "When you run an agent preview conversation (either interactive or programmatic), trace files are automatically recorded and saved in your local DX project. Use this command to delete some or all of the trace files.\n\nBy default, this command shows a preview of what will be deleted and prompts for confirmation. Use --no-prompt to skip confirmation.\n\nWithout filters, this comamnd deletes all trace files for all agents and sessions. Use flags to narrow the scope: filter by agent API name (--agent), by session (--session-id), or by age (--older-than).",
3309
3224
  "examples": [
3310
- "List the agent tests in your default org:\n<%= config.bin %> <%= command.id %>",
3311
- "List the agent tests in an org with alias \"my-org\"\"\n<%= config.bin %> <%= command.id %> --target-org my-org"
3225
+ "Delete all traces for all agents and sessions; prompt for confirmation:\n<%= config.bin %> <%= command.id %>",
3226
+ "Delete all traces for a specific agent:\n<%= config.bin %> <%= command.id %> --agent My_Agent",
3227
+ "Delete traces from a specific session:\n<%= config.bin %> <%= command.id %> --session-id <SESSION_ID>",
3228
+ "Delete traces older than 7 days:\n<%= config.bin %> <%= command.id %> --older-than 7d",
3229
+ "Delete traces older than 24 hours for a specific agent; don't prompt for confirmation:\n<%= config.bin %> <%= command.id %> --agent My_Agent --older-than 24h --no-prompt",
3230
+ "Delete all traces for all agents and sessions; don't prompt for confirmation:\n<%= config.bin %> <%= command.id %> --no-prompt"
3312
3231
  ],
3313
3232
  "flags": {
3314
3233
  "json": {
@@ -3326,52 +3245,141 @@
3326
3245
  "multiple": false,
3327
3246
  "type": "option"
3328
3247
  },
3329
- "target-org": {
3330
- "char": "o",
3331
- "name": "target-org",
3332
- "noCacheDefault": true,
3333
- "required": true,
3334
- "summary": "Username or alias of the target org. Not required if the `target-org` configuration variable is already set.",
3335
- "hasDynamicHelp": true,
3248
+ "agent": {
3249
+ "char": "a",
3250
+ "name": "agent",
3251
+ "summary": "API name of the agent used to filter the list of trace files you want to delete. Matches against the API name used when starting the session, either an authoring bundle or a published agent API name.",
3252
+ "hasDynamicHelp": false,
3336
3253
  "multiple": false,
3337
3254
  "type": "option"
3338
3255
  },
3339
- "api-version": {
3340
- "description": "Override the api version used for api requests made by this command",
3341
- "name": "api-version",
3256
+ "session-id": {
3257
+ "name": "session-id",
3258
+ "summary": "Session ID used to filter the list of trace files you want to delete. Use the \"agent preview sessions\" CLI command to list all known agent preview sessions along with their session IDs.",
3259
+ "hasDynamicHelp": false,
3260
+ "multiple": false,
3261
+ "type": "option"
3262
+ },
3263
+ "older-than": {
3264
+ "name": "older-than",
3265
+ "summary": "Duration used to filter the list of trace files; only files older than the duration are deleted. Accepts a number followed by a unit: m/minutes, h/hours, d/days, w/weeks. Examples: 7d, 24h, 2w.",
3342
3266
  "hasDynamicHelp": false,
3343
3267
  "multiple": false,
3344
3268
  "type": "option"
3269
+ },
3270
+ "no-prompt": {
3271
+ "name": "no-prompt",
3272
+ "summary": "Skip the confirmation prompt and delete immediately.",
3273
+ "allowNo": false,
3274
+ "type": "boolean"
3345
3275
  }
3346
3276
  },
3347
- "hasDynamicHelp": true,
3277
+ "hasDynamicHelp": false,
3348
3278
  "hiddenAliases": [],
3349
- "id": "agent:test:list",
3279
+ "id": "agent:trace:delete",
3350
3280
  "pluginAlias": "@salesforce/plugin-agent",
3351
3281
  "pluginName": "@salesforce/plugin-agent",
3352
3282
  "pluginType": "core",
3353
3283
  "strict": true,
3354
- "summary": "List the available agent tests in your org.",
3284
+ "summary": "Delete trace files from an agent preview session.",
3355
3285
  "enableJsonFlag": true,
3356
- "envVariablesSection": {
3357
- "header": "ENVIRONMENT VARIABLES",
3286
+ "requiresProject": true,
3287
+ "errorCodes": {
3288
+ "header": "ERROR CODES",
3358
3289
  "body": [
3359
3290
  {
3360
- "name": "SF_TARGET_ORG",
3361
- "description": "Username or alias of your default org. Overrides the target-org configuration variable."
3291
+ "name": "Succeeded (0)",
3292
+ "description": "Traces deleted successfully (or no traces matched)."
3362
3293
  }
3363
3294
  ]
3364
3295
  },
3296
+ "isESM": true,
3297
+ "relativePath": [
3298
+ "lib",
3299
+ "commands",
3300
+ "agent",
3301
+ "trace",
3302
+ "delete.js"
3303
+ ],
3304
+ "aliasPermutations": [],
3305
+ "permutations": [
3306
+ "agent:trace:delete",
3307
+ "trace:agent:delete",
3308
+ "trace:delete:agent",
3309
+ "agent:delete:trace",
3310
+ "delete:agent:trace",
3311
+ "delete:trace:agent"
3312
+ ]
3313
+ },
3314
+ "agent:trace:list": {
3315
+ "aliases": [],
3316
+ "args": {},
3317
+ "description": "When you run an agent preview conversation (either interactive or programmatic), trace files are automatically recorded and saved in your local DX project. By default, this command lists all trace files for all agents and all of their sessions. Use flags to narrow results: filter by agent name (--agent), by session (--session-id), or by date (--since).\n\nEach row in the output corresponds to one trace file, which in turn corresponds to one agent session. The Agent column shows the authoring bundle or API name used when starting the session.",
3318
+ "examples": [
3319
+ "List all trace files for all agents and sessions:\n<%= config.bin %> <%= command.id %>",
3320
+ "List all trace files for a specific agent:\n<%= config.bin %> <%= command.id %> --agent My_Agent",
3321
+ "List trace files for a specific session:\n<%= config.bin %> <%= command.id %> --session-id <SESSION_ID>",
3322
+ "List trace files recorded on or after April 20, 2026 (date-only, interpreted as UTC midnight):\n<%= config.bin %> <%= command.id %> --since 2026-04-20",
3323
+ "List trace files recorded on or after a specific UTC time:\n<%= config.bin %> <%= command.id %> --since 2026-04-20T14:00:00Z",
3324
+ "Filter by agent and date together:\n<%= config.bin %> <%= command.id %> --agent My_Agent --since 2026-04-20",
3325
+ "Return results as JSON:\n<%= config.bin %> <%= command.id %> --json"
3326
+ ],
3327
+ "flags": {
3328
+ "json": {
3329
+ "description": "Format output as json.",
3330
+ "helpGroup": "GLOBAL",
3331
+ "name": "json",
3332
+ "allowNo": false,
3333
+ "type": "boolean"
3334
+ },
3335
+ "flags-dir": {
3336
+ "helpGroup": "GLOBAL",
3337
+ "name": "flags-dir",
3338
+ "summary": "Import flag values from a directory.",
3339
+ "hasDynamicHelp": false,
3340
+ "multiple": false,
3341
+ "type": "option"
3342
+ },
3343
+ "session-id": {
3344
+ "name": "session-id",
3345
+ "summary": "Session ID used to filter the list of trace files. Use the \"agent preview sessions\" CLI command to list all known agent preview sessions along with their session IDs.",
3346
+ "hasDynamicHelp": false,
3347
+ "multiple": false,
3348
+ "type": "option"
3349
+ },
3350
+ "agent": {
3351
+ "char": "a",
3352
+ "name": "agent",
3353
+ "summary": "API name of the agent used to filter the list of available trace files. Matches against the API name used when starting the session, either an authoring bundle or a published agent API name.",
3354
+ "hasDynamicHelp": false,
3355
+ "multiple": false,
3356
+ "type": "option"
3357
+ },
3358
+ "since": {
3359
+ "description": "Accepts ISO 8601 format: date-only (2026-04-20), date-time (2026-04-20T14:00:00Z), or date-time with milliseconds (2026-04-20T14:00:00.000Z). The \"Recorded At\" values shown in the table output are valid inputs.",
3360
+ "name": "since",
3361
+ "summary": "Date used to filter the list of trace files; only those recorded on or after the date are listed.",
3362
+ "hasDynamicHelp": false,
3363
+ "multiple": false,
3364
+ "type": "option"
3365
+ }
3366
+ },
3367
+ "hasDynamicHelp": false,
3368
+ "hiddenAliases": [],
3369
+ "id": "agent:trace:list",
3370
+ "pluginAlias": "@salesforce/plugin-agent",
3371
+ "pluginName": "@salesforce/plugin-agent",
3372
+ "pluginType": "core",
3373
+ "strict": true,
3374
+ "summary": "List the available trace files that were recorded during all agent preview sessions.",
3375
+ "enableJsonFlag": true,
3376
+ "requiresProject": true,
3365
3377
  "errorCodes": {
3366
3378
  "header": "ERROR CODES",
3367
3379
  "body": [
3368
3380
  {
3369
3381
  "name": "Succeeded (0)",
3370
- "description": "Agent tests listed successfully."
3371
- },
3372
- {
3373
- "name": "Failed (4)",
3374
- "description": "Failed to retrieve agent tests due to API or network errors."
3382
+ "description": "Trace files listed successfully (or empty list if none found)."
3375
3383
  }
3376
3384
  ]
3377
3385
  },
@@ -3380,27 +3388,31 @@
3380
3388
  "lib",
3381
3389
  "commands",
3382
3390
  "agent",
3383
- "test",
3391
+ "trace",
3384
3392
  "list.js"
3385
3393
  ],
3386
3394
  "aliasPermutations": [],
3387
3395
  "permutations": [
3388
- "agent:test:list",
3389
- "test:agent:list",
3390
- "test:list:agent",
3391
- "agent:list:test",
3392
- "list:agent:test",
3393
- "list:test:agent"
3396
+ "agent:trace:list",
3397
+ "trace:agent:list",
3398
+ "trace:list:agent",
3399
+ "agent:list:trace",
3400
+ "list:agent:trace",
3401
+ "list:trace:agent"
3394
3402
  ]
3395
3403
  },
3396
- "agent:test:results": {
3404
+ "agent:trace:read": {
3397
3405
  "aliases": [],
3398
3406
  "args": {},
3399
- "description": "This command requires a job ID, which the original \"agent test run\" command displays when it completes. You can also use the --use-most-recent flag to see results for the most recently run agent test.\n\nBy default, this command outputs test results in human-readable tables for each test case. The tables show whether the test case passed, the expected and actual values, the test score, how long the test took, and more. Use the --result-format to display the test results in JSON or Junit format. Use the --output-dir flag to write the results to a file rather than to the terminal.",
3407
+ "description": "When you run an agent preview conversation (either interactive or programmatic), trace files are automatically recorded and saved in your local DX project. Each turn (utterance or response) of a conversation creates trace data. Use this command to view trace data for a specific preview session, so you can then analyze the trace data to observe, monitor, investigate, and troubleshoot agent events and behavior.\n\nUse the --format flag to specify one of these formats of the outputted trace data:\n\n- summary (Default): A per-turn narrative showing topic routing, actions executed, and the agent's response. Use this to quickly understand what happened in a preview session.\n- detail: Diagnostic drill-down into a specific dimension. Filters output to only the trace steps relevant to that dimension, minimizing noise.\n- raw: Unprocessed trace JSON. Use this as a fallback when the trace schema has changed or you need to perform custom analysis.\n\nIf you specify \"--format detail\", you must also specify a dimension with the --dimension flag. Dimensions are a way to slice and analyze the agent execution trace from a specific angle or concern. Instead of looking at the raw sequence of everything that happened, each dimension filters and organizes the trace data to answer a specific type of question. These are the available dimensions and the information they provide:\n\n- actions: The actions the agent executed. Includes action name, input parameters, output, and latency. Use this dimension to understand what the agent actually did when answering an utterance in the preview session.\n- grounding: The reasoning steps used by the LLM. Use this dimension to see how the agent \"thought\" about the problem - the AI reasoning that determined which actions to take.\n- routing: How the agent navigated between subagents. Use this dimension to understand conversation flow - when and why the agent switched between different subagents or contexts during the conversation.\n- errors: Aggregates all errors during the session. Use this dimension to quickly identify and debug issues across all steps.",
3400
3408
  "examples": [
3401
- "Get the results of an agent test run in your default org using its job ID:\n<%= config.bin %> <%= command.id %> --job-id 4KBfake0000003F4AQ",
3402
- "Get the results of the most recently run agent test in an org with alias \"my-org\":\n<%= config.bin %> <%= command.id %> --use-most-recent --target-org my-org",
3403
- "Get the results of the most recently run agent test in your default org, and write the JSON-formatted results into a directory called \"test-results\":\n<%= config.bin %> <%= command.id %> --use-most-recent --output-dir ./test-results --result-format json"
3409
+ "Show a session trace summary for all turns in the session with the specified ID:\n<%= config.bin %> <%= command.id %> --session-id <SESSION_ID>",
3410
+ "Show a trace summary for the second turn (utterance or response) of the conversation:\n<%= config.bin %> <%= command.id %> --session-id <SESSION_ID> --turn 2",
3411
+ "Drill into action execution across all turns:\n<%= config.bin %> <%= command.id %> --session-id <SESSION_ID> --format detail --dimension actions",
3412
+ "Drill into routing decisions for the first turn of the conversation:\n<%= config.bin %> <%= command.id %> --session-id <SESSION_ID> --format detail --dimension routing --turn 1",
3413
+ "Show all errors across the session:\n<%= config.bin %> <%= command.id %> --session-id <SESSION_ID> --format detail --dimension errors",
3414
+ "Output raw trace JSON for custom parsing:\n<%= config.bin %> <%= command.id %> --session-id <SESSION_ID> --format raw",
3415
+ "Return results as JSON:\n<%= config.bin %> <%= command.id %> --session-id <SESSION_ID> --json"
3404
3416
  ],
3405
3417
  "flags": {
3406
3418
  "json": {
@@ -3418,136 +3430,87 @@
3418
3430
  "multiple": false,
3419
3431
  "type": "option"
3420
3432
  },
3421
- "target-org": {
3422
- "char": "o",
3423
- "name": "target-org",
3424
- "noCacheDefault": true,
3425
- "required": true,
3426
- "summary": "Username or alias of the target org. Not required if the `target-org` configuration variable is already set.",
3427
- "hasDynamicHelp": true,
3428
- "multiple": false,
3429
- "type": "option"
3430
- },
3431
- "api-version": {
3432
- "description": "Override the api version used for api requests made by this command",
3433
- "name": "api-version",
3434
- "hasDynamicHelp": false,
3435
- "multiple": false,
3436
- "type": "option"
3437
- },
3438
- "job-id": {
3439
- "char": "i",
3440
- "name": "job-id",
3433
+ "session-id": {
3434
+ "char": "s",
3435
+ "name": "session-id",
3441
3436
  "required": true,
3442
- "summary": "Job ID of the completed agent test run.",
3437
+ "summary": "Session ID to read traces for. Use the \"agent preview sessions\" CLI command to list all known agent preview sessions along with their session IDs",
3443
3438
  "hasDynamicHelp": false,
3444
3439
  "multiple": false,
3445
3440
  "type": "option"
3446
3441
  },
3447
- "result-format": {
3448
- "name": "result-format",
3449
- "summary": "Format of the agent test run results.",
3450
- "default": "human",
3442
+ "format": {
3443
+ "char": "f",
3444
+ "name": "format",
3445
+ "summary": "Output format of the trace data; specifies the level of detail you want in the trace files.",
3446
+ "default": "summary",
3451
3447
  "hasDynamicHelp": false,
3452
3448
  "multiple": false,
3453
3449
  "options": [
3454
- "json",
3455
- "human",
3456
- "junit",
3457
- "tap"
3450
+ "summary",
3451
+ "detail",
3452
+ "raw"
3458
3453
  ],
3459
3454
  "type": "option"
3460
3455
  },
3461
- "output-dir": {
3456
+ "dimension": {
3462
3457
  "char": "d",
3463
- "description": "If the agent test run completes, write the results to the specified directory. If the test is still running, the test results aren't written.",
3464
- "name": "output-dir",
3465
- "summary": "Directory to write the agent test results into.",
3458
+ "name": "dimension",
3459
+ "summary": "Dimension to drill into when using \"--format detail\"; used to filter and organize the trace data to answer a specific type of question.",
3466
3460
  "hasDynamicHelp": false,
3467
3461
  "multiple": false,
3462
+ "options": [
3463
+ "actions",
3464
+ "grounding",
3465
+ "routing",
3466
+ "errors"
3467
+ ],
3468
3468
  "type": "option"
3469
3469
  },
3470
- "test-runner": {
3471
- "description": "By default, the command automatically detects which test runner to use based on the test definition metadata type in your org. Use this flag to explicitly specify the runner type. 'agentforce-studio' uses AiTestingDefinition metadata. 'testing-center' uses AiEvaluationDefinition metadata.",
3472
- "name": "test-runner",
3473
- "summary": "Explicitly specify which test runner to use (agentforce-studio or testing-center).",
3470
+ "turn": {
3471
+ "char": "t",
3472
+ "name": "turn",
3473
+ "summary": "Turn number for which you want trace data. A turn is a single utterance or response in a conversation, starting with 1.",
3474
3474
  "hasDynamicHelp": false,
3475
3475
  "multiple": false,
3476
- "options": [
3477
- "agentforce-studio",
3478
- "testing-center"
3479
- ],
3480
3476
  "type": "option"
3481
- },
3482
- "verbose": {
3483
- "description": "When enabled, includes detailed generated data (such as invoked actions) in the human-readable test results output. This is useful for debugging test failures and understanding what actions were actually invoked during the test run.\n\nThe generated data is in JSON format and includes the Apex classes or Flows that were invoked, the Salesforce objects that were touched, and so on. Use the JSON structure of this information to build the test case JSONPath expression when using custom evaluations.",
3484
- "name": "verbose",
3485
- "summary": "Show generated data in the test results output.",
3486
- "allowNo": false,
3487
- "type": "boolean"
3488
3477
  }
3489
3478
  },
3490
- "hasDynamicHelp": true,
3479
+ "hasDynamicHelp": false,
3491
3480
  "hiddenAliases": [],
3492
- "id": "agent:test:results",
3481
+ "id": "agent:trace:read",
3493
3482
  "pluginAlias": "@salesforce/plugin-agent",
3494
3483
  "pluginName": "@salesforce/plugin-agent",
3495
3484
  "pluginType": "core",
3496
3485
  "strict": true,
3497
- "summary": "Get the results of a completed agent test run.",
3486
+ "summary": "Read trace files from an agent preview session.",
3498
3487
  "enableJsonFlag": true,
3499
- "envVariablesSection": {
3500
- "header": "ENVIRONMENT VARIABLES",
3501
- "body": [
3502
- {
3503
- "name": "SF_TARGET_ORG",
3504
- "description": "Username or alias of your default org. Overrides the target-org configuration variable."
3505
- }
3506
- ]
3507
- },
3508
- "errorCodes": {
3509
- "header": "ERROR CODES",
3510
- "body": [
3511
- {
3512
- "name": "Succeeded (0)",
3513
- "description": "Results retrieved successfully. Test results (passed/failed) are in the output."
3514
- },
3515
- {
3516
- "name": "NotFound (2)",
3517
- "description": "Job ID not found or invalid."
3518
- },
3519
- {
3520
- "name": "Failed (4)",
3521
- "description": "Failed to retrieve results due to API or network errors."
3522
- }
3523
- ]
3524
- },
3488
+ "requiresProject": true,
3525
3489
  "isESM": true,
3526
3490
  "relativePath": [
3527
3491
  "lib",
3528
3492
  "commands",
3529
3493
  "agent",
3530
- "test",
3531
- "results.js"
3494
+ "trace",
3495
+ "read.js"
3532
3496
  ],
3533
3497
  "aliasPermutations": [],
3534
3498
  "permutations": [
3535
- "agent:test:results",
3536
- "test:agent:results",
3537
- "test:results:agent",
3538
- "agent:results:test",
3539
- "results:agent:test",
3540
- "results:test:agent"
3499
+ "agent:trace:read",
3500
+ "trace:agent:read",
3501
+ "trace:read:agent",
3502
+ "agent:read:trace",
3503
+ "read:agent:trace",
3504
+ "read:trace:agent"
3541
3505
  ]
3542
3506
  },
3543
- "agent:test:resume": {
3507
+ "agent:validate:authoring-bundle": {
3544
3508
  "aliases": [],
3545
3509
  "args": {},
3546
- "description": "This command requires a job ID, which the original \"agent test run\" command displays when it completes. You can also use the --use-most-recent flag to see results for the most recently run agent test.\n\nUse the --wait flag to specify the number of minutes for this command to wait for the agent test to complete; if the test completes by the end of the wait time, the command displays the test results. If not, the CLI returns control of the terminal to you, and you must run \"agent test resume\" again.\n\nBy default, this command outputs test results in human-readable tables for each test case. The tables show whether the test case passed, the expected and actual values, the test score, how long the test took, and more. Use the --result-format to display the test results in JSON or Junit format. Use the --output-dir flag to write the results to a file rather than to the terminal.",
3510
+ "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.\n\nThis 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.\n\nThis 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.",
3547
3511
  "examples": [
3548
- "Resume an agent test in your default org using a job ID:\n<%= config.bin %> <%= command.id %> --job-id 4KBfake0000003F4AQ",
3549
- "Resume the most recently-run agent test in an org with alias \"my-org\" org; wait 10 minutes for the tests to finish:\n<%= config.bin %> <%= command.id %> --use-most-recent --wait 10 --target-org my-org",
3550
- "Resume the most recent agent test in your default org, and write the JSON-formatted results into a directory called \"test-results\":\n<%= config.bin %> <%= command.id %> --use-most-recent --output-dir ./test-results --result-format json"
3512
+ "Validate an authoring bundle by being prompted for its API name; use your default org:\n<%= config.bin %> <%= command.id %>",
3513
+ "Validate an authoring bundle with API name MyAuthoringBundle; use the org with alias \"my-dev-org\":\n<%= config.bin %> <%= command.id %> --api-name MyAuthoringBundle --target-org my-dev-org"
3551
3514
  ],
3552
3515
  "flags": {
3553
3516
  "json": {
@@ -3582,82 +3545,25 @@
3582
3545
  "multiple": false,
3583
3546
  "type": "option"
3584
3547
  },
3585
- "job-id": {
3586
- "char": "i",
3587
- "name": "job-id",
3588
- "summary": "Job ID of the original agent test run.",
3589
- "hasDynamicHelp": false,
3590
- "multiple": false,
3591
- "type": "option"
3592
- },
3593
- "use-most-recent": {
3594
- "char": "r",
3595
- "name": "use-most-recent",
3596
- "summary": "Use the job ID of the most recent agent test run.",
3597
- "allowNo": false,
3598
- "type": "boolean"
3599
- },
3600
- "wait": {
3601
- "char": "w",
3602
- "name": "wait",
3603
- "summary": "Number of minutes to wait for the command to complete and display results to the terminal window.",
3604
- "default": "5 minutes",
3605
- "hasDynamicHelp": true,
3606
- "multiple": false,
3607
- "type": "option"
3608
- },
3609
- "result-format": {
3610
- "name": "result-format",
3611
- "summary": "Format of the agent test run results.",
3612
- "default": "human",
3613
- "hasDynamicHelp": false,
3614
- "multiple": false,
3615
- "options": [
3616
- "json",
3617
- "human",
3618
- "junit",
3619
- "tap"
3620
- ],
3621
- "type": "option"
3622
- },
3623
- "output-dir": {
3624
- "char": "d",
3625
- "description": "If the agent test run completes, write the results to the specified directory. If the test is still running, the test results aren't written.",
3626
- "name": "output-dir",
3627
- "summary": "Directory to write the agent test results into.",
3628
- "hasDynamicHelp": false,
3629
- "multiple": false,
3630
- "type": "option"
3631
- },
3632
- "test-runner": {
3633
- "description": "By default, the command automatically detects which test runner to use based on the test definition metadata type in your org. Use this flag to explicitly specify the runner type. 'agentforce-studio' uses AiTestingDefinition metadata. 'testing-center' uses AiEvaluationDefinition metadata.",
3634
- "name": "test-runner",
3635
- "summary": "Explicitly specify which test runner to use (agentforce-studio or testing-center).",
3548
+ "api-name": {
3549
+ "char": "n",
3550
+ "name": "api-name",
3551
+ "summary": "API name of the authoring bundle you want to validate; if not specified, the command provides a list that you can choose from.",
3636
3552
  "hasDynamicHelp": false,
3637
3553
  "multiple": false,
3638
- "options": [
3639
- "agentforce-studio",
3640
- "testing-center"
3641
- ],
3642
3554
  "type": "option"
3643
- },
3644
- "verbose": {
3645
- "description": "When enabled, includes detailed generated data (such as invoked actions) in the human-readable test results output. This is useful for debugging test failures and understanding what actions were actually invoked during the test run.\n\nThe generated data is in JSON format and includes the Apex classes or Flows that were invoked, the Salesforce objects that were touched, and so on. Use the JSON structure of this information to build the test case JSONPath expression when using custom evaluations.",
3646
- "name": "verbose",
3647
- "summary": "Show generated data in the test results output.",
3648
- "allowNo": false,
3649
- "type": "boolean"
3650
3555
  }
3651
3556
  },
3652
3557
  "hasDynamicHelp": true,
3653
3558
  "hiddenAliases": [],
3654
- "id": "agent:test:resume",
3559
+ "id": "agent:validate:authoring-bundle",
3655
3560
  "pluginAlias": "@salesforce/plugin-agent",
3656
3561
  "pluginName": "@salesforce/plugin-agent",
3657
3562
  "pluginType": "core",
3658
3563
  "strict": true,
3659
- "summary": "Resume an agent test that you previously started in your org so you can view the test results.",
3564
+ "summary": "Validate an authoring bundle to ensure its Agent Script file compiles successfully and can be used to publish an agent.",
3660
3565
  "enableJsonFlag": true,
3566
+ "requiresProject": true,
3661
3567
  "envVariablesSection": {
3662
3568
  "header": "ENVIRONMENT VARIABLES",
3663
3569
  "body": [
@@ -3672,51 +3578,56 @@
3672
3578
  "body": [
3673
3579
  {
3674
3580
  "name": "Succeeded (0)",
3675
- "description": "Test completed successfully (with test results in the output)."
3581
+ "description": "Agent Script file compiled successfully without errors."
3676
3582
  },
3677
3583
  {
3678
3584
  "name": "Failed (1)",
3679
- "description": "Tests encountered execution errors (test cases with ERROR status)."
3585
+ "description": "Compilation errors found in the Agent Script file."
3680
3586
  },
3681
3587
  {
3682
3588
  "name": "NotFound (2)",
3683
- "description": "Job ID not found or invalid."
3589
+ "description": "Validation/compilation API returned HTTP 404. The API endpoint may not be available in your org or region."
3684
3590
  },
3685
3591
  {
3686
- "name": "OperationFailed (4)",
3687
- "description": "Failed to poll test due to API or network errors."
3592
+ "name": "ServerError (3)",
3593
+ "description": "Validation/compilation API returned HTTP 500. A server error occurred during compilation."
3688
3594
  }
3689
3595
  ]
3690
3596
  },
3597
+ "FLAGGABLE_PROMPTS": {
3598
+ "api-name": {
3599
+ "message": "API name of the authoring bundle you want to validate; if not specified, the command provides a list that you can choose from.",
3600
+ "promptMessage": "API name of the authoring bundle to validate"
3601
+ }
3602
+ },
3691
3603
  "isESM": true,
3692
3604
  "relativePath": [
3693
3605
  "lib",
3694
3606
  "commands",
3695
3607
  "agent",
3696
- "test",
3697
- "resume.js"
3608
+ "validate",
3609
+ "authoring-bundle.js"
3698
3610
  ],
3699
3611
  "aliasPermutations": [],
3700
3612
  "permutations": [
3701
- "agent:test:resume",
3702
- "test:agent:resume",
3703
- "test:resume:agent",
3704
- "agent:resume:test",
3705
- "resume:agent:test",
3706
- "resume:test:agent"
3613
+ "agent:validate:authoring-bundle",
3614
+ "validate:agent:authoring-bundle",
3615
+ "validate:authoring-bundle:agent",
3616
+ "agent:authoring-bundle:validate",
3617
+ "authoring-bundle:agent:validate",
3618
+ "authoring-bundle:validate:agent"
3707
3619
  ]
3708
3620
  },
3709
- "agent:test:run-eval": {
3621
+ "agent:preview:end": {
3710
3622
  "aliases": [],
3711
3623
  "args": {},
3712
- "description": "Specify the tests you want to run with one of these inputs to the --spec flag:\n\n- YAML test spec generated by the `agent generate test-spec` CLI command\n- JSON payload\n\nWhen you provide a YAML test spec, this command automatically translates test cases into internal state-based evaluation framework calls and infers the agent name from the test spec's `subjectName` field. As a result, you can use the same test spec with both the `agent test run` and `agent test run-eval` commands. YAML test specs also support context variables, which allow you to inject contextual data (such as CaseId or RoutableId) into agent sessions for testing with different contexts.\n\nWhen you provide a JSON payload, it's sent directly to the evaluation framework with optional normalization. The normalizer auto-corrects common field name mistakes, converts shorthand references to JSONPath, and injects defaults. Use `--no-normalize` to disable this auto-normalization. JSON payloads can also include context_variables on agent.create_session steps for the same contextual testing capabilities as when you use a YAML test spec.\n\nThis command supports more than 8 evaluator types, including subagent routing assertions, action invocation checks, string/numeric assertions, semantic similarity scoring, and LLM-based quality ratings.",
3624
+ "description": "You must have previously started a programmatic agent preview session with the \"agent preview start\" command to then use this command to end it. This command also displays the local directory where the session trace files are stored.\n\nThe original \"agent preview start\" command outputs a session ID which you then use with the --session-id flag of this command to end the session. You don't have to specify the --session-id flag if an agent has only one active preview session. You must also use either the --authoring-bundle or --api-name flag to specify the API name of the authoring bundle or the published agent, respectively. 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.\n\nUse the --all flag to end all active preview sessions at once. You can combine --all with --api-name or --authoring-bundle to end only sessions for a specific agent, or use --all on its own to end every session across all agents in the project.",
3713
3625
  "examples": [
3714
- "Run tests using a YAML test spec on the org with alias \"my-org\":\n<%= config.bin %> <%= command.id %> --spec specs/my-agent-testSpec.yaml --target-org my-org",
3715
- "Run tests using a YAML spec with explicit agent name override; use your default org:\n<%= config.bin %> <%= command.id %> --spec specs/my-agent-testSpec.yaml --api-name My_Agent",
3716
- "Run tests using a JSON payload:\n<%= config.bin %> <%= command.id %> --spec specs/eval-payload.json --target-org my-org",
3717
- "Run tests and output results in JUnit format; useful for continuous integration and deployment (CI/CD):\n<%= config.bin %> <%= command.id %> --spec specs/my-agent-testSpec.yaml --target-org my-org --result-format junit",
3718
- "Run tests with contextVariables to inject contextual data into agent sessions (add contextVariables to test cases in your YAML spec):\n<%= config.bin %> <%= command.id %> --spec specs/agent-with-context.yaml --target-org my-org",
3719
- "Pipe JSON payload from stdin (--spec flag is automatically populated from stdin):\n$ echo '{\"tests\":[...]}' | <%= config.bin %> <%= command.id %> --spec --target-org my-org"
3626
+ "End a preview session of a published agent by specifying its session ID and API name; use the default org:\n<%= config.bin %> <%= command.id %> --session-id <SESSION_ID> --api-name My_Published_Agent",
3627
+ "Similar to previous example, but don't specify a session ID; you get an error if the published agent has more than one active session. Use the org with alias \"my-dev-org\":\n<%= config.bin %> <%= command.id %> --api-name My_Published_Agent --target-org my-dev-org",
3628
+ "End a preview session of an agent using its authoring bundle API name; you get an error if the agent has more than one active session.\n<%= config.bin %> <%= command.id %> --authoring-bundle My_Local_Agent",
3629
+ "End all active preview sessions for a specific agent without prompting:\n<%= config.bin %> <%= command.id %> --all --authoring-bundle My_Local_Agent --target-org <target_org> --no-prompt",
3630
+ "End all active preview sessions across every agent in the local session cache for an org:\n<%= config.bin %> <%= command.id %> --all --target-org <target_org>"
3720
3631
  ],
3721
3632
  "flags": {
3722
3633
  "json": {
@@ -3751,62 +3662,65 @@
3751
3662
  "multiple": false,
3752
3663
  "type": "option"
3753
3664
  },
3754
- "spec": {
3755
- "char": "s",
3756
- "name": "spec",
3757
- "required": true,
3758
- "summary": "Path to test spec file (YAML or JSON). Supports reading from stdin when piping content.",
3665
+ "session-id": {
3666
+ "exclusive": [
3667
+ "all"
3668
+ ],
3669
+ "name": "session-id",
3670
+ "required": false,
3671
+ "summary": "Session ID outputted by \"agent preview start\". Not required when the agent has exactly one active session. Run \"agent preview sessions\" to see the list of all sessions.",
3759
3672
  "hasDynamicHelp": false,
3760
3673
  "multiple": false,
3761
3674
  "type": "option"
3762
3675
  },
3763
3676
  "api-name": {
3764
3677
  "char": "n",
3678
+ "exclusive": [
3679
+ "authoring-bundle"
3680
+ ],
3765
3681
  "name": "api-name",
3766
- "summary": "Agent API name (also called DeveloperName) used to resolve agent_id and agent_version_id. Auto-inferred from the YAML spec's subjectName.",
3682
+ "summary": "API name of the activated published agent you want to preview.",
3767
3683
  "hasDynamicHelp": false,
3768
3684
  "multiple": false,
3769
3685
  "type": "option"
3770
3686
  },
3771
- "result-format": {
3772
- "name": "result-format",
3773
- "summary": "Format of the agent test run results.",
3774
- "default": "human",
3775
- "hasDynamicHelp": false,
3776
- "multiple": false,
3777
- "options": [
3778
- "json",
3779
- "human",
3780
- "junit",
3781
- "tap"
3687
+ "authoring-bundle": {
3688
+ "exclusive": [
3689
+ "api-name"
3782
3690
  ],
3783
- "type": "option"
3784
- },
3785
- "batch-size": {
3786
- "name": "batch-size",
3787
- "summary": "Number of tests per API request (max 5).",
3788
- "default": 5,
3691
+ "name": "authoring-bundle",
3692
+ "summary": "API name of the authoring bundle metadata component that contains the agent's Agent Script file.",
3789
3693
  "hasDynamicHelp": false,
3790
3694
  "multiple": false,
3791
3695
  "type": "option"
3792
3696
  },
3793
- "no-normalize": {
3794
- "name": "no-normalize",
3795
- "summary": "Disable auto-normalization of field names and shorthand references.",
3697
+ "all": {
3698
+ "exclusive": [
3699
+ "session-id"
3700
+ ],
3701
+ "name": "all",
3702
+ "summary": "End all active preview sessions. Combine with --api-name or --authoring-bundle to limit to a specific agent, or use with only --target-org to end sessions for all agents found in the local session cache. Requires --target-org.",
3703
+ "allowNo": false,
3704
+ "type": "boolean"
3705
+ },
3706
+ "no-prompt": {
3707
+ "char": "p",
3708
+ "name": "no-prompt",
3709
+ "summary": "Don't prompt for confirmation before ending sessions. Has an effect only when used with --all.",
3796
3710
  "allowNo": false,
3797
3711
  "type": "boolean"
3798
3712
  }
3799
3713
  },
3800
3714
  "hasDynamicHelp": true,
3801
3715
  "hiddenAliases": [],
3802
- "id": "agent:test:run-eval",
3716
+ "id": "agent:preview:end",
3803
3717
  "pluginAlias": "@salesforce/plugin-agent",
3804
3718
  "pluginName": "@salesforce/plugin-agent",
3805
3719
  "pluginType": "core",
3806
- "state": "beta",
3807
3720
  "strict": true,
3808
- "summary": "Run rich evaluation tests against an Agentforce agent.",
3721
+ "summary": "End an existing programmatic agent preview session and get trace location.",
3809
3722
  "enableJsonFlag": true,
3723
+ "requiresProject": true,
3810
3724
  "envVariablesSection": {
3811
3725
  "header": "ENVIRONMENT VARIABLES",
3812
3726
  "body": [
@@ -3821,19 +3735,27 @@
3821
3735
  "body": [
3822
3736
  {
3823
3737
  "name": "Succeeded (0)",
3824
- "description": "Tests completed successfully. Test results (passed/failed) are in the JSON output."
3738
+ "description": "Preview session ended successfully and traces saved."
3825
3739
  },
3826
3740
  {
3827
- "name": "Failed (1)",
3828
- "description": "Tests encountered execution errors (tests couldn't run properly)."
3741
+ "name": "ExactlyOneRequired (2)",
3742
+ "description": "Neither --api-name nor --authoring-bundle was provided (required when --all is not set)."
3829
3743
  },
3830
3744
  {
3831
3745
  "name": "NotFound (2)",
3832
- "description": "Agent not found, spec file not found, or invalid agent name."
3746
+ "description": "Agent not found, or no preview session exists for this agent."
3833
3747
  },
3834
3748
  {
3835
- "name": "OperationFailed (4)",
3836
- "description": "Failed to execute tests due to API or network errors."
3749
+ "name": "PreviewEndFailed (4)",
3750
+ "description": "Failed to end the preview session."
3751
+ },
3752
+ {
3753
+ "name": "PreviewEndPartialFailure (68)",
3754
+ "description": "With --all, one or more sessions failed to end while others succeeded."
3755
+ },
3756
+ {
3757
+ "name": "SessionAmbiguous (5)",
3758
+ "description": "Multiple preview sessions found; specify --session-id to choose one."
3837
3759
  }
3838
3760
  ]
3839
3761
  },
@@ -3842,27 +3764,27 @@
3842
3764
  "lib",
3843
3765
  "commands",
3844
3766
  "agent",
3845
- "test",
3846
- "run-eval.js"
3767
+ "preview",
3768
+ "end.js"
3847
3769
  ],
3848
3770
  "aliasPermutations": [],
3849
3771
  "permutations": [
3850
- "agent:test:run-eval",
3851
- "test:agent:run-eval",
3852
- "test:run-eval:agent",
3853
- "agent:run-eval:test",
3854
- "run-eval:agent:test",
3855
- "run-eval:test:agent"
3772
+ "agent:preview:end",
3773
+ "preview:agent:end",
3774
+ "preview:end:agent",
3775
+ "agent:end:preview",
3776
+ "end:agent:preview",
3777
+ "end:preview:agent"
3856
3778
  ]
3857
3779
  },
3858
- "agent:test:run": {
3780
+ "agent:preview:send": {
3859
3781
  "aliases": [],
3860
3782
  "args": {},
3861
- "description": "Use the --api-name flag to specify the name of the agent test you want to run. Use the output of the \"agent test list\" command to get the names of all the available agent tests in your org.\n\nBy default, this command starts the agent test in your org, but it doesn't wait for the test to finish. Instead, it displays the \"agent test resume\" command, with a job ID, that you execute to see the results of the test run, and then returns control of the terminal window to you. Use the --wait flag to specify the number of minutes for the command to wait for the agent test to complete; if the test completes by the end of the wait time, the command displays the test results. If not, run \"agent test resume\".\n\nBy default, this command outputs test results in human-readable tables for each test case, if the test completes in time. The tables show whether the test case passed, the expected and actual values, the test score, how long the test took, and more. Use the --result-format to display the test results in JSON or Junit format. Use the --output-dir flag to write the results to a file rather than to the terminal.",
3783
+ "description": "You must have previously started a programmatic agent preview session with the \"agent preview start\" command to then use this command to send the agent a message (utterance). This command then displays the agent's response.\n\nThe original \"agent preview start\" command outputs a session ID which you then use with the --session-id flag of this command to send a message. You don't have to specify the --session-id flag if an agent has only one active preview session. You must also use either the --authoring-bundle or --api-name flag to specify the API name of the authoring bundle or the published agent, respecitvely. 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.",
3862
3784
  "examples": [
3863
- "Start an agent test called Resort_Manager_Test for an agent in your default org, don't wait for the test to finish:\n<%= config.bin %> <%= command.id %> --api-name Resort_Manager_Test",
3864
- "Start an agent test for an agent in an org with alias \"my-org\" and wait for 10 minutes for the test to finish:\n<%= config.bin %> <%= command.id %> --api-name Resort_Manager_Test --wait 10 --target-org my-org",
3865
- "Start an agent test and write the JSON-formatted results into a directory called \"test-results\":\n<%= config.bin %> <%= command.id %> --api-name Resort_Manager_Test --wait 10 --output-dir ./test-results --result-format json"
3785
+ "Send a message to an activated published agent using its API name and session ID; use the default org:\n<%= config.bin %> <%= command.id %> --utterance \"What can you help me with?\" --api-name My_Published_Agent --session-id <SESSION_ID>",
3786
+ "Similar to previous example, but don't specify a session ID; you get an error if the agent has more than one active session. Use the org with alias \"my-dev-org\":\n<%= config.bin %> <%= command.id %> --utterance \"What can you help me with?\" --api-name My_Published_Agent --target-org my-dev-org",
3787
+ "Send a message to an agent using its authoring bundle API name; you get an error if the agent has more than one active session:\n<%= config.bin %> <%= command.id %> --utterance \"what can you help me with?\" --authoring-bundle My_Local_Agent"
3866
3788
  ],
3867
3789
  "flags": {
3868
3790
  "json": {
@@ -3897,101 +3819,137 @@
3897
3819
  "multiple": false,
3898
3820
  "type": "option"
3899
3821
  },
3900
- "api-name": {
3901
- "char": "n",
3902
- "name": "api-name",
3903
- "summary": "API name of the agent test to run; corresponds to the name of the AiEvaluationDefinition metadata component that implements the agent test.",
3822
+ "session-id": {
3823
+ "name": "session-id",
3824
+ "required": false,
3825
+ "summary": "Session ID outputted by \"agent preview start\". Not required when the agent has exactly one active session. Run \"agent preview sessions\" to see list of all sessions.",
3904
3826
  "hasDynamicHelp": false,
3905
3827
  "multiple": false,
3906
3828
  "type": "option"
3907
3829
  },
3908
- "wait": {
3909
- "char": "w",
3910
- "name": "wait",
3911
- "summary": "Number of minutes to wait for the command to complete and display results to the terminal window.",
3912
- "hasDynamicHelp": true,
3830
+ "utterance": {
3831
+ "char": "u",
3832
+ "name": "utterance",
3833
+ "required": true,
3834
+ "summary": "Utterance to send to the agent, enclosed in double quotes.",
3835
+ "hasDynamicHelp": false,
3913
3836
  "multiple": false,
3914
3837
  "type": "option"
3915
3838
  },
3916
- "result-format": {
3917
- "name": "result-format",
3918
- "summary": "Format of the agent test run results.",
3919
- "default": "human",
3839
+ "api-name": {
3840
+ "char": "n",
3841
+ "name": "api-name",
3842
+ "summary": "API name of the activated published agent you want to preview.",
3920
3843
  "hasDynamicHelp": false,
3921
3844
  "multiple": false,
3922
- "options": [
3923
- "json",
3924
- "human",
3925
- "junit",
3926
- "tap"
3927
- ],
3928
3845
  "type": "option"
3929
3846
  },
3930
- "output-dir": {
3931
- "char": "d",
3932
- "description": "If the agent test run completes, write the results to the specified directory. If the test is still running, the test results aren't written.",
3933
- "name": "output-dir",
3934
- "summary": "Directory to write the agent test results into.",
3847
+ "authoring-bundle": {
3848
+ "name": "authoring-bundle",
3849
+ "summary": "API name of the authoring bundle metadata component that contains the agent's Agent Script file.",
3935
3850
  "hasDynamicHelp": false,
3936
3851
  "multiple": false,
3937
3852
  "type": "option"
3938
- },
3939
- "test-runner": {
3940
- "description": "By default, the command automatically detects which test runner to use based on the test definition metadata type in your org. Use this flag to explicitly specify the runner type. 'agentforce-studio' uses AiTestingDefinition metadata. 'testing-center' uses AiEvaluationDefinition metadata.",
3941
- "name": "test-runner",
3942
- "summary": "Explicitly specify which test runner to use (agentforce-studio or testing-center).",
3853
+ }
3854
+ },
3855
+ "hasDynamicHelp": true,
3856
+ "hiddenAliases": [],
3857
+ "id": "agent:preview:send",
3858
+ "pluginAlias": "@salesforce/plugin-agent",
3859
+ "pluginName": "@salesforce/plugin-agent",
3860
+ "pluginType": "core",
3861
+ "strict": true,
3862
+ "summary": "Send a message to an existing agent preview session.",
3863
+ "enableJsonFlag": true,
3864
+ "requiresProject": true,
3865
+ "envVariablesSection": {
3866
+ "header": "ENVIRONMENT VARIABLES",
3867
+ "body": [
3868
+ {
3869
+ "name": "SF_TARGET_ORG",
3870
+ "description": "Username or alias of your default org. Overrides the target-org configuration variable."
3871
+ }
3872
+ ]
3873
+ },
3874
+ "errorCodes": {
3875
+ "header": "ERROR CODES",
3876
+ "body": [
3877
+ {
3878
+ "name": "Succeeded (0)",
3879
+ "description": "Message sent successfully and agent response received."
3880
+ },
3881
+ {
3882
+ "name": "NotFound (2)",
3883
+ "description": "Agent not found, or no preview session exists for this agent."
3884
+ },
3885
+ {
3886
+ "name": "PreviewSendFailed (4)",
3887
+ "description": "Failed to send message or receive response from the preview session."
3888
+ },
3889
+ {
3890
+ "name": "SessionAmbiguous (5)",
3891
+ "description": "Multiple preview sessions found; specify --session-id to choose one."
3892
+ }
3893
+ ]
3894
+ },
3895
+ "isESM": true,
3896
+ "relativePath": [
3897
+ "lib",
3898
+ "commands",
3899
+ "agent",
3900
+ "preview",
3901
+ "send.js"
3902
+ ],
3903
+ "aliasPermutations": [],
3904
+ "permutations": [
3905
+ "agent:preview:send",
3906
+ "preview:agent:send",
3907
+ "preview:send:agent",
3908
+ "agent:send:preview",
3909
+ "send:agent:preview",
3910
+ "send:preview:agent"
3911
+ ]
3912
+ },
3913
+ "agent:preview:sessions": {
3914
+ "aliases": [],
3915
+ "args": {},
3916
+ "description": "This command lists the agent preview sessions that were started with the \"agent preview start\" command and are still in the local cache. Use this command to discover specific session IDs that you can pass to the \"agent preview send\" or \"agent preview end\" commands with the --session-id flag.\n\nProgrammatic agent preview sessions can be started for both published activated agents and by using an agent's local authoring bundle, which contains its Agent Script file. In this command's output table, the Agent column contains either the API name of the authoring bundle or the published agent, whichever was used when starting the session. In the table, if the same API name has multiple rows with different session IDs, then it means that you previously started multiple preview sessions with the associated agent.",
3917
+ "examples": [
3918
+ "List all cached agent preview sessions:\n<%= config.bin %> <%= command.id %>"
3919
+ ],
3920
+ "flags": {
3921
+ "json": {
3922
+ "description": "Format output as json.",
3923
+ "helpGroup": "GLOBAL",
3924
+ "name": "json",
3925
+ "allowNo": false,
3926
+ "type": "boolean"
3927
+ },
3928
+ "flags-dir": {
3929
+ "helpGroup": "GLOBAL",
3930
+ "name": "flags-dir",
3931
+ "summary": "Import flag values from a directory.",
3943
3932
  "hasDynamicHelp": false,
3944
3933
  "multiple": false,
3945
- "options": [
3946
- "agentforce-studio",
3947
- "testing-center"
3948
- ],
3949
3934
  "type": "option"
3950
- },
3951
- "verbose": {
3952
- "description": "When enabled, includes detailed generated data (such as invoked actions) in the human-readable test results output. This is useful for debugging test failures and understanding what actions were actually invoked during the test run.\n\nThe generated data is in JSON format and includes the Apex classes or Flows that were invoked, the Salesforce objects that were touched, and so on. Use the JSON structure of this information to build the test case JSONPath expression when using custom evaluations.",
3953
- "name": "verbose",
3954
- "summary": "Show generated data in the test results output.",
3955
- "allowNo": false,
3956
- "type": "boolean"
3957
3935
  }
3958
3936
  },
3959
- "hasDynamicHelp": true,
3937
+ "hasDynamicHelp": false,
3960
3938
  "hiddenAliases": [],
3961
- "id": "agent:test:run",
3939
+ "id": "agent:preview:sessions",
3962
3940
  "pluginAlias": "@salesforce/plugin-agent",
3963
3941
  "pluginName": "@salesforce/plugin-agent",
3964
3942
  "pluginType": "core",
3965
3943
  "strict": true,
3966
- "summary": "Start an agent test in your org.",
3944
+ "summary": "List all known programmatic agent preview sessions.",
3967
3945
  "enableJsonFlag": true,
3968
- "envVariablesSection": {
3969
- "header": "ENVIRONMENT VARIABLES",
3970
- "body": [
3971
- {
3972
- "name": "SF_TARGET_ORG",
3973
- "description": "Username or alias of your default org. Overrides the target-org configuration variable."
3974
- }
3975
- ]
3976
- },
3946
+ "requiresProject": true,
3977
3947
  "errorCodes": {
3978
3948
  "header": "ERROR CODES",
3979
3949
  "body": [
3980
3950
  {
3981
3951
  "name": "Succeeded (0)",
3982
- "description": "Test started successfully (without --wait), or test completed successfully (with --wait)."
3983
- },
3984
- {
3985
- "name": "Failed (1)",
3986
- "description": "Tests encountered execution errors (test cases with ERROR status when using --wait)."
3987
- },
3988
- {
3989
- "name": "NotFound (2)",
3990
- "description": "Test definition not found or invalid test name."
3991
- },
3992
- {
3993
- "name": "OperationFailed (4)",
3994
- "description": "Failed to start or poll test due to API or network errors."
3952
+ "description": "Sessions listed successfully (or empty list if no active sessions)."
3995
3953
  }
3996
3954
  ]
3997
3955
  },
@@ -4000,26 +3958,27 @@
4000
3958
  "lib",
4001
3959
  "commands",
4002
3960
  "agent",
4003
- "test",
4004
- "run.js"
3961
+ "preview",
3962
+ "sessions.js"
4005
3963
  ],
4006
3964
  "aliasPermutations": [],
4007
3965
  "permutations": [
4008
- "agent:test:run",
4009
- "test:agent:run",
4010
- "test:run:agent",
4011
- "agent:run:test",
4012
- "run:agent:test",
4013
- "run:test:agent"
3966
+ "agent:preview:sessions",
3967
+ "preview:agent:sessions",
3968
+ "preview:sessions:agent",
3969
+ "agent:sessions:preview",
3970
+ "sessions:agent:preview",
3971
+ "sessions:preview:agent"
4014
3972
  ]
4015
3973
  },
4016
- "agent:validate:authoring-bundle": {
3974
+ "agent:preview:start": {
4017
3975
  "aliases": [],
4018
3976
  "args": {},
4019
- "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.\n\nThis 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.\n\nThis 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.",
3977
+ "description": "This command outputs a session ID that you then use with the \"agent preview send\" command to send an utterance to the agent. Use the \"agent preview sessions\" command to list all active sessions and the \"agent preview end\" command to end a specific session.\n\nIdentify 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.\n\nWhen starting a preview session with --authoring-bundle, you must explicitly specify the execution mode using one of these flags:\n\n- --use-live-actions: Executes real Apex classes, flows, and other actions in the org. This surfaces compile and validation errors during preview.\n- --simulate-actions: Uses AI to simulate action execution without calling real implementations.\n\nPublished agents (--api-name) always use live actions. The mode flags are optional and have no effect for published agents.",
4020
3978
  "examples": [
4021
- "Validate an authoring bundle by being prompted for its API name; use your default org:\n<%= config.bin %> <%= command.id %>",
4022
- "Validate an authoring bundle with API name MyAuthoringBundle; use the org with alias \"my-dev-org\":\n<%= config.bin %> <%= command.id %> --api-name MyAuthoringBundle --target-org my-dev-org"
3979
+ "Start a programmatic agent preview session by specifying an authoring bundle; use simulated actions. Use the org with alias \"my-dev-org\":\n<%= config.bin %> <%= command.id %> --authoring-bundle My_Agent_Bundle --target-org my-dev-org --simulate-actions",
3980
+ "Similar to previous example but use live actions and the default org:\n<%= config.bin %> <%= command.id %> --authoring-bundle My_Agent_Bundle --use-live-actions",
3981
+ "Start a preview session with an activated published agent (always uses live actions):\n<%= config.bin %> <%= command.id %> --api-name My_Published_Agent"
4023
3982
  ],
4024
3983
  "flags": {
4025
3984
  "json": {
@@ -4057,7 +4016,60 @@
4057
4016
  "api-name": {
4058
4017
  "char": "n",
4059
4018
  "name": "api-name",
4060
- "summary": "API name of the authoring bundle you want to validate; if not specified, the command provides a list that you can choose from.",
4019
+ "summary": "API name of the activated published agent you want to preview.",
4020
+ "hasDynamicHelp": false,
4021
+ "multiple": false,
4022
+ "type": "option"
4023
+ },
4024
+ "authoring-bundle": {
4025
+ "name": "authoring-bundle",
4026
+ "summary": "API name of the authoring bundle metadata component that contains the agent's Agent Script file.",
4027
+ "hasDynamicHelp": false,
4028
+ "multiple": false,
4029
+ "type": "option"
4030
+ },
4031
+ "use-live-actions": {
4032
+ "exclusive": [
4033
+ "simulate-actions"
4034
+ ],
4035
+ "name": "use-live-actions",
4036
+ "summary": "Execute real actions in the org (Apex classes, flows, etc.). Required with --authoring-bundle.",
4037
+ "allowNo": false,
4038
+ "type": "boolean"
4039
+ },
4040
+ "simulate-actions": {
4041
+ "exclusive": [
4042
+ "use-live-actions"
4043
+ ],
4044
+ "name": "simulate-actions",
4045
+ "summary": "Use AI to simulate action execution instead of calling real actions. Required with --authoring-bundle.",
4046
+ "allowNo": false,
4047
+ "type": "boolean"
4048
+ },
4049
+ "context-variables": {
4050
+ "description": "Sets variables on the agent preview session, mirroring what the in-org Agentforce Builder UI does when you override variables before sending a message. Specify this flag multiple times or use comma-separated values. Two namespaces are supported, distinguished by the name shape. Names pass through to the runtime verbatim — the CLI doesn't transform them.\n\nLinked context variables use the \"$Context.\" prefix. These map to externally-provided fields that the runtime resolves (declared in the bundle's globalConfiguration.contextVariables) and are read by live actions and topic-routing expressions via $Context.Name. Example: $Context.MyLinkedVar=some-value.\n\nState variables use the bare developerName, no prefix. These seed mutable agent state declared in agentVersion.stateVariables. Example: MyStateVar=some-value.\n\nBoth namespaces can be mixed in one value. Example: --context-variables '$Context.MyLinkedVar=foo,MyStateVar=bar'.\n\nTips: (1) Quote the whole value in single quotes so $Context isn't shell-expanded. (2) Names are sent verbatim — a bare name is treated as a state variable, not a linked context variable, so live actions that bind via $Context.Name will see null. (3) Type is always Text; to send a typed variable, use --context-variables-json.",
4051
+ "name": "context-variables",
4052
+ "summary": "Session variables for the agent preview session, in the form Name=Value.",
4053
+ "delimiter": ",",
4054
+ "hasDynamicHelp": false,
4055
+ "multiple": true,
4056
+ "type": "option"
4057
+ },
4058
+ "context-variables-json": {
4059
+ "description": "Sets typed variables on the agent preview session. Use this instead of --context-variables when a variable is not Text, for example a boolean-gated route (available when @variables.myFlag == True) that needs a real Boolean, or a Number, Object, List, or Json value.\n\nThe value is a JSON array of objects, each with a \"name\", a \"type\", and an optional \"value\". The \"type\" is one of Text, Date, DateTime, Money, Ref, Boolean, Number, Object, List, or Json. The JSON type of \"value\" must match \"type\": Boolean takes a boolean, Number takes a number, the string types take a string, Object and List take an array, and Json takes an object.\n\nExample: --context-variables-json '[{\"name\":\"probeGate\",\"type\":\"Boolean\",\"value\":true},{\"name\":\"retryCount\",\"type\":\"Number\",\"value\":3}]'.\n\nYou can pass both --context-variables and --context-variables-json in the same command. When the same variable name appears in both, the --context-variables-json value wins.\n\nTip: names follow the same rules as --context-variables. Use the \"$Context.\" prefix for linked context variables, and a bare name for state variables.",
4060
+ "name": "context-variables-json",
4061
+ "summary": "Typed session variables for the agent preview session, as a JSON array.",
4062
+ "hasDynamicHelp": false,
4063
+ "multiple": false,
4064
+ "type": "option"
4065
+ },
4066
+ "agent-json": {
4067
+ "dependsOn": [
4068
+ "authoring-bundle"
4069
+ ],
4070
+ "hidden": true,
4071
+ "name": "agent-json",
4072
+ "summary": "Path to a pre-compiled AgentJSON file to use instead of compiling the Agent Script file. Intended for internal use and testing.",
4061
4073
  "hasDynamicHelp": false,
4062
4074
  "multiple": false,
4063
4075
  "type": "option"
@@ -4065,12 +4077,12 @@
4065
4077
  },
4066
4078
  "hasDynamicHelp": true,
4067
4079
  "hiddenAliases": [],
4068
- "id": "agent:validate:authoring-bundle",
4080
+ "id": "agent:preview:start",
4069
4081
  "pluginAlias": "@salesforce/plugin-agent",
4070
4082
  "pluginName": "@salesforce/plugin-agent",
4071
4083
  "pluginType": "core",
4072
4084
  "strict": true,
4073
- "summary": "Validate an authoring bundle to ensure its Agent Script file compiles successfully and can be used to publish an agent.",
4085
+ "summary": "Start a programmatic agent preview session.",
4074
4086
  "enableJsonFlag": true,
4075
4087
  "requiresProject": true,
4076
4088
  "envVariablesSection": {
@@ -4087,44 +4099,42 @@
4087
4099
  "body": [
4088
4100
  {
4089
4101
  "name": "Succeeded (0)",
4090
- "description": "Agent Script file compiled successfully without errors."
4102
+ "description": "Preview session started successfully."
4091
4103
  },
4092
4104
  {
4093
4105
  "name": "Failed (1)",
4094
- "description": "Compilation errors found in the Agent Script file."
4106
+ "description": "Agent Script compilation failed (syntax errors in the script)."
4095
4107
  },
4096
4108
  {
4097
4109
  "name": "NotFound (2)",
4098
- "description": "Validation/compilation API returned HTTP 404. The API endpoint may not be available in your org or region."
4110
+ "description": "Agent not found, or compilation API returned HTTP 404 (endpoint may not be available in your org or region)."
4099
4111
  },
4100
4112
  {
4101
4113
  "name": "ServerError (3)",
4102
- "description": "Validation/compilation API returned HTTP 500. A server error occurred during compilation."
4114
+ "description": "Compilation API returned HTTP 500 (server error during compilation)."
4115
+ },
4116
+ {
4117
+ "name": "PreviewStartFailed (4)",
4118
+ "description": "Preview session failed to start due to API or network errors."
4103
4119
  }
4104
4120
  ]
4105
4121
  },
4106
- "FLAGGABLE_PROMPTS": {
4107
- "api-name": {
4108
- "message": "API name of the authoring bundle you want to validate; if not specified, the command provides a list that you can choose from.",
4109
- "promptMessage": "API name of the authoring bundle to validate"
4110
- }
4111
- },
4112
4122
  "isESM": true,
4113
4123
  "relativePath": [
4114
4124
  "lib",
4115
4125
  "commands",
4116
4126
  "agent",
4117
- "validate",
4118
- "authoring-bundle.js"
4127
+ "preview",
4128
+ "start.js"
4119
4129
  ],
4120
4130
  "aliasPermutations": [],
4121
4131
  "permutations": [
4122
- "agent:validate:authoring-bundle",
4123
- "validate:agent:authoring-bundle",
4124
- "validate:authoring-bundle:agent",
4125
- "agent:authoring-bundle:validate",
4126
- "authoring-bundle:agent:validate",
4127
- "authoring-bundle:validate:agent"
4132
+ "agent:preview:start",
4133
+ "preview:agent:start",
4134
+ "preview:start:agent",
4135
+ "agent:start:preview",
4136
+ "start:agent:preview",
4137
+ "start:preview:agent"
4128
4138
  ]
4129
4139
  },
4130
4140
  "agent:adl:file:add": {
@@ -4465,6 +4475,141 @@
4465
4475
  "list:file:adl:agent"
4466
4476
  ]
4467
4477
  },
4478
+ "agent:mcp:asset:afscript": {
4479
+ "aliases": [],
4480
+ "args": {},
4481
+ "description": "Prints the same Agent Script blocks that Agentforce Builder writes when you add the tool to an agent: one action block for the subagent actions section and one reasoning action for the reasoning actions section, for each tool. The blocks are indented for a subagent: action blocks at 8 spaces (under `actions:`) and reasoning actions at 12 spaces (under `reasoning:` > `actions:`). Paste them as printed. With --json, the blocks are returned without indentation.\n\nSelect tools by name with --tool (with or without the `McpTool__` prefix) or by asset ID with --asset-id. You must use at least one of the two flags. Each tool must be allowlisted (active) on the MCP server; run \"agent mcp asset replace\" to allowlist a tool. The output follows the order of the flags: all --tool values first, then all --asset-id values. Duplicates are sent once.\n\nTo add the blocks to a local authoring bundle instead of printing them, use --authoring-bundle with one or more --subagent flags. The command adds each action block under the subagent's `actions:` and each reasoning action under its `reasoning:` > `actions:`, and creates a missing section. It skips an action that the subagent already has, so you can run it again safely. It does not compile the bundle; run \"agent validate authoring-bundle\" after it. Run the command from a Salesforce DX project.\n\nThe API call also assigns the MCP runtime permissions that Agentforce Builder assigns, so it is not read-only.",
4482
+ "examples": [
4483
+ "Print the Agent Script for one tool of an MCP server:\n<%= config.bin %> <%= command.id %> --target-org myOrg --mcp-server-id 0XSxx0000000001 --tool hello_world",
4484
+ "Print the Agent Script for two tools:\n<%= config.bin %> <%= command.id %> --target-org myOrg --mcp-server-id 0XSxx0000000001 --tool hello_world --tool add",
4485
+ "Select a tool by its asset ID and output as JSON:\n<%= config.bin %> <%= command.id %> --target-org myOrg --mcp-server-id 0XSxx0000000001 --asset-id 1XOxx0000000001 --json",
4486
+ "Add two tools to the \"order_status\" and \"returns\" subagents of the \"My_Agent\" authoring bundle:\n<%= config.bin %> <%= command.id %> --target-org myOrg --mcp-server-id 0XSxx0000000001 --tool hello_world --tool add --authoring-bundle My_Agent --subagent order_status --subagent returns"
4487
+ ],
4488
+ "flags": {
4489
+ "json": {
4490
+ "description": "Format output as json.",
4491
+ "helpGroup": "GLOBAL",
4492
+ "name": "json",
4493
+ "allowNo": false,
4494
+ "type": "boolean"
4495
+ },
4496
+ "flags-dir": {
4497
+ "helpGroup": "GLOBAL",
4498
+ "name": "flags-dir",
4499
+ "summary": "Import flag values from a directory.",
4500
+ "hasDynamicHelp": false,
4501
+ "multiple": false,
4502
+ "type": "option"
4503
+ },
4504
+ "target-org": {
4505
+ "char": "o",
4506
+ "name": "target-org",
4507
+ "noCacheDefault": true,
4508
+ "required": true,
4509
+ "summary": "Username or alias of the target org. Not required if the `target-org` configuration variable is already set.",
4510
+ "hasDynamicHelp": true,
4511
+ "multiple": false,
4512
+ "type": "option"
4513
+ },
4514
+ "api-version": {
4515
+ "description": "Override the api version used for api requests made by this command",
4516
+ "name": "api-version",
4517
+ "hasDynamicHelp": false,
4518
+ "multiple": false,
4519
+ "type": "option"
4520
+ },
4521
+ "mcp-server-id": {
4522
+ "char": "i",
4523
+ "name": "mcp-server-id",
4524
+ "required": true,
4525
+ "summary": "The ID of the MCP server that owns the tools.",
4526
+ "hasDynamicHelp": false,
4527
+ "multiple": false,
4528
+ "type": "option"
4529
+ },
4530
+ "tool": {
4531
+ "char": "t",
4532
+ "name": "tool",
4533
+ "summary": "Name of a tool on the server, with or without the `McpTool__` prefix. Repeat the flag for more tools.",
4534
+ "hasDynamicHelp": false,
4535
+ "multiple": true,
4536
+ "type": "option"
4537
+ },
4538
+ "asset-id": {
4539
+ "name": "asset-id",
4540
+ "summary": "Asset ID (1XO...) of a tool on the server. Repeat the flag for more tools.",
4541
+ "hasDynamicHelp": false,
4542
+ "multiple": true,
4543
+ "type": "option"
4544
+ },
4545
+ "authoring-bundle": {
4546
+ "dependsOn": [
4547
+ "subagent"
4548
+ ],
4549
+ "name": "authoring-bundle",
4550
+ "summary": "API name of a local authoring bundle to update instead of printing the blocks. Requires --subagent.",
4551
+ "hasDynamicHelp": false,
4552
+ "multiple": false,
4553
+ "type": "option"
4554
+ },
4555
+ "subagent": {
4556
+ "dependsOn": [
4557
+ "authoring-bundle"
4558
+ ],
4559
+ "name": "subagent",
4560
+ "summary": "Name of a subagent (or the start agent) in the authoring bundle to add the tools to. Repeat the flag for more subagents. Requires --authoring-bundle.",
4561
+ "hasDynamicHelp": false,
4562
+ "multiple": true,
4563
+ "type": "option"
4564
+ }
4565
+ },
4566
+ "hasDynamicHelp": true,
4567
+ "hiddenAliases": [],
4568
+ "id": "agent:mcp:asset:afscript",
4569
+ "pluginAlias": "@salesforce/plugin-agent",
4570
+ "pluginName": "@salesforce/plugin-agent",
4571
+ "pluginType": "core",
4572
+ "state": "preview",
4573
+ "strict": true,
4574
+ "summary": "Print or add the Agent Script action blocks and reasoning actions for MCP tools of a server.",
4575
+ "enableJsonFlag": true,
4576
+ "isESM": true,
4577
+ "relativePath": [
4578
+ "lib",
4579
+ "commands",
4580
+ "agent",
4581
+ "mcp",
4582
+ "asset",
4583
+ "afscript.js"
4584
+ ],
4585
+ "aliasPermutations": [],
4586
+ "permutations": [
4587
+ "agent:mcp:asset:afscript",
4588
+ "mcp:agent:asset:afscript",
4589
+ "mcp:asset:agent:afscript",
4590
+ "mcp:asset:afscript:agent",
4591
+ "agent:asset:mcp:afscript",
4592
+ "asset:agent:mcp:afscript",
4593
+ "asset:mcp:agent:afscript",
4594
+ "asset:mcp:afscript:agent",
4595
+ "agent:asset:afscript:mcp",
4596
+ "asset:agent:afscript:mcp",
4597
+ "asset:afscript:agent:mcp",
4598
+ "asset:afscript:mcp:agent",
4599
+ "agent:mcp:afscript:asset",
4600
+ "mcp:agent:afscript:asset",
4601
+ "mcp:afscript:agent:asset",
4602
+ "mcp:afscript:asset:agent",
4603
+ "agent:afscript:mcp:asset",
4604
+ "afscript:agent:mcp:asset",
4605
+ "afscript:mcp:agent:asset",
4606
+ "afscript:mcp:asset:agent",
4607
+ "agent:afscript:asset:mcp",
4608
+ "afscript:agent:asset:mcp",
4609
+ "afscript:asset:agent:mcp",
4610
+ "afscript:asset:mcp:agent"
4611
+ ]
4612
+ },
4468
4613
  "agent:mcp:asset:list": {
4469
4614
  "aliases": [],
4470
4615
  "args": {},
@@ -4683,5 +4828,5 @@
4683
4828
  ]
4684
4829
  }
4685
4830
  },
4686
- "version": "2.2.4"
4831
+ "version": "2.4.0"
4687
4832
  }