@salesforce/plugin-agent 1.44.4 → 1.45.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.
@@ -2252,16 +2252,15 @@
2252
2252
  "start:preview:agent"
2253
2253
  ]
2254
2254
  },
2255
- "agent:generate:agent-spec": {
2255
+ "agent:publish:authoring-bundle": {
2256
2256
  "aliases": [],
2257
2257
  "args": {},
2258
- "description": "An agent spec is a YAML-formatted file that contains basic information about the agent, such as its role, company description, and an AI-generated list of topics based on this information. Topics define the range of jobs your agent can handle.\n\nUse flags, such as --role and --company-description, to provide details about your company and the role that the agent plays in your company. If you prefer, you can also be prompted for the basic information; use --full-interview to be prompted for all required and optional properties. Upon command execution, the large language model (LLM) associated with your org uses the provided information to generate a list of topics for the agent. Because the LLM uses the company and role information to generate the topics, we recommend that you provide accurate, complete, and specific details so the LLM generates the best and most relevant topics. Once generated, you can edit the spec file; for example, you can remove topics that don't apply or change a topic's description.\n\nYou can also iterate the spec generation process by using the --spec flag to pass an existing agent spec file to this command, and then using the --role, --company-description, etc, flags to refine your agent properties. Iteratively improving the description of your agent allows the LLM to generate progressively better topics.\n\nYou can also specify other agent properties, such as a custom prompt template, how to ground the prompt template to add context to the agent's prompts, the tone of the prompts, and the username of a user in the org to assign to the agent.\n\nWhen your agent spec is ready, generate an authoring bundle from it by passing the spec file to the --spec flag of the \"agent generate authoring-bundle\" CLI command. An authoring bundle is a metadata type that contains an Agent Script file, which is the blueprint for an agent. (While not recommended, you can also use the agent spec file to immediately create an agent with the \"agent create\" command. We don't recommend this workflow because these types of agents don't use Agent Script, and are thus less flexible and more difficult to maintain.)",
2258
+ "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.",
2259
2259
  "examples": [
2260
- "Generate an agent spec in the default location and use flags to specify the agent properties, such as its role and your company details; use your default org:\n<%= config.bin %> <%= command.id %> --type customer --role \"Field customer complaints and manage employee schedules.\" --company-name \"Coral Cloud Resorts\" --company-description \"Provide customers with exceptional destination activities, unforgettable experiences, and reservation services.\"",
2261
- "Generate an agent spec by being prompted for the required agent properties and generate a maxiumum of 5 topics; write the generated file to the \"specs/resortManagerSpec.yaml\" file and use the org with alias \"my-org\":\n<%= config.bin %> <%= command.id %> --max-topics 5 --output-file specs/resortManagerAgent.yaml --target-org my-org",
2262
- "Be prompted for all required and optional agent properties; use your default org:\n<%= config.bin %> <%= command.id %> --full-interview",
2263
- "Specify an existing agent spec file called \"specs/resortManagerAgent.yaml\", and then overwrite it with a new version that contains newly AI-generated topics based on the updated role information passed in with the --role flag:\n<%= config.bin %> <%= command.id %> --spec specs/resortManagerAgent.yaml --output-file specs/resortManagerAgent.yaml --role \"Field customer complaints, manage employee schedules, and ensure all resort operations are running smoothly\"",
2264
- "Specify that the conversational tone of the agent is formal and to attach the \"resortmanager@myorg.com\" username to it; be prompted for the required properties and use your default org:\n<%= config.bin %> <%= command.id %> --tone formal --agent-user resortmanager@myorg.com"
2260
+ "Publish an authoring bundle by being prompted for its API name; use your default org:\n<%= config.bin %> <%= command.id %>",
2261
+ "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",
2262
+ "Publish with verbose output to see all retrieved and deployed metadata components:\n<%= config.bin %> <%= command.id %> --api-name MyAuthoringbundle --verbose",
2263
+ "Publish with concise output showing only essential information:\n<%= config.bin %> <%= command.id %> --api-name MyAuthoringbundle --concise"
2265
2264
  ],
2266
2265
  "flags": {
2267
2266
  "json": {
@@ -2296,164 +2295,96 @@
2296
2295
  "multiple": false,
2297
2296
  "type": "option"
2298
2297
  },
2299
- "type": {
2300
- "name": "type",
2301
- "summary": "Type of agent to create. Internal types are copilots used internally by your company and customer types are the agents you create for your customers.",
2302
- "hasDynamicHelp": false,
2303
- "multiple": false,
2304
- "options": [
2305
- "customer",
2306
- "internal"
2307
- ],
2308
- "type": "option"
2309
- },
2310
- "role": {
2311
- "name": "role",
2312
- "summary": "Role of the agent.",
2313
- "hasDynamicHelp": false,
2314
- "multiple": false,
2315
- "type": "option"
2316
- },
2317
- "company-name": {
2318
- "name": "company-name",
2319
- "summary": "Name of your company.",
2320
- "hasDynamicHelp": false,
2321
- "multiple": false,
2322
- "type": "option"
2323
- },
2324
- "company-description": {
2325
- "name": "company-description",
2326
- "summary": "Description of your company.",
2327
- "hasDynamicHelp": false,
2328
- "multiple": false,
2329
- "type": "option"
2330
- },
2331
- "company-website": {
2332
- "name": "company-website",
2333
- "summary": "Website URL of your company.",
2334
- "hasDynamicHelp": false,
2335
- "multiple": false,
2336
- "type": "option"
2337
- },
2338
- "max-topics": {
2339
- "name": "max-topics",
2340
- "summary": "Maximum number of topics to generate in the agent spec; default is 5.",
2341
- "hasDynamicHelp": false,
2342
- "multiple": false,
2343
- "type": "option"
2344
- },
2345
- "agent-user": {
2346
- "name": "agent-user",
2347
- "summary": "Username of a user in your org to assign to your agent; determines what your agent can access and do.",
2298
+ "api-name": {
2299
+ "char": "n",
2300
+ "name": "api-name",
2301
+ "summary": "API name of the authoring bundle you want to publish; if not specified, the command provides a list that you can choose from.",
2348
2302
  "hasDynamicHelp": false,
2349
2303
  "multiple": false,
2350
2304
  "type": "option"
2351
2305
  },
2352
- "enrich-logs": {
2353
- "name": "enrich-logs",
2354
- "summary": "Adds agent conversation data to event logs so you can view all agent session activity in one place.",
2355
- "hasDynamicHelp": false,
2356
- "multiple": false,
2357
- "options": [
2358
- "true",
2359
- "false"
2360
- ],
2361
- "type": "option"
2306
+ "skip-retrieve": {
2307
+ "name": "skip-retrieve",
2308
+ "summary": "Don't retrieve the metadata associated with the agent to your DX project.",
2309
+ "allowNo": false,
2310
+ "type": "boolean"
2362
2311
  },
2363
- "tone": {
2364
- "name": "tone",
2365
- "summary": "Conversational style of the agent, such as how it expresses your brand personality in its messages through word choice, punctuation, and sentence structure.",
2366
- "hasDynamicHelp": false,
2367
- "multiple": false,
2368
- "options": [
2369
- "formal",
2370
- "casual",
2371
- "neutral"
2312
+ "verbose": {
2313
+ "char": "v",
2314
+ "exclusive": [
2315
+ "concise"
2372
2316
  ],
2373
- "type": "option"
2374
- },
2375
- "spec": {
2376
- "name": "spec",
2377
- "summary": "Agent spec file, in YAML format, to use as input to the command.",
2378
- "hasDynamicHelp": false,
2379
- "multiple": false,
2380
- "type": "option"
2381
- },
2382
- "output-file": {
2383
- "name": "output-file",
2384
- "summary": "Path for the generated YAML agent spec file; can be an absolute or relative path.",
2385
- "default": "specs/agentSpec.yaml",
2386
- "hasDynamicHelp": false,
2387
- "multiple": false,
2388
- "type": "option"
2389
- },
2390
- "full-interview": {
2391
- "name": "full-interview",
2392
- "summary": "Prompt for both required and optional flags.",
2317
+ "name": "verbose",
2318
+ "summary": "Display detailed output showing all metadata components retrieved and deployed during the publish process.",
2393
2319
  "allowNo": false,
2394
2320
  "type": "boolean"
2395
2321
  },
2396
- "prompt-template": {
2397
- "name": "prompt-template",
2398
- "summary": "API name of a customized prompt template to use instead of the default prompt template.",
2399
- "hasDynamicHelp": false,
2400
- "multiple": false,
2401
- "type": "option"
2402
- },
2403
- "grounding-context": {
2404
- "dependsOn": [
2405
- "prompt-template"
2322
+ "concise": {
2323
+ "exclusive": [
2324
+ "verbose"
2406
2325
  ],
2407
- "name": "grounding-context",
2408
- "summary": "Context information and personalization that's added to your prompts when using a custom prompt template.",
2409
- "hasDynamicHelp": false,
2410
- "multiple": false,
2411
- "type": "option"
2412
- },
2413
- "force-overwrite": {
2414
- "name": "force-overwrite",
2415
- "summary": "Don't prompt the user to confirm that an existing spec file will be overwritten.",
2326
+ "name": "concise",
2327
+ "summary": "Display minimal output with only essential information about the publish operation.",
2416
2328
  "allowNo": false,
2417
2329
  "type": "boolean"
2418
2330
  }
2419
2331
  },
2420
2332
  "hasDynamicHelp": true,
2421
2333
  "hiddenAliases": [],
2422
- "id": "agent:generate:agent-spec",
2334
+ "id": "agent:publish:authoring-bundle",
2423
2335
  "pluginAlias": "@salesforce/plugin-agent",
2424
2336
  "pluginName": "@salesforce/plugin-agent",
2425
2337
  "pluginType": "core",
2426
2338
  "strict": true,
2427
- "summary": "Generate an agent spec, which is a YAML file that captures what an agent can do.",
2339
+ "summary": "Publish an authoring bundle to your org, which results in a new agent or a new version of an existing agent.",
2428
2340
  "enableJsonFlag": true,
2429
2341
  "requiresProject": true,
2342
+ "errorCodes": {
2343
+ "header": "ERROR CODES",
2344
+ "body": [
2345
+ {
2346
+ "name": "Succeeded (0)",
2347
+ "description": "Agent published successfully without errors."
2348
+ },
2349
+ {
2350
+ "name": "Failed (1)",
2351
+ "description": "Compilation errors found in the Agent Script file."
2352
+ }
2353
+ ]
2354
+ },
2355
+ "FLAGGABLE_PROMPTS": {
2356
+ "api-name": {
2357
+ "message": "API name of the authoring bundle you want to publish; if not specified, the command provides a list that you can choose from.",
2358
+ "promptMessage": "API name of the authoring bundle to publish"
2359
+ }
2360
+ },
2430
2361
  "isESM": true,
2431
2362
  "relativePath": [
2432
2363
  "lib",
2433
2364
  "commands",
2434
2365
  "agent",
2435
- "generate",
2436
- "agent-spec.js"
2366
+ "publish",
2367
+ "authoring-bundle.js"
2437
2368
  ],
2438
2369
  "aliasPermutations": [],
2439
2370
  "permutations": [
2440
- "agent:generate:agent-spec",
2441
- "generate:agent:agent-spec",
2442
- "generate:agent-spec:agent",
2443
- "agent:agent-spec:generate",
2444
- "agent-spec:agent:generate",
2445
- "agent-spec:generate:agent"
2371
+ "agent:publish:authoring-bundle",
2372
+ "publish:agent:authoring-bundle",
2373
+ "publish:authoring-bundle:agent",
2374
+ "agent:authoring-bundle:publish",
2375
+ "authoring-bundle:agent:publish",
2376
+ "authoring-bundle:publish:agent"
2446
2377
  ]
2447
2378
  },
2448
- "agent:generate:authoring-bundle": {
2379
+ "agent:test:create": {
2449
2380
  "aliases": [],
2450
2381
  "args": {},
2451
- "description": "Authoring bundles are metadata components that contain an agent's Agent Script file. The Agent Script file is the agent's blueprint; it fully describes what the agent can do using the Agent Script language.\n\nUse this command to generate a new authoring bundle based on an agent spec YAML file, which you create with the \"agent generate agent-spec\" command. The agent spec YAML file is a high-level description of the agent; it describes its essence rather than exactly what it can do. The resulting Agent Script file is customized to reflect what's in the agent spec file. You can also create an authoring bundle without an agent spec file by specifying the \"--no-spec\" flag; in this case, the resulting Agent Script file is just the default boilerplate.\n\nThe metadata type for authoring bundles is aiAuthoringBundle, which consist of a standard \"<bundle-api-name>.bundle-meta.xml\" metadata file and the Agent Script file (with extension \".agent\"). When you run this command, the new authoring bundle is generated in the force-app/main/default/aiAuthoringBundles/<bundle-api-name> directory. Use the --output-dir flag to generate them elsewhere.\n\nAfter you generate the initial authoring bundle, code the Agent Script file so your agent behaves exactly as you want. The Agent Script file generated by this command is just a first draft of your agent! Interactively test the agent by conversing with it using the \"agent preview\" command. Then publish the agent to your org with the \"agent publish authoring-bundle\" command.\n\nThis command requires an org because it uses it to access an LLM for generating the Agent Script file.",
2382
+ "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.",
2452
2383
  "examples": [
2453
- "Generate an authoring bundle by being prompted for all required values, such as the agent spec YAML file, the bundle name, and the API name; use your default org:\n<%= config.bin %> <%= command.id %>",
2454
- "Generate an authoring bundle without using an agent spec file; give the bundle the label \"My Authoring Bundle\" and use your default org:\n<%= config.bin %> <%= command.id %> --no-spec --name \"My Authoring Bundle\"",
2455
- "Generate an authoring bundle from the \"specs/agentSpec.yaml\" agent spec YAML file and give it the label \"My Authoring Bundle\"; use your default org:\n<%= config.bin %> <%= command.id %> --spec specs/agentSpec.yaml --name \"My Authoring Bundle\"",
2456
- "Similar to previous example, but generate the authoring bundle files in the \"other-package-dir/main/default\" package directory; use the org with alias \"my-dev-org\":\n<%= config.bin %> <%= command.id %> --spec specs/agentSpec.yaml --name \"My Authoring Bundle\" --output-dir other-package-dir/main/default --target-org my-dev-org"
2384
+ "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 %>",
2385
+ "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",
2386
+ "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",
2387
+ "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"
2457
2388
  ],
2458
2389
  "flags": {
2459
2390
  "json": {
@@ -2471,6 +2402,20 @@
2471
2402
  "multiple": false,
2472
2403
  "type": "option"
2473
2404
  },
2405
+ "api-name": {
2406
+ "name": "api-name",
2407
+ "summary": "API name of the new test; the API name must not exist in the org.",
2408
+ "hasDynamicHelp": false,
2409
+ "multiple": false,
2410
+ "type": "option"
2411
+ },
2412
+ "spec": {
2413
+ "name": "spec",
2414
+ "summary": "Path to the test spec YAML file.",
2415
+ "hasDynamicHelp": false,
2416
+ "multiple": false,
2417
+ "type": "option"
2418
+ },
2474
2419
  "target-org": {
2475
2420
  "char": "o",
2476
2421
  "name": "target-org",
@@ -2481,13 +2426,6 @@
2481
2426
  "multiple": false,
2482
2427
  "type": "option"
2483
2428
  },
2484
- "api-name": {
2485
- "name": "api-name",
2486
- "summary": "API name of the new authoring bundle; if not specified, the API name is derived from the authoring bundle name (label); the API name can't exist in the org.",
2487
- "hasDynamicHelp": false,
2488
- "multiple": false,
2489
- "type": "option"
2490
- },
2491
2429
  "api-version": {
2492
2430
  "description": "Override the api version used for api requests made by this command",
2493
2431
  "name": "api-version",
@@ -2495,77 +2433,95 @@
2495
2433
  "multiple": false,
2496
2434
  "type": "option"
2497
2435
  },
2498
- "spec": {
2499
- "char": "f",
2500
- "name": "spec",
2501
- "summary": "Path to the agent spec YAML file. If you don't specify the flag, the command provides a list that you can choose from. Use the --no-spec flag to skip using an agent spec entirely.",
2502
- "hasDynamicHelp": false,
2503
- "multiple": false,
2504
- "type": "option"
2505
- },
2506
- "no-spec": {
2507
- "name": "no-spec",
2508
- "summary": "Skip prompting for an agent spec and use the default Agent Script boilerplate in the generated authoring bundle.",
2436
+ "preview": {
2437
+ "name": "preview",
2438
+ "summary": "Preview the test metadata file without deploying to your org.",
2509
2439
  "allowNo": false,
2510
2440
  "type": "boolean"
2511
2441
  },
2512
- "output-dir": {
2513
- "char": "d",
2514
- "name": "output-dir",
2515
- "summary": "Directory where the authoring bundle files are generated.",
2516
- "hasDynamicHelp": false,
2517
- "multiple": false,
2518
- "type": "option"
2519
- },
2520
- "name": {
2521
- "char": "n",
2522
- "name": "name",
2523
- "summary": "Name (label) of the authoring bundle; if not specified, you're prompted for the name.",
2524
- "hasDynamicHelp": false,
2525
- "multiple": false,
2526
- "type": "option"
2527
- },
2528
2442
  "force-overwrite": {
2529
2443
  "name": "force-overwrite",
2530
- "summary": "Overwrite the existing authoring bundle if one with the same API name already exists locally.",
2444
+ "summary": "Don't prompt for confirmation when overwriting an existing test (based on API name) in your org.",
2531
2445
  "allowNo": false,
2532
2446
  "type": "boolean"
2447
+ },
2448
+ "test-runner": {
2449
+ "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.",
2450
+ "name": "test-runner",
2451
+ "summary": "Explicitly specify which test runner to use (agentforce-studio or testing-center).",
2452
+ "hasDynamicHelp": false,
2453
+ "multiple": false,
2454
+ "options": [
2455
+ "agentforce-studio",
2456
+ "testing-center"
2457
+ ],
2458
+ "type": "option"
2533
2459
  }
2534
2460
  },
2535
2461
  "hasDynamicHelp": true,
2536
2462
  "hiddenAliases": [],
2537
- "id": "agent:generate:authoring-bundle",
2463
+ "id": "agent:test:create",
2538
2464
  "pluginAlias": "@salesforce/plugin-agent",
2539
2465
  "pluginName": "@salesforce/plugin-agent",
2540
2466
  "pluginType": "core",
2541
2467
  "strict": true,
2542
- "summary": "Generate an authoring bundle from an existing agent spec YAML file.",
2468
+ "summary": "Create an agent test in your org using a local test spec YAML file.",
2543
2469
  "enableJsonFlag": true,
2544
- "requiresProject": true,
2470
+ "envVariablesSection": {
2471
+ "header": "ENVIRONMENT VARIABLES",
2472
+ "body": [
2473
+ {
2474
+ "name": "SF_TARGET_ORG",
2475
+ "description": "Username or alias of your default org. Overrides the target-org configuration variable."
2476
+ }
2477
+ ]
2478
+ },
2479
+ "errorCodes": {
2480
+ "header": "ERROR CODES",
2481
+ "body": [
2482
+ {
2483
+ "name": "Succeeded (0)",
2484
+ "description": "Test created and deployed successfully."
2485
+ },
2486
+ {
2487
+ "name": "Failed (1)",
2488
+ "description": "Test validation errors or metadata format issues."
2489
+ },
2490
+ {
2491
+ "name": "NotFound (2)",
2492
+ "description": "Test spec file not found or org connection failed."
2493
+ },
2494
+ {
2495
+ "name": "DeploymentFailed (4)",
2496
+ "description": "Deployment failed due to API or network errors."
2497
+ }
2498
+ ]
2499
+ },
2545
2500
  "isESM": true,
2546
2501
  "relativePath": [
2547
2502
  "lib",
2548
2503
  "commands",
2549
2504
  "agent",
2550
- "generate",
2551
- "authoring-bundle.js"
2505
+ "test",
2506
+ "create.js"
2552
2507
  ],
2553
2508
  "aliasPermutations": [],
2554
2509
  "permutations": [
2555
- "agent:generate:authoring-bundle",
2556
- "generate:agent:authoring-bundle",
2557
- "generate:authoring-bundle:agent",
2558
- "agent:authoring-bundle:generate",
2559
- "authoring-bundle:agent:generate",
2560
- "authoring-bundle:generate:agent"
2510
+ "agent:test:create",
2511
+ "test:agent:create",
2512
+ "test:create:agent",
2513
+ "agent:create:test",
2514
+ "create:agent:test",
2515
+ "create:test:agent"
2561
2516
  ]
2562
2517
  },
2563
- "agent:generate:template": {
2518
+ "agent:test:list": {
2564
2519
  "aliases": [],
2565
2520
  "args": {},
2566
- "description": "WARNING: This command doesn't work for agents that were created from an Agent Script file. In other words, you can't currently package an agent template for agents that use Agent Script.\n\nAt a high-level, agents are defined by the Bot, BotVersion, and GenAiPlannerBundle metadata types. The GenAiPlannerBundle type in turn defines the agent's topics and actions. This command uses the metadata files for these three types, located in your local DX project, to generate a BotTemplate metadata file for a specific agent (Bot). You then use the BotTemplate metadata file, along with the GenAiPlannerBundle metadata file that references the BotTemplate, to package the template in a managed package that you can share between orgs or on AppExchange.\n\nUse the --agent-file flag to specify the relative or full pathname of the Bot metadata file, such as force-app/main/default/bots/My_Awesome_Agent/My_Awesome_Agent.bot-meta.xml. A single Bot can have multiple BotVersions, so use the --agent-version flag to specify the version. The corresponding BotVersion metadata file must exist locally. For example, if you specify \"--agent-version 4\", then the file force-app/main/default/bots/My_Awesome_Agent/v4.botVersion-meta.xml must exist.\n\nThe new BotTemplate metadata file is generated in the \"botTemplates\" directory in the output directory specified with the --output-dir flag, and has the name <Agent_API_name>\\_v<Version>\\_Template.botTemplate-meta.xml, such as my-package/botTemplates/My_Awesome_Agent_v4_Template.botTemplate-meta.xml. The command displays the full pathname of the generated files when it completes.\n\nSee \"Develop and Package Agent Templates Using Scratch Orgs\" (https://developer.salesforce.com/docs/atlas.en-us.pkg2_dev.meta/pkg2_dev/dev2gp_package_agent_templates.htm) for details about the complete process, which includes using a scratch org to create and test the agent, retrieving the agent metadata to your DX project, running this command to create the agent template, and then packaging the template.",
2521
+ "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.",
2567
2522
  "examples": [
2568
- "Generate an agent template from the My_Awesome_Agent Bot metadata file in your DX project and save the BotTemplate and GenAiPlannerBundle to the specified directory; use version 1 of the agent. The agent that the template is based on is in the org with alias \"my-scratch-org\":\n<%= config.bin %> <%= command.id %> --agent-file force-app/main/default/bots/My_Awesome_Agent/My_Awesome_Agent.bot-meta.xml --agent-version 1 --output-dir my-package --source-org my-scratch-org"
2523
+ "List the agent tests in your default org:\n<%= config.bin %> <%= command.id %>",
2524
+ "List the agent tests in an org with alias \"my-org\"\"\n<%= config.bin %> <%= command.id %> --target-org my-org"
2569
2525
  ],
2570
2526
  "flags": {
2571
2527
  "json": {
@@ -2583,44 +2539,19 @@
2583
2539
  "multiple": false,
2584
2540
  "type": "option"
2585
2541
  },
2586
- "api-version": {
2587
- "description": "Override the api version used for api requests made by this command",
2588
- "name": "api-version",
2589
- "hasDynamicHelp": false,
2590
- "multiple": false,
2591
- "type": "option"
2592
- },
2593
- "source-org": {
2594
- "char": "s",
2595
- "name": "source-org",
2542
+ "target-org": {
2543
+ "char": "o",
2544
+ "name": "target-org",
2596
2545
  "noCacheDefault": true,
2597
2546
  "required": true,
2598
- "summary": "Username or alias of the namespaced scratch org that contains the agent which this template is based on.",
2547
+ "summary": "Username or alias of the target org. Not required if the `target-org` configuration variable is already set.",
2599
2548
  "hasDynamicHelp": true,
2600
2549
  "multiple": false,
2601
2550
  "type": "option"
2602
2551
  },
2603
- "agent-version": {
2604
- "name": "agent-version",
2605
- "required": true,
2606
- "summary": "Version of the agent (BotVersion).",
2607
- "hasDynamicHelp": false,
2608
- "multiple": false,
2609
- "type": "option"
2610
- },
2611
- "agent-file": {
2612
- "char": "f",
2613
- "name": "agent-file",
2614
- "required": true,
2615
- "summary": "Path to an agent (Bot) metadata file.",
2616
- "hasDynamicHelp": false,
2617
- "multiple": false,
2618
- "type": "option"
2619
- },
2620
- "output-dir": {
2621
- "char": "r",
2622
- "name": "output-dir",
2623
- "summary": "Directory where the generated BotTemplate and GenAiPlannerBundle files are saved.",
2552
+ "api-version": {
2553
+ "description": "Override the api version used for api requests made by this command",
2554
+ "name": "api-version",
2624
2555
  "hasDynamicHelp": false,
2625
2556
  "multiple": false,
2626
2557
  "type": "option"
@@ -2628,44 +2559,70 @@
2628
2559
  },
2629
2560
  "hasDynamicHelp": true,
2630
2561
  "hiddenAliases": [],
2631
- "id": "agent:generate:template",
2562
+ "id": "agent:test:list",
2632
2563
  "pluginAlias": "@salesforce/plugin-agent",
2633
2564
  "pluginName": "@salesforce/plugin-agent",
2634
2565
  "pluginType": "core",
2635
2566
  "strict": true,
2636
- "summary": "Generate an agent template from an existing agent in your DX project so you can then package the template in a second-generation managed package.",
2567
+ "summary": "List the available agent tests in your org.",
2637
2568
  "enableJsonFlag": true,
2638
- "requiresProject": true,
2569
+ "envVariablesSection": {
2570
+ "header": "ENVIRONMENT VARIABLES",
2571
+ "body": [
2572
+ {
2573
+ "name": "SF_TARGET_ORG",
2574
+ "description": "Username or alias of your default org. Overrides the target-org configuration variable."
2575
+ }
2576
+ ]
2577
+ },
2578
+ "errorCodes": {
2579
+ "header": "ERROR CODES",
2580
+ "body": [
2581
+ {
2582
+ "name": "Succeeded (0)",
2583
+ "description": "Agent tests listed successfully."
2584
+ },
2585
+ {
2586
+ "name": "Failed (4)",
2587
+ "description": "Failed to retrieve agent tests due to API or network errors."
2588
+ }
2589
+ ]
2590
+ },
2639
2591
  "isESM": true,
2640
2592
  "relativePath": [
2641
2593
  "lib",
2642
2594
  "commands",
2643
2595
  "agent",
2644
- "generate",
2645
- "template.js"
2596
+ "test",
2597
+ "list.js"
2646
2598
  ],
2647
2599
  "aliasPermutations": [],
2648
2600
  "permutations": [
2649
- "agent:generate:template",
2650
- "generate:agent:template",
2651
- "generate:template:agent",
2652
- "agent:template:generate",
2653
- "template:agent:generate",
2654
- "template:generate:agent"
2601
+ "agent:test:list",
2602
+ "test:agent:list",
2603
+ "test:list:agent",
2604
+ "agent:list:test",
2605
+ "list:agent:test",
2606
+ "list:test:agent"
2655
2607
  ]
2656
2608
  },
2657
- "agent:generate:test-spec": {
2609
+ "agent:test:results": {
2658
2610
  "aliases": [],
2659
2611
  "args": {},
2660
- "description": "The first step when using Salesforce CLI to create an agent test in your org is to use this interactive command to generate a local YAML-formatted test spec file. The test spec YAML file contains information about the agent being tested, such as its API name, and then one or more test cases. This command uses the metadata components in your DX project when prompting for information, such as the agent API name; it doesn't look in your org.\n\nTo generate a specific agent test case, this command prompts you for this information; when possible, the command provides a list of options for you to choose from:\n\n- Utterance: Natural language statement, question, or command used to test the agent.\n- Expected topic: API name of the topic you expect the agent to use when responding to the utterance.\n- Expected actions: One or more API names of the expection actions the agent takes.\n- Expected outcome: Natural language description of the outcome you expect.\n- (Optional) Custom evaluation: Test an agent's response for specific strings or numbers.\n- (Optional) Conversation history: Boilerplate for additional context you can add to the test in the form of a conversation history.\n\nYou can manually add contextVariables to test cases in the generated YAML file to inject contextual data (such as CaseId or RoutableId) into agent sessions. This is useful for testing agent behavior with different contextual information.\n\nWhen your test spec is ready, you then run the \"agent test create\" command to actually create the test in your org and synchronize the metadata with your DX project. The metadata type for an agent test is `AiEvaluationDefinition` (legacy testing-center) or `AiTestingDefinition` (Agentforce Studio / NGT), selected via --test-runner.\n\nIf you have an existing AiEvaluationDefinition or AiTestingDefinition metadata XML file in your DX project, you can generate its equivalent YAML test spec file with the --from-definition flag. The runner is inferred from the file extension; pass --test-runner to override.",
2612
+ "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.",
2661
2613
  "examples": [
2662
- "Generate an agent test spec YAML file interactively:\n<%= config.bin %> <%= command.id %>",
2663
- "Generate an Agentforce Studio (NGT) test spec YAML file interactively:\n<%= config.bin %> <%= command.id %> --test-runner agentforce-studio",
2664
- "Generate an agent test spec YAML file and specify a name for the new file; if the file exists, overwrite it without confirmation:\n<%= config.bin %> <%= command.id %> --output-file specs/Resort_Manager-new-version-testSpec.yaml --force-overwrite",
2665
- "Generate an agent test spec YAML file from an existing AiEvaluationDefinition metadata XML file in your DX project:\n<%= config.bin %> <%= command.id %> --from-definition force-app/main/default/aiEvaluationDefinitions/Resort_Manager_Tests.aiEvaluationDefinition-meta.xml",
2666
- "Generate an Agentforce Studio (NGT) test spec YAML file from an existing AiTestingDefinition metadata XML file:\n<%= config.bin %> <%= command.id %> --from-definition force-app/main/default/aiTestingDefinitions/Returns_Checkout_Tests.aiTestingDefinition-meta.xml"
2614
+ "Get the results of an agent test run in your default org using its job ID:\n<%= config.bin %> <%= command.id %> --job-id 4KBfake0000003F4AQ",
2615
+ "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",
2616
+ "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"
2667
2617
  ],
2668
2618
  "flags": {
2619
+ "json": {
2620
+ "description": "Format output as json.",
2621
+ "helpGroup": "GLOBAL",
2622
+ "name": "json",
2623
+ "allowNo": false,
2624
+ "type": "boolean"
2625
+ },
2669
2626
  "flags-dir": {
2670
2627
  "helpGroup": "GLOBAL",
2671
2628
  "name": "flags-dir",
@@ -2674,24 +2631,51 @@
2674
2631
  "multiple": false,
2675
2632
  "type": "option"
2676
2633
  },
2677
- "from-definition": {
2678
- "char": "d",
2679
- "name": "from-definition",
2680
- "summary": "Filepath to an AiEvaluationDefinition or AiTestingDefinition metadata XML file in your DX project that you want to convert to a test spec YAML file.",
2634
+ "target-org": {
2635
+ "char": "o",
2636
+ "name": "target-org",
2637
+ "noCacheDefault": true,
2638
+ "required": true,
2639
+ "summary": "Username or alias of the target org. Not required if the `target-org` configuration variable is already set.",
2640
+ "hasDynamicHelp": true,
2641
+ "multiple": false,
2642
+ "type": "option"
2643
+ },
2644
+ "api-version": {
2645
+ "description": "Override the api version used for api requests made by this command",
2646
+ "name": "api-version",
2681
2647
  "hasDynamicHelp": false,
2682
2648
  "multiple": false,
2683
2649
  "type": "option"
2684
2650
  },
2685
- "force-overwrite": {
2686
- "name": "force-overwrite",
2687
- "summary": "Don't prompt for confirmation when overwriting an existing test spec YAML file.",
2688
- "allowNo": false,
2689
- "type": "boolean"
2651
+ "job-id": {
2652
+ "char": "i",
2653
+ "name": "job-id",
2654
+ "required": true,
2655
+ "summary": "Job ID of the completed agent test run.",
2656
+ "hasDynamicHelp": false,
2657
+ "multiple": false,
2658
+ "type": "option"
2690
2659
  },
2691
- "output-file": {
2692
- "char": "f",
2693
- "name": "output-file",
2694
- "summary": "Name of the generated test spec YAML file. Default value is \"specs/<AGENT_API_NAME>-testSpec.yaml\" (legacy) or \"specs/<AGENT_API_NAME>-ngtTestSpec.yaml\" (Agentforce Studio).",
2660
+ "result-format": {
2661
+ "name": "result-format",
2662
+ "summary": "Format of the agent test run results.",
2663
+ "default": "human",
2664
+ "hasDynamicHelp": false,
2665
+ "multiple": false,
2666
+ "options": [
2667
+ "json",
2668
+ "human",
2669
+ "junit",
2670
+ "tap"
2671
+ ],
2672
+ "type": "option"
2673
+ },
2674
+ "output-dir": {
2675
+ "char": "d",
2676
+ "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.",
2677
+ "name": "output-dir",
2678
+ "summary": "Directory to write the agent test results into.",
2695
2679
  "hasDynamicHelp": false,
2696
2680
  "multiple": false,
2697
2681
  "type": "option"
@@ -2707,44 +2691,76 @@
2707
2691
  "testing-center"
2708
2692
  ],
2709
2693
  "type": "option"
2694
+ },
2695
+ "verbose": {
2696
+ "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.",
2697
+ "name": "verbose",
2698
+ "summary": "Show generated data in the test results output.",
2699
+ "allowNo": false,
2700
+ "type": "boolean"
2710
2701
  }
2711
2702
  },
2712
- "hasDynamicHelp": false,
2703
+ "hasDynamicHelp": true,
2713
2704
  "hiddenAliases": [],
2714
- "id": "agent:generate:test-spec",
2705
+ "id": "agent:test:results",
2715
2706
  "pluginAlias": "@salesforce/plugin-agent",
2716
2707
  "pluginName": "@salesforce/plugin-agent",
2717
2708
  "pluginType": "core",
2718
2709
  "strict": true,
2719
- "summary": "Generate an agent test spec, which is a YAML file that lists the test cases for testing a specific agent.",
2720
- "enableJsonFlag": false,
2710
+ "summary": "Get the results of a completed agent test run.",
2711
+ "enableJsonFlag": true,
2712
+ "envVariablesSection": {
2713
+ "header": "ENVIRONMENT VARIABLES",
2714
+ "body": [
2715
+ {
2716
+ "name": "SF_TARGET_ORG",
2717
+ "description": "Username or alias of your default org. Overrides the target-org configuration variable."
2718
+ }
2719
+ ]
2720
+ },
2721
+ "errorCodes": {
2722
+ "header": "ERROR CODES",
2723
+ "body": [
2724
+ {
2725
+ "name": "Succeeded (0)",
2726
+ "description": "Results retrieved successfully. Test results (passed/failed) are in the output."
2727
+ },
2728
+ {
2729
+ "name": "NotFound (2)",
2730
+ "description": "Job ID not found or invalid."
2731
+ },
2732
+ {
2733
+ "name": "Failed (4)",
2734
+ "description": "Failed to retrieve results due to API or network errors."
2735
+ }
2736
+ ]
2737
+ },
2721
2738
  "isESM": true,
2722
2739
  "relativePath": [
2723
2740
  "lib",
2724
2741
  "commands",
2725
2742
  "agent",
2726
- "generate",
2727
- "test-spec.js"
2728
- ],
2743
+ "test",
2744
+ "results.js"
2745
+ ],
2729
2746
  "aliasPermutations": [],
2730
2747
  "permutations": [
2731
- "agent:generate:test-spec",
2732
- "generate:agent:test-spec",
2733
- "generate:test-spec:agent",
2734
- "agent:test-spec:generate",
2735
- "test-spec:agent:generate",
2736
- "test-spec:generate:agent"
2748
+ "agent:test:results",
2749
+ "test:agent:results",
2750
+ "test:results:agent",
2751
+ "agent:results:test",
2752
+ "results:agent:test",
2753
+ "results:test:agent"
2737
2754
  ]
2738
2755
  },
2739
- "agent:publish:authoring-bundle": {
2756
+ "agent:test:resume": {
2740
2757
  "aliases": [],
2741
2758
  "args": {},
2742
- "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.",
2759
+ "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.",
2743
2760
  "examples": [
2744
- "Publish an authoring bundle by being prompted for its API name; use your default org:\n<%= config.bin %> <%= command.id %>",
2745
- "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",
2746
- "Publish with verbose output to see all retrieved and deployed metadata components:\n<%= config.bin %> <%= command.id %> --api-name MyAuthoringbundle --verbose",
2747
- "Publish with concise output showing only essential information:\n<%= config.bin %> <%= command.id %> --api-name MyAuthoringbundle --concise"
2761
+ "Resume an agent test in your default org using a job ID:\n<%= config.bin %> <%= command.id %> --job-id 4KBfake0000003F4AQ",
2762
+ "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",
2763
+ "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"
2748
2764
  ],
2749
2765
  "flags": {
2750
2766
  "json": {
@@ -2779,96 +2795,141 @@
2779
2795
  "multiple": false,
2780
2796
  "type": "option"
2781
2797
  },
2782
- "api-name": {
2783
- "char": "n",
2784
- "name": "api-name",
2785
- "summary": "API name of the authoring bundle you want to publish; if not specified, the command provides a list that you can choose from.",
2798
+ "job-id": {
2799
+ "char": "i",
2800
+ "name": "job-id",
2801
+ "summary": "Job ID of the original agent test run.",
2786
2802
  "hasDynamicHelp": false,
2787
2803
  "multiple": false,
2788
2804
  "type": "option"
2789
2805
  },
2790
- "skip-retrieve": {
2791
- "name": "skip-retrieve",
2792
- "summary": "Don't retrieve the metadata associated with the agent to your DX project.",
2806
+ "use-most-recent": {
2807
+ "char": "r",
2808
+ "name": "use-most-recent",
2809
+ "summary": "Use the job ID of the most recent agent test run.",
2793
2810
  "allowNo": false,
2794
2811
  "type": "boolean"
2795
2812
  },
2796
- "verbose": {
2797
- "char": "v",
2798
- "exclusive": [
2799
- "concise"
2813
+ "wait": {
2814
+ "char": "w",
2815
+ "name": "wait",
2816
+ "summary": "Number of minutes to wait for the command to complete and display results to the terminal window.",
2817
+ "default": "5 minutes",
2818
+ "hasDynamicHelp": true,
2819
+ "multiple": false,
2820
+ "type": "option"
2821
+ },
2822
+ "result-format": {
2823
+ "name": "result-format",
2824
+ "summary": "Format of the agent test run results.",
2825
+ "default": "human",
2826
+ "hasDynamicHelp": false,
2827
+ "multiple": false,
2828
+ "options": [
2829
+ "json",
2830
+ "human",
2831
+ "junit",
2832
+ "tap"
2800
2833
  ],
2801
- "name": "verbose",
2802
- "summary": "Display detailed output showing all metadata components retrieved and deployed during the publish process.",
2803
- "allowNo": false,
2804
- "type": "boolean"
2834
+ "type": "option"
2805
2835
  },
2806
- "concise": {
2807
- "exclusive": [
2808
- "verbose"
2836
+ "output-dir": {
2837
+ "char": "d",
2838
+ "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.",
2839
+ "name": "output-dir",
2840
+ "summary": "Directory to write the agent test results into.",
2841
+ "hasDynamicHelp": false,
2842
+ "multiple": false,
2843
+ "type": "option"
2844
+ },
2845
+ "test-runner": {
2846
+ "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.",
2847
+ "name": "test-runner",
2848
+ "summary": "Explicitly specify which test runner to use (agentforce-studio or testing-center).",
2849
+ "hasDynamicHelp": false,
2850
+ "multiple": false,
2851
+ "options": [
2852
+ "agentforce-studio",
2853
+ "testing-center"
2809
2854
  ],
2810
- "name": "concise",
2811
- "summary": "Display minimal output with only essential information about the publish operation.",
2855
+ "type": "option"
2856
+ },
2857
+ "verbose": {
2858
+ "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.",
2859
+ "name": "verbose",
2860
+ "summary": "Show generated data in the test results output.",
2812
2861
  "allowNo": false,
2813
2862
  "type": "boolean"
2814
2863
  }
2815
2864
  },
2816
2865
  "hasDynamicHelp": true,
2817
2866
  "hiddenAliases": [],
2818
- "id": "agent:publish:authoring-bundle",
2867
+ "id": "agent:test:resume",
2819
2868
  "pluginAlias": "@salesforce/plugin-agent",
2820
2869
  "pluginName": "@salesforce/plugin-agent",
2821
2870
  "pluginType": "core",
2822
2871
  "strict": true,
2823
- "summary": "Publish an authoring bundle to your org, which results in a new agent or a new version of an existing agent.",
2872
+ "summary": "Resume an agent test that you previously started in your org so you can view the test results.",
2824
2873
  "enableJsonFlag": true,
2825
- "requiresProject": true,
2874
+ "envVariablesSection": {
2875
+ "header": "ENVIRONMENT VARIABLES",
2876
+ "body": [
2877
+ {
2878
+ "name": "SF_TARGET_ORG",
2879
+ "description": "Username or alias of your default org. Overrides the target-org configuration variable."
2880
+ }
2881
+ ]
2882
+ },
2826
2883
  "errorCodes": {
2827
2884
  "header": "ERROR CODES",
2828
2885
  "body": [
2829
2886
  {
2830
2887
  "name": "Succeeded (0)",
2831
- "description": "Agent published successfully without errors."
2888
+ "description": "Test completed successfully (with test results in the output)."
2832
2889
  },
2833
2890
  {
2834
2891
  "name": "Failed (1)",
2835
- "description": "Compilation errors found in the Agent Script file."
2892
+ "description": "Tests encountered execution errors (test cases with ERROR status)."
2893
+ },
2894
+ {
2895
+ "name": "NotFound (2)",
2896
+ "description": "Job ID not found or invalid."
2897
+ },
2898
+ {
2899
+ "name": "OperationFailed (4)",
2900
+ "description": "Failed to poll test due to API or network errors."
2836
2901
  }
2837
2902
  ]
2838
2903
  },
2839
- "FLAGGABLE_PROMPTS": {
2840
- "api-name": {
2841
- "message": "API name of the authoring bundle you want to publish; if not specified, the command provides a list that you can choose from.",
2842
- "promptMessage": "API name of the authoring bundle to publish"
2843
- }
2844
- },
2845
2904
  "isESM": true,
2846
2905
  "relativePath": [
2847
2906
  "lib",
2848
2907
  "commands",
2849
2908
  "agent",
2850
- "publish",
2851
- "authoring-bundle.js"
2909
+ "test",
2910
+ "resume.js"
2852
2911
  ],
2853
2912
  "aliasPermutations": [],
2854
2913
  "permutations": [
2855
- "agent:publish:authoring-bundle",
2856
- "publish:agent:authoring-bundle",
2857
- "publish:authoring-bundle:agent",
2858
- "agent:authoring-bundle:publish",
2859
- "authoring-bundle:agent:publish",
2860
- "authoring-bundle:publish:agent"
2914
+ "agent:test:resume",
2915
+ "test:agent:resume",
2916
+ "test:resume:agent",
2917
+ "agent:resume:test",
2918
+ "resume:agent:test",
2919
+ "resume:test:agent"
2861
2920
  ]
2862
2921
  },
2863
- "agent:test:create": {
2922
+ "agent:test:run-eval": {
2864
2923
  "aliases": [],
2865
2924
  "args": {},
2866
- "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.",
2925
+ "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.",
2867
2926
  "examples": [
2868
- "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 %>",
2869
- "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",
2870
- "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",
2871
- "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"
2927
+ "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",
2928
+ "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",
2929
+ "Run tests using a JSON payload:\n<%= config.bin %> <%= command.id %> --spec specs/eval-payload.json --target-org my-org",
2930
+ "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",
2931
+ "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",
2932
+ "Pipe JSON payload from stdin (--spec flag is automatically populated from stdin):\n$ echo '{\"tests\":[...]}' | <%= config.bin %> <%= command.id %> --spec --target-org my-org"
2872
2933
  ],
2873
2934
  "flags": {
2874
2935
  "json": {
@@ -2886,20 +2947,6 @@
2886
2947
  "multiple": false,
2887
2948
  "type": "option"
2888
2949
  },
2889
- "api-name": {
2890
- "name": "api-name",
2891
- "summary": "API name of the new test; the API name must not exist in the org.",
2892
- "hasDynamicHelp": false,
2893
- "multiple": false,
2894
- "type": "option"
2895
- },
2896
- "spec": {
2897
- "name": "spec",
2898
- "summary": "Path to the test spec YAML file.",
2899
- "hasDynamicHelp": false,
2900
- "multiple": false,
2901
- "type": "option"
2902
- },
2903
2950
  "target-org": {
2904
2951
  "char": "o",
2905
2952
  "name": "target-org",
@@ -2917,39 +2964,61 @@
2917
2964
  "multiple": false,
2918
2965
  "type": "option"
2919
2966
  },
2920
- "preview": {
2921
- "name": "preview",
2922
- "summary": "Preview the test metadata file without deploying to your org.",
2923
- "allowNo": false,
2924
- "type": "boolean"
2967
+ "spec": {
2968
+ "char": "s",
2969
+ "name": "spec",
2970
+ "required": true,
2971
+ "summary": "Path to test spec file (YAML or JSON). Supports reading from stdin when piping content.",
2972
+ "hasDynamicHelp": false,
2973
+ "multiple": false,
2974
+ "type": "option"
2925
2975
  },
2926
- "force-overwrite": {
2927
- "name": "force-overwrite",
2928
- "summary": "Don't prompt for confirmation when overwriting an existing test (based on API name) in your org.",
2929
- "allowNo": false,
2930
- "type": "boolean"
2976
+ "api-name": {
2977
+ "char": "n",
2978
+ "name": "api-name",
2979
+ "summary": "Agent API name (also called DeveloperName) used to resolve agent_id and agent_version_id. Auto-inferred from the YAML spec's subjectName.",
2980
+ "hasDynamicHelp": false,
2981
+ "multiple": false,
2982
+ "type": "option"
2931
2983
  },
2932
- "test-runner": {
2933
- "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.",
2934
- "name": "test-runner",
2935
- "summary": "Explicitly specify which test runner to use (agentforce-studio or testing-center).",
2984
+ "result-format": {
2985
+ "name": "result-format",
2986
+ "summary": "Format of the agent test run results.",
2987
+ "default": "human",
2936
2988
  "hasDynamicHelp": false,
2937
2989
  "multiple": false,
2938
2990
  "options": [
2939
- "agentforce-studio",
2940
- "testing-center"
2991
+ "json",
2992
+ "human",
2993
+ "junit",
2994
+ "tap"
2941
2995
  ],
2942
2996
  "type": "option"
2997
+ },
2998
+ "batch-size": {
2999
+ "name": "batch-size",
3000
+ "summary": "Number of tests per API request (max 5).",
3001
+ "default": 5,
3002
+ "hasDynamicHelp": false,
3003
+ "multiple": false,
3004
+ "type": "option"
3005
+ },
3006
+ "no-normalize": {
3007
+ "name": "no-normalize",
3008
+ "summary": "Disable auto-normalization of field names and shorthand references.",
3009
+ "allowNo": false,
3010
+ "type": "boolean"
2943
3011
  }
2944
3012
  },
2945
3013
  "hasDynamicHelp": true,
2946
3014
  "hiddenAliases": [],
2947
- "id": "agent:test:create",
3015
+ "id": "agent:test:run-eval",
2948
3016
  "pluginAlias": "@salesforce/plugin-agent",
2949
3017
  "pluginName": "@salesforce/plugin-agent",
2950
3018
  "pluginType": "core",
3019
+ "state": "beta",
2951
3020
  "strict": true,
2952
- "summary": "Create an agent test in your org using a local test spec YAML file.",
3021
+ "summary": "Run rich evaluation tests against an Agentforce agent.",
2953
3022
  "enableJsonFlag": true,
2954
3023
  "envVariablesSection": {
2955
3024
  "header": "ENVIRONMENT VARIABLES",
@@ -2965,19 +3034,19 @@
2965
3034
  "body": [
2966
3035
  {
2967
3036
  "name": "Succeeded (0)",
2968
- "description": "Test created and deployed successfully."
3037
+ "description": "Tests completed successfully. Test results (passed/failed) are in the JSON output."
2969
3038
  },
2970
3039
  {
2971
3040
  "name": "Failed (1)",
2972
- "description": "Test validation errors or metadata format issues."
3041
+ "description": "Tests encountered execution errors (tests couldn't run properly)."
2973
3042
  },
2974
3043
  {
2975
3044
  "name": "NotFound (2)",
2976
- "description": "Test spec file not found or org connection failed."
3045
+ "description": "Agent not found, spec file not found, or invalid agent name."
2977
3046
  },
2978
3047
  {
2979
- "name": "DeploymentFailed (4)",
2980
- "description": "Deployment failed due to API or network errors."
3048
+ "name": "OperationFailed (4)",
3049
+ "description": "Failed to execute tests due to API or network errors."
2981
3050
  }
2982
3051
  ]
2983
3052
  },
@@ -2987,117 +3056,26 @@
2987
3056
  "commands",
2988
3057
  "agent",
2989
3058
  "test",
2990
- "create.js"
3059
+ "run-eval.js"
2991
3060
  ],
2992
3061
  "aliasPermutations": [],
2993
3062
  "permutations": [
2994
- "agent:test:create",
2995
- "test:agent:create",
2996
- "test:create:agent",
2997
- "agent:create:test",
2998
- "create:agent:test",
2999
- "create:test:agent"
3000
- ]
3001
- },
3002
- "agent:test:list": {
3003
- "aliases": [],
3004
- "args": {},
3005
- "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.",
3006
- "examples": [
3007
- "List the agent tests in your default org:\n<%= config.bin %> <%= command.id %>",
3008
- "List the agent tests in an org with alias \"my-org\"\"\n<%= config.bin %> <%= command.id %> --target-org my-org"
3009
- ],
3010
- "flags": {
3011
- "json": {
3012
- "description": "Format output as json.",
3013
- "helpGroup": "GLOBAL",
3014
- "name": "json",
3015
- "allowNo": false,
3016
- "type": "boolean"
3017
- },
3018
- "flags-dir": {
3019
- "helpGroup": "GLOBAL",
3020
- "name": "flags-dir",
3021
- "summary": "Import flag values from a directory.",
3022
- "hasDynamicHelp": false,
3023
- "multiple": false,
3024
- "type": "option"
3025
- },
3026
- "target-org": {
3027
- "char": "o",
3028
- "name": "target-org",
3029
- "noCacheDefault": true,
3030
- "required": true,
3031
- "summary": "Username or alias of the target org. Not required if the `target-org` configuration variable is already set.",
3032
- "hasDynamicHelp": true,
3033
- "multiple": false,
3034
- "type": "option"
3035
- },
3036
- "api-version": {
3037
- "description": "Override the api version used for api requests made by this command",
3038
- "name": "api-version",
3039
- "hasDynamicHelp": false,
3040
- "multiple": false,
3041
- "type": "option"
3042
- }
3043
- },
3044
- "hasDynamicHelp": true,
3045
- "hiddenAliases": [],
3046
- "id": "agent:test:list",
3047
- "pluginAlias": "@salesforce/plugin-agent",
3048
- "pluginName": "@salesforce/plugin-agent",
3049
- "pluginType": "core",
3050
- "strict": true,
3051
- "summary": "List the available agent tests in your org.",
3052
- "enableJsonFlag": true,
3053
- "envVariablesSection": {
3054
- "header": "ENVIRONMENT VARIABLES",
3055
- "body": [
3056
- {
3057
- "name": "SF_TARGET_ORG",
3058
- "description": "Username or alias of your default org. Overrides the target-org configuration variable."
3059
- }
3060
- ]
3061
- },
3062
- "errorCodes": {
3063
- "header": "ERROR CODES",
3064
- "body": [
3065
- {
3066
- "name": "Succeeded (0)",
3067
- "description": "Agent tests listed successfully."
3068
- },
3069
- {
3070
- "name": "Failed (4)",
3071
- "description": "Failed to retrieve agent tests due to API or network errors."
3072
- }
3073
- ]
3074
- },
3075
- "isESM": true,
3076
- "relativePath": [
3077
- "lib",
3078
- "commands",
3079
- "agent",
3080
- "test",
3081
- "list.js"
3082
- ],
3083
- "aliasPermutations": [],
3084
- "permutations": [
3085
- "agent:test:list",
3086
- "test:agent:list",
3087
- "test:list:agent",
3088
- "agent:list:test",
3089
- "list:agent:test",
3090
- "list:test:agent"
3063
+ "agent:test:run-eval",
3064
+ "test:agent:run-eval",
3065
+ "test:run-eval:agent",
3066
+ "agent:run-eval:test",
3067
+ "run-eval:agent:test",
3068
+ "run-eval:test:agent"
3091
3069
  ]
3092
3070
  },
3093
- "agent:test:results": {
3071
+ "agent:test:run": {
3094
3072
  "aliases": [],
3095
3073
  "args": {},
3096
- "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.",
3074
+ "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.",
3097
3075
  "examples": [
3098
- "Get the results of an agent test run in your default org using its job ID:\n<%= config.bin %> <%= command.id %> --job-id 4KBfake0000003F4AQ",
3099
- "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",
3100
- "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"
3076
+ "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",
3077
+ "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",
3078
+ "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"
3101
3079
  ],
3102
3080
  "flags": {
3103
3081
  "json": {
@@ -3132,15 +3110,22 @@
3132
3110
  "multiple": false,
3133
3111
  "type": "option"
3134
3112
  },
3135
- "job-id": {
3136
- "char": "i",
3137
- "name": "job-id",
3138
- "required": true,
3139
- "summary": "Job ID of the completed agent test run.",
3113
+ "api-name": {
3114
+ "char": "n",
3115
+ "name": "api-name",
3116
+ "summary": "API name of the agent test to run; corresponds to the name of the AiEvaluationDefinition metadata component that implements the agent test.",
3140
3117
  "hasDynamicHelp": false,
3141
3118
  "multiple": false,
3142
3119
  "type": "option"
3143
3120
  },
3121
+ "wait": {
3122
+ "char": "w",
3123
+ "name": "wait",
3124
+ "summary": "Number of minutes to wait for the command to complete and display results to the terminal window.",
3125
+ "hasDynamicHelp": true,
3126
+ "multiple": false,
3127
+ "type": "option"
3128
+ },
3144
3129
  "result-format": {
3145
3130
  "name": "result-format",
3146
3131
  "summary": "Format of the agent test run results.",
@@ -3186,12 +3171,12 @@
3186
3171
  },
3187
3172
  "hasDynamicHelp": true,
3188
3173
  "hiddenAliases": [],
3189
- "id": "agent:test:results",
3174
+ "id": "agent:test:run",
3190
3175
  "pluginAlias": "@salesforce/plugin-agent",
3191
3176
  "pluginName": "@salesforce/plugin-agent",
3192
3177
  "pluginType": "core",
3193
3178
  "strict": true,
3194
- "summary": "Get the results of a completed agent test run.",
3179
+ "summary": "Start an agent test in your org.",
3195
3180
  "enableJsonFlag": true,
3196
3181
  "envVariablesSection": {
3197
3182
  "header": "ENVIRONMENT VARIABLES",
@@ -3207,15 +3192,19 @@
3207
3192
  "body": [
3208
3193
  {
3209
3194
  "name": "Succeeded (0)",
3210
- "description": "Results retrieved successfully. Test results (passed/failed) are in the output."
3195
+ "description": "Test started successfully (without --wait), or test completed successfully (with --wait)."
3196
+ },
3197
+ {
3198
+ "name": "Failed (1)",
3199
+ "description": "Tests encountered execution errors (test cases with ERROR status when using --wait)."
3211
3200
  },
3212
3201
  {
3213
3202
  "name": "NotFound (2)",
3214
- "description": "Job ID not found or invalid."
3203
+ "description": "Test definition not found or invalid test name."
3215
3204
  },
3216
3205
  {
3217
- "name": "Failed (4)",
3218
- "description": "Failed to retrieve results due to API or network errors."
3206
+ "name": "OperationFailed (4)",
3207
+ "description": "Failed to start or poll test due to API or network errors."
3219
3208
  }
3220
3209
  ]
3221
3210
  },
@@ -3225,26 +3214,29 @@
3225
3214
  "commands",
3226
3215
  "agent",
3227
3216
  "test",
3228
- "results.js"
3217
+ "run.js"
3229
3218
  ],
3230
3219
  "aliasPermutations": [],
3231
3220
  "permutations": [
3232
- "agent:test:results",
3233
- "test:agent:results",
3234
- "test:results:agent",
3235
- "agent:results:test",
3236
- "results:agent:test",
3237
- "results:test:agent"
3221
+ "agent:test:run",
3222
+ "test:agent:run",
3223
+ "test:run:agent",
3224
+ "agent:run:test",
3225
+ "run:agent:test",
3226
+ "run:test:agent"
3238
3227
  ]
3239
3228
  },
3240
- "agent:test:resume": {
3229
+ "agent:trace:delete": {
3241
3230
  "aliases": [],
3242
3231
  "args": {},
3243
- "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.",
3232
+ "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).",
3244
3233
  "examples": [
3245
- "Resume an agent test in your default org using a job ID:\n<%= config.bin %> <%= command.id %> --job-id 4KBfake0000003F4AQ",
3246
- "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",
3247
- "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"
3234
+ "Delete all traces for all agents and sessions; prompt for confirmation:\n<%= config.bin %> <%= command.id %>",
3235
+ "Delete all traces for a specific agent:\n<%= config.bin %> <%= command.id %> --agent My_Agent",
3236
+ "Delete traces from a specific session:\n<%= config.bin %> <%= command.id %> --session-id <SESSION_ID>",
3237
+ "Delete traces older than 7 days:\n<%= config.bin %> <%= command.id %> --older-than 7d",
3238
+ "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",
3239
+ "Delete all traces for all agents and sessions; don't prompt for confirmation:\n<%= config.bin %> <%= command.id %> --no-prompt"
3248
3240
  ],
3249
3241
  "flags": {
3250
3242
  "json": {
@@ -3262,126 +3254,51 @@
3262
3254
  "multiple": false,
3263
3255
  "type": "option"
3264
3256
  },
3265
- "target-org": {
3266
- "char": "o",
3267
- "name": "target-org",
3268
- "noCacheDefault": true,
3269
- "required": true,
3270
- "summary": "Username or alias of the target org. Not required if the `target-org` configuration variable is already set.",
3271
- "hasDynamicHelp": true,
3272
- "multiple": false,
3273
- "type": "option"
3274
- },
3275
- "api-version": {
3276
- "description": "Override the api version used for api requests made by this command",
3277
- "name": "api-version",
3278
- "hasDynamicHelp": false,
3279
- "multiple": false,
3280
- "type": "option"
3281
- },
3282
- "job-id": {
3283
- "char": "i",
3284
- "name": "job-id",
3285
- "summary": "Job ID of the original agent test run.",
3286
- "hasDynamicHelp": false,
3287
- "multiple": false,
3288
- "type": "option"
3289
- },
3290
- "use-most-recent": {
3291
- "char": "r",
3292
- "name": "use-most-recent",
3293
- "summary": "Use the job ID of the most recent agent test run.",
3294
- "allowNo": false,
3295
- "type": "boolean"
3296
- },
3297
- "wait": {
3298
- "char": "w",
3299
- "name": "wait",
3300
- "summary": "Number of minutes to wait for the command to complete and display results to the terminal window.",
3301
- "default": "5 minutes",
3302
- "hasDynamicHelp": true,
3303
- "multiple": false,
3304
- "type": "option"
3305
- },
3306
- "result-format": {
3307
- "name": "result-format",
3308
- "summary": "Format of the agent test run results.",
3309
- "default": "human",
3257
+ "agent": {
3258
+ "char": "a",
3259
+ "name": "agent",
3260
+ "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.",
3310
3261
  "hasDynamicHelp": false,
3311
3262
  "multiple": false,
3312
- "options": [
3313
- "json",
3314
- "human",
3315
- "junit",
3316
- "tap"
3317
- ],
3318
3263
  "type": "option"
3319
3264
  },
3320
- "output-dir": {
3321
- "char": "d",
3322
- "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.",
3323
- "name": "output-dir",
3324
- "summary": "Directory to write the agent test results into.",
3265
+ "session-id": {
3266
+ "name": "session-id",
3267
+ "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.",
3325
3268
  "hasDynamicHelp": false,
3326
3269
  "multiple": false,
3327
3270
  "type": "option"
3328
3271
  },
3329
- "test-runner": {
3330
- "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.",
3331
- "name": "test-runner",
3332
- "summary": "Explicitly specify which test runner to use (agentforce-studio or testing-center).",
3272
+ "older-than": {
3273
+ "name": "older-than",
3274
+ "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.",
3333
3275
  "hasDynamicHelp": false,
3334
3276
  "multiple": false,
3335
- "options": [
3336
- "agentforce-studio",
3337
- "testing-center"
3338
- ],
3339
3277
  "type": "option"
3340
3278
  },
3341
- "verbose": {
3342
- "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.",
3343
- "name": "verbose",
3344
- "summary": "Show generated data in the test results output.",
3279
+ "no-prompt": {
3280
+ "name": "no-prompt",
3281
+ "summary": "Skip the confirmation prompt and delete immediately.",
3345
3282
  "allowNo": false,
3346
3283
  "type": "boolean"
3347
3284
  }
3348
3285
  },
3349
- "hasDynamicHelp": true,
3286
+ "hasDynamicHelp": false,
3350
3287
  "hiddenAliases": [],
3351
- "id": "agent:test:resume",
3288
+ "id": "agent:trace:delete",
3352
3289
  "pluginAlias": "@salesforce/plugin-agent",
3353
3290
  "pluginName": "@salesforce/plugin-agent",
3354
3291
  "pluginType": "core",
3355
3292
  "strict": true,
3356
- "summary": "Resume an agent test that you previously started in your org so you can view the test results.",
3293
+ "summary": "Delete trace files from an agent preview session.",
3357
3294
  "enableJsonFlag": true,
3358
- "envVariablesSection": {
3359
- "header": "ENVIRONMENT VARIABLES",
3360
- "body": [
3361
- {
3362
- "name": "SF_TARGET_ORG",
3363
- "description": "Username or alias of your default org. Overrides the target-org configuration variable."
3364
- }
3365
- ]
3366
- },
3367
- "errorCodes": {
3368
- "header": "ERROR CODES",
3295
+ "requiresProject": true,
3296
+ "errorCodes": {
3297
+ "header": "ERROR CODES",
3369
3298
  "body": [
3370
3299
  {
3371
3300
  "name": "Succeeded (0)",
3372
- "description": "Test completed successfully (with test results in the output)."
3373
- },
3374
- {
3375
- "name": "Failed (1)",
3376
- "description": "Tests encountered execution errors (test cases with ERROR status)."
3377
- },
3378
- {
3379
- "name": "NotFound (2)",
3380
- "description": "Job ID not found or invalid."
3381
- },
3382
- {
3383
- "name": "OperationFailed (4)",
3384
- "description": "Failed to poll test due to API or network errors."
3301
+ "description": "Traces deleted successfully (or no traces matched)."
3385
3302
  }
3386
3303
  ]
3387
3304
  },
@@ -3390,30 +3307,31 @@
3390
3307
  "lib",
3391
3308
  "commands",
3392
3309
  "agent",
3393
- "test",
3394
- "resume.js"
3310
+ "trace",
3311
+ "delete.js"
3395
3312
  ],
3396
3313
  "aliasPermutations": [],
3397
3314
  "permutations": [
3398
- "agent:test:resume",
3399
- "test:agent:resume",
3400
- "test:resume:agent",
3401
- "agent:resume:test",
3402
- "resume:agent:test",
3403
- "resume:test:agent"
3315
+ "agent:trace:delete",
3316
+ "trace:agent:delete",
3317
+ "trace:delete:agent",
3318
+ "agent:delete:trace",
3319
+ "delete:agent:trace",
3320
+ "delete:trace:agent"
3404
3321
  ]
3405
3322
  },
3406
- "agent:test:run-eval": {
3323
+ "agent:trace:list": {
3407
3324
  "aliases": [],
3408
3325
  "args": {},
3409
- "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.",
3326
+ "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.",
3410
3327
  "examples": [
3411
- "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",
3412
- "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",
3413
- "Run tests using a JSON payload:\n<%= config.bin %> <%= command.id %> --spec specs/eval-payload.json --target-org my-org",
3414
- "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",
3415
- "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",
3416
- "Pipe JSON payload from stdin (--spec flag is automatically populated from stdin):\n$ echo '{\"tests\":[...]}' | <%= config.bin %> <%= command.id %> --spec --target-org my-org"
3328
+ "List all trace files for all agents and sessions:\n<%= config.bin %> <%= command.id %>",
3329
+ "List all trace files for a specific agent:\n<%= config.bin %> <%= command.id %> --agent My_Agent",
3330
+ "List trace files for a specific session:\n<%= config.bin %> <%= command.id %> --session-id <SESSION_ID>",
3331
+ "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",
3332
+ "List trace files recorded on or after a specific UTC time:\n<%= config.bin %> <%= command.id %> --since 2026-04-20T14:00:00Z",
3333
+ "Filter by agent and date together:\n<%= config.bin %> <%= command.id %> --agent My_Agent --since 2026-04-20",
3334
+ "Return results as JSON:\n<%= config.bin %> <%= command.id %> --json"
3417
3335
  ],
3418
3336
  "flags": {
3419
3337
  "json": {
@@ -3431,135 +3349,180 @@
3431
3349
  "multiple": false,
3432
3350
  "type": "option"
3433
3351
  },
3434
- "target-org": {
3435
- "char": "o",
3436
- "name": "target-org",
3437
- "noCacheDefault": true,
3438
- "required": true,
3439
- "summary": "Username or alias of the target org. Not required if the `target-org` configuration variable is already set.",
3440
- "hasDynamicHelp": true,
3352
+ "session-id": {
3353
+ "name": "session-id",
3354
+ "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.",
3355
+ "hasDynamicHelp": false,
3441
3356
  "multiple": false,
3442
3357
  "type": "option"
3443
3358
  },
3444
- "api-version": {
3445
- "description": "Override the api version used for api requests made by this command",
3446
- "name": "api-version",
3359
+ "agent": {
3360
+ "char": "a",
3361
+ "name": "agent",
3362
+ "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.",
3447
3363
  "hasDynamicHelp": false,
3448
3364
  "multiple": false,
3449
3365
  "type": "option"
3450
3366
  },
3451
- "spec": {
3367
+ "since": {
3368
+ "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.",
3369
+ "name": "since",
3370
+ "summary": "Date used to filter the list of trace files; only those recorded on or after the date are listed.",
3371
+ "hasDynamicHelp": false,
3372
+ "multiple": false,
3373
+ "type": "option"
3374
+ }
3375
+ },
3376
+ "hasDynamicHelp": false,
3377
+ "hiddenAliases": [],
3378
+ "id": "agent:trace:list",
3379
+ "pluginAlias": "@salesforce/plugin-agent",
3380
+ "pluginName": "@salesforce/plugin-agent",
3381
+ "pluginType": "core",
3382
+ "strict": true,
3383
+ "summary": "List the available trace files that were recorded during all agent preview sessions.",
3384
+ "enableJsonFlag": true,
3385
+ "requiresProject": true,
3386
+ "errorCodes": {
3387
+ "header": "ERROR CODES",
3388
+ "body": [
3389
+ {
3390
+ "name": "Succeeded (0)",
3391
+ "description": "Trace files listed successfully (or empty list if none found)."
3392
+ }
3393
+ ]
3394
+ },
3395
+ "isESM": true,
3396
+ "relativePath": [
3397
+ "lib",
3398
+ "commands",
3399
+ "agent",
3400
+ "trace",
3401
+ "list.js"
3402
+ ],
3403
+ "aliasPermutations": [],
3404
+ "permutations": [
3405
+ "agent:trace:list",
3406
+ "trace:agent:list",
3407
+ "trace:list:agent",
3408
+ "agent:list:trace",
3409
+ "list:agent:trace",
3410
+ "list:trace:agent"
3411
+ ]
3412
+ },
3413
+ "agent:trace:read": {
3414
+ "aliases": [],
3415
+ "args": {},
3416
+ "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.",
3417
+ "examples": [
3418
+ "Show a session trace summary for all turns in the session with the specified ID:\n<%= config.bin %> <%= command.id %> --session-id <SESSION_ID>",
3419
+ "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",
3420
+ "Drill into action execution across all turns:\n<%= config.bin %> <%= command.id %> --session-id <SESSION_ID> --format detail --dimension actions",
3421
+ "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",
3422
+ "Show all errors across the session:\n<%= config.bin %> <%= command.id %> --session-id <SESSION_ID> --format detail --dimension errors",
3423
+ "Output raw trace JSON for custom parsing:\n<%= config.bin %> <%= command.id %> --session-id <SESSION_ID> --format raw",
3424
+ "Return results as JSON:\n<%= config.bin %> <%= command.id %> --session-id <SESSION_ID> --json"
3425
+ ],
3426
+ "flags": {
3427
+ "json": {
3428
+ "description": "Format output as json.",
3429
+ "helpGroup": "GLOBAL",
3430
+ "name": "json",
3431
+ "allowNo": false,
3432
+ "type": "boolean"
3433
+ },
3434
+ "flags-dir": {
3435
+ "helpGroup": "GLOBAL",
3436
+ "name": "flags-dir",
3437
+ "summary": "Import flag values from a directory.",
3438
+ "hasDynamicHelp": false,
3439
+ "multiple": false,
3440
+ "type": "option"
3441
+ },
3442
+ "session-id": {
3452
3443
  "char": "s",
3453
- "name": "spec",
3444
+ "name": "session-id",
3454
3445
  "required": true,
3455
- "summary": "Path to test spec file (YAML or JSON). Supports reading from stdin when piping content.",
3446
+ "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",
3456
3447
  "hasDynamicHelp": false,
3457
3448
  "multiple": false,
3458
3449
  "type": "option"
3459
3450
  },
3460
- "api-name": {
3461
- "char": "n",
3462
- "name": "api-name",
3463
- "summary": "Agent API name (also called DeveloperName) used to resolve agent_id and agent_version_id. Auto-inferred from the YAML spec's subjectName.",
3451
+ "format": {
3452
+ "char": "f",
3453
+ "name": "format",
3454
+ "summary": "Output format of the trace data; specifies the level of detail you want in the trace files.",
3455
+ "default": "summary",
3464
3456
  "hasDynamicHelp": false,
3465
3457
  "multiple": false,
3458
+ "options": [
3459
+ "summary",
3460
+ "detail",
3461
+ "raw"
3462
+ ],
3466
3463
  "type": "option"
3467
3464
  },
3468
- "result-format": {
3469
- "name": "result-format",
3470
- "summary": "Format of the agent test run results.",
3471
- "default": "human",
3465
+ "dimension": {
3466
+ "char": "d",
3467
+ "name": "dimension",
3468
+ "summary": "Dimension to drill into when using \"--format detail\"; used to filter and organize the trace data to answer a specific type of question.",
3472
3469
  "hasDynamicHelp": false,
3473
3470
  "multiple": false,
3474
3471
  "options": [
3475
- "json",
3476
- "human",
3477
- "junit",
3478
- "tap"
3472
+ "actions",
3473
+ "grounding",
3474
+ "routing",
3475
+ "errors"
3479
3476
  ],
3480
3477
  "type": "option"
3481
3478
  },
3482
- "batch-size": {
3483
- "name": "batch-size",
3484
- "summary": "Number of tests per API request (max 5).",
3485
- "default": 5,
3479
+ "turn": {
3480
+ "char": "t",
3481
+ "name": "turn",
3482
+ "summary": "Turn number for which you want trace data. A turn is a single utterance or response in a conversation, starting with 1.",
3486
3483
  "hasDynamicHelp": false,
3487
3484
  "multiple": false,
3488
3485
  "type": "option"
3489
- },
3490
- "no-normalize": {
3491
- "name": "no-normalize",
3492
- "summary": "Disable auto-normalization of field names and shorthand references.",
3493
- "allowNo": false,
3494
- "type": "boolean"
3495
3486
  }
3496
3487
  },
3497
- "hasDynamicHelp": true,
3488
+ "hasDynamicHelp": false,
3498
3489
  "hiddenAliases": [],
3499
- "id": "agent:test:run-eval",
3490
+ "id": "agent:trace:read",
3500
3491
  "pluginAlias": "@salesforce/plugin-agent",
3501
3492
  "pluginName": "@salesforce/plugin-agent",
3502
3493
  "pluginType": "core",
3503
- "state": "beta",
3504
3494
  "strict": true,
3505
- "summary": "Run rich evaluation tests against an Agentforce agent.",
3495
+ "summary": "Read trace files from an agent preview session.",
3506
3496
  "enableJsonFlag": true,
3507
- "envVariablesSection": {
3508
- "header": "ENVIRONMENT VARIABLES",
3509
- "body": [
3510
- {
3511
- "name": "SF_TARGET_ORG",
3512
- "description": "Username or alias of your default org. Overrides the target-org configuration variable."
3513
- }
3514
- ]
3515
- },
3516
- "errorCodes": {
3517
- "header": "ERROR CODES",
3518
- "body": [
3519
- {
3520
- "name": "Succeeded (0)",
3521
- "description": "Tests completed successfully. Test results (passed/failed) are in the JSON output."
3522
- },
3523
- {
3524
- "name": "Failed (1)",
3525
- "description": "Tests encountered execution errors (tests couldn't run properly)."
3526
- },
3527
- {
3528
- "name": "NotFound (2)",
3529
- "description": "Agent not found, spec file not found, or invalid agent name."
3530
- },
3531
- {
3532
- "name": "OperationFailed (4)",
3533
- "description": "Failed to execute tests due to API or network errors."
3534
- }
3535
- ]
3536
- },
3497
+ "requiresProject": true,
3537
3498
  "isESM": true,
3538
3499
  "relativePath": [
3539
3500
  "lib",
3540
3501
  "commands",
3541
3502
  "agent",
3542
- "test",
3543
- "run-eval.js"
3503
+ "trace",
3504
+ "read.js"
3544
3505
  ],
3545
3506
  "aliasPermutations": [],
3546
3507
  "permutations": [
3547
- "agent:test:run-eval",
3548
- "test:agent:run-eval",
3549
- "test:run-eval:agent",
3550
- "agent:run-eval:test",
3551
- "run-eval:agent:test",
3552
- "run-eval:test:agent"
3508
+ "agent:trace:read",
3509
+ "trace:agent:read",
3510
+ "trace:read:agent",
3511
+ "agent:read:trace",
3512
+ "read:agent:trace",
3513
+ "read:trace:agent"
3553
3514
  ]
3554
3515
  },
3555
- "agent:test:run": {
3516
+ "agent:generate:agent-spec": {
3556
3517
  "aliases": [],
3557
3518
  "args": {},
3558
- "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.",
3519
+ "description": "An agent spec is a YAML-formatted file that contains basic information about the agent, such as its role, company description, and an AI-generated list of topics based on this information. Topics define the range of jobs your agent can handle.\n\nUse flags, such as --role and --company-description, to provide details about your company and the role that the agent plays in your company. If you prefer, you can also be prompted for the basic information; use --full-interview to be prompted for all required and optional properties. Upon command execution, the large language model (LLM) associated with your org uses the provided information to generate a list of topics for the agent. Because the LLM uses the company and role information to generate the topics, we recommend that you provide accurate, complete, and specific details so the LLM generates the best and most relevant topics. Once generated, you can edit the spec file; for example, you can remove topics that don't apply or change a topic's description.\n\nYou can also iterate the spec generation process by using the --spec flag to pass an existing agent spec file to this command, and then using the --role, --company-description, etc, flags to refine your agent properties. Iteratively improving the description of your agent allows the LLM to generate progressively better topics.\n\nYou can also specify other agent properties, such as a custom prompt template, how to ground the prompt template to add context to the agent's prompts, the tone of the prompts, and the username of a user in the org to assign to the agent.\n\nWhen your agent spec is ready, generate an authoring bundle from it by passing the spec file to the --spec flag of the \"agent generate authoring-bundle\" CLI command. An authoring bundle is a metadata type that contains an Agent Script file, which is the blueprint for an agent. (While not recommended, you can also use the agent spec file to immediately create an agent with the \"agent create\" command. We don't recommend this workflow because these types of agents don't use Agent Script, and are thus less flexible and more difficult to maintain.)",
3559
3520
  "examples": [
3560
- "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",
3561
- "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",
3562
- "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"
3521
+ "Generate an agent spec in the default location and use flags to specify the agent properties, such as its role and your company details; use your default org:\n<%= config.bin %> <%= command.id %> --type customer --role \"Field customer complaints and manage employee schedules.\" --company-name \"Coral Cloud Resorts\" --company-description \"Provide customers with exceptional destination activities, unforgettable experiences, and reservation services.\"",
3522
+ "Generate an agent spec by being prompted for the required agent properties and generate a maxiumum of 5 topics; write the generated file to the \"specs/resortManagerSpec.yaml\" file and use the org with alias \"my-org\":\n<%= config.bin %> <%= command.id %> --max-topics 5 --output-file specs/resortManagerAgent.yaml --target-org my-org",
3523
+ "Be prompted for all required and optional agent properties; use your default org:\n<%= config.bin %> <%= command.id %> --full-interview",
3524
+ "Specify an existing agent spec file called \"specs/resortManagerAgent.yaml\", and then overwrite it with a new version that contains newly AI-generated topics based on the updated role information passed in with the --role flag:\n<%= config.bin %> <%= command.id %> --spec specs/resortManagerAgent.yaml --output-file specs/resortManagerAgent.yaml --role \"Field customer complaints, manage employee schedules, and ensure all resort operations are running smoothly\"",
3525
+ "Specify that the conversational tone of the agent is formal and to attach the \"resortmanager@myorg.com\" username to it; be prompted for the required properties and use your default org:\n<%= config.bin %> <%= command.id %> --tone formal --agent-user resortmanager@myorg.com"
3563
3526
  ],
3564
3527
  "flags": {
3565
3528
  "json": {
@@ -3594,133 +3557,164 @@
3594
3557
  "multiple": false,
3595
3558
  "type": "option"
3596
3559
  },
3597
- "api-name": {
3598
- "char": "n",
3599
- "name": "api-name",
3600
- "summary": "API name of the agent test to run; corresponds to the name of the AiEvaluationDefinition metadata component that implements the agent test.",
3560
+ "type": {
3561
+ "name": "type",
3562
+ "summary": "Type of agent to create. Internal types are copilots used internally by your company and customer types are the agents you create for your customers.",
3601
3563
  "hasDynamicHelp": false,
3602
3564
  "multiple": false,
3565
+ "options": [
3566
+ "customer",
3567
+ "internal"
3568
+ ],
3603
3569
  "type": "option"
3604
3570
  },
3605
- "wait": {
3606
- "char": "w",
3607
- "name": "wait",
3608
- "summary": "Number of minutes to wait for the command to complete and display results to the terminal window.",
3609
- "hasDynamicHelp": true,
3571
+ "role": {
3572
+ "name": "role",
3573
+ "summary": "Role of the agent.",
3574
+ "hasDynamicHelp": false,
3610
3575
  "multiple": false,
3611
3576
  "type": "option"
3612
3577
  },
3613
- "result-format": {
3614
- "name": "result-format",
3615
- "summary": "Format of the agent test run results.",
3616
- "default": "human",
3578
+ "company-name": {
3579
+ "name": "company-name",
3580
+ "summary": "Name of your company.",
3581
+ "hasDynamicHelp": false,
3582
+ "multiple": false,
3583
+ "type": "option"
3584
+ },
3585
+ "company-description": {
3586
+ "name": "company-description",
3587
+ "summary": "Description of your company.",
3588
+ "hasDynamicHelp": false,
3589
+ "multiple": false,
3590
+ "type": "option"
3591
+ },
3592
+ "company-website": {
3593
+ "name": "company-website",
3594
+ "summary": "Website URL of your company.",
3595
+ "hasDynamicHelp": false,
3596
+ "multiple": false,
3597
+ "type": "option"
3598
+ },
3599
+ "max-topics": {
3600
+ "name": "max-topics",
3601
+ "summary": "Maximum number of topics to generate in the agent spec; default is 5.",
3602
+ "hasDynamicHelp": false,
3603
+ "multiple": false,
3604
+ "type": "option"
3605
+ },
3606
+ "agent-user": {
3607
+ "name": "agent-user",
3608
+ "summary": "Username of a user in your org to assign to your agent; determines what your agent can access and do.",
3609
+ "hasDynamicHelp": false,
3610
+ "multiple": false,
3611
+ "type": "option"
3612
+ },
3613
+ "enrich-logs": {
3614
+ "name": "enrich-logs",
3615
+ "summary": "Adds agent conversation data to event logs so you can view all agent session activity in one place.",
3617
3616
  "hasDynamicHelp": false,
3618
3617
  "multiple": false,
3619
3618
  "options": [
3620
- "json",
3621
- "human",
3622
- "junit",
3623
- "tap"
3619
+ "true",
3620
+ "false"
3624
3621
  ],
3625
3622
  "type": "option"
3626
3623
  },
3627
- "output-dir": {
3628
- "char": "d",
3629
- "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.",
3630
- "name": "output-dir",
3631
- "summary": "Directory to write the agent test results into.",
3624
+ "tone": {
3625
+ "name": "tone",
3626
+ "summary": "Conversational style of the agent, such as how it expresses your brand personality in its messages through word choice, punctuation, and sentence structure.",
3632
3627
  "hasDynamicHelp": false,
3633
3628
  "multiple": false,
3629
+ "options": [
3630
+ "formal",
3631
+ "casual",
3632
+ "neutral"
3633
+ ],
3634
3634
  "type": "option"
3635
3635
  },
3636
- "test-runner": {
3637
- "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.",
3638
- "name": "test-runner",
3639
- "summary": "Explicitly specify which test runner to use (agentforce-studio or testing-center).",
3636
+ "spec": {
3637
+ "name": "spec",
3638
+ "summary": "Agent spec file, in YAML format, to use as input to the command.",
3640
3639
  "hasDynamicHelp": false,
3641
3640
  "multiple": false,
3642
- "options": [
3643
- "agentforce-studio",
3644
- "testing-center"
3641
+ "type": "option"
3642
+ },
3643
+ "output-file": {
3644
+ "name": "output-file",
3645
+ "summary": "Path for the generated YAML agent spec file; can be an absolute or relative path.",
3646
+ "default": "specs/agentSpec.yaml",
3647
+ "hasDynamicHelp": false,
3648
+ "multiple": false,
3649
+ "type": "option"
3650
+ },
3651
+ "full-interview": {
3652
+ "name": "full-interview",
3653
+ "summary": "Prompt for both required and optional flags.",
3654
+ "allowNo": false,
3655
+ "type": "boolean"
3656
+ },
3657
+ "prompt-template": {
3658
+ "name": "prompt-template",
3659
+ "summary": "API name of a customized prompt template to use instead of the default prompt template.",
3660
+ "hasDynamicHelp": false,
3661
+ "multiple": false,
3662
+ "type": "option"
3663
+ },
3664
+ "grounding-context": {
3665
+ "dependsOn": [
3666
+ "prompt-template"
3645
3667
  ],
3668
+ "name": "grounding-context",
3669
+ "summary": "Context information and personalization that's added to your prompts when using a custom prompt template.",
3670
+ "hasDynamicHelp": false,
3671
+ "multiple": false,
3646
3672
  "type": "option"
3647
3673
  },
3648
- "verbose": {
3649
- "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.",
3650
- "name": "verbose",
3651
- "summary": "Show generated data in the test results output.",
3674
+ "force-overwrite": {
3675
+ "name": "force-overwrite",
3676
+ "summary": "Don't prompt the user to confirm that an existing spec file will be overwritten.",
3652
3677
  "allowNo": false,
3653
3678
  "type": "boolean"
3654
3679
  }
3655
3680
  },
3656
3681
  "hasDynamicHelp": true,
3657
3682
  "hiddenAliases": [],
3658
- "id": "agent:test:run",
3683
+ "id": "agent:generate:agent-spec",
3659
3684
  "pluginAlias": "@salesforce/plugin-agent",
3660
3685
  "pluginName": "@salesforce/plugin-agent",
3661
3686
  "pluginType": "core",
3662
3687
  "strict": true,
3663
- "summary": "Start an agent test in your org.",
3688
+ "summary": "Generate an agent spec, which is a YAML file that captures what an agent can do.",
3664
3689
  "enableJsonFlag": true,
3665
- "envVariablesSection": {
3666
- "header": "ENVIRONMENT VARIABLES",
3667
- "body": [
3668
- {
3669
- "name": "SF_TARGET_ORG",
3670
- "description": "Username or alias of your default org. Overrides the target-org configuration variable."
3671
- }
3672
- ]
3673
- },
3674
- "errorCodes": {
3675
- "header": "ERROR CODES",
3676
- "body": [
3677
- {
3678
- "name": "Succeeded (0)",
3679
- "description": "Test started successfully (without --wait), or test completed successfully (with --wait)."
3680
- },
3681
- {
3682
- "name": "Failed (1)",
3683
- "description": "Tests encountered execution errors (test cases with ERROR status when using --wait)."
3684
- },
3685
- {
3686
- "name": "NotFound (2)",
3687
- "description": "Test definition not found or invalid test name."
3688
- },
3689
- {
3690
- "name": "OperationFailed (4)",
3691
- "description": "Failed to start or poll test due to API or network errors."
3692
- }
3693
- ]
3694
- },
3690
+ "requiresProject": true,
3695
3691
  "isESM": true,
3696
3692
  "relativePath": [
3697
3693
  "lib",
3698
3694
  "commands",
3699
3695
  "agent",
3700
- "test",
3701
- "run.js"
3696
+ "generate",
3697
+ "agent-spec.js"
3702
3698
  ],
3703
3699
  "aliasPermutations": [],
3704
3700
  "permutations": [
3705
- "agent:test:run",
3706
- "test:agent:run",
3707
- "test:run:agent",
3708
- "agent:run:test",
3709
- "run:agent:test",
3710
- "run:test:agent"
3701
+ "agent:generate:agent-spec",
3702
+ "generate:agent:agent-spec",
3703
+ "generate:agent-spec:agent",
3704
+ "agent:agent-spec:generate",
3705
+ "agent-spec:agent:generate",
3706
+ "agent-spec:generate:agent"
3711
3707
  ]
3712
3708
  },
3713
- "agent:trace:delete": {
3709
+ "agent:generate:authoring-bundle": {
3714
3710
  "aliases": [],
3715
3711
  "args": {},
3716
- "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).",
3712
+ "description": "Authoring bundles are metadata components that contain an agent's Agent Script file. The Agent Script file is the agent's blueprint; it fully describes what the agent can do using the Agent Script language.\n\nUse this command to generate a new authoring bundle based on an agent spec YAML file, which you create with the \"agent generate agent-spec\" command. The agent spec YAML file is a high-level description of the agent; it describes its essence rather than exactly what it can do. The resulting Agent Script file is customized to reflect what's in the agent spec file. You can also create an authoring bundle without an agent spec file by specifying the \"--no-spec\" flag; in this case, the resulting Agent Script file is just the default boilerplate.\n\nThe metadata type for authoring bundles is aiAuthoringBundle, which consist of a standard \"<bundle-api-name>.bundle-meta.xml\" metadata file and the Agent Script file (with extension \".agent\"). When you run this command, the new authoring bundle is generated in the force-app/main/default/aiAuthoringBundles/<bundle-api-name> directory. Use the --output-dir flag to generate them elsewhere.\n\nAfter you generate the initial authoring bundle, code the Agent Script file so your agent behaves exactly as you want. The Agent Script file generated by this command is just a first draft of your agent! Interactively test the agent by conversing with it using the \"agent preview\" command. Then publish the agent to your org with the \"agent publish authoring-bundle\" command.\n\nThis command requires an org because it uses it to access an LLM for generating the Agent Script file.",
3717
3713
  "examples": [
3718
- "Delete all traces for all agents and sessions; prompt for confirmation:\n<%= config.bin %> <%= command.id %>",
3719
- "Delete all traces for a specific agent:\n<%= config.bin %> <%= command.id %> --agent My_Agent",
3720
- "Delete traces from a specific session:\n<%= config.bin %> <%= command.id %> --session-id <SESSION_ID>",
3721
- "Delete traces older than 7 days:\n<%= config.bin %> <%= command.id %> --older-than 7d",
3722
- "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",
3723
- "Delete all traces for all agents and sessions; don't prompt for confirmation:\n<%= config.bin %> <%= command.id %> --no-prompt"
3714
+ "Generate an authoring bundle by being prompted for all required values, such as the agent spec YAML file, the bundle name, and the API name; use your default org:\n<%= config.bin %> <%= command.id %>",
3715
+ "Generate an authoring bundle without using an agent spec file; give the bundle the label \"My Authoring Bundle\" and use your default org:\n<%= config.bin %> <%= command.id %> --no-spec --name \"My Authoring Bundle\"",
3716
+ "Generate an authoring bundle from the \"specs/agentSpec.yaml\" agent spec YAML file and give it the label \"My Authoring Bundle\"; use your default org:\n<%= config.bin %> <%= command.id %> --spec specs/agentSpec.yaml --name \"My Authoring Bundle\"",
3717
+ "Similar to previous example, but generate the authoring bundle files in the \"other-package-dir/main/default\" package directory; use the org with alias \"my-dev-org\":\n<%= config.bin %> <%= command.id %> --spec specs/agentSpec.yaml --name \"My Authoring Bundle\" --output-dir other-package-dir/main/default --target-org my-dev-org"
3724
3718
  ],
3725
3719
  "flags": {
3726
3720
  "json": {
@@ -3730,92 +3724,109 @@
3730
3724
  "allowNo": false,
3731
3725
  "type": "boolean"
3732
3726
  },
3733
- "flags-dir": {
3734
- "helpGroup": "GLOBAL",
3735
- "name": "flags-dir",
3736
- "summary": "Import flag values from a directory.",
3727
+ "flags-dir": {
3728
+ "helpGroup": "GLOBAL",
3729
+ "name": "flags-dir",
3730
+ "summary": "Import flag values from a directory.",
3731
+ "hasDynamicHelp": false,
3732
+ "multiple": false,
3733
+ "type": "option"
3734
+ },
3735
+ "target-org": {
3736
+ "char": "o",
3737
+ "name": "target-org",
3738
+ "noCacheDefault": true,
3739
+ "required": true,
3740
+ "summary": "Username or alias of the target org. Not required if the `target-org` configuration variable is already set.",
3741
+ "hasDynamicHelp": true,
3742
+ "multiple": false,
3743
+ "type": "option"
3744
+ },
3745
+ "api-name": {
3746
+ "name": "api-name",
3747
+ "summary": "API name of the new authoring bundle; if not specified, the API name is derived from the authoring bundle name (label); the API name can't exist in the org.",
3748
+ "hasDynamicHelp": false,
3749
+ "multiple": false,
3750
+ "type": "option"
3751
+ },
3752
+ "api-version": {
3753
+ "description": "Override the api version used for api requests made by this command",
3754
+ "name": "api-version",
3737
3755
  "hasDynamicHelp": false,
3738
3756
  "multiple": false,
3739
3757
  "type": "option"
3740
3758
  },
3741
- "agent": {
3742
- "char": "a",
3743
- "name": "agent",
3744
- "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.",
3759
+ "spec": {
3760
+ "char": "f",
3761
+ "name": "spec",
3762
+ "summary": "Path to the agent spec YAML file. If you don't specify the flag, the command provides a list that you can choose from. Use the --no-spec flag to skip using an agent spec entirely.",
3745
3763
  "hasDynamicHelp": false,
3746
3764
  "multiple": false,
3747
3765
  "type": "option"
3748
3766
  },
3749
- "session-id": {
3750
- "name": "session-id",
3751
- "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.",
3767
+ "no-spec": {
3768
+ "name": "no-spec",
3769
+ "summary": "Skip prompting for an agent spec and use the default Agent Script boilerplate in the generated authoring bundle.",
3770
+ "allowNo": false,
3771
+ "type": "boolean"
3772
+ },
3773
+ "output-dir": {
3774
+ "char": "d",
3775
+ "name": "output-dir",
3776
+ "summary": "Directory where the authoring bundle files are generated.",
3752
3777
  "hasDynamicHelp": false,
3753
3778
  "multiple": false,
3754
3779
  "type": "option"
3755
3780
  },
3756
- "older-than": {
3757
- "name": "older-than",
3758
- "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.",
3781
+ "name": {
3782
+ "char": "n",
3783
+ "name": "name",
3784
+ "summary": "Name (label) of the authoring bundle; if not specified, you're prompted for the name.",
3759
3785
  "hasDynamicHelp": false,
3760
3786
  "multiple": false,
3761
3787
  "type": "option"
3762
3788
  },
3763
- "no-prompt": {
3764
- "name": "no-prompt",
3765
- "summary": "Skip the confirmation prompt and delete immediately.",
3789
+ "force-overwrite": {
3790
+ "name": "force-overwrite",
3791
+ "summary": "Overwrite the existing authoring bundle if one with the same API name already exists locally.",
3766
3792
  "allowNo": false,
3767
3793
  "type": "boolean"
3768
3794
  }
3769
3795
  },
3770
- "hasDynamicHelp": false,
3796
+ "hasDynamicHelp": true,
3771
3797
  "hiddenAliases": [],
3772
- "id": "agent:trace:delete",
3798
+ "id": "agent:generate:authoring-bundle",
3773
3799
  "pluginAlias": "@salesforce/plugin-agent",
3774
3800
  "pluginName": "@salesforce/plugin-agent",
3775
3801
  "pluginType": "core",
3776
3802
  "strict": true,
3777
- "summary": "Delete trace files from an agent preview session.",
3803
+ "summary": "Generate an authoring bundle from an existing agent spec YAML file.",
3778
3804
  "enableJsonFlag": true,
3779
3805
  "requiresProject": true,
3780
- "errorCodes": {
3781
- "header": "ERROR CODES",
3782
- "body": [
3783
- {
3784
- "name": "Succeeded (0)",
3785
- "description": "Traces deleted successfully (or no traces matched)."
3786
- }
3787
- ]
3788
- },
3789
3806
  "isESM": true,
3790
3807
  "relativePath": [
3791
3808
  "lib",
3792
3809
  "commands",
3793
3810
  "agent",
3794
- "trace",
3795
- "delete.js"
3811
+ "generate",
3812
+ "authoring-bundle.js"
3796
3813
  ],
3797
3814
  "aliasPermutations": [],
3798
3815
  "permutations": [
3799
- "agent:trace:delete",
3800
- "trace:agent:delete",
3801
- "trace:delete:agent",
3802
- "agent:delete:trace",
3803
- "delete:agent:trace",
3804
- "delete:trace:agent"
3816
+ "agent:generate:authoring-bundle",
3817
+ "generate:agent:authoring-bundle",
3818
+ "generate:authoring-bundle:agent",
3819
+ "agent:authoring-bundle:generate",
3820
+ "authoring-bundle:agent:generate",
3821
+ "authoring-bundle:generate:agent"
3805
3822
  ]
3806
3823
  },
3807
- "agent:trace:list": {
3824
+ "agent:generate:template": {
3808
3825
  "aliases": [],
3809
3826
  "args": {},
3810
- "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.",
3827
+ "description": "WARNING: This command doesn't work for agents that were created from an Agent Script file. In other words, you can't currently package an agent template for agents that use Agent Script.\n\nAt a high-level, agents are defined by the Bot, BotVersion, and GenAiPlannerBundle metadata types. The GenAiPlannerBundle type in turn defines the agent's topics and actions. This command uses the metadata files for these three types, located in your local DX project, to generate a BotTemplate metadata file for a specific agent (Bot). You then use the BotTemplate metadata file, along with the GenAiPlannerBundle metadata file that references the BotTemplate, to package the template in a managed package that you can share between orgs or on AppExchange.\n\nUse the --agent-file flag to specify the relative or full pathname of the Bot metadata file, such as force-app/main/default/bots/My_Awesome_Agent/My_Awesome_Agent.bot-meta.xml. A single Bot can have multiple BotVersions, so use the --agent-version flag to specify the version. The corresponding BotVersion metadata file must exist locally. For example, if you specify \"--agent-version 4\", then the file force-app/main/default/bots/My_Awesome_Agent/v4.botVersion-meta.xml must exist.\n\nThe new BotTemplate metadata file is generated in the \"botTemplates\" directory in the output directory specified with the --output-dir flag, and has the name <Agent_API_name>\\_v<Version>\\_Template.botTemplate-meta.xml, such as my-package/botTemplates/My_Awesome_Agent_v4_Template.botTemplate-meta.xml. The command displays the full pathname of the generated files when it completes.\n\nSee \"Develop and Package Agent Templates Using Scratch Orgs\" (https://developer.salesforce.com/docs/atlas.en-us.pkg2_dev.meta/pkg2_dev/dev2gp_package_agent_templates.htm) for details about the complete process, which includes using a scratch org to create and test the agent, retrieving the agent metadata to your DX project, running this command to create the agent template, and then packaging the template.",
3811
3828
  "examples": [
3812
- "List all trace files for all agents and sessions:\n<%= config.bin %> <%= command.id %>",
3813
- "List all trace files for a specific agent:\n<%= config.bin %> <%= command.id %> --agent My_Agent",
3814
- "List trace files for a specific session:\n<%= config.bin %> <%= command.id %> --session-id <SESSION_ID>",
3815
- "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",
3816
- "List trace files recorded on or after a specific UTC time:\n<%= config.bin %> <%= command.id %> --since 2026-04-20T14:00:00Z",
3817
- "Filter by agent and date together:\n<%= config.bin %> <%= command.id %> --agent My_Agent --since 2026-04-20",
3818
- "Return results as JSON:\n<%= config.bin %> <%= command.id %> --json"
3829
+ "Generate an agent template from the My_Awesome_Agent Bot metadata file in your DX project and save the BotTemplate and GenAiPlannerBundle to the specified directory; use version 1 of the agent. The agent that the template is based on is in the org with alias \"my-scratch-org\":\n<%= config.bin %> <%= command.id %> --agent-file force-app/main/default/bots/My_Awesome_Agent/My_Awesome_Agent.bot-meta.xml --agent-version 1 --output-dir my-package --source-org my-scratch-org"
3819
3830
  ],
3820
3831
  "flags": {
3821
3832
  "json": {
@@ -3833,88 +3844,89 @@
3833
3844
  "multiple": false,
3834
3845
  "type": "option"
3835
3846
  },
3836
- "session-id": {
3837
- "name": "session-id",
3838
- "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.",
3847
+ "api-version": {
3848
+ "description": "Override the api version used for api requests made by this command",
3849
+ "name": "api-version",
3839
3850
  "hasDynamicHelp": false,
3840
3851
  "multiple": false,
3841
3852
  "type": "option"
3842
3853
  },
3843
- "agent": {
3844
- "char": "a",
3845
- "name": "agent",
3846
- "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.",
3854
+ "source-org": {
3855
+ "char": "s",
3856
+ "name": "source-org",
3857
+ "noCacheDefault": true,
3858
+ "required": true,
3859
+ "summary": "Username or alias of the namespaced scratch org that contains the agent which this template is based on.",
3860
+ "hasDynamicHelp": true,
3861
+ "multiple": false,
3862
+ "type": "option"
3863
+ },
3864
+ "agent-version": {
3865
+ "name": "agent-version",
3866
+ "required": true,
3867
+ "summary": "Version of the agent (BotVersion).",
3847
3868
  "hasDynamicHelp": false,
3848
3869
  "multiple": false,
3849
3870
  "type": "option"
3850
3871
  },
3851
- "since": {
3852
- "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.",
3853
- "name": "since",
3854
- "summary": "Date used to filter the list of trace files; only those recorded on or after the date are listed.",
3872
+ "agent-file": {
3873
+ "char": "f",
3874
+ "name": "agent-file",
3875
+ "required": true,
3876
+ "summary": "Path to an agent (Bot) metadata file.",
3877
+ "hasDynamicHelp": false,
3878
+ "multiple": false,
3879
+ "type": "option"
3880
+ },
3881
+ "output-dir": {
3882
+ "char": "r",
3883
+ "name": "output-dir",
3884
+ "summary": "Directory where the generated BotTemplate and GenAiPlannerBundle files are saved.",
3855
3885
  "hasDynamicHelp": false,
3856
3886
  "multiple": false,
3857
3887
  "type": "option"
3858
3888
  }
3859
3889
  },
3860
- "hasDynamicHelp": false,
3890
+ "hasDynamicHelp": true,
3861
3891
  "hiddenAliases": [],
3862
- "id": "agent:trace:list",
3892
+ "id": "agent:generate:template",
3863
3893
  "pluginAlias": "@salesforce/plugin-agent",
3864
3894
  "pluginName": "@salesforce/plugin-agent",
3865
3895
  "pluginType": "core",
3866
3896
  "strict": true,
3867
- "summary": "List the available trace files that were recorded during all agent preview sessions.",
3897
+ "summary": "Generate an agent template from an existing agent in your DX project so you can then package the template in a second-generation managed package.",
3868
3898
  "enableJsonFlag": true,
3869
3899
  "requiresProject": true,
3870
- "errorCodes": {
3871
- "header": "ERROR CODES",
3872
- "body": [
3873
- {
3874
- "name": "Succeeded (0)",
3875
- "description": "Trace files listed successfully (or empty list if none found)."
3876
- }
3877
- ]
3878
- },
3879
3900
  "isESM": true,
3880
3901
  "relativePath": [
3881
3902
  "lib",
3882
3903
  "commands",
3883
3904
  "agent",
3884
- "trace",
3885
- "list.js"
3905
+ "generate",
3906
+ "template.js"
3886
3907
  ],
3887
3908
  "aliasPermutations": [],
3888
3909
  "permutations": [
3889
- "agent:trace:list",
3890
- "trace:agent:list",
3891
- "trace:list:agent",
3892
- "agent:list:trace",
3893
- "list:agent:trace",
3894
- "list:trace:agent"
3910
+ "agent:generate:template",
3911
+ "generate:agent:template",
3912
+ "generate:template:agent",
3913
+ "agent:template:generate",
3914
+ "template:agent:generate",
3915
+ "template:generate:agent"
3895
3916
  ]
3896
3917
  },
3897
- "agent:trace:read": {
3918
+ "agent:generate:test-spec": {
3898
3919
  "aliases": [],
3899
3920
  "args": {},
3900
- "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.",
3921
+ "description": "The first step when using Salesforce CLI to create an agent test in your org is to use this interactive command to generate a local YAML-formatted test spec file. The test spec YAML file contains information about the agent being tested, such as its API name, and then one or more test cases. This command uses the metadata components in your DX project when prompting for information, such as the agent API name; it doesn't look in your org.\n\nTo generate a specific agent test case, this command prompts you for this information; when possible, the command provides a list of options for you to choose from:\n\n- Utterance: Natural language statement, question, or command used to test the agent.\n- Expected topic: API name of the topic you expect the agent to use when responding to the utterance.\n- Expected actions: One or more API names of the expection actions the agent takes.\n- Expected outcome: Natural language description of the outcome you expect.\n- (Optional) Custom evaluation: Test an agent's response for specific strings or numbers.\n- (Optional) Conversation history: Boilerplate for additional context you can add to the test in the form of a conversation history.\n\nYou can manually add contextVariables to test cases in the generated YAML file to inject contextual data (such as CaseId or RoutableId) into agent sessions. This is useful for testing agent behavior with different contextual information.\n\nWhen your test spec is ready, you then run the \"agent test create\" command to actually create the test in your org and synchronize the metadata with your DX project. The metadata type for an agent test is `AiEvaluationDefinition` (legacy testing-center) or `AiTestingDefinition` (Agentforce Studio / NGT), selected via --test-runner.\n\nIf you have an existing AiEvaluationDefinition or AiTestingDefinition metadata XML file in your DX project, you can generate its equivalent YAML test spec file with the --from-definition flag. The runner is inferred from the file extension; pass --test-runner to override.",
3901
3922
  "examples": [
3902
- "Show a session trace summary for all turns in the session with the specified ID:\n<%= config.bin %> <%= command.id %> --session-id <SESSION_ID>",
3903
- "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",
3904
- "Drill into action execution across all turns:\n<%= config.bin %> <%= command.id %> --session-id <SESSION_ID> --format detail --dimension actions",
3905
- "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",
3906
- "Show all errors across the session:\n<%= config.bin %> <%= command.id %> --session-id <SESSION_ID> --format detail --dimension errors",
3907
- "Output raw trace JSON for custom parsing:\n<%= config.bin %> <%= command.id %> --session-id <SESSION_ID> --format raw",
3908
- "Return results as JSON:\n<%= config.bin %> <%= command.id %> --session-id <SESSION_ID> --json"
3923
+ "Generate an agent test spec YAML file interactively:\n<%= config.bin %> <%= command.id %>",
3924
+ "Generate an Agentforce Studio (NGT) test spec YAML file interactively:\n<%= config.bin %> <%= command.id %> --test-runner agentforce-studio",
3925
+ "Generate an agent test spec YAML file and specify a name for the new file; if the file exists, overwrite it without confirmation:\n<%= config.bin %> <%= command.id %> --output-file specs/Resort_Manager-new-version-testSpec.yaml --force-overwrite",
3926
+ "Generate an agent test spec YAML file from an existing AiEvaluationDefinition metadata XML file in your DX project:\n<%= config.bin %> <%= command.id %> --from-definition force-app/main/default/aiEvaluationDefinitions/Resort_Manager_Tests.aiEvaluationDefinition-meta.xml",
3927
+ "Generate an Agentforce Studio (NGT) test spec YAML file from an existing AiTestingDefinition metadata XML file:\n<%= config.bin %> <%= command.id %> --from-definition force-app/main/default/aiTestingDefinitions/Returns_Checkout_Tests.aiTestingDefinition-meta.xml"
3909
3928
  ],
3910
3929
  "flags": {
3911
- "json": {
3912
- "description": "Format output as json.",
3913
- "helpGroup": "GLOBAL",
3914
- "name": "json",
3915
- "allowNo": false,
3916
- "type": "boolean"
3917
- },
3918
3930
  "flags-dir": {
3919
3931
  "helpGroup": "GLOBAL",
3920
3932
  "name": "flags-dir",
@@ -3923,78 +3935,66 @@
3923
3935
  "multiple": false,
3924
3936
  "type": "option"
3925
3937
  },
3926
- "session-id": {
3927
- "char": "s",
3928
- "name": "session-id",
3929
- "required": true,
3930
- "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",
3938
+ "from-definition": {
3939
+ "char": "d",
3940
+ "name": "from-definition",
3941
+ "summary": "Filepath to an AiEvaluationDefinition or AiTestingDefinition metadata XML file in your DX project that you want to convert to a test spec YAML file.",
3931
3942
  "hasDynamicHelp": false,
3932
3943
  "multiple": false,
3933
3944
  "type": "option"
3934
3945
  },
3935
- "format": {
3946
+ "force-overwrite": {
3947
+ "name": "force-overwrite",
3948
+ "summary": "Don't prompt for confirmation when overwriting an existing test spec YAML file.",
3949
+ "allowNo": false,
3950
+ "type": "boolean"
3951
+ },
3952
+ "output-file": {
3936
3953
  "char": "f",
3937
- "name": "format",
3938
- "summary": "Output format of the trace data; specifies the level of detail you want in the trace files.",
3939
- "default": "summary",
3954
+ "name": "output-file",
3955
+ "summary": "Name of the generated test spec YAML file. Default value is \"specs/<AGENT_API_NAME>-testSpec.yaml\" (legacy) or \"specs/<AGENT_API_NAME>-ngtTestSpec.yaml\" (Agentforce Studio).",
3940
3956
  "hasDynamicHelp": false,
3941
3957
  "multiple": false,
3942
- "options": [
3943
- "summary",
3944
- "detail",
3945
- "raw"
3946
- ],
3947
3958
  "type": "option"
3948
3959
  },
3949
- "dimension": {
3950
- "char": "d",
3951
- "name": "dimension",
3952
- "summary": "Dimension to drill into when using \"--format detail\"; used to filter and organize the trace data to answer a specific type of question.",
3960
+ "test-runner": {
3961
+ "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.",
3962
+ "name": "test-runner",
3963
+ "summary": "Explicitly specify which test runner to use (agentforce-studio or testing-center).",
3953
3964
  "hasDynamicHelp": false,
3954
3965
  "multiple": false,
3955
3966
  "options": [
3956
- "actions",
3957
- "grounding",
3958
- "routing",
3959
- "errors"
3967
+ "agentforce-studio",
3968
+ "testing-center"
3960
3969
  ],
3961
3970
  "type": "option"
3962
- },
3963
- "turn": {
3964
- "char": "t",
3965
- "name": "turn",
3966
- "summary": "Turn number for which you want trace data. A turn is a single utterance or response in a conversation, starting with 1.",
3967
- "hasDynamicHelp": false,
3968
- "multiple": false,
3969
- "type": "option"
3970
3971
  }
3971
3972
  },
3972
3973
  "hasDynamicHelp": false,
3973
3974
  "hiddenAliases": [],
3974
- "id": "agent:trace:read",
3975
+ "id": "agent:generate:test-spec",
3975
3976
  "pluginAlias": "@salesforce/plugin-agent",
3976
3977
  "pluginName": "@salesforce/plugin-agent",
3977
3978
  "pluginType": "core",
3978
3979
  "strict": true,
3979
- "summary": "Read trace files from an agent preview session.",
3980
- "enableJsonFlag": true,
3981
- "requiresProject": true,
3980
+ "summary": "Generate an agent test spec, which is a YAML file that lists the test cases for testing a specific agent.",
3981
+ "enableJsonFlag": false,
3982
3982
  "isESM": true,
3983
3983
  "relativePath": [
3984
3984
  "lib",
3985
3985
  "commands",
3986
3986
  "agent",
3987
- "trace",
3988
- "read.js"
3987
+ "generate",
3988
+ "test-spec.js"
3989
3989
  ],
3990
3990
  "aliasPermutations": [],
3991
3991
  "permutations": [
3992
- "agent:trace:read",
3993
- "trace:agent:read",
3994
- "trace:read:agent",
3995
- "agent:read:trace",
3996
- "read:agent:trace",
3997
- "read:trace:agent"
3992
+ "agent:generate:test-spec",
3993
+ "generate:agent:test-spec",
3994
+ "generate:test-spec:agent",
3995
+ "agent:test-spec:generate",
3996
+ "test-spec:agent:generate",
3997
+ "test-spec:generate:agent"
3998
3998
  ]
3999
3999
  },
4000
4000
  "agent:validate:authoring-bundle": {
@@ -4667,5 +4667,5 @@
4667
4667
  ]
4668
4668
  }
4669
4669
  },
4670
- "version": "1.44.4"
4670
+ "version": "1.45.0"
4671
4671
  }