@salesforce/plugin-agent 2.2.4 → 2.3.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.
@@ -2809,6 +2809,16 @@
2809
2809
  "allowNo": false,
2810
2810
  "type": "boolean"
2811
2811
  },
2812
+ "source-type": {
2813
+ "name": "source-type",
2814
+ "summary": "Where the agent came from. Use \"Bot\" when the agent was converted from an Einstein Bot. Applied on the first publish only.",
2815
+ "hasDynamicHelp": false,
2816
+ "multiple": false,
2817
+ "options": [
2818
+ "Bot"
2819
+ ],
2820
+ "type": "option"
2821
+ },
2812
2822
  "verbose": {
2813
2823
  "char": "v",
2814
2824
  "exclusive": [
@@ -2876,17 +2886,15 @@
2876
2886
  "authoring-bundle:publish:agent"
2877
2887
  ]
2878
2888
  },
2879
- "agent:trace:delete": {
2889
+ "agent:test:create": {
2880
2890
  "aliases": [],
2881
2891
  "args": {},
2882
- "description": "When you run an agent preview conversation (either interactive or programmatic), trace files are automatically recorded and saved in your local DX project. Use this command to delete some or all of the trace files.\n\nBy default, this command shows a preview of what will be deleted and prompts for confirmation. Use --no-prompt to skip confirmation.\n\nWithout filters, this comamnd deletes all trace files for all agents and sessions. Use flags to narrow the scope: filter by agent API name (--agent), by session (--session-id), or by age (--older-than).",
2892
+ "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.",
2883
2893
  "examples": [
2884
- "Delete all traces for all agents and sessions; prompt for confirmation:\n<%= config.bin %> <%= command.id %>",
2885
- "Delete all traces for a specific agent:\n<%= config.bin %> <%= command.id %> --agent My_Agent",
2886
- "Delete traces from a specific session:\n<%= config.bin %> <%= command.id %> --session-id <SESSION_ID>",
2887
- "Delete traces older than 7 days:\n<%= config.bin %> <%= command.id %> --older-than 7d",
2888
- "Delete traces older than 24 hours for a specific agent; don't prompt for confirmation:\n<%= config.bin %> <%= command.id %> --agent My_Agent --older-than 24h --no-prompt",
2889
- "Delete all traces for all agents and sessions; don't prompt for confirmation:\n<%= config.bin %> <%= command.id %> --no-prompt"
2894
+ "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 %>",
2895
+ "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",
2896
+ "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",
2897
+ "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"
2890
2898
  ],
2891
2899
  "flags": {
2892
2900
  "json": {
@@ -2904,51 +2912,98 @@
2904
2912
  "multiple": false,
2905
2913
  "type": "option"
2906
2914
  },
2907
- "agent": {
2908
- "char": "a",
2909
- "name": "agent",
2910
- "summary": "API name of the agent used to filter the list of trace files you want to delete. Matches against the API name used when starting the session, either an authoring bundle or a published agent API name.",
2915
+ "api-name": {
2916
+ "name": "api-name",
2917
+ "summary": "API name of the new test; the API name must not exist in the org.",
2911
2918
  "hasDynamicHelp": false,
2912
2919
  "multiple": false,
2913
2920
  "type": "option"
2914
2921
  },
2915
- "session-id": {
2916
- "name": "session-id",
2917
- "summary": "Session ID used to filter the list of trace files you want to delete. Use the \"agent preview sessions\" CLI command to list all known agent preview sessions along with their session IDs.",
2922
+ "spec": {
2923
+ "name": "spec",
2924
+ "summary": "Path to the test spec YAML file.",
2918
2925
  "hasDynamicHelp": false,
2919
2926
  "multiple": false,
2920
2927
  "type": "option"
2921
2928
  },
2922
- "older-than": {
2923
- "name": "older-than",
2924
- "summary": "Duration used to filter the list of trace files; only files older than the duration are deleted. Accepts a number followed by a unit: m/minutes, h/hours, d/days, w/weeks. Examples: 7d, 24h, 2w.",
2929
+ "target-org": {
2930
+ "char": "o",
2931
+ "name": "target-org",
2932
+ "noCacheDefault": true,
2933
+ "required": true,
2934
+ "summary": "Username or alias of the target org. Not required if the `target-org` configuration variable is already set.",
2935
+ "hasDynamicHelp": true,
2936
+ "multiple": false,
2937
+ "type": "option"
2938
+ },
2939
+ "api-version": {
2940
+ "description": "Override the api version used for api requests made by this command",
2941
+ "name": "api-version",
2925
2942
  "hasDynamicHelp": false,
2926
2943
  "multiple": false,
2927
2944
  "type": "option"
2928
2945
  },
2929
- "no-prompt": {
2930
- "name": "no-prompt",
2931
- "summary": "Skip the confirmation prompt and delete immediately.",
2946
+ "preview": {
2947
+ "name": "preview",
2948
+ "summary": "Preview the test metadata file without deploying to your org.",
2949
+ "allowNo": false,
2950
+ "type": "boolean"
2951
+ },
2952
+ "force-overwrite": {
2953
+ "name": "force-overwrite",
2954
+ "summary": "Don't prompt for confirmation when overwriting an existing test (based on API name) in your org.",
2932
2955
  "allowNo": false,
2933
2956
  "type": "boolean"
2957
+ },
2958
+ "test-runner": {
2959
+ "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.",
2960
+ "name": "test-runner",
2961
+ "summary": "Explicitly specify which test runner to use (agentforce-studio or testing-center).",
2962
+ "hasDynamicHelp": false,
2963
+ "multiple": false,
2964
+ "options": [
2965
+ "agentforce-studio",
2966
+ "testing-center"
2967
+ ],
2968
+ "type": "option"
2934
2969
  }
2935
2970
  },
2936
- "hasDynamicHelp": false,
2971
+ "hasDynamicHelp": true,
2937
2972
  "hiddenAliases": [],
2938
- "id": "agent:trace:delete",
2973
+ "id": "agent:test:create",
2939
2974
  "pluginAlias": "@salesforce/plugin-agent",
2940
2975
  "pluginName": "@salesforce/plugin-agent",
2941
2976
  "pluginType": "core",
2942
2977
  "strict": true,
2943
- "summary": "Delete trace files from an agent preview session.",
2978
+ "summary": "Create an agent test in your org using a local test spec YAML file.",
2944
2979
  "enableJsonFlag": true,
2945
- "requiresProject": true,
2980
+ "envVariablesSection": {
2981
+ "header": "ENVIRONMENT VARIABLES",
2982
+ "body": [
2983
+ {
2984
+ "name": "SF_TARGET_ORG",
2985
+ "description": "Username or alias of your default org. Overrides the target-org configuration variable."
2986
+ }
2987
+ ]
2988
+ },
2946
2989
  "errorCodes": {
2947
2990
  "header": "ERROR CODES",
2948
2991
  "body": [
2949
2992
  {
2950
2993
  "name": "Succeeded (0)",
2951
- "description": "Traces deleted successfully (or no traces matched)."
2994
+ "description": "Test created and deployed successfully."
2995
+ },
2996
+ {
2997
+ "name": "Failed (1)",
2998
+ "description": "Test validation errors or metadata format issues."
2999
+ },
3000
+ {
3001
+ "name": "NotFound (2)",
3002
+ "description": "Test spec file not found or org connection failed."
3003
+ },
3004
+ {
3005
+ "name": "DeploymentFailed (4)",
3006
+ "description": "Deployment failed due to API or network errors."
2952
3007
  }
2953
3008
  ]
2954
3009
  },
@@ -2957,31 +3012,26 @@
2957
3012
  "lib",
2958
3013
  "commands",
2959
3014
  "agent",
2960
- "trace",
2961
- "delete.js"
3015
+ "test",
3016
+ "create.js"
2962
3017
  ],
2963
3018
  "aliasPermutations": [],
2964
3019
  "permutations": [
2965
- "agent:trace:delete",
2966
- "trace:agent:delete",
2967
- "trace:delete:agent",
2968
- "agent:delete:trace",
2969
- "delete:agent:trace",
2970
- "delete:trace:agent"
3020
+ "agent:test:create",
3021
+ "test:agent:create",
3022
+ "test:create:agent",
3023
+ "agent:create:test",
3024
+ "create:agent:test",
3025
+ "create:test:agent"
2971
3026
  ]
2972
3027
  },
2973
- "agent:trace:list": {
3028
+ "agent:test:list": {
2974
3029
  "aliases": [],
2975
3030
  "args": {},
2976
- "description": "When you run an agent preview conversation (either interactive or programmatic), trace files are automatically recorded and saved in your local DX project. By default, this command lists all trace files for all agents and all of their sessions. Use flags to narrow results: filter by agent name (--agent), by session (--session-id), or by date (--since).\n\nEach row in the output corresponds to one trace file, which in turn corresponds to one agent session. The Agent column shows the authoring bundle or API name used when starting the session.",
3031
+ "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.",
2977
3032
  "examples": [
2978
- "List all trace files for all agents and sessions:\n<%= config.bin %> <%= command.id %>",
2979
- "List all trace files for a specific agent:\n<%= config.bin %> <%= command.id %> --agent My_Agent",
2980
- "List trace files for a specific session:\n<%= config.bin %> <%= command.id %> --session-id <SESSION_ID>",
2981
- "List trace files recorded on or after April 20, 2026 (date-only, interpreted as UTC midnight):\n<%= config.bin %> <%= command.id %> --since 2026-04-20",
2982
- "List trace files recorded on or after a specific UTC time:\n<%= config.bin %> <%= command.id %> --since 2026-04-20T14:00:00Z",
2983
- "Filter by agent and date together:\n<%= config.bin %> <%= command.id %> --agent My_Agent --since 2026-04-20",
2984
- "Return results as JSON:\n<%= config.bin %> <%= command.id %> --json"
3033
+ "List the agent tests in your default org:\n<%= config.bin %> <%= command.id %>",
3034
+ "List the agent tests in an org with alias \"my-org\"\"\n<%= config.bin %> <%= command.id %> --target-org my-org"
2985
3035
  ],
2986
3036
  "flags": {
2987
3037
  "json": {
@@ -2999,46 +3049,52 @@
2999
3049
  "multiple": false,
3000
3050
  "type": "option"
3001
3051
  },
3002
- "session-id": {
3003
- "name": "session-id",
3004
- "summary": "Session ID used to filter the list of trace files. Use the \"agent preview sessions\" CLI command to list all known agent preview sessions along with their session IDs.",
3005
- "hasDynamicHelp": false,
3006
- "multiple": false,
3007
- "type": "option"
3008
- },
3009
- "agent": {
3010
- "char": "a",
3011
- "name": "agent",
3012
- "summary": "API name of the agent used to filter the list of available trace files. Matches against the API name used when starting the session, either an authoring bundle or a published agent API name.",
3013
- "hasDynamicHelp": false,
3052
+ "target-org": {
3053
+ "char": "o",
3054
+ "name": "target-org",
3055
+ "noCacheDefault": true,
3056
+ "required": true,
3057
+ "summary": "Username or alias of the target org. Not required if the `target-org` configuration variable is already set.",
3058
+ "hasDynamicHelp": true,
3014
3059
  "multiple": false,
3015
3060
  "type": "option"
3016
3061
  },
3017
- "since": {
3018
- "description": "Accepts ISO 8601 format: date-only (2026-04-20), date-time (2026-04-20T14:00:00Z), or date-time with milliseconds (2026-04-20T14:00:00.000Z). The \"Recorded At\" values shown in the table output are valid inputs.",
3019
- "name": "since",
3020
- "summary": "Date used to filter the list of trace files; only those recorded on or after the date are listed.",
3062
+ "api-version": {
3063
+ "description": "Override the api version used for api requests made by this command",
3064
+ "name": "api-version",
3021
3065
  "hasDynamicHelp": false,
3022
3066
  "multiple": false,
3023
3067
  "type": "option"
3024
3068
  }
3025
3069
  },
3026
- "hasDynamicHelp": false,
3070
+ "hasDynamicHelp": true,
3027
3071
  "hiddenAliases": [],
3028
- "id": "agent:trace:list",
3072
+ "id": "agent:test:list",
3029
3073
  "pluginAlias": "@salesforce/plugin-agent",
3030
3074
  "pluginName": "@salesforce/plugin-agent",
3031
3075
  "pluginType": "core",
3032
3076
  "strict": true,
3033
- "summary": "List the available trace files that were recorded during all agent preview sessions.",
3077
+ "summary": "List the available agent tests in your org.",
3034
3078
  "enableJsonFlag": true,
3035
- "requiresProject": true,
3079
+ "envVariablesSection": {
3080
+ "header": "ENVIRONMENT VARIABLES",
3081
+ "body": [
3082
+ {
3083
+ "name": "SF_TARGET_ORG",
3084
+ "description": "Username or alias of your default org. Overrides the target-org configuration variable."
3085
+ }
3086
+ ]
3087
+ },
3036
3088
  "errorCodes": {
3037
3089
  "header": "ERROR CODES",
3038
3090
  "body": [
3039
3091
  {
3040
3092
  "name": "Succeeded (0)",
3041
- "description": "Trace files listed successfully (or empty list if none found)."
3093
+ "description": "Agent tests listed successfully."
3094
+ },
3095
+ {
3096
+ "name": "Failed (4)",
3097
+ "description": "Failed to retrieve agent tests due to API or network errors."
3042
3098
  }
3043
3099
  ]
3044
3100
  },
@@ -3047,31 +3103,27 @@
3047
3103
  "lib",
3048
3104
  "commands",
3049
3105
  "agent",
3050
- "trace",
3106
+ "test",
3051
3107
  "list.js"
3052
3108
  ],
3053
3109
  "aliasPermutations": [],
3054
3110
  "permutations": [
3055
- "agent:trace:list",
3056
- "trace:agent:list",
3057
- "trace:list:agent",
3058
- "agent:list:trace",
3059
- "list:agent:trace",
3060
- "list:trace:agent"
3111
+ "agent:test:list",
3112
+ "test:agent:list",
3113
+ "test:list:agent",
3114
+ "agent:list:test",
3115
+ "list:agent:test",
3116
+ "list:test:agent"
3061
3117
  ]
3062
3118
  },
3063
- "agent:trace:read": {
3119
+ "agent:test:results": {
3064
3120
  "aliases": [],
3065
3121
  "args": {},
3066
- "description": "When you run an agent preview conversation (either interactive or programmatic), trace files are automatically recorded and saved in your local DX project. Each turn (utterance or response) of a conversation creates trace data. Use this command to view trace data for a specific preview session, so you can then analyze the trace data to observe, monitor, investigate, and troubleshoot agent events and behavior.\n\nUse the --format flag to specify one of these formats of the outputted trace data:\n\n- summary (Default): A per-turn narrative showing topic routing, actions executed, and the agent's response. Use this to quickly understand what happened in a preview session.\n- detail: Diagnostic drill-down into a specific dimension. Filters output to only the trace steps relevant to that dimension, minimizing noise.\n- raw: Unprocessed trace JSON. Use this as a fallback when the trace schema has changed or you need to perform custom analysis.\n\nIf you specify \"--format detail\", you must also specify a dimension with the --dimension flag. Dimensions are a way to slice and analyze the agent execution trace from a specific angle or concern. Instead of looking at the raw sequence of everything that happened, each dimension filters and organizes the trace data to answer a specific type of question. These are the available dimensions and the information they provide:\n\n- actions: The actions the agent executed. Includes action name, input parameters, output, and latency. Use this dimension to understand what the agent actually did when answering an utterance in the preview session.\n- grounding: The reasoning steps used by the LLM. Use this dimension to see how the agent \"thought\" about the problem - the AI reasoning that determined which actions to take.\n- routing: How the agent navigated between subagents. Use this dimension to understand conversation flow - when and why the agent switched between different subagents or contexts during the conversation.\n- errors: Aggregates all errors during the session. Use this dimension to quickly identify and debug issues across all steps.",
3122
+ "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.",
3067
3123
  "examples": [
3068
- "Show a session trace summary for all turns in the session with the specified ID:\n<%= config.bin %> <%= command.id %> --session-id <SESSION_ID>",
3069
- "Show a trace summary for the second turn (utterance or response) of the conversation:\n<%= config.bin %> <%= command.id %> --session-id <SESSION_ID> --turn 2",
3070
- "Drill into action execution across all turns:\n<%= config.bin %> <%= command.id %> --session-id <SESSION_ID> --format detail --dimension actions",
3071
- "Drill into routing decisions for the first turn of the conversation:\n<%= config.bin %> <%= command.id %> --session-id <SESSION_ID> --format detail --dimension routing --turn 1",
3072
- "Show all errors across the session:\n<%= config.bin %> <%= command.id %> --session-id <SESSION_ID> --format detail --dimension errors",
3073
- "Output raw trace JSON for custom parsing:\n<%= config.bin %> <%= command.id %> --session-id <SESSION_ID> --format raw",
3074
- "Return results as JSON:\n<%= config.bin %> <%= command.id %> --session-id <SESSION_ID> --json"
3124
+ "Get the results of an agent test run in your default org using its job ID:\n<%= config.bin %> <%= command.id %> --job-id 4KBfake0000003F4AQ",
3125
+ "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",
3126
+ "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"
3075
3127
  ],
3076
3128
  "flags": {
3077
3129
  "json": {
@@ -3089,89 +3141,136 @@
3089
3141
  "multiple": false,
3090
3142
  "type": "option"
3091
3143
  },
3092
- "session-id": {
3093
- "char": "s",
3094
- "name": "session-id",
3144
+ "target-org": {
3145
+ "char": "o",
3146
+ "name": "target-org",
3147
+ "noCacheDefault": true,
3095
3148
  "required": true,
3096
- "summary": "Session ID to read traces for. Use the \"agent preview sessions\" CLI command to list all known agent preview sessions along with their session IDs",
3097
- "hasDynamicHelp": false,
3149
+ "summary": "Username or alias of the target org. Not required if the `target-org` configuration variable is already set.",
3150
+ "hasDynamicHelp": true,
3098
3151
  "multiple": false,
3099
3152
  "type": "option"
3100
3153
  },
3101
- "format": {
3102
- "char": "f",
3103
- "name": "format",
3104
- "summary": "Output format of the trace data; specifies the level of detail you want in the trace files.",
3105
- "default": "summary",
3154
+ "api-version": {
3155
+ "description": "Override the api version used for api requests made by this command",
3156
+ "name": "api-version",
3106
3157
  "hasDynamicHelp": false,
3107
3158
  "multiple": false,
3108
- "options": [
3109
- "summary",
3110
- "detail",
3111
- "raw"
3112
- ],
3113
3159
  "type": "option"
3114
3160
  },
3115
- "dimension": {
3116
- "char": "d",
3117
- "name": "dimension",
3118
- "summary": "Dimension to drill into when using \"--format detail\"; used to filter and organize the trace data to answer a specific type of question.",
3161
+ "job-id": {
3162
+ "char": "i",
3163
+ "name": "job-id",
3164
+ "required": true,
3165
+ "summary": "Job ID of the completed agent test run.",
3119
3166
  "hasDynamicHelp": false,
3120
3167
  "multiple": false,
3121
- "options": [
3122
- "actions",
3123
- "grounding",
3124
- "routing",
3125
- "errors"
3126
- ],
3127
3168
  "type": "option"
3128
3169
  },
3129
- "turn": {
3130
- "char": "t",
3131
- "name": "turn",
3132
- "summary": "Turn number for which you want trace data. A turn is a single utterance or response in a conversation, starting with 1.",
3133
- "hasDynamicHelp": false,
3134
- "multiple": false,
3135
- "type": "option"
3170
+ "result-format": {
3171
+ "name": "result-format",
3172
+ "summary": "Format of the agent test run results.",
3173
+ "default": "human",
3174
+ "hasDynamicHelp": false,
3175
+ "multiple": false,
3176
+ "options": [
3177
+ "json",
3178
+ "human",
3179
+ "junit",
3180
+ "tap"
3181
+ ],
3182
+ "type": "option"
3183
+ },
3184
+ "output-dir": {
3185
+ "char": "d",
3186
+ "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.",
3187
+ "name": "output-dir",
3188
+ "summary": "Directory to write the agent test results into.",
3189
+ "hasDynamicHelp": false,
3190
+ "multiple": false,
3191
+ "type": "option"
3192
+ },
3193
+ "test-runner": {
3194
+ "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.",
3195
+ "name": "test-runner",
3196
+ "summary": "Explicitly specify which test runner to use (agentforce-studio or testing-center).",
3197
+ "hasDynamicHelp": false,
3198
+ "multiple": false,
3199
+ "options": [
3200
+ "agentforce-studio",
3201
+ "testing-center"
3202
+ ],
3203
+ "type": "option"
3204
+ },
3205
+ "verbose": {
3206
+ "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.",
3207
+ "name": "verbose",
3208
+ "summary": "Show generated data in the test results output.",
3209
+ "allowNo": false,
3210
+ "type": "boolean"
3136
3211
  }
3137
3212
  },
3138
- "hasDynamicHelp": false,
3213
+ "hasDynamicHelp": true,
3139
3214
  "hiddenAliases": [],
3140
- "id": "agent:trace:read",
3215
+ "id": "agent:test:results",
3141
3216
  "pluginAlias": "@salesforce/plugin-agent",
3142
3217
  "pluginName": "@salesforce/plugin-agent",
3143
3218
  "pluginType": "core",
3144
3219
  "strict": true,
3145
- "summary": "Read trace files from an agent preview session.",
3220
+ "summary": "Get the results of a completed agent test run.",
3146
3221
  "enableJsonFlag": true,
3147
- "requiresProject": true,
3222
+ "envVariablesSection": {
3223
+ "header": "ENVIRONMENT VARIABLES",
3224
+ "body": [
3225
+ {
3226
+ "name": "SF_TARGET_ORG",
3227
+ "description": "Username or alias of your default org. Overrides the target-org configuration variable."
3228
+ }
3229
+ ]
3230
+ },
3231
+ "errorCodes": {
3232
+ "header": "ERROR CODES",
3233
+ "body": [
3234
+ {
3235
+ "name": "Succeeded (0)",
3236
+ "description": "Results retrieved successfully. Test results (passed/failed) are in the output."
3237
+ },
3238
+ {
3239
+ "name": "NotFound (2)",
3240
+ "description": "Job ID not found or invalid."
3241
+ },
3242
+ {
3243
+ "name": "Failed (4)",
3244
+ "description": "Failed to retrieve results due to API or network errors."
3245
+ }
3246
+ ]
3247
+ },
3148
3248
  "isESM": true,
3149
3249
  "relativePath": [
3150
3250
  "lib",
3151
3251
  "commands",
3152
3252
  "agent",
3153
- "trace",
3154
- "read.js"
3253
+ "test",
3254
+ "results.js"
3155
3255
  ],
3156
3256
  "aliasPermutations": [],
3157
3257
  "permutations": [
3158
- "agent:trace:read",
3159
- "trace:agent:read",
3160
- "trace:read:agent",
3161
- "agent:read:trace",
3162
- "read:agent:trace",
3163
- "read:trace:agent"
3258
+ "agent:test:results",
3259
+ "test:agent:results",
3260
+ "test:results:agent",
3261
+ "agent:results:test",
3262
+ "results:agent:test",
3263
+ "results:test:agent"
3164
3264
  ]
3165
3265
  },
3166
- "agent:test:create": {
3266
+ "agent:test:resume": {
3167
3267
  "aliases": [],
3168
3268
  "args": {},
3169
- "description": "To run this command, you must have an agent test spec file, which is a YAML file that lists the test cases for testing a specific agent. Use the \"agent generate test-spec\" CLI command to generate a test spec file. Then specify the file to this command with the --spec flag, or run this command with no flags to be prompted.\n\nWhen this command completes, your org contains the new agent test, which you can view and edit using the Testing Center UI (legacy) or Agentforce Studio (NGT). This command also retrieves the metadata component associated with the new test to your local Salesforce DX project and displays its filename. By default, the legacy AiEvaluationDefinition is created; use --test-runner agentforce-studio to author an AiTestingDefinition (NGT) instead.\n\nAfter you've created the test in the org, use the \"agent test run\" command to run it.",
3269
+ "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.",
3170
3270
  "examples": [
3171
- "Create an agent test interactively and be prompted for the test spec and API name of the test in the org; use the default org:\n<%= config.bin %> <%= command.id %>",
3172
- "Create an agent test and use flags to specify all required information; if a test with same API name already exists in the org, overwrite it without confirmation. Use the org with alias \"my-org\":\n<%= config.bin %> <%= command.id %> --spec specs/Resort_Manager-testSpec.yaml --api-name Resort_Manager_Test --force-overwrite --target-org my-org",
3173
- "Preview what the agent test metadata (AiEvaluationDefinition) looks like without deploying it to your default org:\n<%= config.bin %> <%= command.id %> --spec specs/Resort_Manager-testSpec.yaml --api-name Resort_Manager_Test --preview",
3174
- "Author an Agentforce Studio (NGT) test from an NGT-shaped YAML; writes an AiTestingDefinition metadata file:\n<%= config.bin %> <%= command.id %> --spec specs/ReturnsCheckout.ngt.yaml --api-name Returns_Checkout --test-runner agentforce-studio --target-org my-org"
3271
+ "Resume an agent test in your default org using a job ID:\n<%= config.bin %> <%= command.id %> --job-id 4KBfake0000003F4AQ",
3272
+ "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",
3273
+ "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"
3175
3274
  ],
3176
3275
  "flags": {
3177
3276
  "json": {
@@ -3189,20 +3288,6 @@
3189
3288
  "multiple": false,
3190
3289
  "type": "option"
3191
3290
  },
3192
- "api-name": {
3193
- "name": "api-name",
3194
- "summary": "API name of the new test; the API name must not exist in the org.",
3195
- "hasDynamicHelp": false,
3196
- "multiple": false,
3197
- "type": "option"
3198
- },
3199
- "spec": {
3200
- "name": "spec",
3201
- "summary": "Path to the test spec YAML file.",
3202
- "hasDynamicHelp": false,
3203
- "multiple": false,
3204
- "type": "option"
3205
- },
3206
3291
  "target-org": {
3207
3292
  "char": "o",
3208
3293
  "name": "target-org",
@@ -3220,18 +3305,53 @@
3220
3305
  "multiple": false,
3221
3306
  "type": "option"
3222
3307
  },
3223
- "preview": {
3224
- "name": "preview",
3225
- "summary": "Preview the test metadata file without deploying to your org.",
3226
- "allowNo": false,
3227
- "type": "boolean"
3308
+ "job-id": {
3309
+ "char": "i",
3310
+ "name": "job-id",
3311
+ "summary": "Job ID of the original agent test run.",
3312
+ "hasDynamicHelp": false,
3313
+ "multiple": false,
3314
+ "type": "option"
3228
3315
  },
3229
- "force-overwrite": {
3230
- "name": "force-overwrite",
3231
- "summary": "Don't prompt for confirmation when overwriting an existing test (based on API name) in your org.",
3316
+ "use-most-recent": {
3317
+ "char": "r",
3318
+ "name": "use-most-recent",
3319
+ "summary": "Use the job ID of the most recent agent test run.",
3232
3320
  "allowNo": false,
3233
3321
  "type": "boolean"
3234
3322
  },
3323
+ "wait": {
3324
+ "char": "w",
3325
+ "name": "wait",
3326
+ "summary": "Number of minutes to wait for the command to complete and display results to the terminal window.",
3327
+ "default": "5 minutes",
3328
+ "hasDynamicHelp": true,
3329
+ "multiple": false,
3330
+ "type": "option"
3331
+ },
3332
+ "result-format": {
3333
+ "name": "result-format",
3334
+ "summary": "Format of the agent test run results.",
3335
+ "default": "human",
3336
+ "hasDynamicHelp": false,
3337
+ "multiple": false,
3338
+ "options": [
3339
+ "json",
3340
+ "human",
3341
+ "junit",
3342
+ "tap"
3343
+ ],
3344
+ "type": "option"
3345
+ },
3346
+ "output-dir": {
3347
+ "char": "d",
3348
+ "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.",
3349
+ "name": "output-dir",
3350
+ "summary": "Directory to write the agent test results into.",
3351
+ "hasDynamicHelp": false,
3352
+ "multiple": false,
3353
+ "type": "option"
3354
+ },
3235
3355
  "test-runner": {
3236
3356
  "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.",
3237
3357
  "name": "test-runner",
@@ -3243,16 +3363,23 @@
3243
3363
  "testing-center"
3244
3364
  ],
3245
3365
  "type": "option"
3366
+ },
3367
+ "verbose": {
3368
+ "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.",
3369
+ "name": "verbose",
3370
+ "summary": "Show generated data in the test results output.",
3371
+ "allowNo": false,
3372
+ "type": "boolean"
3246
3373
  }
3247
3374
  },
3248
3375
  "hasDynamicHelp": true,
3249
3376
  "hiddenAliases": [],
3250
- "id": "agent:test:create",
3377
+ "id": "agent:test:resume",
3251
3378
  "pluginAlias": "@salesforce/plugin-agent",
3252
3379
  "pluginName": "@salesforce/plugin-agent",
3253
3380
  "pluginType": "core",
3254
3381
  "strict": true,
3255
- "summary": "Create an agent test in your org using a local test spec YAML file.",
3382
+ "summary": "Resume an agent test that you previously started in your org so you can view the test results.",
3256
3383
  "enableJsonFlag": true,
3257
3384
  "envVariablesSection": {
3258
3385
  "header": "ENVIRONMENT VARIABLES",
@@ -3268,19 +3395,19 @@
3268
3395
  "body": [
3269
3396
  {
3270
3397
  "name": "Succeeded (0)",
3271
- "description": "Test created and deployed successfully."
3398
+ "description": "Test completed successfully (with test results in the output)."
3272
3399
  },
3273
3400
  {
3274
3401
  "name": "Failed (1)",
3275
- "description": "Test validation errors or metadata format issues."
3402
+ "description": "Tests encountered execution errors (test cases with ERROR status)."
3276
3403
  },
3277
3404
  {
3278
3405
  "name": "NotFound (2)",
3279
- "description": "Test spec file not found or org connection failed."
3406
+ "description": "Job ID not found or invalid."
3280
3407
  },
3281
3408
  {
3282
- "name": "DeploymentFailed (4)",
3283
- "description": "Deployment failed due to API or network errors."
3409
+ "name": "OperationFailed (4)",
3410
+ "description": "Failed to poll test due to API or network errors."
3284
3411
  }
3285
3412
  ]
3286
3413
  },
@@ -3290,25 +3417,29 @@
3290
3417
  "commands",
3291
3418
  "agent",
3292
3419
  "test",
3293
- "create.js"
3420
+ "resume.js"
3294
3421
  ],
3295
3422
  "aliasPermutations": [],
3296
3423
  "permutations": [
3297
- "agent:test:create",
3298
- "test:agent:create",
3299
- "test:create:agent",
3300
- "agent:create:test",
3301
- "create:agent:test",
3302
- "create:test:agent"
3424
+ "agent:test:resume",
3425
+ "test:agent:resume",
3426
+ "test:resume:agent",
3427
+ "agent:resume:test",
3428
+ "resume:agent:test",
3429
+ "resume:test:agent"
3303
3430
  ]
3304
3431
  },
3305
- "agent:test:list": {
3432
+ "agent:test:run-eval": {
3306
3433
  "aliases": [],
3307
3434
  "args": {},
3308
- "description": "The command outputs a table with the name (API name) of each test along with its unique ID, type ('agentforce-studio' or 'testing-center'), and the date it was created in the org.",
3435
+ "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.",
3309
3436
  "examples": [
3310
- "List the agent tests in your default org:\n<%= config.bin %> <%= command.id %>",
3311
- "List the agent tests in an org with alias \"my-org\"\"\n<%= config.bin %> <%= command.id %> --target-org my-org"
3437
+ "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",
3438
+ "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",
3439
+ "Run tests using a JSON payload:\n<%= config.bin %> <%= command.id %> --spec specs/eval-payload.json --target-org my-org",
3440
+ "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",
3441
+ "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",
3442
+ "Pipe JSON payload from stdin (--spec flag is automatically populated from stdin):\n$ echo '{\"tests\":[...]}' | <%= config.bin %> <%= command.id %> --spec --target-org my-org"
3312
3443
  ],
3313
3444
  "flags": {
3314
3445
  "json": {
@@ -3342,104 +3473,20 @@
3342
3473
  "hasDynamicHelp": false,
3343
3474
  "multiple": false,
3344
3475
  "type": "option"
3345
- }
3346
- },
3347
- "hasDynamicHelp": true,
3348
- "hiddenAliases": [],
3349
- "id": "agent:test:list",
3350
- "pluginAlias": "@salesforce/plugin-agent",
3351
- "pluginName": "@salesforce/plugin-agent",
3352
- "pluginType": "core",
3353
- "strict": true,
3354
- "summary": "List the available agent tests in your org.",
3355
- "enableJsonFlag": true,
3356
- "envVariablesSection": {
3357
- "header": "ENVIRONMENT VARIABLES",
3358
- "body": [
3359
- {
3360
- "name": "SF_TARGET_ORG",
3361
- "description": "Username or alias of your default org. Overrides the target-org configuration variable."
3362
- }
3363
- ]
3364
- },
3365
- "errorCodes": {
3366
- "header": "ERROR CODES",
3367
- "body": [
3368
- {
3369
- "name": "Succeeded (0)",
3370
- "description": "Agent tests listed successfully."
3371
- },
3372
- {
3373
- "name": "Failed (4)",
3374
- "description": "Failed to retrieve agent tests due to API or network errors."
3375
- }
3376
- ]
3377
- },
3378
- "isESM": true,
3379
- "relativePath": [
3380
- "lib",
3381
- "commands",
3382
- "agent",
3383
- "test",
3384
- "list.js"
3385
- ],
3386
- "aliasPermutations": [],
3387
- "permutations": [
3388
- "agent:test:list",
3389
- "test:agent:list",
3390
- "test:list:agent",
3391
- "agent:list:test",
3392
- "list:agent:test",
3393
- "list:test:agent"
3394
- ]
3395
- },
3396
- "agent:test:results": {
3397
- "aliases": [],
3398
- "args": {},
3399
- "description": "This command requires a job ID, which the original \"agent test run\" command displays when it completes. You can also use the --use-most-recent flag to see results for the most recently run agent test.\n\nBy default, this command outputs test results in human-readable tables for each test case. The tables show whether the test case passed, the expected and actual values, the test score, how long the test took, and more. Use the --result-format to display the test results in JSON or Junit format. Use the --output-dir flag to write the results to a file rather than to the terminal.",
3400
- "examples": [
3401
- "Get the results of an agent test run in your default org using its job ID:\n<%= config.bin %> <%= command.id %> --job-id 4KBfake0000003F4AQ",
3402
- "Get the results of the most recently run agent test in an org with alias \"my-org\":\n<%= config.bin %> <%= command.id %> --use-most-recent --target-org my-org",
3403
- "Get the results of the most recently run agent test in your default org, and write the JSON-formatted results into a directory called \"test-results\":\n<%= config.bin %> <%= command.id %> --use-most-recent --output-dir ./test-results --result-format json"
3404
- ],
3405
- "flags": {
3406
- "json": {
3407
- "description": "Format output as json.",
3408
- "helpGroup": "GLOBAL",
3409
- "name": "json",
3410
- "allowNo": false,
3411
- "type": "boolean"
3412
- },
3413
- "flags-dir": {
3414
- "helpGroup": "GLOBAL",
3415
- "name": "flags-dir",
3416
- "summary": "Import flag values from a directory.",
3417
- "hasDynamicHelp": false,
3418
- "multiple": false,
3419
- "type": "option"
3420
3476
  },
3421
- "target-org": {
3422
- "char": "o",
3423
- "name": "target-org",
3424
- "noCacheDefault": true,
3477
+ "spec": {
3478
+ "char": "s",
3479
+ "name": "spec",
3425
3480
  "required": true,
3426
- "summary": "Username or alias of the target org. Not required if the `target-org` configuration variable is already set.",
3427
- "hasDynamicHelp": true,
3428
- "multiple": false,
3429
- "type": "option"
3430
- },
3431
- "api-version": {
3432
- "description": "Override the api version used for api requests made by this command",
3433
- "name": "api-version",
3481
+ "summary": "Path to test spec file (YAML or JSON). Supports reading from stdin when piping content.",
3434
3482
  "hasDynamicHelp": false,
3435
3483
  "multiple": false,
3436
3484
  "type": "option"
3437
3485
  },
3438
- "job-id": {
3439
- "char": "i",
3440
- "name": "job-id",
3441
- "required": true,
3442
- "summary": "Job ID of the completed agent test run.",
3486
+ "api-name": {
3487
+ "char": "n",
3488
+ "name": "api-name",
3489
+ "summary": "Agent API name (also called DeveloperName) used to resolve agent_id and agent_version_id. Auto-inferred from the YAML spec's subjectName.",
3443
3490
  "hasDynamicHelp": false,
3444
3491
  "multiple": false,
3445
3492
  "type": "option"
@@ -3458,43 +3505,30 @@
3458
3505
  ],
3459
3506
  "type": "option"
3460
3507
  },
3461
- "output-dir": {
3462
- "char": "d",
3463
- "description": "If the agent test run completes, write the results to the specified directory. If the test is still running, the test results aren't written.",
3464
- "name": "output-dir",
3465
- "summary": "Directory to write the agent test results into.",
3466
- "hasDynamicHelp": false,
3467
- "multiple": false,
3468
- "type": "option"
3469
- },
3470
- "test-runner": {
3471
- "description": "By default, the command automatically detects which test runner to use based on the test definition metadata type in your org. Use this flag to explicitly specify the runner type. 'agentforce-studio' uses AiTestingDefinition metadata. 'testing-center' uses AiEvaluationDefinition metadata.",
3472
- "name": "test-runner",
3473
- "summary": "Explicitly specify which test runner to use (agentforce-studio or testing-center).",
3508
+ "batch-size": {
3509
+ "name": "batch-size",
3510
+ "summary": "Number of tests per API request (max 5).",
3511
+ "default": 5,
3474
3512
  "hasDynamicHelp": false,
3475
3513
  "multiple": false,
3476
- "options": [
3477
- "agentforce-studio",
3478
- "testing-center"
3479
- ],
3480
3514
  "type": "option"
3481
3515
  },
3482
- "verbose": {
3483
- "description": "When enabled, includes detailed generated data (such as invoked actions) in the human-readable test results output. This is useful for debugging test failures and understanding what actions were actually invoked during the test run.\n\nThe generated data is in JSON format and includes the Apex classes or Flows that were invoked, the Salesforce objects that were touched, and so on. Use the JSON structure of this information to build the test case JSONPath expression when using custom evaluations.",
3484
- "name": "verbose",
3485
- "summary": "Show generated data in the test results output.",
3516
+ "no-normalize": {
3517
+ "name": "no-normalize",
3518
+ "summary": "Disable auto-normalization of field names and shorthand references.",
3486
3519
  "allowNo": false,
3487
3520
  "type": "boolean"
3488
3521
  }
3489
3522
  },
3490
3523
  "hasDynamicHelp": true,
3491
3524
  "hiddenAliases": [],
3492
- "id": "agent:test:results",
3525
+ "id": "agent:test:run-eval",
3493
3526
  "pluginAlias": "@salesforce/plugin-agent",
3494
3527
  "pluginName": "@salesforce/plugin-agent",
3495
3528
  "pluginType": "core",
3529
+ "state": "beta",
3496
3530
  "strict": true,
3497
- "summary": "Get the results of a completed agent test run.",
3531
+ "summary": "Run rich evaluation tests against an Agentforce agent.",
3498
3532
  "enableJsonFlag": true,
3499
3533
  "envVariablesSection": {
3500
3534
  "header": "ENVIRONMENT VARIABLES",
@@ -3510,15 +3544,19 @@
3510
3544
  "body": [
3511
3545
  {
3512
3546
  "name": "Succeeded (0)",
3513
- "description": "Results retrieved successfully. Test results (passed/failed) are in the output."
3547
+ "description": "Tests completed successfully. Test results (passed/failed) are in the JSON output."
3548
+ },
3549
+ {
3550
+ "name": "Failed (1)",
3551
+ "description": "Tests encountered execution errors (tests couldn't run properly)."
3514
3552
  },
3515
3553
  {
3516
3554
  "name": "NotFound (2)",
3517
- "description": "Job ID not found or invalid."
3555
+ "description": "Agent not found, spec file not found, or invalid agent name."
3518
3556
  },
3519
3557
  {
3520
- "name": "Failed (4)",
3521
- "description": "Failed to retrieve results due to API or network errors."
3558
+ "name": "OperationFailed (4)",
3559
+ "description": "Failed to execute tests due to API or network errors."
3522
3560
  }
3523
3561
  ]
3524
3562
  },
@@ -3528,26 +3566,26 @@
3528
3566
  "commands",
3529
3567
  "agent",
3530
3568
  "test",
3531
- "results.js"
3569
+ "run-eval.js"
3532
3570
  ],
3533
3571
  "aliasPermutations": [],
3534
3572
  "permutations": [
3535
- "agent:test:results",
3536
- "test:agent:results",
3537
- "test:results:agent",
3538
- "agent:results:test",
3539
- "results:agent:test",
3540
- "results:test:agent"
3573
+ "agent:test:run-eval",
3574
+ "test:agent:run-eval",
3575
+ "test:run-eval:agent",
3576
+ "agent:run-eval:test",
3577
+ "run-eval:agent:test",
3578
+ "run-eval:test:agent"
3541
3579
  ]
3542
3580
  },
3543
- "agent:test:resume": {
3581
+ "agent:test:run": {
3544
3582
  "aliases": [],
3545
3583
  "args": {},
3546
- "description": "This command requires a job ID, which the original \"agent test run\" command displays when it completes. You can also use the --use-most-recent flag to see results for the most recently run agent test.\n\nUse the --wait flag to specify the number of minutes for this command to wait for the agent test to complete; if the test completes by the end of the wait time, the command displays the test results. If not, the CLI returns control of the terminal to you, and you must run \"agent test resume\" again.\n\nBy default, this command outputs test results in human-readable tables for each test case. The tables show whether the test case passed, the expected and actual values, the test score, how long the test took, and more. Use the --result-format to display the test results in JSON or Junit format. Use the --output-dir flag to write the results to a file rather than to the terminal.",
3584
+ "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.",
3547
3585
  "examples": [
3548
- "Resume an agent test in your default org using a job ID:\n<%= config.bin %> <%= command.id %> --job-id 4KBfake0000003F4AQ",
3549
- "Resume the most recently-run agent test in an org with alias \"my-org\" org; wait 10 minutes for the tests to finish:\n<%= config.bin %> <%= command.id %> --use-most-recent --wait 10 --target-org my-org",
3550
- "Resume the most recent agent test in your default org, and write the JSON-formatted results into a directory called \"test-results\":\n<%= config.bin %> <%= command.id %> --use-most-recent --output-dir ./test-results --result-format json"
3586
+ "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",
3587
+ "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",
3588
+ "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"
3551
3589
  ],
3552
3590
  "flags": {
3553
3591
  "json": {
@@ -3582,26 +3620,18 @@
3582
3620
  "multiple": false,
3583
3621
  "type": "option"
3584
3622
  },
3585
- "job-id": {
3586
- "char": "i",
3587
- "name": "job-id",
3588
- "summary": "Job ID of the original agent test run.",
3623
+ "api-name": {
3624
+ "char": "n",
3625
+ "name": "api-name",
3626
+ "summary": "API name of the agent test to run; corresponds to the name of the AiEvaluationDefinition metadata component that implements the agent test.",
3589
3627
  "hasDynamicHelp": false,
3590
3628
  "multiple": false,
3591
3629
  "type": "option"
3592
3630
  },
3593
- "use-most-recent": {
3594
- "char": "r",
3595
- "name": "use-most-recent",
3596
- "summary": "Use the job ID of the most recent agent test run.",
3597
- "allowNo": false,
3598
- "type": "boolean"
3599
- },
3600
3631
  "wait": {
3601
3632
  "char": "w",
3602
3633
  "name": "wait",
3603
3634
  "summary": "Number of minutes to wait for the command to complete and display results to the terminal window.",
3604
- "default": "5 minutes",
3605
3635
  "hasDynamicHelp": true,
3606
3636
  "multiple": false,
3607
3637
  "type": "option"
@@ -3651,12 +3681,12 @@
3651
3681
  },
3652
3682
  "hasDynamicHelp": true,
3653
3683
  "hiddenAliases": [],
3654
- "id": "agent:test:resume",
3684
+ "id": "agent:test:run",
3655
3685
  "pluginAlias": "@salesforce/plugin-agent",
3656
3686
  "pluginName": "@salesforce/plugin-agent",
3657
3687
  "pluginType": "core",
3658
3688
  "strict": true,
3659
- "summary": "Resume an agent test that you previously started in your org so you can view the test results.",
3689
+ "summary": "Start an agent test in your org.",
3660
3690
  "enableJsonFlag": true,
3661
3691
  "envVariablesSection": {
3662
3692
  "header": "ENVIRONMENT VARIABLES",
@@ -3672,19 +3702,19 @@
3672
3702
  "body": [
3673
3703
  {
3674
3704
  "name": "Succeeded (0)",
3675
- "description": "Test completed successfully (with test results in the output)."
3705
+ "description": "Test started successfully (without --wait), or test completed successfully (with --wait)."
3676
3706
  },
3677
3707
  {
3678
3708
  "name": "Failed (1)",
3679
- "description": "Tests encountered execution errors (test cases with ERROR status)."
3709
+ "description": "Tests encountered execution errors (test cases with ERROR status when using --wait)."
3680
3710
  },
3681
3711
  {
3682
3712
  "name": "NotFound (2)",
3683
- "description": "Job ID not found or invalid."
3713
+ "description": "Test definition not found or invalid test name."
3684
3714
  },
3685
3715
  {
3686
3716
  "name": "OperationFailed (4)",
3687
- "description": "Failed to poll test due to API or network errors."
3717
+ "description": "Failed to start or poll test due to API or network errors."
3688
3718
  }
3689
3719
  ]
3690
3720
  },
@@ -3694,29 +3724,29 @@
3694
3724
  "commands",
3695
3725
  "agent",
3696
3726
  "test",
3697
- "resume.js"
3727
+ "run.js"
3698
3728
  ],
3699
3729
  "aliasPermutations": [],
3700
3730
  "permutations": [
3701
- "agent:test:resume",
3702
- "test:agent:resume",
3703
- "test:resume:agent",
3704
- "agent:resume:test",
3705
- "resume:agent:test",
3706
- "resume:test:agent"
3731
+ "agent:test:run",
3732
+ "test:agent:run",
3733
+ "test:run:agent",
3734
+ "agent:run:test",
3735
+ "run:agent:test",
3736
+ "run:test:agent"
3707
3737
  ]
3708
3738
  },
3709
- "agent:test:run-eval": {
3739
+ "agent:trace:delete": {
3710
3740
  "aliases": [],
3711
3741
  "args": {},
3712
- "description": "Specify the tests you want to run with one of these inputs to the --spec flag:\n\n- YAML test spec generated by the `agent generate test-spec` CLI command\n- JSON payload\n\nWhen you provide a YAML test spec, this command automatically translates test cases into internal state-based evaluation framework calls and infers the agent name from the test spec's `subjectName` field. As a result, you can use the same test spec with both the `agent test run` and `agent test run-eval` commands. YAML test specs also support context variables, which allow you to inject contextual data (such as CaseId or RoutableId) into agent sessions for testing with different contexts.\n\nWhen you provide a JSON payload, it's sent directly to the evaluation framework with optional normalization. The normalizer auto-corrects common field name mistakes, converts shorthand references to JSONPath, and injects defaults. Use `--no-normalize` to disable this auto-normalization. JSON payloads can also include context_variables on agent.create_session steps for the same contextual testing capabilities as when you use a YAML test spec.\n\nThis command supports more than 8 evaluator types, including subagent routing assertions, action invocation checks, string/numeric assertions, semantic similarity scoring, and LLM-based quality ratings.",
3742
+ "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).",
3713
3743
  "examples": [
3714
- "Run tests using a YAML test spec on the org with alias \"my-org\":\n<%= config.bin %> <%= command.id %> --spec specs/my-agent-testSpec.yaml --target-org my-org",
3715
- "Run tests using a YAML spec with explicit agent name override; use your default org:\n<%= config.bin %> <%= command.id %> --spec specs/my-agent-testSpec.yaml --api-name My_Agent",
3716
- "Run tests using a JSON payload:\n<%= config.bin %> <%= command.id %> --spec specs/eval-payload.json --target-org my-org",
3717
- "Run tests and output results in JUnit format; useful for continuous integration and deployment (CI/CD):\n<%= config.bin %> <%= command.id %> --spec specs/my-agent-testSpec.yaml --target-org my-org --result-format junit",
3718
- "Run tests with contextVariables to inject contextual data into agent sessions (add contextVariables to test cases in your YAML spec):\n<%= config.bin %> <%= command.id %> --spec specs/agent-with-context.yaml --target-org my-org",
3719
- "Pipe JSON payload from stdin (--spec flag is automatically populated from stdin):\n$ echo '{\"tests\":[...]}' | <%= config.bin %> <%= command.id %> --spec --target-org my-org"
3744
+ "Delete all traces for all agents and sessions; prompt for confirmation:\n<%= config.bin %> <%= command.id %>",
3745
+ "Delete all traces for a specific agent:\n<%= config.bin %> <%= command.id %> --agent My_Agent",
3746
+ "Delete traces from a specific session:\n<%= config.bin %> <%= command.id %> --session-id <SESSION_ID>",
3747
+ "Delete traces older than 7 days:\n<%= config.bin %> <%= command.id %> --older-than 7d",
3748
+ "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",
3749
+ "Delete all traces for all agents and sessions; don't prompt for confirmation:\n<%= config.bin %> <%= command.id %> --no-prompt"
3720
3750
  ],
3721
3751
  "flags": {
3722
3752
  "json": {
@@ -3734,106 +3764,51 @@
3734
3764
  "multiple": false,
3735
3765
  "type": "option"
3736
3766
  },
3737
- "target-org": {
3738
- "char": "o",
3739
- "name": "target-org",
3740
- "noCacheDefault": true,
3741
- "required": true,
3742
- "summary": "Username or alias of the target org. Not required if the `target-org` configuration variable is already set.",
3743
- "hasDynamicHelp": true,
3744
- "multiple": false,
3745
- "type": "option"
3746
- },
3747
- "api-version": {
3748
- "description": "Override the api version used for api requests made by this command",
3749
- "name": "api-version",
3750
- "hasDynamicHelp": false,
3751
- "multiple": false,
3752
- "type": "option"
3753
- },
3754
- "spec": {
3755
- "char": "s",
3756
- "name": "spec",
3757
- "required": true,
3758
- "summary": "Path to test spec file (YAML or JSON). Supports reading from stdin when piping content.",
3759
- "hasDynamicHelp": false,
3760
- "multiple": false,
3761
- "type": "option"
3762
- },
3763
- "api-name": {
3764
- "char": "n",
3765
- "name": "api-name",
3766
- "summary": "Agent API name (also called DeveloperName) used to resolve agent_id and agent_version_id. Auto-inferred from the YAML spec's subjectName.",
3767
+ "agent": {
3768
+ "char": "a",
3769
+ "name": "agent",
3770
+ "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.",
3767
3771
  "hasDynamicHelp": false,
3768
3772
  "multiple": false,
3769
3773
  "type": "option"
3770
3774
  },
3771
- "result-format": {
3772
- "name": "result-format",
3773
- "summary": "Format of the agent test run results.",
3774
- "default": "human",
3775
+ "session-id": {
3776
+ "name": "session-id",
3777
+ "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.",
3775
3778
  "hasDynamicHelp": false,
3776
3779
  "multiple": false,
3777
- "options": [
3778
- "json",
3779
- "human",
3780
- "junit",
3781
- "tap"
3782
- ],
3783
3780
  "type": "option"
3784
3781
  },
3785
- "batch-size": {
3786
- "name": "batch-size",
3787
- "summary": "Number of tests per API request (max 5).",
3788
- "default": 5,
3782
+ "older-than": {
3783
+ "name": "older-than",
3784
+ "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.",
3789
3785
  "hasDynamicHelp": false,
3790
3786
  "multiple": false,
3791
3787
  "type": "option"
3792
3788
  },
3793
- "no-normalize": {
3794
- "name": "no-normalize",
3795
- "summary": "Disable auto-normalization of field names and shorthand references.",
3789
+ "no-prompt": {
3790
+ "name": "no-prompt",
3791
+ "summary": "Skip the confirmation prompt and delete immediately.",
3796
3792
  "allowNo": false,
3797
3793
  "type": "boolean"
3798
3794
  }
3799
3795
  },
3800
- "hasDynamicHelp": true,
3796
+ "hasDynamicHelp": false,
3801
3797
  "hiddenAliases": [],
3802
- "id": "agent:test:run-eval",
3798
+ "id": "agent:trace:delete",
3803
3799
  "pluginAlias": "@salesforce/plugin-agent",
3804
3800
  "pluginName": "@salesforce/plugin-agent",
3805
3801
  "pluginType": "core",
3806
- "state": "beta",
3807
3802
  "strict": true,
3808
- "summary": "Run rich evaluation tests against an Agentforce agent.",
3803
+ "summary": "Delete trace files from an agent preview session.",
3809
3804
  "enableJsonFlag": true,
3810
- "envVariablesSection": {
3811
- "header": "ENVIRONMENT VARIABLES",
3812
- "body": [
3813
- {
3814
- "name": "SF_TARGET_ORG",
3815
- "description": "Username or alias of your default org. Overrides the target-org configuration variable."
3816
- }
3817
- ]
3818
- },
3805
+ "requiresProject": true,
3819
3806
  "errorCodes": {
3820
3807
  "header": "ERROR CODES",
3821
3808
  "body": [
3822
3809
  {
3823
3810
  "name": "Succeeded (0)",
3824
- "description": "Tests completed successfully. Test results (passed/failed) are in the JSON output."
3825
- },
3826
- {
3827
- "name": "Failed (1)",
3828
- "description": "Tests encountered execution errors (tests couldn't run properly)."
3829
- },
3830
- {
3831
- "name": "NotFound (2)",
3832
- "description": "Agent not found, spec file not found, or invalid agent name."
3833
- },
3834
- {
3835
- "name": "OperationFailed (4)",
3836
- "description": "Failed to execute tests due to API or network errors."
3811
+ "description": "Traces deleted successfully (or no traces matched)."
3837
3812
  }
3838
3813
  ]
3839
3814
  },
@@ -3842,27 +3817,31 @@
3842
3817
  "lib",
3843
3818
  "commands",
3844
3819
  "agent",
3845
- "test",
3846
- "run-eval.js"
3820
+ "trace",
3821
+ "delete.js"
3847
3822
  ],
3848
3823
  "aliasPermutations": [],
3849
3824
  "permutations": [
3850
- "agent:test:run-eval",
3851
- "test:agent:run-eval",
3852
- "test:run-eval:agent",
3853
- "agent:run-eval:test",
3854
- "run-eval:agent:test",
3855
- "run-eval:test:agent"
3825
+ "agent:trace:delete",
3826
+ "trace:agent:delete",
3827
+ "trace:delete:agent",
3828
+ "agent:delete:trace",
3829
+ "delete:agent:trace",
3830
+ "delete:trace:agent"
3856
3831
  ]
3857
3832
  },
3858
- "agent:test:run": {
3833
+ "agent:trace:list": {
3859
3834
  "aliases": [],
3860
3835
  "args": {},
3861
- "description": "Use the --api-name flag to specify the name of the agent test you want to run. Use the output of the \"agent test list\" command to get the names of all the available agent tests in your org.\n\nBy default, this command starts the agent test in your org, but it doesn't wait for the test to finish. Instead, it displays the \"agent test resume\" command, with a job ID, that you execute to see the results of the test run, and then returns control of the terminal window to you. Use the --wait flag to specify the number of minutes for the command to wait for the agent test to complete; if the test completes by the end of the wait time, the command displays the test results. If not, run \"agent test resume\".\n\nBy default, this command outputs test results in human-readable tables for each test case, if the test completes in time. The tables show whether the test case passed, the expected and actual values, the test score, how long the test took, and more. Use the --result-format to display the test results in JSON or Junit format. Use the --output-dir flag to write the results to a file rather than to the terminal.",
3836
+ "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.",
3862
3837
  "examples": [
3863
- "Start an agent test called Resort_Manager_Test for an agent in your default org, don't wait for the test to finish:\n<%= config.bin %> <%= command.id %> --api-name Resort_Manager_Test",
3864
- "Start an agent test for an agent in an org with alias \"my-org\" and wait for 10 minutes for the test to finish:\n<%= config.bin %> <%= command.id %> --api-name Resort_Manager_Test --wait 10 --target-org my-org",
3865
- "Start an agent test and write the JSON-formatted results into a directory called \"test-results\":\n<%= config.bin %> <%= command.id %> --api-name Resort_Manager_Test --wait 10 --output-dir ./test-results --result-format json"
3838
+ "List all trace files for all agents and sessions:\n<%= config.bin %> <%= command.id %>",
3839
+ "List all trace files for a specific agent:\n<%= config.bin %> <%= command.id %> --agent My_Agent",
3840
+ "List trace files for a specific session:\n<%= config.bin %> <%= command.id %> --session-id <SESSION_ID>",
3841
+ "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",
3842
+ "List trace files recorded on or after a specific UTC time:\n<%= config.bin %> <%= command.id %> --since 2026-04-20T14:00:00Z",
3843
+ "Filter by agent and date together:\n<%= config.bin %> <%= command.id %> --agent My_Agent --since 2026-04-20",
3844
+ "Return results as JSON:\n<%= config.bin %> <%= command.id %> --json"
3866
3845
  ],
3867
3846
  "flags": {
3868
3847
  "json": {
@@ -3880,137 +3859,168 @@
3880
3859
  "multiple": false,
3881
3860
  "type": "option"
3882
3861
  },
3883
- "target-org": {
3884
- "char": "o",
3885
- "name": "target-org",
3886
- "noCacheDefault": true,
3887
- "required": true,
3888
- "summary": "Username or alias of the target org. Not required if the `target-org` configuration variable is already set.",
3889
- "hasDynamicHelp": true,
3862
+ "session-id": {
3863
+ "name": "session-id",
3864
+ "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.",
3865
+ "hasDynamicHelp": false,
3890
3866
  "multiple": false,
3891
3867
  "type": "option"
3892
3868
  },
3893
- "api-version": {
3894
- "description": "Override the api version used for api requests made by this command",
3895
- "name": "api-version",
3869
+ "agent": {
3870
+ "char": "a",
3871
+ "name": "agent",
3872
+ "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.",
3896
3873
  "hasDynamicHelp": false,
3897
3874
  "multiple": false,
3898
3875
  "type": "option"
3899
3876
  },
3900
- "api-name": {
3901
- "char": "n",
3902
- "name": "api-name",
3903
- "summary": "API name of the agent test to run; corresponds to the name of the AiEvaluationDefinition metadata component that implements the agent test.",
3877
+ "since": {
3878
+ "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.",
3879
+ "name": "since",
3880
+ "summary": "Date used to filter the list of trace files; only those recorded on or after the date are listed.",
3904
3881
  "hasDynamicHelp": false,
3905
3882
  "multiple": false,
3906
3883
  "type": "option"
3884
+ }
3885
+ },
3886
+ "hasDynamicHelp": false,
3887
+ "hiddenAliases": [],
3888
+ "id": "agent:trace:list",
3889
+ "pluginAlias": "@salesforce/plugin-agent",
3890
+ "pluginName": "@salesforce/plugin-agent",
3891
+ "pluginType": "core",
3892
+ "strict": true,
3893
+ "summary": "List the available trace files that were recorded during all agent preview sessions.",
3894
+ "enableJsonFlag": true,
3895
+ "requiresProject": true,
3896
+ "errorCodes": {
3897
+ "header": "ERROR CODES",
3898
+ "body": [
3899
+ {
3900
+ "name": "Succeeded (0)",
3901
+ "description": "Trace files listed successfully (or empty list if none found)."
3902
+ }
3903
+ ]
3904
+ },
3905
+ "isESM": true,
3906
+ "relativePath": [
3907
+ "lib",
3908
+ "commands",
3909
+ "agent",
3910
+ "trace",
3911
+ "list.js"
3912
+ ],
3913
+ "aliasPermutations": [],
3914
+ "permutations": [
3915
+ "agent:trace:list",
3916
+ "trace:agent:list",
3917
+ "trace:list:agent",
3918
+ "agent:list:trace",
3919
+ "list:agent:trace",
3920
+ "list:trace:agent"
3921
+ ]
3922
+ },
3923
+ "agent:trace:read": {
3924
+ "aliases": [],
3925
+ "args": {},
3926
+ "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.",
3927
+ "examples": [
3928
+ "Show a session trace summary for all turns in the session with the specified ID:\n<%= config.bin %> <%= command.id %> --session-id <SESSION_ID>",
3929
+ "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",
3930
+ "Drill into action execution across all turns:\n<%= config.bin %> <%= command.id %> --session-id <SESSION_ID> --format detail --dimension actions",
3931
+ "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",
3932
+ "Show all errors across the session:\n<%= config.bin %> <%= command.id %> --session-id <SESSION_ID> --format detail --dimension errors",
3933
+ "Output raw trace JSON for custom parsing:\n<%= config.bin %> <%= command.id %> --session-id <SESSION_ID> --format raw",
3934
+ "Return results as JSON:\n<%= config.bin %> <%= command.id %> --session-id <SESSION_ID> --json"
3935
+ ],
3936
+ "flags": {
3937
+ "json": {
3938
+ "description": "Format output as json.",
3939
+ "helpGroup": "GLOBAL",
3940
+ "name": "json",
3941
+ "allowNo": false,
3942
+ "type": "boolean"
3907
3943
  },
3908
- "wait": {
3909
- "char": "w",
3910
- "name": "wait",
3911
- "summary": "Number of minutes to wait for the command to complete and display results to the terminal window.",
3912
- "hasDynamicHelp": true,
3944
+ "flags-dir": {
3945
+ "helpGroup": "GLOBAL",
3946
+ "name": "flags-dir",
3947
+ "summary": "Import flag values from a directory.",
3948
+ "hasDynamicHelp": false,
3913
3949
  "multiple": false,
3914
3950
  "type": "option"
3915
3951
  },
3916
- "result-format": {
3917
- "name": "result-format",
3918
- "summary": "Format of the agent test run results.",
3919
- "default": "human",
3952
+ "session-id": {
3953
+ "char": "s",
3954
+ "name": "session-id",
3955
+ "required": true,
3956
+ "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",
3920
3957
  "hasDynamicHelp": false,
3921
3958
  "multiple": false,
3922
- "options": [
3923
- "json",
3924
- "human",
3925
- "junit",
3926
- "tap"
3927
- ],
3928
3959
  "type": "option"
3929
3960
  },
3930
- "output-dir": {
3931
- "char": "d",
3932
- "description": "If the agent test run completes, write the results to the specified directory. If the test is still running, the test results aren't written.",
3933
- "name": "output-dir",
3934
- "summary": "Directory to write the agent test results into.",
3961
+ "format": {
3962
+ "char": "f",
3963
+ "name": "format",
3964
+ "summary": "Output format of the trace data; specifies the level of detail you want in the trace files.",
3965
+ "default": "summary",
3935
3966
  "hasDynamicHelp": false,
3936
3967
  "multiple": false,
3968
+ "options": [
3969
+ "summary",
3970
+ "detail",
3971
+ "raw"
3972
+ ],
3937
3973
  "type": "option"
3938
3974
  },
3939
- "test-runner": {
3940
- "description": "By default, the command automatically detects which test runner to use based on the test definition metadata type in your org. Use this flag to explicitly specify the runner type. 'agentforce-studio' uses AiTestingDefinition metadata. 'testing-center' uses AiEvaluationDefinition metadata.",
3941
- "name": "test-runner",
3942
- "summary": "Explicitly specify which test runner to use (agentforce-studio or testing-center).",
3975
+ "dimension": {
3976
+ "char": "d",
3977
+ "name": "dimension",
3978
+ "summary": "Dimension to drill into when using \"--format detail\"; used to filter and organize the trace data to answer a specific type of question.",
3943
3979
  "hasDynamicHelp": false,
3944
3980
  "multiple": false,
3945
3981
  "options": [
3946
- "agentforce-studio",
3947
- "testing-center"
3982
+ "actions",
3983
+ "grounding",
3984
+ "routing",
3985
+ "errors"
3948
3986
  ],
3949
3987
  "type": "option"
3950
3988
  },
3951
- "verbose": {
3952
- "description": "When enabled, includes detailed generated data (such as invoked actions) in the human-readable test results output. This is useful for debugging test failures and understanding what actions were actually invoked during the test run.\n\nThe generated data is in JSON format and includes the Apex classes or Flows that were invoked, the Salesforce objects that were touched, and so on. Use the JSON structure of this information to build the test case JSONPath expression when using custom evaluations.",
3953
- "name": "verbose",
3954
- "summary": "Show generated data in the test results output.",
3955
- "allowNo": false,
3956
- "type": "boolean"
3989
+ "turn": {
3990
+ "char": "t",
3991
+ "name": "turn",
3992
+ "summary": "Turn number for which you want trace data. A turn is a single utterance or response in a conversation, starting with 1.",
3993
+ "hasDynamicHelp": false,
3994
+ "multiple": false,
3995
+ "type": "option"
3957
3996
  }
3958
3997
  },
3959
- "hasDynamicHelp": true,
3998
+ "hasDynamicHelp": false,
3960
3999
  "hiddenAliases": [],
3961
- "id": "agent:test:run",
4000
+ "id": "agent:trace:read",
3962
4001
  "pluginAlias": "@salesforce/plugin-agent",
3963
4002
  "pluginName": "@salesforce/plugin-agent",
3964
4003
  "pluginType": "core",
3965
4004
  "strict": true,
3966
- "summary": "Start an agent test in your org.",
4005
+ "summary": "Read trace files from an agent preview session.",
3967
4006
  "enableJsonFlag": true,
3968
- "envVariablesSection": {
3969
- "header": "ENVIRONMENT VARIABLES",
3970
- "body": [
3971
- {
3972
- "name": "SF_TARGET_ORG",
3973
- "description": "Username or alias of your default org. Overrides the target-org configuration variable."
3974
- }
3975
- ]
3976
- },
3977
- "errorCodes": {
3978
- "header": "ERROR CODES",
3979
- "body": [
3980
- {
3981
- "name": "Succeeded (0)",
3982
- "description": "Test started successfully (without --wait), or test completed successfully (with --wait)."
3983
- },
3984
- {
3985
- "name": "Failed (1)",
3986
- "description": "Tests encountered execution errors (test cases with ERROR status when using --wait)."
3987
- },
3988
- {
3989
- "name": "NotFound (2)",
3990
- "description": "Test definition not found or invalid test name."
3991
- },
3992
- {
3993
- "name": "OperationFailed (4)",
3994
- "description": "Failed to start or poll test due to API or network errors."
3995
- }
3996
- ]
3997
- },
4007
+ "requiresProject": true,
3998
4008
  "isESM": true,
3999
4009
  "relativePath": [
4000
4010
  "lib",
4001
4011
  "commands",
4002
4012
  "agent",
4003
- "test",
4004
- "run.js"
4013
+ "trace",
4014
+ "read.js"
4005
4015
  ],
4006
4016
  "aliasPermutations": [],
4007
4017
  "permutations": [
4008
- "agent:test:run",
4009
- "test:agent:run",
4010
- "test:run:agent",
4011
- "agent:run:test",
4012
- "run:agent:test",
4013
- "run:test:agent"
4018
+ "agent:trace:read",
4019
+ "trace:agent:read",
4020
+ "trace:read:agent",
4021
+ "agent:read:trace",
4022
+ "read:agent:trace",
4023
+ "read:trace:agent"
4014
4024
  ]
4015
4025
  },
4016
4026
  "agent:validate:authoring-bundle": {
@@ -4683,5 +4693,5 @@
4683
4693
  ]
4684
4694
  }
4685
4695
  },
4686
- "version": "2.2.4"
4696
+ "version": "2.3.0"
4687
4697
  }