@salesforce/plugin-agent 1.36.1 → 1.38.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.
Files changed (34) hide show
  1. package/README.md +294 -19
  2. package/lib/agentSessionScanner.d.ts +12 -0
  3. package/lib/agentSessionScanner.js +56 -0
  4. package/lib/agentSessionScanner.js.map +1 -0
  5. package/lib/commands/agent/test/run-eval.d.ts +1 -5
  6. package/lib/commands/agent/test/run-eval.js +54 -149
  7. package/lib/commands/agent/test/run-eval.js.map +1 -1
  8. package/lib/commands/agent/trace/delete.d.ts +21 -0
  9. package/lib/commands/agent/trace/delete.js +118 -0
  10. package/lib/commands/agent/trace/delete.js.map +1 -0
  11. package/lib/commands/agent/trace/list.d.ts +22 -0
  12. package/lib/commands/agent/trace/list.js +101 -0
  13. package/lib/commands/agent/trace/list.js.map +1 -0
  14. package/lib/commands/agent/trace/read.d.ts +75 -0
  15. package/lib/commands/agent/trace/read.js +308 -0
  16. package/lib/commands/agent/trace/read.js.map +1 -0
  17. package/messages/agent.test.run-eval.md +0 -4
  18. package/messages/agent.trace.delete.md +87 -0
  19. package/messages/agent.trace.list.md +87 -0
  20. package/messages/agent.trace.read.md +171 -0
  21. package/oclif.manifest.json +801 -525
  22. package/package.json +4 -4
  23. package/schemas/agent-trace-delete.json +28 -0
  24. package/schemas/agent-trace-list.json +34 -0
  25. package/schemas/agent-trace-read.json +466 -0
  26. package/lib/evalFormatter.d.ts +0 -30
  27. package/lib/evalFormatter.js +0 -263
  28. package/lib/evalFormatter.js.map +0 -1
  29. package/lib/evalNormalizer.d.ts +0 -57
  30. package/lib/evalNormalizer.js +0 -431
  31. package/lib/evalNormalizer.js.map +0 -1
  32. package/lib/yamlSpecTranslator.d.ts +0 -20
  33. package/lib/yamlSpecTranslator.js +0 -227
  34. package/lib/yamlSpecTranslator.js.map +0 -1
