@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.
- package/README.md +294 -19
- package/lib/agentSessionScanner.d.ts +12 -0
- package/lib/agentSessionScanner.js +56 -0
- package/lib/agentSessionScanner.js.map +1 -0
- package/lib/commands/agent/test/run-eval.d.ts +1 -5
- package/lib/commands/agent/test/run-eval.js +54 -149
- package/lib/commands/agent/test/run-eval.js.map +1 -1
- package/lib/commands/agent/trace/delete.d.ts +21 -0
- package/lib/commands/agent/trace/delete.js +118 -0
- package/lib/commands/agent/trace/delete.js.map +1 -0
- package/lib/commands/agent/trace/list.d.ts +22 -0
- package/lib/commands/agent/trace/list.js +101 -0
- package/lib/commands/agent/trace/list.js.map +1 -0
- package/lib/commands/agent/trace/read.d.ts +75 -0
- package/lib/commands/agent/trace/read.js +308 -0
- package/lib/commands/agent/trace/read.js.map +1 -0
- package/messages/agent.test.run-eval.md +0 -4
- package/messages/agent.trace.delete.md +87 -0
- package/messages/agent.trace.list.md +87 -0
- package/messages/agent.trace.read.md +171 -0
- package/oclif.manifest.json +801 -525
- package/package.json +4 -4
- package/schemas/agent-trace-delete.json +28 -0
- package/schemas/agent-trace-list.json +34 -0
- package/schemas/agent-trace-read.json +466 -0
- package/lib/evalFormatter.d.ts +0 -30
- package/lib/evalFormatter.js +0 -263
- package/lib/evalFormatter.js.map +0 -1
- package/lib/evalNormalizer.d.ts +0 -57
- package/lib/evalNormalizer.js +0 -431
- package/lib/evalNormalizer.js.map +0 -1
- package/lib/yamlSpecTranslator.d.ts +0 -20
- package/lib/yamlSpecTranslator.js +0 -227
- 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.
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
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>;
|