@salesforce/plugin-agent 1.36.0 → 1.37.0

package/oclif.manifest.json

@@ -1003,14 +1003,14 @@
         "authoring-bundle:publish:agent"
       ]
     },
-    "agent:preview:end": {
+    "agent:test:create": {
       "aliases": [],
       "args": {},
-      "description": "You must have previously started a programmatic agent preview session with the \"agent preview start\" command to then use this command to end it. This command also displays the local directory where the session trace files are stored.\n\nThe original \"agent preview start\" command outputs a session ID which you then use with the --session-id flag of this command to end the session. You don't have to specify the --session-id flag if an agent has only one active preview session. You must also use either the --authoring-bundle or --api-name flag to specify the API name of the authoring bundle or the published agent, respecitvely. To find either API name, navigate to your package directory in your DX project. The API name of an authoring bundle is the same as its directory name under the \"aiAuthoringBundles\" metadata directory. Similarly, the published agent's API name is the same as its directory name under the \"Bots\" metadata directory.",
+      "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. This command also retrieves the metadata component (AiEvaluationDefinition) associated with the new test to your local Salesforce DX project and displays its filename.\n\nAfter you've created the test in the org, use the \"agent test run\" command to run it.",
       "examples": [
-        "End a preview session of a published agent by specifying its session ID and API name ; use the default org:\n<%= config.bin %> <%= command.id %> --session-id <SESSION_ID> --api-name My_Published_Agent",
-        "Similar to previous example, but don't specify a session ID; you get an error if the published agent has more than one active session. Use the org with alias \"my-dev-org\":\n<%= config.bin %> <%= command.id %> --api-name My_Published_Agent --target-org my-dev-org",
-        "End a preview session of an agent using its authoring bundle API name; you get an error if the agent has more than one active session.\n<%= config.bin %> <%= command.id %> --authoring-bundle My_Local_Agent"
+        "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 %>",
+        "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",
+        "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"
       ],
       "flags": {
         "json": {
@@ -1028,6 +1028,20 @@
           "multiple": false,
           "type": "option"
         },
+        "api-name": {
+          "name": "api-name",
+          "summary": "API name of the new test; the API name must not exist in the org.",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "spec": {
+          "name": "spec",
+          "summary": "Path to the test spec YAML file.",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
         "target-org": {
           "char": "o",
           "name": "target-org",
@@ -1045,40 +1059,28 @@
           "multiple": false,
           "type": "option"
         },
-        "session-id": {
-          "name": "session-id",
-          "required": false,
-          "summary": "Session ID outputted by \"agent preview start\". Not required when the agent has exactly one active session. Run \"agent preview sessions\" to see the list of all sessions.",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
-        },
-        "api-name": {
-          "char": "n",
-          "name": "api-name",
-          "summary": "API name of the activated published agent you want to preview.",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
+        "preview": {
+          "name": "preview",
+          "summary": "Preview the test metadata file (AiEvaluationDefinition) without deploying to your org.",
+          "allowNo": false,
+          "type": "boolean"
         },
-        "authoring-bundle": {
-          "name": "authoring-bundle",
-          "summary": "API name of the authoring bundle metadata component that contains the agent's Agent Script file.",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
+        "force-overwrite": {
+          "name": "force-overwrite",
+          "summary": "Don't prompt for confirmation when overwriting an existing test (based on API name) in your org.",
+          "allowNo": false,
+          "type": "boolean"
         }
       },
       "hasDynamicHelp": true,
       "hiddenAliases": [],
-      "id": "agent:preview:end",
+      "id": "agent:test:create",
       "pluginAlias": "@salesforce/plugin-agent",
       "pluginName": "@salesforce/plugin-agent",
       "pluginType": "core",
       "strict": true,
-      "summary": "End an existing programmatic agent preview session and get trace location.",
+      "summary": "Create an agent test in your org using a local test spec YAML file.",
       "enableJsonFlag": true,
-      "requiresProject": true,
       "envVariablesSection": {
         "header": "ENVIRONMENT VARIABLES",
         "body": [
@@ -1093,19 +1095,19 @@
         "body": [
           {
             "name": "Succeeded (0)",
-            "description": "Preview session ended successfully and traces saved."
+            "description": "Test created and deployed successfully."
           },
           {
-            "name": "NotFound (2)",
-            "description": "Agent not found, or no preview session exists for this agent."
+            "name": "Failed (1)",
+            "description": "Test validation errors or metadata format issues."
           },
           {
-            "name": "PreviewEndFailed (4)",
-            "description": "Failed to end the preview session."
+            "name": "NotFound (2)",
+            "description": "Test spec file not found or org connection failed."
           },
           {
-            "name": "SessionAmbiguous (5)",
-            "description": "Multiple preview sessions found; specify --session-id to choose one."
+            "name": "DeploymentFailed (4)",
+            "description": "Deployment failed due to API or network errors."
           }
         ]
       },
@@ -1114,27 +1116,26 @@
         "lib",
         "commands",
         "agent",
-        "preview",
-        "end.js"
+        "test",
+        "create.js"
       ],
       "aliasPermutations": [],
       "permutations": [
-        "agent:preview:end",
-        "preview:agent:end",
-        "preview:end:agent",
-        "agent:end:preview",
-        "end:agent:preview",
-        "end:preview:agent"
+        "agent:test:create",
+        "test:agent:create",
+        "test:create:agent",
+        "agent:create:test",
+        "create:agent:test",
+        "create:test:agent"
       ]
     },
-    "agent:preview:send": {
+    "agent:test:list": {
       "aliases": [],
       "args": {},
-      "description": "You must have previously started a programmatic agent preview session with the \"agent preview start\" command to then use this command to send the agent a message (utterance). This command then displays the agent's response.\n\nThe original \"agent preview start\" command outputs a session ID which you then use with the --session-id flag of this command to send a message. You don't have to specify the --session-id flag if an agent has only one active preview session. You must also use either the --authoring-bundle or --api-name flag to specify the API name of the authoring bundle or the published agent, respecitvely. To find either API name, navigate to your package directory in your DX project. The API name of an authoring bundle is the same as its directory name under the \"aiAuthoringBundles\" metadata directory. Similarly, the published agent's API name is the same as its directory name under the \"Bots\" metadata directory.",
+      "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.",
       "examples": [
-        "Send a message to an activated published agent using its API name and session ID; use the default org:\n<%= config.bin %> <%= command.id %> --utterance \"What can you help me with?\" --api-name My_Published_Agent --session-id <SESSION_ID>",
-        "Similar to previous example, but don't specify a session ID; you get an error if the agent has more than one active session. Use the org with alias \"my-dev-org\":\n<%= config.bin %> <%= command.id %> --utterance \"What can you help me with?\" --api-name My_Published_Agent --target-org my-dev-org",
-        "Send a message to an agent using its authoring bundle API name; you get an error if the agent has more than one active session:\n<%= config.bin %> <%= command.id %> --utterance \"what can you help me with?\" --authoring-bundle My_Local_Agent"
+        "List the agent tests in your default org:\n<%= config.bin %> <%= command.id %>",
+        "List the agent tests in an org with alias \"my-org\"\"\n<%= config.bin %> <%= command.id %> --target-org my-org"
       ],
       "flags": {
         "json": {
@@ -1168,50 +1169,17 @@
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
-        },
-        "session-id": {
-          "name": "session-id",
-          "required": false,
-          "summary": "Session ID outputted by \"agent preview start\". Not required when the agent has exactly one active session. Run \"agent preview sessions\" to see list of all sessions.",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
-        },
-        "utterance": {
-          "char": "u",
-          "name": "utterance",
-          "required": true,
-          "summary": "Utterance to send to the agent, enclosed in double quotes.",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
-        },
-        "api-name": {
-          "char": "n",
-          "name": "api-name",
-          "summary": "API name of the activated published agent you want to preview.",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
-        },
-        "authoring-bundle": {
-          "name": "authoring-bundle",
-          "summary": "API name of the authoring bundle metadata component that contains the agent's Agent Script file.",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
         }
       },
       "hasDynamicHelp": true,
       "hiddenAliases": [],
-      "id": "agent:preview:send",
+      "id": "agent:test:list",
       "pluginAlias": "@salesforce/plugin-agent",
       "pluginName": "@salesforce/plugin-agent",
       "pluginType": "core",
       "strict": true,
-      "summary": "Send a message to an existing agent preview session.",
+      "summary": "List the available agent tests in your org.",
       "enableJsonFlag": true,
-      "requiresProject": true,
       "envVariablesSection": {
         "header": "ENVIRONMENT VARIABLES",
         "body": [
@@ -1226,80 +1194,11 @@
         "body": [
           {
             "name": "Succeeded (0)",
-            "description": "Message sent successfully and agent response received."
-          },
-          {
-            "name": "NotFound (2)",
-            "description": "Agent not found, or no preview session exists for this agent."
-          },
-          {
-            "name": "PreviewSendFailed (4)",
-            "description": "Failed to send message or receive response from the preview session."
+            "description": "Agent tests listed successfully."
           },
           {
-            "name": "SessionAmbiguous (5)",
-            "description": "Multiple preview sessions found; specify --session-id to choose one."
-          }
-        ]
-      },
-      "isESM": true,
-      "relativePath": [
-        "lib",
-        "commands",
-        "agent",
-        "preview",
-        "send.js"
-      ],
-      "aliasPermutations": [],
-      "permutations": [
-        "agent:preview:send",
-        "preview:agent:send",
-        "preview:send:agent",
-        "agent:send:preview",
-        "send:agent:preview",
-        "send:preview:agent"
-      ]
-    },
-    "agent:preview:sessions": {
-      "aliases": [],
-      "args": {},
-      "description": "This command lists the agent preview sessions that were started with the \"agent preview start\" command and are still in the local cache. Use this command to discover specific session IDs that you can pass to the \"agent preview send\" or \"agent preview end\" commands with the --session-id flag.\n\nProgrammatic agent preview sessions can be started for both published activated agents and by using an agent's local authoring bundle, which contains its Agent Script file. In this command's output table, the Agent column contains either the API name of the authoring bundle or the published agent, whichever was used when starting the session. In the table, if the same API name has multiple rows with different session IDs, then it means that you previously started multiple preview sessions with the associated agent.",
-      "examples": [
-        "List all cached agent preview sessions:\n<%= config.bin %> <%= command.id %>"
-      ],
-      "flags": {
-        "json": {
-          "description": "Format output as json.",
-          "helpGroup": "GLOBAL",
-          "name": "json",
-          "allowNo": false,
-          "type": "boolean"
-        },
-        "flags-dir": {
-          "helpGroup": "GLOBAL",
-          "name": "flags-dir",
-          "summary": "Import flag values from a directory.",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
-        }
-      },
-      "hasDynamicHelp": false,
-      "hiddenAliases": [],
-      "id": "agent:preview:sessions",
-      "pluginAlias": "@salesforce/plugin-agent",
-      "pluginName": "@salesforce/plugin-agent",
-      "pluginType": "core",
-      "strict": true,
-      "summary": "List all known programmatic agent preview sessions.",
-      "enableJsonFlag": true,
-      "requiresProject": true,
-      "errorCodes": {
-        "header": "ERROR CODES",
-        "body": [
-          {
-            "name": "Succeeded (0)",
-            "description": "Sessions listed successfully (or empty list if no active sessions)."
+            "name": "Failed (4)",
+            "description": "Failed to retrieve agent tests due to API or network errors."
           }
         ]
       },
@@ -1308,27 +1207,27 @@
         "lib",
         "commands",
         "agent",
-        "preview",
-        "sessions.js"
+        "test",
+        "list.js"
       ],
       "aliasPermutations": [],
       "permutations": [
-        "agent:preview:sessions",
-        "preview:agent:sessions",
-        "preview:sessions:agent",
-        "agent:sessions:preview",
-        "sessions:agent:preview",
-        "sessions:preview:agent"
+        "agent:test:list",
+        "test:agent:list",
+        "test:list:agent",
+        "agent:list:test",
+        "list:agent:test",
+        "list:test:agent"
       ]
     },
-    "agent:preview:start": {
+    "agent:test:results": {
       "aliases": [],
       "args": {},
-      "description": "This command outputs a session ID that you then use with the \"agent preview send\" command to send an utterance to the agent. Use the \"agent preview sessions\" command to list all active sessions and the \"agent preview end\" command to end a specific session.\n\nIdentify the agent you want to start previewing with either the --authoring-bundle flag to specify a local authoring bundle's API name or --api-name to specify an activated published agent's API name. To find either API name, navigate to your package directory in your DX project. The API name of an authoring bundle is the same as its directory name under the \"aiAuthoringBundles\" metadata directory. Similarly, the published agent's API name is the same as its directory name under the \"Bots\" metadata directory.\n\nWhen starting a preview session with --authoring-bundle, you must explicitly specify the execution mode using one of these flags:\n\n- --use-live-actions: Executes real Apex classes, flows, and other actions in the org. This surfaces compile and validation errors during preview.\n- --simulate-actions: Uses AI to simulate action execution without calling real implementations.\n\nPublished agents (--api-name) always use live actions. The mode flags are optional and have no effect for published agents.",
+      "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.",
       "examples": [
-        "Start a programmatic agent preview session by specifying an authoring bundle; use simulated actions. Use the org with alias \"my-dev-org\":\n<%= config.bin %> <%= command.id %> --authoring-bundle My_Agent_Bundle --target-org my-dev-org --simulate-actions",
-        "Similar to previous example but use live actions and the default org:\n<%= config.bin %> <%= command.id %> --authoring-bundle My_Agent_Bundle --use-live-actions",
-        "Start a preview session with an activated published agent (always uses live actions):\n<%= config.bin %> <%= command.id %> --api-name My_Published_Agent"
+        "Get the results of an agent test run in your default org using its job ID:\n<%= config.bin %> <%= command.id %> --job-id 4KBfake0000003F4AQ",
+        "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",
+        "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"
       ],
       "flags": {
         "json": {
@@ -1363,61 +1262,67 @@
           "multiple": false,
           "type": "option"
         },
-        "api-name": {
-          "char": "n",
-          "name": "api-name",
-          "summary": "API name of the activated published agent you want to preview.",
+        "job-id": {
+          "char": "i",
+          "name": "job-id",
+          "required": true,
+          "summary": "Job ID of the completed agent test run.",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
         },
-        "authoring-bundle": {
-          "name": "authoring-bundle",
-          "summary": "API name of the authoring bundle metadata component that contains the agent's Agent Script file.",
+        "result-format": {
+          "name": "result-format",
+          "summary": "Format of the agent test run results.",
+          "default": "human",
           "hasDynamicHelp": false,
           "multiple": false,
-          "type": "option"
-        },
-        "use-live-actions": {
-          "exclusive": [
-            "simulate-actions"
+          "options": [
+            "json",
+            "human",
+            "junit",
+            "tap"
           ],
-          "name": "use-live-actions",
-          "summary": "Execute real actions in the org (Apex classes, flows, etc.). Required with --authoring-bundle.",
-          "allowNo": false,
-          "type": "boolean"
+          "type": "option"
         },
-        "simulate-actions": {
-          "exclusive": [
-            "use-live-actions"
-          ],
-          "name": "simulate-actions",
-          "summary": "Use AI to simulate action execution instead of calling real actions. Required with --authoring-bundle.",
-          "allowNo": false,
-          "type": "boolean"
+        "output-dir": {
+          "char": "d",
+          "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.",
+          "name": "output-dir",
+          "summary": "Directory to write the agent test results into.",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
         },
-        "agent-json": {
-          "dependsOn": [
-            "authoring-bundle"
-          ],
-          "hidden": true,
-          "name": "agent-json",
-          "summary": "Path to a pre-compiled AgentJSON file to use instead of compiling the Agent Script file. Intended for internal use and testing.",
+        "test-runner": {
+          "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.",
+          "name": "test-runner",
+          "summary": "Explicitly specify which test runner to use (agentforce-studio or testing-center).",
           "hasDynamicHelp": false,
           "multiple": false,
+          "options": [
+            "agentforce-studio",
+            "testing-center"
+          ],
           "type": "option"
+        },
+        "verbose": {
+          "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.",
+          "name": "verbose",
+          "summary": "Show generated data in the test results output.",
+          "allowNo": false,
+          "type": "boolean"
         }
       },
       "hasDynamicHelp": true,
       "hiddenAliases": [],
-      "id": "agent:preview:start",
+      "id": "agent:test:results",
       "pluginAlias": "@salesforce/plugin-agent",
       "pluginName": "@salesforce/plugin-agent",
       "pluginType": "core",
       "strict": true,
-      "summary": "Start a programmatic agent preview session.",
+      "summary": "Get the results of a completed agent test run.",
       "enableJsonFlag": true,
-      "requiresProject": true,
       "envVariablesSection": {
         "header": "ENVIRONMENT VARIABLES",
         "body": [
@@ -1432,23 +1337,15 @@
         "body": [
           {
             "name": "Succeeded (0)",
-            "description": "Preview session started successfully."
-          },
-          {
-            "name": "Failed (1)",
-            "description": "Agent Script compilation failed (syntax errors in the script)."
+            "description": "Results retrieved successfully. Test results (passed/failed) are in the output."
           },
           {
             "name": "NotFound (2)",
-            "description": "Agent not found, or compilation API returned HTTP 404 (endpoint may not be available in your org or region)."
-          },
-          {
-            "name": "ServerError (3)",
-            "description": "Compilation API returned HTTP 500 (server error during compilation)."
+            "description": "Job ID not found or invalid."
           },
           {
-            "name": "PreviewStartFailed (4)",
-            "description": "Preview session failed to start due to API or network errors."
+            "name": "Failed (4)",
+            "description": "Failed to retrieve results due to API or network errors."
           }
         ]
       },
@@ -1457,27 +1354,27 @@
         "lib",
         "commands",
         "agent",
-        "preview",
-        "start.js"
+        "test",
+        "results.js"
       ],
       "aliasPermutations": [],
       "permutations": [
-        "agent:preview:start",
-        "preview:agent:start",
-        "preview:start:agent",
-        "agent:start:preview",
-        "start:agent:preview",
-        "start:preview:agent"
+        "agent:test:results",
+        "test:agent:results",
+        "test:results:agent",
+        "agent:results:test",
+        "results:agent:test",
+        "results:test:agent"
       ]
     },
-    "agent:test:create": {
+    "agent:test:resume": {
       "aliases": [],
       "args": {},
-      "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. This command also retrieves the metadata component (AiEvaluationDefinition) associated with the new test to your local Salesforce DX project and displays its filename.\n\nAfter you've created the test in the org, use the \"agent test run\" command to run it.",
+      "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.",
       "examples": [
-        "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 %>",
-        "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",
-        "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"
+        "Resume an agent test in your default org using a job ID:\n<%= config.bin %> <%= command.id %> --job-id 4KBfake0000003F4AQ",
+        "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",
+        "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"
       ],
       "flags": {
         "json": {
@@ -1495,20 +1392,6 @@
           "multiple": false,
           "type": "option"
         },
-        "api-name": {
-          "name": "api-name",
-          "summary": "API name of the new test; the API name must not exist in the org.",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
-        },
-        "spec": {
-          "name": "spec",
-          "summary": "Path to the test spec YAML file.",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
-        },
         "target-org": {
           "char": "o",
           "name": "target-org",
@@ -1526,27 +1409,81 @@
           "multiple": false,
           "type": "option"
         },
-        "preview": {
-          "name": "preview",
-          "summary": "Preview the test metadata file (AiEvaluationDefinition) without deploying to your org.",
+        "job-id": {
+          "char": "i",
+          "name": "job-id",
+          "summary": "Job ID of the original agent test run.",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "use-most-recent": {
+          "char": "r",
+          "name": "use-most-recent",
+          "summary": "Use the job ID of the most recent agent test run.",
           "allowNo": false,
           "type": "boolean"
         },
-        "force-overwrite": {
-          "name": "force-overwrite",
-          "summary": "Don't prompt for confirmation when overwriting an existing test (based on API name) in your org.",
+        "wait": {
+          "char": "w",
+          "name": "wait",
+          "summary": "Number of minutes to wait for the command to complete and display results to the terminal window.",
+          "default": "5 minutes",
+          "hasDynamicHelp": true,
+          "multiple": false,
+          "type": "option"
+        },
+        "result-format": {
+          "name": "result-format",
+          "summary": "Format of the agent test run results.",
+          "default": "human",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "options": [
+            "json",
+            "human",
+            "junit",
+            "tap"
+          ],
+          "type": "option"
+        },
+        "output-dir": {
+          "char": "d",
+          "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.",
+          "name": "output-dir",
+          "summary": "Directory to write the agent test results into.",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "test-runner": {
+          "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.",
+          "name": "test-runner",
+          "summary": "Explicitly specify which test runner to use (agentforce-studio or testing-center).",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "options": [
+            "agentforce-studio",
+            "testing-center"
+          ],
+          "type": "option"
+        },
+        "verbose": {
+          "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.",
+          "name": "verbose",
+          "summary": "Show generated data in the test results output.",
           "allowNo": false,
           "type": "boolean"
         }
       },
       "hasDynamicHelp": true,
       "hiddenAliases": [],
-      "id": "agent:test:create",
+      "id": "agent:test:resume",
       "pluginAlias": "@salesforce/plugin-agent",
       "pluginName": "@salesforce/plugin-agent",
       "pluginType": "core",
       "strict": true,
-      "summary": "Create an agent test in your org using a local test spec YAML file.",
+      "summary": "Resume an agent test that you previously started in your org so you can view the test results.",
       "enableJsonFlag": true,
       "envVariablesSection": {
         "header": "ENVIRONMENT VARIABLES",
@@ -1562,19 +1499,19 @@
         "body": [
           {
             "name": "Succeeded (0)",
-            "description": "Test created and deployed successfully."
+            "description": "Test completed successfully (with test results in the output)."
           },
           {
             "name": "Failed (1)",
-            "description": "Test validation errors or metadata format issues."
+            "description": "Tests encountered execution errors (test cases with ERROR status)."
           },
           {
             "name": "NotFound (2)",
-            "description": "Test spec file not found or org connection failed."
+            "description": "Job ID not found or invalid."
           },
           {
-            "name": "DeploymentFailed (4)",
-            "description": "Deployment failed due to API or network errors."
+            "name": "OperationFailed (4)",
+            "description": "Failed to poll test due to API or network errors."
           }
         ]
       },
@@ -1584,25 +1521,29 @@
         "commands",
         "agent",
         "test",
-        "create.js"
+        "resume.js"
       ],
       "aliasPermutations": [],
       "permutations": [
-        "agent:test:create",
-        "test:agent:create",
-        "test:create:agent",
-        "agent:create:test",
-        "create:agent:test",
-        "create:test:agent"
+        "agent:test:resume",
+        "test:agent:resume",
+        "test:resume:agent",
+        "agent:resume:test",
+        "resume:agent:test",
+        "resume:test:agent"
       ]
     },
-    "agent:test:list": {
+    "agent:test:run-eval": {
       "aliases": [],
       "args": {},
-      "description": "The command outputs a table with the name (API name) of each test along with its unique ID and the date it was created in the org.",
+      "description": "Execute rich evaluation tests against an Agentforce agent using the Einstein Evaluation API. Supports both YAML test specs (same format as `sf agent generate test-spec`) and JSON payloads.\n\nWhen you provide a YAML test spec, the command automatically translates test cases into Evaluation API calls and infers the agent name from the spec's `subjectName` field. This means you can use the same test spec with both `sf agent test run` and `sf agent test run-eval`. YAML test specs also support contextVariables, 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 API 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.\n\nSupports 8+ evaluator types, including topic routing assertions, action invocation checks, string/numeric assertions, semantic similarity scoring, and LLM-based quality ratings.",
       "examples": [
-        "List the agent tests in your default org:\n<%= config.bin %> <%= command.id %>",
-        "List the agent tests in an org with alias \"my-org\"\"\n<%= config.bin %> <%= command.id %> --target-org my-org"
+        "Run tests using a YAML test spec on the org with alias \"my-org\":\n<%= config.bin %> <%= command.id %> --spec tests/my-agent-testSpec.yaml --target-org my-org",
+        "Run tests using a YAML spec with explicit agent name override; use your default org:\n<%= config.bin %> <%= command.id %> --spec tests/my-agent-testSpec.yaml --api-name My_Agent --target-org my-org",
+        "Run tests using a JSON payload:\n<%= config.bin %> <%= command.id %> --spec tests/eval-payload.json --target-org my-org",
+        "Run tests and output results in JUnit format; useful for continuous integration and deployment (CI/CD):\n<%= config.bin %> <%= command.id %> --spec tests/my-agent-testSpec.yaml --target-org my-org --result-format junit",
+        "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 tests/agent-with-context.yaml --target-org my-org",
+        "Pipe JSON payload from stdin (--spec flag is automatically populated from stdin):\n$ echo '{\"tests\":[...]}' | <%= config.bin %> <%= command.id %> --spec --target-org my-org"
       ],
       "flags": {
         "json": {
@@ -1636,16 +1577,61 @@
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
+        },
+        "spec": {
+          "char": "s",
+          "name": "spec",
+          "required": true,
+          "summary": "Path to test spec file (YAML or JSON). Supports reading from stdin when piping content.",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "api-name": {
+          "char": "n",
+          "name": "api-name",
+          "summary": "Agent DeveloperName (also called API name) to resolve agent_id and agent_version_id. Auto-inferred from the YAML spec's subjectName.",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "result-format": {
+          "name": "result-format",
+          "summary": "Format of the agent test run results.",
+          "default": "human",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "options": [
+            "json",
+            "human",
+            "junit",
+            "tap"
+          ],
+          "type": "option"
+        },
+        "batch-size": {
+          "name": "batch-size",
+          "summary": "Number of tests per API request (max 5).",
+          "default": 5,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "no-normalize": {
+          "name": "no-normalize",
+          "summary": "Disable auto-normalization of field names and shorthand references.",
+          "allowNo": false,
+          "type": "boolean"
         }
       },
       "hasDynamicHelp": true,
       "hiddenAliases": [],
-      "id": "agent:test:list",
+      "id": "agent:test:run-eval",
       "pluginAlias": "@salesforce/plugin-agent",
       "pluginName": "@salesforce/plugin-agent",
       "pluginType": "core",
       "strict": true,
-      "summary": "List the available agent tests in your org.",
+      "summary": "Run evaluation tests against an Agentforce agent.",
       "enableJsonFlag": true,
       "envVariablesSection": {
         "header": "ENVIRONMENT VARIABLES",
@@ -1661,11 +1647,19 @@
         "body": [
           {
             "name": "Succeeded (0)",
-            "description": "Agent tests listed successfully."
+            "description": "Tests completed successfully. Test results (passed/failed) are in the JSON output."
           },
           {
-            "name": "Failed (4)",
-            "description": "Failed to retrieve agent tests due to API or network errors."
+            "name": "Failed (1)",
+            "description": "Tests encountered execution errors (tests couldn't run properly)."
+          },
+          {
+            "name": "NotFound (2)",
+            "description": "Agent not found, spec file not found, or invalid agent name."
+          },
+          {
+            "name": "OperationFailed (4)",
+            "description": "Failed to execute tests due to API or network errors."
           }
         ]
       },
@@ -1675,26 +1669,26 @@
         "commands",
         "agent",
         "test",
-        "list.js"
+        "run-eval.js"
       ],
       "aliasPermutations": [],
       "permutations": [
-        "agent:test:list",
-        "test:agent:list",
-        "test:list:agent",
-        "agent:list:test",
-        "list:agent:test",
-        "list:test:agent"
+        "agent:test:run-eval",
+        "test:agent:run-eval",
+        "test:run-eval:agent",
+        "agent:run-eval:test",
+        "run-eval:agent:test",
+        "run-eval:test:agent"
       ]
     },
-    "agent:test:results": {
+    "agent:test:run": {
       "aliases": [],
       "args": {},
-      "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.",
+      "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.",
       "examples": [
-        "Get the results of an agent test run in your default org using its job ID:\n<%= config.bin %> <%= command.id %> --job-id 4KBfake0000003F4AQ",
-        "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",
-        "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"
+        "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",
+        "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",
+        "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"
       ],
       "flags": {
         "json": {
@@ -1729,15 +1723,22 @@
           "multiple": false,
           "type": "option"
         },
-        "job-id": {
-          "char": "i",
-          "name": "job-id",
-          "required": true,
-          "summary": "Job ID of the completed agent test run.",
+        "api-name": {
+          "char": "n",
+          "name": "api-name",
+          "summary": "API name of the agent test to run; corresponds to the name of the AiEvaluationDefinition metadata component that implements the agent test.",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
         },
+        "wait": {
+          "char": "w",
+          "name": "wait",
+          "summary": "Number of minutes to wait for the command to complete and display results to the terminal window.",
+          "hasDynamicHelp": true,
+          "multiple": false,
+          "type": "option"
+        },
         "result-format": {
           "name": "result-format",
           "summary": "Format of the agent test run results.",
@@ -1761,6 +1762,18 @@
           "multiple": false,
           "type": "option"
         },
+        "test-runner": {
+          "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.",
+          "name": "test-runner",
+          "summary": "Explicitly specify which test runner to use (agentforce-studio or testing-center).",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "options": [
+            "agentforce-studio",
+            "testing-center"
+          ],
+          "type": "option"
+        },
         "verbose": {
           "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.",
           "name": "verbose",
@@ -1771,12 +1784,12 @@
       },
       "hasDynamicHelp": true,
       "hiddenAliases": [],
-      "id": "agent:test:results",
+      "id": "agent:test:run",
       "pluginAlias": "@salesforce/plugin-agent",
       "pluginName": "@salesforce/plugin-agent",
       "pluginType": "core",
       "strict": true,
-      "summary": "Get the results of a completed agent test run.",
+      "summary": "Start an agent test in your org.",
       "enableJsonFlag": true,
       "envVariablesSection": {
         "header": "ENVIRONMENT VARIABLES",
@@ -1792,15 +1805,19 @@
         "body": [
           {
             "name": "Succeeded (0)",
-            "description": "Results retrieved successfully. Test results (passed/failed) are in the output."
+            "description": "Test started successfully (without --wait), or test completed successfully (with --wait)."
+          },
+          {
+            "name": "Failed (1)",
+            "description": "Tests encountered execution errors (test cases with ERROR status when using --wait)."
           },
           {
             "name": "NotFound (2)",
-            "description": "Job ID not found or invalid."
+            "description": "Test definition not found or invalid test name."
           },
           {
-            "name": "Failed (4)",
-            "description": "Failed to retrieve results due to API or network errors."
+            "name": "OperationFailed (4)",
+            "description": "Failed to start or poll test due to API or network errors."
           }
         ]
       },
@@ -1810,26 +1827,26 @@
         "commands",
         "agent",
         "test",
-        "results.js"
+        "run.js"
       ],
       "aliasPermutations": [],
       "permutations": [
-        "agent:test:results",
-        "test:agent:results",
-        "test:results:agent",
-        "agent:results:test",
-        "results:agent:test",
-        "results:test:agent"
+        "agent:test:run",
+        "test:agent:run",
+        "test:run:agent",
+        "agent:run:test",
+        "run:agent:test",
+        "run:test:agent"
       ]
     },
-    "agent:test:resume": {
+    "agent:preview:end": {
       "aliases": [],
       "args": {},
-      "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.",
+      "description": "You must have previously started a programmatic agent preview session with the \"agent preview start\" command to then use this command to end it. This command also displays the local directory where the session trace files are stored.\n\nThe original \"agent preview start\" command outputs a session ID which you then use with the --session-id flag of this command to end the session. You don't have to specify the --session-id flag if an agent has only one active preview session. You must also use either the --authoring-bundle or --api-name flag to specify the API name of the authoring bundle or the published agent, respecitvely. To find either API name, navigate to your package directory in your DX project. The API name of an authoring bundle is the same as its directory name under the \"aiAuthoringBundles\" metadata directory. Similarly, the published agent's API name is the same as its directory name under the \"Bots\" metadata directory.",
       "examples": [
-        "Resume an agent test in your default org using a job ID:\n<%= config.bin %> <%= command.id %> --job-id 4KBfake0000003F4AQ",
-        "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",
-        "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"
+        "End a preview session of a published agent by specifying its session ID and API name ; use the default org:\n<%= config.bin %> <%= command.id %> --session-id <SESSION_ID> --api-name My_Published_Agent",
+        "Similar to previous example, but don't specify a session ID; you get an error if the published agent has more than one active session. Use the org with alias \"my-dev-org\":\n<%= config.bin %> <%= command.id %> --api-name My_Published_Agent --target-org my-dev-org",
+        "End a preview session of an agent using its authoring bundle API name; you get an error if the agent has more than one active session.\n<%= config.bin %> <%= command.id %> --authoring-bundle My_Local_Agent"
       ],
       "flags": {
         "json": {
@@ -1864,70 +1881,40 @@
           "multiple": false,
           "type": "option"
         },
-        "job-id": {
-          "char": "i",
-          "name": "job-id",
-          "summary": "Job ID of the original agent test run.",
+        "session-id": {
+          "name": "session-id",
+          "required": false,
+          "summary": "Session ID outputted by \"agent preview start\". Not required when the agent has exactly one active session. Run \"agent preview sessions\" to see the list of all sessions.",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
         },
-        "use-most-recent": {
-          "char": "r",
-          "name": "use-most-recent",
-          "summary": "Use the job ID of the most recent agent test run.",
-          "allowNo": false,
-          "type": "boolean"
-        },
-        "wait": {
-          "char": "w",
-          "name": "wait",
-          "summary": "Number of minutes to wait for the command to complete and display results to the terminal window.",
-          "default": "5 minutes",
-          "hasDynamicHelp": true,
-          "multiple": false,
-          "type": "option"
-        },
-        "result-format": {
-          "name": "result-format",
-          "summary": "Format of the agent test run results.",
-          "default": "human",
+        "api-name": {
+          "char": "n",
+          "name": "api-name",
+          "summary": "API name of the activated published agent you want to preview.",
           "hasDynamicHelp": false,
           "multiple": false,
-          "options": [
-            "json",
-            "human",
-            "junit",
-            "tap"
-          ],
           "type": "option"
         },
-        "output-dir": {
-          "char": "d",
-          "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.",
-          "name": "output-dir",
-          "summary": "Directory to write the agent test results into.",
+        "authoring-bundle": {
+          "name": "authoring-bundle",
+          "summary": "API name of the authoring bundle metadata component that contains the agent's Agent Script file.",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
-        },
-        "verbose": {
-          "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.",
-          "name": "verbose",
-          "summary": "Show generated data in the test results output.",
-          "allowNo": false,
-          "type": "boolean"
         }
       },
       "hasDynamicHelp": true,
       "hiddenAliases": [],
-      "id": "agent:test:resume",
+      "id": "agent:preview:end",
       "pluginAlias": "@salesforce/plugin-agent",
       "pluginName": "@salesforce/plugin-agent",
       "pluginType": "core",
       "strict": true,
-      "summary": "Resume an agent test that you previously started in your org so you can view the test results.",
+      "summary": "End an existing programmatic agent preview session and get trace location.",
       "enableJsonFlag": true,
+      "requiresProject": true,
       "envVariablesSection": {
         "header": "ENVIRONMENT VARIABLES",
         "body": [
@@ -1942,19 +1929,19 @@
         "body": [
           {
             "name": "Succeeded (0)",
-            "description": "Test completed successfully (with test results in the output)."
+            "description": "Preview session ended successfully and traces saved."
           },
           {
-            "name": "Failed (1)",
-            "description": "Tests encountered execution errors (test cases with ERROR status)."
+            "name": "NotFound (2)",
+            "description": "Agent not found, or no preview session exists for this agent."
           },
           {
-            "name": "NotFound (2)",
-            "description": "Job ID not found or invalid."
+            "name": "PreviewEndFailed (4)",
+            "description": "Failed to end the preview session."
           },
           {
-            "name": "OperationFailed (4)",
-            "description": "Failed to poll test due to API or network errors."
+            "name": "SessionAmbiguous (5)",
+            "description": "Multiple preview sessions found; specify --session-id to choose one."
           }
         ]
       },
@@ -1963,30 +1950,27 @@
         "lib",
         "commands",
         "agent",
-        "test",
-        "resume.js"
+        "preview",
+        "end.js"
       ],
       "aliasPermutations": [],
       "permutations": [
-        "agent:test:resume",
-        "test:agent:resume",
-        "test:resume:agent",
-        "agent:resume:test",
-        "resume:agent:test",
-        "resume:test:agent"
+        "agent:preview:end",
+        "preview:agent:end",
+        "preview:end:agent",
+        "agent:end:preview",
+        "end:agent:preview",
+        "end:preview:agent"
       ]
     },
-    "agent:test:run-eval": {
+    "agent:preview:send": {
       "aliases": [],
       "args": {},
-      "description": "Execute rich evaluation tests against an Agentforce agent using the Einstein Evaluation API. Supports both YAML test specs (same format as `sf agent generate test-spec`) and JSON payloads.\n\nWhen you provide a YAML test spec, the command automatically translates test cases into Evaluation API calls and infers the agent name from the spec's `subjectName` field. This means you can use the same test spec with both `sf agent test run` and `sf agent test run-eval`. YAML test specs also support contextVariables, 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 API 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.\n\nSupports 8+ evaluator types, including topic routing assertions, action invocation checks, string/numeric assertions, semantic similarity scoring, and LLM-based quality ratings.",
+      "description": "You must have previously started a programmatic agent preview session with the \"agent preview start\" command to then use this command to send the agent a message (utterance). This command then displays the agent's response.\n\nThe original \"agent preview start\" command outputs a session ID which you then use with the --session-id flag of this command to send a message. You don't have to specify the --session-id flag if an agent has only one active preview session. You must also use either the --authoring-bundle or --api-name flag to specify the API name of the authoring bundle or the published agent, respecitvely. To find either API name, navigate to your package directory in your DX project. The API name of an authoring bundle is the same as its directory name under the \"aiAuthoringBundles\" metadata directory. Similarly, the published agent's API name is the same as its directory name under the \"Bots\" metadata directory.",
       "examples": [
-        "Run tests using a YAML test spec on the org with alias \"my-org\":\n<%= config.bin %> <%= command.id %> --spec tests/my-agent-testSpec.yaml --target-org my-org",
-        "Run tests using a YAML spec with explicit agent name override; use your default org:\n<%= config.bin %> <%= command.id %> --spec tests/my-agent-testSpec.yaml --api-name My_Agent --target-org my-org",
-        "Run tests using a JSON payload:\n<%= config.bin %> <%= command.id %> --spec tests/eval-payload.json --target-org my-org",
-        "Run tests and output results in JUnit format; useful for continuous integration and deployment (CI/CD):\n<%= config.bin %> <%= command.id %> --spec tests/my-agent-testSpec.yaml --target-org my-org --result-format junit",
-        "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 tests/agent-with-context.yaml --target-org my-org",
-        "Pipe JSON payload from stdin (--spec flag is automatically populated from stdin):\n$ echo '{\"tests\":[...]}' | <%= config.bin %> <%= command.id %> --spec --target-org my-org"
+        "Send a message to an activated published agent using its API name and session ID; use the default org:\n<%= config.bin %> <%= command.id %> --utterance \"What can you help me with?\" --api-name My_Published_Agent --session-id <SESSION_ID>",
+        "Similar to previous example, but don't specify a session ID; you get an error if the agent has more than one active session. Use the org with alias \"my-dev-org\":\n<%= config.bin %> <%= command.id %> --utterance \"What can you help me with?\" --api-name My_Published_Agent --target-org my-dev-org",
+        "Send a message to an agent using its authoring bundle API name; you get an error if the agent has more than one active session:\n<%= config.bin %> <%= command.id %> --utterance \"what can you help me with?\" --authoring-bundle My_Local_Agent"
       ],
       "flags": {
         "json": {
@@ -2021,72 +2005,49 @@
           "multiple": false,
           "type": "option"
         },
-        "spec": {
-          "char": "s",
-          "name": "spec",
-          "required": true,
-          "summary": "Path to test spec file (YAML or JSON). Supports reading from stdin when piping content.",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
-        },
-        "api-name": {
-          "char": "n",
-          "name": "api-name",
-          "summary": "Agent DeveloperName (also called API name) to resolve agent_id and agent_version_id. Auto-inferred from the YAML spec's subjectName.",
+        "session-id": {
+          "name": "session-id",
+          "required": false,
+          "summary": "Session ID outputted by \"agent preview start\". Not required when the agent has exactly one active session. Run \"agent preview sessions\" to see list of all sessions.",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
         },
-        "wait": {
-          "char": "w",
-          "name": "wait",
-          "summary": "Number of minutes to wait for results.",
-          "default": 10,
+        "utterance": {
+          "char": "u",
+          "name": "utterance",
+          "required": true,
+          "summary": "Utterance to send to the agent, enclosed in double quotes.",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
         },
-        "result-format": {
-          "name": "result-format",
-          "summary": "Format of the agent test run results.",
-          "default": "human",
+        "api-name": {
+          "char": "n",
+          "name": "api-name",
+          "summary": "API name of the activated published agent you want to preview.",
           "hasDynamicHelp": false,
           "multiple": false,
-          "options": [
-            "json",
-            "human",
-            "junit",
-            "tap"
-          ],
           "type": "option"
         },
-        "batch-size": {
-          "name": "batch-size",
-          "summary": "Number of tests per API request (max 5).",
-          "default": 5,
+        "authoring-bundle": {
+          "name": "authoring-bundle",
+          "summary": "API name of the authoring bundle metadata component that contains the agent's Agent Script file.",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
-        },
-        "no-normalize": {
-          "name": "no-normalize",
-          "summary": "Disable auto-normalization of field names and shorthand references.",
-          "allowNo": false,
-          "type": "boolean"
         }
       },
       "hasDynamicHelp": true,
-      "hidden": true,
       "hiddenAliases": [],
-      "id": "agent:test:run-eval",
+      "id": "agent:preview:send",
       "pluginAlias": "@salesforce/plugin-agent",
       "pluginName": "@salesforce/plugin-agent",
       "pluginType": "core",
-      "state": "beta",
       "strict": true,
-      "summary": "Run evaluation tests against an Agentforce agent.",
+      "summary": "Send a message to an existing agent preview session.",
       "enableJsonFlag": true,
+      "requiresProject": true,
       "envVariablesSection": {
         "header": "ENVIRONMENT VARIABLES",
         "body": [
@@ -2101,19 +2062,19 @@
         "body": [
           {
             "name": "Succeeded (0)",
-            "description": "Tests completed successfully. Test results (passed/failed) are in the JSON output."
+            "description": "Message sent successfully and agent response received."
           },
           {
-            "name": "Failed (1)",
-            "description": "Tests encountered execution errors (tests couldn't run properly)."
+            "name": "NotFound (2)",
+            "description": "Agent not found, or no preview session exists for this agent."
           },
           {
-            "name": "NotFound (2)",
-            "description": "Agent not found, spec file not found, or invalid agent name."
+            "name": "PreviewSendFailed (4)",
+            "description": "Failed to send message or receive response from the preview session."
           },
           {
-            "name": "OperationFailed (4)",
-            "description": "Failed to execute tests due to API or network errors."
+            "name": "SessionAmbiguous (5)",
+            "description": "Multiple preview sessions found; specify --session-id to choose one."
           }
         ]
       },
@@ -2122,27 +2083,88 @@
         "lib",
         "commands",
         "agent",
-        "test",
-        "run-eval.js"
+        "preview",
+        "send.js"
       ],
       "aliasPermutations": [],
       "permutations": [
-        "agent:test:run-eval",
-        "test:agent:run-eval",
-        "test:run-eval:agent",
-        "agent:run-eval:test",
-        "run-eval:agent:test",
-        "run-eval:test:agent"
+        "agent:preview:send",
+        "preview:agent:send",
+        "preview:send:agent",
+        "agent:send:preview",
+        "send:agent:preview",
+        "send:preview:agent"
       ]
     },
-    "agent:test:run": {
+    "agent:preview:sessions": {
       "aliases": [],
       "args": {},
-      "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.",
+      "description": "This command lists the agent preview sessions that were started with the \"agent preview start\" command and are still in the local cache. Use this command to discover specific session IDs that you can pass to the \"agent preview send\" or \"agent preview end\" commands with the --session-id flag.\n\nProgrammatic agent preview sessions can be started for both published activated agents and by using an agent's local authoring bundle, which contains its Agent Script file. In this command's output table, the Agent column contains either the API name of the authoring bundle or the published agent, whichever was used when starting the session. In the table, if the same API name has multiple rows with different session IDs, then it means that you previously started multiple preview sessions with the associated agent.",
       "examples": [
-        "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",
-        "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",
-        "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"
+        "List all cached agent preview sessions:\n<%= config.bin %> <%= command.id %>"
+      ],
+      "flags": {
+        "json": {
+          "description": "Format output as json.",
+          "helpGroup": "GLOBAL",
+          "name": "json",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "flags-dir": {
+          "helpGroup": "GLOBAL",
+          "name": "flags-dir",
+          "summary": "Import flag values from a directory.",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "agent:preview:sessions",
+      "pluginAlias": "@salesforce/plugin-agent",
+      "pluginName": "@salesforce/plugin-agent",
+      "pluginType": "core",
+      "strict": true,
+      "summary": "List all known programmatic agent preview sessions.",
+      "enableJsonFlag": true,
+      "requiresProject": true,
+      "errorCodes": {
+        "header": "ERROR CODES",
+        "body": [
+          {
+            "name": "Succeeded (0)",
+            "description": "Sessions listed successfully (or empty list if no active sessions)."
+          }
+        ]
+      },
+      "isESM": true,
+      "relativePath": [
+        "lib",
+        "commands",
+        "agent",
+        "preview",
+        "sessions.js"
+      ],
+      "aliasPermutations": [],
+      "permutations": [
+        "agent:preview:sessions",
+        "preview:agent:sessions",
+        "preview:sessions:agent",
+        "agent:sessions:preview",
+        "sessions:agent:preview",
+        "sessions:preview:agent"
+      ]
+    },
+    "agent:preview:start": {
+      "aliases": [],
+      "args": {},
+      "description": "This command outputs a session ID that you then use with the \"agent preview send\" command to send an utterance to the agent. Use the \"agent preview sessions\" command to list all active sessions and the \"agent preview end\" command to end a specific session.\n\nIdentify the agent you want to start previewing with either the --authoring-bundle flag to specify a local authoring bundle's API name or --api-name to specify an activated published agent's API name. To find either API name, navigate to your package directory in your DX project. The API name of an authoring bundle is the same as its directory name under the \"aiAuthoringBundles\" metadata directory. Similarly, the published agent's API name is the same as its directory name under the \"Bots\" metadata directory.\n\nWhen starting a preview session with --authoring-bundle, you must explicitly specify the execution mode using one of these flags:\n\n- --use-live-actions: Executes real Apex classes, flows, and other actions in the org. This surfaces compile and validation errors during preview.\n- --simulate-actions: Uses AI to simulate action execution without calling real implementations.\n\nPublished agents (--api-name) always use live actions. The mode flags are optional and have no effect for published agents.",
+      "examples": [
+        "Start a programmatic agent preview session by specifying an authoring bundle; use simulated actions. Use the org with alias \"my-dev-org\":\n<%= config.bin %> <%= command.id %> --authoring-bundle My_Agent_Bundle --target-org my-dev-org --simulate-actions",
+        "Similar to previous example but use live actions and the default org:\n<%= config.bin %> <%= command.id %> --authoring-bundle My_Agent_Bundle --use-live-actions",
+        "Start a preview session with an activated published agent (always uses live actions):\n<%= config.bin %> <%= command.id %> --api-name My_Published_Agent"
       ],
       "flags": {
         "json": {
@@ -2180,59 +2202,58 @@
         "api-name": {
           "char": "n",
           "name": "api-name",
-          "summary": "API name of the agent test to run; corresponds to the name of the AiEvaluationDefinition metadata component that implements the agent test.",
+          "summary": "API name of the activated published agent you want to preview.",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
         },
-        "wait": {
-          "char": "w",
-          "name": "wait",
-          "summary": "Number of minutes to wait for the command to complete and display results to the terminal window.",
-          "hasDynamicHelp": true,
+        "authoring-bundle": {
+          "name": "authoring-bundle",
+          "summary": "API name of the authoring bundle metadata component that contains the agent's Agent Script file.",
+          "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
         },
-        "result-format": {
-          "name": "result-format",
-          "summary": "Format of the agent test run results.",
-          "default": "human",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "options": [
-            "json",
-            "human",
-            "junit",
-            "tap"
+        "use-live-actions": {
+          "exclusive": [
+            "simulate-actions"
           ],
-          "type": "option"
+          "name": "use-live-actions",
+          "summary": "Execute real actions in the org (Apex classes, flows, etc.). Required with --authoring-bundle.",
+          "allowNo": false,
+          "type": "boolean"
         },
-        "output-dir": {
-          "char": "d",
-          "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.",
-          "name": "output-dir",
-          "summary": "Directory to write the agent test results into.",
+        "simulate-actions": {
+          "exclusive": [
+            "use-live-actions"
+          ],
+          "name": "simulate-actions",
+          "summary": "Use AI to simulate action execution instead of calling real actions. Required with --authoring-bundle.",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "agent-json": {
+          "dependsOn": [
+            "authoring-bundle"
+          ],
+          "hidden": true,
+          "name": "agent-json",
+          "summary": "Path to a pre-compiled AgentJSON file to use instead of compiling the Agent Script file. Intended for internal use and testing.",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
-        },
-        "verbose": {
-          "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.",
-          "name": "verbose",
-          "summary": "Show generated data in the test results output.",
-          "allowNo": false,
-          "type": "boolean"
         }
       },
       "hasDynamicHelp": true,
       "hiddenAliases": [],
-      "id": "agent:test:run",
+      "id": "agent:preview:start",
       "pluginAlias": "@salesforce/plugin-agent",
       "pluginName": "@salesforce/plugin-agent",
       "pluginType": "core",
       "strict": true,
-      "summary": "Start an agent test in your org.",
+      "summary": "Start a programmatic agent preview session.",
       "enableJsonFlag": true,
+      "requiresProject": true,
       "envVariablesSection": {
         "header": "ENVIRONMENT VARIABLES",
         "body": [
@@ -2247,19 +2268,23 @@
         "body": [
           {
             "name": "Succeeded (0)",
-            "description": "Test started successfully (without --wait), or test completed successfully (with --wait)."
+            "description": "Preview session started successfully."
           },
           {
             "name": "Failed (1)",
-            "description": "Tests encountered execution errors (test cases with ERROR status when using --wait)."
+            "description": "Agent Script compilation failed (syntax errors in the script)."
           },
           {
             "name": "NotFound (2)",
-            "description": "Test definition not found or invalid test name."
+            "description": "Agent not found, or compilation API returned HTTP 404 (endpoint may not be available in your org or region)."
           },
           {
-            "name": "OperationFailed (4)",
-            "description": "Failed to start or poll test due to API or network errors."
+            "name": "ServerError (3)",
+            "description": "Compilation API returned HTTP 500 (server error during compilation)."
+          },
+          {
+            "name": "PreviewStartFailed (4)",
+            "description": "Preview session failed to start due to API or network errors."
           }
         ]
       },
@@ -2268,17 +2293,17 @@
         "lib",
         "commands",
         "agent",
-        "test",
-        "run.js"
+        "preview",
+        "start.js"
       ],
       "aliasPermutations": [],
       "permutations": [
-        "agent:test:run",
-        "test:agent:run",
-        "test:run:agent",
-        "agent:run:test",
-        "run:agent:test",
-        "run:test:agent"
+        "agent:preview:start",
+        "preview:agent:start",
+        "preview:start:agent",
+        "agent:start:preview",
+        "start:agent:preview",
+        "start:preview:agent"
       ]
     },
     "agent:validate:authoring-bundle": {
@@ -2396,5 +2421,5 @@
       ]
     }
   },
-  "version": "1.36.0"
+  "version": "1.37.0"
 }