package/README.md CHANGED
@@ -77,6 +77,10 @@ sf plugins
77
77
  - [`sf agent test results`](#sf-agent-test-results)
78
78
  - [`sf agent test resume`](#sf-agent-test-resume)
79
79
  - [`sf agent test run`](#sf-agent-test-run)
80
+ - [`sf agent test run-eval`](#sf-agent-test-run-eval)
81
+ - [`sf agent trace delete`](#sf-agent-trace-delete)
82
+ - [`sf agent trace list`](#sf-agent-trace-list)
83
+ - [`sf agent trace read`](#sf-agent-trace-read)
80
84
  - [`sf agent validate authoring-bundle`](#sf-agent-validate-authoring-bundle)
81
85
 
82
86
  ## `sf agent activate`
@@ -126,7 +130,7 @@ EXAMPLES
126
130
  $ sf agent activate --api-name Resort_Manager --version 2 --target-org my-org
127
131
  ```
128
132
 
129
- _See code: [src/commands/agent/activate.ts](https://github.com/salesforcecli/plugin-agent/blob/1.36.1/src/commands/agent/activate.ts)_
133
+ _See code: [src/commands/agent/activate.ts](https://github.com/salesforcecli/plugin-agent/blob/1.38.0/src/commands/agent/activate.ts)_
130
134
 
131
135
  ## `sf agent create`
132
136
 
@@ -193,7 +197,7 @@ EXAMPLES
193
197
  $ sf agent create --name "Resort Manager" --spec specs/resortManagerAgent.yaml --preview
194
198
  ```
195
199
 
196
- _See code: [src/commands/agent/create.ts](https://github.com/salesforcecli/plugin-agent/blob/1.36.1/src/commands/agent/create.ts)_
200
+ _See code: [src/commands/agent/create.ts](https://github.com/salesforcecli/plugin-agent/blob/1.38.0/src/commands/agent/create.ts)_
197
201
 
198
202
  ## `sf agent deactivate`
199
203
 
@@ -234,7 +238,7 @@ EXAMPLES
234
238
  $ sf agent deactivate --api-name Resort_Manager --target-org my-org
235
239
  ```
236
240
 
237
- _See code: [src/commands/agent/deactivate.ts](https://github.com/salesforcecli/plugin-agent/blob/1.36.1/src/commands/agent/deactivate.ts)_
241
+ _See code: [src/commands/agent/deactivate.ts](https://github.com/salesforcecli/plugin-agent/blob/1.38.0/src/commands/agent/deactivate.ts)_
238
242
 
239
243
  ## `sf agent generate agent-spec`
240
244
 
@@ -341,7 +345,7 @@ EXAMPLES
341
345
  $ sf agent generate agent-spec --tone formal --agent-user resortmanager@myorg.com
342
346
  ```
343
347
 
344
- _See code: [src/commands/agent/generate/agent-spec.ts](https://github.com/salesforcecli/plugin-agent/blob/1.36.1/src/commands/agent/generate/agent-spec.ts)_
348
+ _See code: [src/commands/agent/generate/agent-spec.ts](https://github.com/salesforcecli/plugin-agent/blob/1.38.0/src/commands/agent/generate/agent-spec.ts)_
345
349
 
346
350
  ## `sf agent generate authoring-bundle`
347
351
 
@@ -418,7 +422,7 @@ EXAMPLES
418
422
  other-package-dir/main/default --target-org my-dev-org
419
423
  ```
420
424
 
421
- _See code: [src/commands/agent/generate/authoring-bundle.ts](https://github.com/salesforcecli/plugin-agent/blob/1.36.1/src/commands/agent/generate/authoring-bundle.ts)_
425
+ _See code: [src/commands/agent/generate/authoring-bundle.ts](https://github.com/salesforcecli/plugin-agent/blob/1.38.0/src/commands/agent/generate/authoring-bundle.ts)_
422
426
 
423
427
  ## `sf agent generate template`
424
428
 
@@ -480,7 +484,7 @@ EXAMPLES
480
484
  my-package --source-org my-scratch-org
481
485
  ```
482
486
 
483
- _See code: [src/commands/agent/generate/template.ts](https://github.com/salesforcecli/plugin-agent/blob/1.36.1/src/commands/agent/generate/template.ts)_
487
+ _See code: [src/commands/agent/generate/template.ts](https://github.com/salesforcecli/plugin-agent/blob/1.38.0/src/commands/agent/generate/template.ts)_
484
488
 
485
489
  ## `sf agent generate test-spec`
486
490
 
@@ -545,7 +549,7 @@ EXAMPLES
545
549
  force-app//main/default/aiEvaluationDefinitions/Resort_Manager_Tests.aiEvaluationDefinition-meta.xml
546
550
  ```
547
551
 
548
- _See code: [src/commands/agent/generate/test-spec.ts](https://github.com/salesforcecli/plugin-agent/blob/1.36.1/src/commands/agent/generate/test-spec.ts)_
552
+ _See code: [src/commands/agent/generate/test-spec.ts](https://github.com/salesforcecli/plugin-agent/blob/1.38.0/src/commands/agent/generate/test-spec.ts)_
549
553
 
550
554
  ## `sf agent preview`
551
555
 
@@ -618,7 +622,7 @@ EXAMPLES
618
622
  $ sf agent preview --use-live-actions --apex-debug --output-dir transcripts/my-preview
619
623
  ```
620
624
 
621
- _See code: [src/commands/agent/preview.ts](https://github.com/salesforcecli/plugin-agent/blob/1.36.1/src/commands/agent/preview.ts)_
625
+ _See code: [src/commands/agent/preview.ts](https://github.com/salesforcecli/plugin-agent/blob/1.38.0/src/commands/agent/preview.ts)_
622
626
 
623
627
  ## `sf agent preview end`
624
628
 
@@ -673,7 +677,7 @@ EXAMPLES
673
677
  $ sf agent preview end --authoring-bundle My_Local_Agent
674
678
  ```
675
679
 
676
- _See code: [src/commands/agent/preview/end.ts](https://github.com/salesforcecli/plugin-agent/blob/1.36.1/src/commands/agent/preview/end.ts)_
680
+ _See code: [src/commands/agent/preview/end.ts](https://github.com/salesforcecli/plugin-agent/blob/1.38.0/src/commands/agent/preview/end.ts)_
677
681
 
678
682
  ## `sf agent preview send`
679
683
 
@@ -731,7 +735,7 @@ EXAMPLES
731
735
  $ sf agent preview send --utterance "what can you help me with?" --authoring-bundle My_Local_Agent
732
736
  ```
733
737
 
734
- _See code: [src/commands/agent/preview/send.ts](https://github.com/salesforcecli/plugin-agent/blob/1.36.1/src/commands/agent/preview/send.ts)_
738
+ _See code: [src/commands/agent/preview/send.ts](https://github.com/salesforcecli/plugin-agent/blob/1.38.0/src/commands/agent/preview/send.ts)_
735
739
 
736
740
  ## `sf agent preview sessions`
737
741
 
@@ -764,7 +768,7 @@ EXAMPLES
764
768
  $ sf agent preview sessions
765
769
  ```
766
770
 
767
- _See code: [src/commands/agent/preview/sessions.ts](https://github.com/salesforcecli/plugin-agent/blob/1.36.1/src/commands/agent/preview/sessions.ts)_
771
+ _See code: [src/commands/agent/preview/sessions.ts](https://github.com/salesforcecli/plugin-agent/blob/1.38.0/src/commands/agent/preview/sessions.ts)_
768
772
 
769
773
  ## `sf agent preview start`
770
774
 
@@ -829,7 +833,7 @@ EXAMPLES
829
833
  $ sf agent preview start --api-name My_Published_Agent
830
834
  ```
831
835
 
832
- _See code: [src/commands/agent/preview/start.ts](https://github.com/salesforcecli/plugin-agent/blob/1.36.1/src/commands/agent/preview/start.ts)_
836
+ _See code: [src/commands/agent/preview/start.ts](https://github.com/salesforcecli/plugin-agent/blob/1.38.0/src/commands/agent/preview/start.ts)_
833
837
 
834
838
  ## `sf agent publish authoring-bundle`
835
839
 
@@ -889,7 +893,7 @@ EXAMPLES
889
893
  $ sf agent publish authoring-bundle --api-name MyAuthoringbundle --concise
890
894
  ```
891
895
 
892
- _See code: [src/commands/agent/publish/authoring-bundle.ts](https://github.com/salesforcecli/plugin-agent/blob/1.36.1/src/commands/agent/publish/authoring-bundle.ts)_
896
+ _See code: [src/commands/agent/publish/authoring-bundle.ts](https://github.com/salesforcecli/plugin-agent/blob/1.38.0/src/commands/agent/publish/authoring-bundle.ts)_
893
897
 
894
898
  ## `sf agent test create`
895
899
 
@@ -944,7 +948,7 @@ EXAMPLES
944
948
  $ sf agent test create --spec specs/Resort_Manager-testSpec.yaml --api-name Resort_Manager_Test --preview
945
949
  ```
946
950
 
947
- _See code: [src/commands/agent/test/create.ts](https://github.com/salesforcecli/plugin-agent/blob/1.36.1/src/commands/agent/test/create.ts)_
951
+ _See code: [src/commands/agent/test/create.ts](https://github.com/salesforcecli/plugin-agent/blob/1.38.0/src/commands/agent/test/create.ts)_
948
952
 
949
953
  ## `sf agent test list`
950
954
 
@@ -979,7 +983,7 @@ EXAMPLES
979
983
  $ sf agent test list --target-org my-org
980
984
  ```
981
985
 
982
- _See code: [src/commands/agent/test/list.ts](https://github.com/salesforcecli/plugin-agent/blob/1.36.1/src/commands/agent/test/list.ts)_
986
+ _See code: [src/commands/agent/test/list.ts](https://github.com/salesforcecli/plugin-agent/blob/1.38.0/src/commands/agent/test/list.ts)_
983
987
 
984
988
  ## `sf agent test results`
985
989
 
@@ -1055,7 +1059,7 @@ FLAG DESCRIPTIONS
1055
1059
  expression when using custom evaluations.
1056
1060
  ```
1057
1061
 
1058
- _See code: [src/commands/agent/test/results.ts](https://github.com/salesforcecli/plugin-agent/blob/1.36.1/src/commands/agent/test/results.ts)_
1062
+ _See code: [src/commands/agent/test/results.ts](https://github.com/salesforcecli/plugin-agent/blob/1.38.0/src/commands/agent/test/results.ts)_
1059
1063
 
1060
1064
  ## `sf agent test resume`
1061
1065
 
@@ -1139,7 +1143,7 @@ FLAG DESCRIPTIONS
1139
1143
  expression when using custom evaluations.
1140
1144
  ```
1141
1145
 
1142
- _See code: [src/commands/agent/test/resume.ts](https://github.com/salesforcecli/plugin-agent/blob/1.36.1/src/commands/agent/test/resume.ts)_
1146
+ _See code: [src/commands/agent/test/resume.ts](https://github.com/salesforcecli/plugin-agent/blob/1.38.0/src/commands/agent/test/resume.ts)_
1143
1147
 
1144
1148
  ## `sf agent test run`
1145
1149
 
@@ -1223,7 +1227,278 @@ FLAG DESCRIPTIONS
1223
1227
  expression when using custom evaluations.
1224
1228
  ```
1225
1229
 
1226
- _See code: [src/commands/agent/test/run.ts](https://github.com/salesforcecli/plugin-agent/blob/1.36.1/src/commands/agent/test/run.ts)_
1230
+ _See code: [src/commands/agent/test/run.ts](https://github.com/salesforcecli/plugin-agent/blob/1.38.0/src/commands/agent/test/run.ts)_
1231
+
1232
+ ## `sf agent test run-eval`
1233
+
1234
+ Run evaluation tests against an Agentforce agent.
1235
+
1236
+ ```
1237
+ USAGE
1238
+ $ sf agent test run-eval -o <value> -s <value> [--json] [--flags-dir <value>] [--api-version <value>] [-n <value>]
1239
+ [--result-format json|human|junit|tap] [--batch-size <value>] [--no-normalize]
1240
+
1241
+ FLAGS
1242
+ -n, --api-name=<value> Agent DeveloperName (also called API name) to resolve agent_id and agent_version_id.
1243
+ Auto-inferred from the YAML spec's subjectName.
1244
+ -o, --target-org=<value> (required) Username or alias of the target org. Not required if the `target-org`
1245
+ configuration variable is already set.
1246
+ -s, --spec=<value> (required) Path to test spec file (YAML or JSON). Supports reading from stdin when
1247
+ piping content.
1248
+ --api-version=<value> Override the api version used for api requests made by this command
1249
+ --batch-size=<value> [default: 5] Number of tests per API request (max 5).
1250
+ --no-normalize Disable auto-normalization of field names and shorthand references.
1251
+ --result-format=<option> [default: human] Format of the agent test run results.
1252
+ <options: json|human|junit|tap>
1253
+
1254
+ GLOBAL FLAGS
1255
+ --flags-dir=<value> Import flag values from a directory.
1256
+ --json Format output as json.
1257
+
1258
+ DESCRIPTION
1259
+ Run evaluation tests against an Agentforce agent.
1260
+
1261
+ Execute rich evaluation tests against an Agentforce agent using the Einstein Evaluation API. Supports both YAML test
1262
+ specs (same format as `sf agent generate test-spec`) and JSON payloads.
1263
+
1264
+ When you provide a YAML test spec, the command automatically translates test cases into Evaluation API calls and
1265
+ infers the agent name from the spec's `subjectName` field. This means you can use the same test spec with both `sf
1266
+ agent test run` and `sf agent test run-eval`. YAML test specs also support contextVariables, which allow you to inject
1267
+ contextual data (such as CaseId or RoutableId) into agent sessions for testing with different contexts.
1268
+
1269
+ When you provide a JSON payload, it's sent directly to the API with optional normalization. The normalizer
1270
+ auto-corrects common field name mistakes, converts shorthand references to JSONPath, and injects defaults. Use
1271
+ `--no-normalize` to disable this auto-normalization. JSON payloads can also include context_variables on
1272
+ agent.create_session steps for the same contextual testing capabilities.
1273
+
1274
+ Supports 8+ evaluator types, including topic routing assertions, action invocation checks, string/numeric assertions,
1275
+ semantic similarity scoring, and LLM-based quality ratings.
1276
+
1277
+ EXAMPLES
1278
+ Run tests using a YAML test spec on the org with alias "my-org":
1279
+
1280
+ $ sf agent test run-eval --spec tests/my-agent-testSpec.yaml --target-org my-org
1281
+
1282
+ Run tests using a YAML spec with explicit agent name override; use your default org:
1283
+
1284
+ $ sf agent test run-eval --spec tests/my-agent-testSpec.yaml --api-name My_Agent --target-org my-org
1285
+
1286
+ Run tests using a JSON payload:
1287
+
1288
+ $ sf agent test run-eval --spec tests/eval-payload.json --target-org my-org
1289
+
1290
+ Run tests and output results in JUnit format; useful for continuous integration and deployment (CI/CD):
1291
+
1292
+ $ sf agent test run-eval --spec tests/my-agent-testSpec.yaml --target-org my-org --result-format junit
1293
+
1294
+ Run tests with contextVariables to inject contextual data into agent sessions (add contextVariables to test cases in
1295
+ your YAML spec):
1296
+
1297
+ $ sf agent test run-eval --spec tests/agent-with-context.yaml --target-org my-org
1298
+
1299
+ Pipe JSON payload from stdin (--spec flag is automatically populated from stdin):
1300
+ $ echo '{"tests":[...]}' | sf agent test run-eval --spec --target-org my-org
1301
+ ```
1302
+
1303
+ _See code: [src/commands/agent/test/run-eval.ts](https://github.com/salesforcecli/plugin-agent/blob/1.38.0/src/commands/agent/test/run-eval.ts)_
1304
+
1305
+ ## `sf agent trace delete`
1306
+
1307
+ Delete agent preview trace files.
1308
+
1309
+ ```
1310
+ USAGE
1311
+ $ sf agent trace delete [--json] [--flags-dir <value>] [-a <value>] [--session-id <value>] [--older-than <value>]
1312
+ [--no-prompt]
1313
+
1314
+ FLAGS
1315
+ -a, --agent=<value> Only delete traces for this agent name (substring match). Matches against the name used when
1316
+ starting the session, whether that's an authoring bundle or a published agent API name.
1317
+ --no-prompt Skip the confirmation prompt and delete immediately.
1318
+ --older-than=<value> Only delete traces older than this duration. Accepts a number followed by a unit: m/minutes,
1319
+ h/hours, d/days, w/weeks (e.g. 7d, 24h, 2w).
1320
+ --session-id=<value> Only delete traces from this session ID.
1321
+
1322
+ GLOBAL FLAGS
1323
+ --flags-dir=<value> Import flag values from a directory.
1324
+ --json Format output as json.
1325
+
1326
+ DESCRIPTION
1327
+ Delete agent preview trace files.
1328
+
1329
+ Deletes trace files recorded during agent preview sessions. By default, shows a preview of what will be deleted and
1330
+ prompts for confirmation. Use --no-prompt to skip confirmation.
1331
+
1332
+ Without filters, deletes all traces for all agents and sessions. Use flags to narrow the scope: filter by agent name
1333
+ (--agent), by session (--session-id), or by age (--older-than).
1334
+
1335
+ EXAMPLES
1336
+ Delete all traces for all agents and sessions (with confirmation prompt):
1337
+
1338
+ $ sf agent trace delete
1339
+
1340
+ Delete all traces for a specific agent:
1341
+
1342
+ $ sf agent trace delete --agent My_Agent
1343
+
1344
+ Delete traces from a specific session:
1345
+
1346
+ $ sf agent trace delete --session-id <SESSION_ID>
1347
+
1348
+ Delete traces older than 7 days:
1349
+
1350
+ $ sf agent trace delete --older-than 7d
1351
+
1352
+ Delete traces older than 24 hours for a specific agent, no prompt:
1353
+
1354
+ $ sf agent trace delete --agent My_Agent --older-than 24h --no-prompt
1355
+
1356
+ Delete all traces without confirmation:
1357
+
1358
+ $ sf agent trace delete --no-prompt
1359
+ ```
1360
+
1361
+ _See code: [src/commands/agent/trace/delete.ts](https://github.com/salesforcecli/plugin-agent/blob/1.38.0/src/commands/agent/trace/delete.ts)_
1362
+
1363
+ ## `sf agent trace list`
1364
+
1365
+ List the trace files that were recorded during all agent preview sessions.
1366
+
1367
+ ```
1368
+ USAGE
1369
+ $ sf agent trace list [--json] [--flags-dir <value>] [--session-id <value>] [-a <value>] [--since <value>]
1370
+
1371
+ FLAGS
1372
+ -a, --agent=<value> Only show traces for this agent name (substring match). Matches against the name used when
1373
+ starting the session, whether that's an authoring bundle or a published agent API name.
1374
+ --session-id=<value> Session ID used to filter the list of trace files.
1375
+ --since=<value> Date used to filter the list of trace files; only those recorded on or after the date are
1376
+ listed.
1377
+
1378
+ GLOBAL FLAGS
1379
+ --flags-dir=<value> Import flag values from a directory.
1380
+ --json Format output as json.
1381
+
1382
+ DESCRIPTION
1383
+ List the trace files that were recorded during all agent preview sessions.
1384
+
1385
+ Lists trace files recorded during agent preview sessions. By default, lists all traces for all agents and all of their
1386
+ sessions. Use flags to narrow results: filter by agent name (--agent), by session (--session-id), or by date
1387
+ (--since).
1388
+
1389
+ Each row in the output corresponds to one trace file, which in turn corresponds to one agent session. The Agent column
1390
+ shows the authoring bundle or API name used when starting the session.
1391
+
1392
+ EXAMPLES
1393
+ List all traces for all agents and sessions:
1394
+
1395
+ $ sf agent trace list
1396
+
1397
+ List all traces for a specific agent:
1398
+
1399
+ $ sf agent trace list --agent My_Agent
1400
+
1401
+ List traces for a specific session:
1402
+
1403
+ $ sf agent trace list --session-id <SESSION_ID>
1404
+
1405
+ List traces recorded on or after April 20, 2026 (date-only, interpreted as UTC midnight):
1406
+
1407
+ $ sf agent trace list --since 2026-04-20
1408
+
1409
+ List traces recorded on or after a specific UTC time:
1410
+
1411
+ $ sf agent trace list --since 2026-04-20T14:00:00Z
1412
+
1413
+ Filter by agent and date together:
1414
+
1415
+ $ sf agent trace list --agent My_Agent --since 2026-04-20
1416
+
1417
+ Return results as JSON:
1418
+
1419
+ $ sf agent trace list --json
1420
+
1421
+ FLAG DESCRIPTIONS
1422
+ --since=<value> Date used to filter the list of trace files; only those recorded on or after the date are listed.
1423
+
1424
+ Accepts ISO 8601 format: date-only (2026-04-20), date-time (2026-04-20T14:00:00Z), or date-time with milliseconds
1425
+ (2026-04-20T14:00:00.000Z). The "Recorded At" values shown in the table output are valid inputs.
1426
+ ```
1427
+
1428
+ _See code: [src/commands/agent/trace/list.ts](https://github.com/salesforcecli/plugin-agent/blob/1.38.0/src/commands/agent/trace/list.ts)_
1429
+
1430
+ ## `sf agent trace read`
1431
+
1432
+ Read and analyze trace files from an agent preview session.
1433
+
1434
+ ```
1435
+ USAGE
1436
+ $ sf agent trace read -s <value> [--json] [--flags-dir <value>] [-f summary|detail|raw] [-d
1437
+ actions|grounding|routing|errors] [-t <value>]
1438
+
1439
+ FLAGS
1440
+ -d, --dimension=<option> Dimension to drill into when using --format detail. One of: actions, grounding, routing,
1441
+ errors. Required when --format is detail.
1442
+ <options: actions|grounding|routing|errors>
1443
+ -f, --format=<option> [default: summary] Output format: summary (default), detail, or raw. Use detail with
1444
+ --dimension to drill into a specific aspect of the trace.
1445
+ <options: summary|detail|raw>
1446
+ -s, --session-id=<value> (required) Session ID to read traces for.
1447
+ -t, --turn=<value> Scope output to this conversation turn number.
1448
+
1449
+ GLOBAL FLAGS
1450
+ --flags-dir=<value> Import flag values from a directory.
1451
+ --json Format output as json.
1452
+
1453
+ DESCRIPTION
1454
+ Read and analyze trace files from an agent preview session.
1455
+
1456
+ Reads trace files recorded during an agent preview session and outputs them in one of three formats.
1457
+
1458
+ **--format summary** (default): A per-turn narrative showing topic routing, actions executed, and the agent's
1459
+ response. Use this to quickly understand what happened in a session.
1460
+
1461
+ **--format detail**: Diagnostic drill-down into a specific dimension (--dimension required). Filters output to only
1462
+ the trace steps relevant to that dimension, minimizing noise.
1463
+
1464
+ **--format raw**: Unprocessed trace JSON. Use this as a fallback when the trace schema has changed or you need to
1465
+ perform custom analysis.
1466
+
1467
+ Available dimensions for --format detail: actions, grounding, routing, errors.
1468
+
1469
+ Use --turn N to scope output to a single conversation turn.
1470
+
1471
+ EXAMPLES
1472
+ Show a session summary (all turns):
1473
+
1474
+ $ sf agent trace read --session-id <SESSION_ID>
1475
+
1476
+ Show summary for a single turn:
1477
+
1478
+ $ sf agent trace read --session-id <SESSION_ID> --turn 2
1479
+
1480
+ Drill into action execution across all turns:
1481
+
1482
+ $ sf agent trace read --session-id <SESSION_ID> --format detail --dimension actions
1483
+
1484
+ Drill into routing decisions for a specific turn:
1485
+
1486
+ $ sf agent trace read --session-id <SESSION_ID> --format detail --dimension routing --turn 1
1487
+
1488
+ Show all errors across the session:
1489
+
1490
+ $ sf agent trace read --session-id <SESSION_ID> --format detail --dimension errors
1491
+
1492
+ Output raw trace JSON for custom parsing:
1493
+
1494
+ $ sf agent trace read --session-id <SESSION_ID> --format raw
1495
+
1496
+ Return results as JSON:
1497
+
1498
+ $ sf agent trace read --session-id <SESSION_ID> --json
1499
+ ```
1500
+
1501
+ _See code: [src/commands/agent/trace/read.ts](https://github.com/salesforcecli/plugin-agent/blob/1.38.0/src/commands/agent/trace/read.ts)_
1227
1502
 
1228
1503
  ## `sf agent validate authoring-bundle`
1229
1504
 
@@ -1270,6 +1545,6 @@ EXAMPLES
1270
1545
  $ sf agent validate authoring-bundle --api-name MyAuthoringBundle --target-org my-dev-org
1271
1546
  ```
1272
1547
 
1273
- _See code: [src/commands/agent/validate/authoring-bundle.ts](https://github.com/salesforcecli/plugin-agent/blob/1.36.1/src/commands/agent/validate/authoring-bundle.ts)_
1548
+ _See code: [src/commands/agent/validate/authoring-bundle.ts](https://github.com/salesforcecli/plugin-agent/blob/1.38.0/src/commands/agent/validate/authoring-bundle.ts)_
1274
1549
 
1275
1550
  <!-- commandsstop -->
@@ -0,0 +1,12 @@
1
+ import { type SfProject } from '@salesforce/core';
2
+ export type AgentSession = {
3
+ agentId: string;
4
+ displayName: string;
5
+ sessionId: string;
6
+ };
7
+ /**
8
+ * Returns all sessions that have trace data on disk — both active sessions (still in the
9
+ * cache index) and ended sessions (removed from the index by `agent preview end` but whose
10
+ * trace directories remain under .sfdx/agents/<agentId>/sessions/<sessionId>/).
11
+ */
12
+ export declare function listAllAgentSessions(project: SfProject): Promise<AgentSession[]>;
@@ -0,0 +1,56 @@
1
+ /*
2
+ * Copyright 2026, Salesforce, Inc.
3
+ *
4
+ * Licensed under the Apache License, Version 2.0 (the "License");
5
+ * you may not use this file except in compliance with the License.
6
+ * You may obtain a copy of the License at
7
+ *
8
+ * http://www.apache.org/licenses/LICENSE-2.0
9
+ *
10
+ * Unless required by applicable law or agreed to in writing, software
11
+ * distributed under the License is distributed on an "AS IS" BASIS,
12
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13
+ * See the License for the specific language governing permissions and
14
+ * limitations under the License.
15
+ */
16
+ import { readdir } from 'node:fs/promises';
17
+ import { join } from 'node:path';
18
+ import { listCachedPreviewSessions } from '@salesforce/agents';
19
+ /**
20
+ * Returns all sessions that have trace data on disk — both active sessions (still in the
21
+ * cache index) and ended sessions (removed from the index by `agent preview end` but whose
22
+ * trace directories remain under .sfdx/agents/<agentId>/sessions/<sessionId>/).
23
+ */
24
+ export async function listAllAgentSessions(project) {
25
+ const cached = await listCachedPreviewSessions(project);
26
+ const active = cached.flatMap(({ agentId, displayName, sessions }) => sessions.map(({ sessionId }) => ({ agentId, displayName: displayName ?? agentId, sessionId })));
27
+ const seen = new Set(active.map((s) => s.sessionId));
28
+ const agentsDir = join(project.getPath(), '.sfdx', 'agents');
29
+ const ended = [];
30
+ try {
31
+ const agentDirs = await readdir(agentsDir, { withFileTypes: true });
32
+ for (const agentEnt of agentDirs) {
33
+ if (!agentEnt.isDirectory())
34
+ continue;
35
+ const sessionsDir = join(agentsDir, agentEnt.name, 'sessions');
36
+ try {
37
+ // eslint-disable-next-line no-await-in-loop
38
+ const sessionDirs = await readdir(sessionsDir, { withFileTypes: true });
39
+ for (const sessEnt of sessionDirs) {
40
+ if (!sessEnt.isDirectory() || seen.has(sessEnt.name))
41
+ continue;
42
+ ended.push({ agentId: agentEnt.name, displayName: agentEnt.name, sessionId: sessEnt.name });
43
+ seen.add(sessEnt.name);
44
+ }
45
+ }
46
+ catch {
47
+ // no sessions dir for this agent
48
+ }
49
+ }
50
+ }
51
+ catch {
52
+ // no .sfdx/agents dir yet
53
+ }
54
+ return [...active, ...ended];
55
+ }
56
+ //# sourceMappingURL=agentSessionScanner.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"agentSessionScanner.js","sourceRoot":"","sources":["../src/agentSessionScanner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAC3C,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,OAAO,EAAE,yBAAyB,EAAE,MAAM,oBAAoB,CAAC;AAI/D;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CAAC,OAAkB;IAC3D,MAAM,MAAM,GAAG,MAAM,yBAAyB,CAAC,OAAO,CAAC,CAAC;IACxD,MAAM,MAAM,GAAmB,MAAM,CAAC,OAAO,CAAC,CAAC,EAAE,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,EAAE,EAAE,CACnF,QAAQ,CAAC,GAAG,CAAC,CAAC,EAAE,SAAS,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,WAAW,EAAE,WAAW,IAAI,OAAO,EAAE,SAAS,EAAE,CAAC,CAAC,CAC/F,CAAC;IAEF,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC;IAErD,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC;IAC7D,MAAM,KAAK,GAAmB,EAAE,CAAC;IACjC,IAAI,CAAC;QACH,MAAM,SAAS,GAAG,MAAM,OAAO,CAAC,SAAS,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;QACpE,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;YACjC,IAAI,CAAC,QAAQ,CAAC,WAAW,EAAE;gBAAE,SAAS;YACtC,MAAM,WAAW,GAAG,IAAI,CAAC,SAAS,EAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;YAC/D,IAAI,CAAC;gBACH,4CAA4C;gBAC5C,MAAM,WAAW,GAAG,MAAM,OAAO,CAAC,WAAW,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;gBACxE,KAAK,MAAM,OAAO,IAAI,WAAW,EAAE,CAAC;oBAClC,IAAI,CAAC,OAAO,CAAC,WAAW,EAAE,IAAI,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC;wBAAE,SAAS;oBAC/D,KAAK,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,QAAQ,CAAC,IAAI,EAAE,WAAW,EAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,EAAE,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;oBAC5F,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;gBACzB,CAAC;YACH,CAAC;YAAC,MAAM,CAAC;gBACP,iCAAiC;YACnC,CAAC;QACH,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,0BAA0B;IAC5B,CAAC;IAED,OAAO,CAAC,GAAG,MAAM,EAAE,GAAG,KAAK,CAAC,CAAC;AAC/B,CAAC"}
@@ -1,5 +1,4 @@
1
1
  import { SfCommand } from '@salesforce/sf-plugins-core';
2
- import { Org } from '@salesforce/core';
3
2
  export type RunEvalResult = {
4
3
  tests: Array<{
5
4
  id: string;
@@ -18,16 +17,13 @@ export default class AgentTestRunEval extends SfCommand<RunEvalResult> {
18
17
  static readonly summary: string;
19
18
  static readonly description: string;
20
19
  static readonly examples: string[];
21
- static state: string;
22
- static readonly hidden = true;
23
20
  static readonly envVariablesSection: import("@oclif/core").HelpSection;
24
21
  static readonly errorCodes: import("@oclif/core").HelpSection;
25
22
  static readonly flags: {
26
- 'target-org': import("@oclif/core/interfaces").OptionFlag<Org, import("@oclif/core/interfaces").CustomOptions>;
23
+ 'target-org': import("@oclif/core/interfaces").OptionFlag<import("@salesforce/core").Org, import("@oclif/core/interfaces").CustomOptions>;
27
24
  'api-version': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
28
25
  spec: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
29
26
  'api-name': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
30
- wait: import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
31
27
  'result-format': import("@oclif/core/interfaces").OptionFlag<"json" | "human" | "junit" | "tap", import("@oclif/core/interfaces").CustomOptions>;
32
28
  'batch-size': import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
33
29
  'no-normalize': import("@oclif/core/interfaces").BooleanFlag<boolean>;