@salesforce/plugin-agent 2.0.0 → 2.0.2

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 (3) hide show
  1. package/README.md +41 -41
  2. package/oclif.manifest.json +1020 -1020
  3. package/package.json +4 -4
@@ -1120,13 +1120,16 @@
1120
1120
  "upload:adl:agent"
1121
1121
  ]
1122
1122
  },
1123
- "agent:mcp:create": {
1123
+ "agent:generate:agent-spec": {
1124
1124
  "aliases": [],
1125
1125
  "args": {},
1126
- "description": "Registers an external Model Context Protocol (MCP) server with the API Catalog and discovers its assets (tools, prompts, and resources). Provide the server URL and, when the server requires it, OAuth authorization details. When the authorization type is OAUTH you must supply the identity provider, client ID, client secret, and scope.",
1126
+ "description": "An agent spec is a YAML-formatted file that contains basic information about the agent, such as its role, company description, and an AI-generated list of topics based on this information. Topics define the range of jobs your agent can handle.\n\nUse flags, such as --role and --company-description, to provide details about your company and the role that the agent plays in your company. If you prefer, you can also be prompted for the basic information; use --full-interview to be prompted for all required and optional properties. Upon command execution, the large language model (LLM) associated with your org uses the provided information to generate a list of topics for the agent. Because the LLM uses the company and role information to generate the topics, we recommend that you provide accurate, complete, and specific details so the LLM generates the best and most relevant topics. Once generated, you can edit the spec file; for example, you can remove topics that don't apply or change a topic's description.\n\nYou can also iterate the spec generation process by using the --spec flag to pass an existing agent spec file to this command, and then using the --role, --company-description, etc, flags to refine your agent properties. Iteratively improving the description of your agent allows the LLM to generate progressively better topics.\n\nYou can also specify other agent properties, such as a custom prompt template, how to ground the prompt template to add context to the agent's prompts, the tone of the prompts, and the username of a user in the org to assign to the agent.\n\nWhen your agent spec is ready, generate an authoring bundle from it by passing the spec file to the --spec flag of the \"agent generate authoring-bundle\" CLI command. An authoring bundle is a metadata type that contains an Agent Script file, which is the blueprint for an agent. (While not recommended, you can also use the agent spec file to immediately create an agent with the \"agent create\" command. We don't recommend this workflow because these types of agents don't use Agent Script, and are thus less flexible and more difficult to maintain.)",
1127
1127
  "examples": [
1128
- "Create an MCP server with no authentication:\n<%= config.bin %> <%= command.id %> --name myServer --server-url https://mcp.example.com --target-org myOrg",
1129
- "Create an MCP server that uses OAuth authentication, piping the client secret from stdin to keep it out of shell history:\ncat secret.txt | <%= config.bin %> <%= command.id %> --name myServer --server-url https://mcp.example.com --auth-type OAUTH --identity-provider myIdp --client-id abc123 --client-secret - --scope \"read write\" --target-org myOrg"
1128
+ "Generate an agent spec in the default location and use flags to specify the agent properties, such as its role and your company details; use your default org:\n<%= config.bin %> <%= command.id %> --type customer --role \"Field customer complaints and manage employee schedules.\" --company-name \"Coral Cloud Resorts\" --company-description \"Provide customers with exceptional destination activities, unforgettable experiences, and reservation services.\"",
1129
+ "Generate an agent spec by being prompted for the required agent properties and generate a maxiumum of 5 topics; write the generated file to the \"specs/resortManagerSpec.yaml\" file and use the org with alias \"my-org\":\n<%= config.bin %> <%= command.id %> --max-topics 5 --output-file specs/resortManagerAgent.yaml --target-org my-org",
1130
+ "Be prompted for all required and optional agent properties; use your default org:\n<%= config.bin %> <%= command.id %> --full-interview",
1131
+ "Specify an existing agent spec file called \"specs/resortManagerAgent.yaml\", and then overwrite it with a new version that contains newly AI-generated topics based on the updated role information passed in with the --role flag:\n<%= config.bin %> <%= command.id %> --spec specs/resortManagerAgent.yaml --output-file specs/resortManagerAgent.yaml --role \"Field customer complaints, manage employee schedules, and ensure all resort operations are running smoothly\"",
1132
+ "Specify that the conversational tone of the agent is formal and to attach the \"resortmanager@myorg.com\" username to it; be prompted for the required properties and use your default org:\n<%= config.bin %> <%= command.id %> --tone formal --agent-user resortmanager@myorg.com"
1130
1133
  ],
1131
1134
  "flags": {
1132
1135
  "json": {
@@ -1161,113 +1164,164 @@
1161
1164
  "multiple": false,
1162
1165
  "type": "option"
1163
1166
  },
1164
- "name": {
1165
- "char": "n",
1166
- "name": "name",
1167
- "required": true,
1168
- "summary": "Unique name of the MCP server.",
1167
+ "type": {
1168
+ "name": "type",
1169
+ "summary": "Type of agent to create. Internal types are copilots used internally by your company and customer types are the agents you create for your customers.",
1169
1170
  "hasDynamicHelp": false,
1170
1171
  "multiple": false,
1172
+ "options": [
1173
+ "customer",
1174
+ "internal"
1175
+ ],
1171
1176
  "type": "option"
1172
1177
  },
1173
- "label": {
1174
- "name": "label",
1175
- "summary": "Human-readable label for the MCP server.",
1178
+ "role": {
1179
+ "name": "role",
1180
+ "summary": "Role of the agent.",
1176
1181
  "hasDynamicHelp": false,
1177
1182
  "multiple": false,
1178
1183
  "type": "option"
1179
1184
  },
1180
- "description": {
1181
- "name": "description",
1182
- "summary": "Description of the MCP server.",
1185
+ "company-name": {
1186
+ "name": "company-name",
1187
+ "summary": "Name of your company.",
1183
1188
  "hasDynamicHelp": false,
1184
1189
  "multiple": false,
1185
1190
  "type": "option"
1186
1191
  },
1187
- "server-url": {
1188
- "name": "server-url",
1189
- "required": true,
1190
- "summary": "URL of the external MCP server.",
1192
+ "company-description": {
1193
+ "name": "company-description",
1194
+ "summary": "Description of your company.",
1191
1195
  "hasDynamicHelp": false,
1192
1196
  "multiple": false,
1193
1197
  "type": "option"
1194
1198
  },
1195
- "auth-type": {
1196
- "name": "auth-type",
1197
- "summary": "Authorization type to use when connecting to the MCP server.",
1198
- "default": "NO_AUTH",
1199
+ "company-website": {
1200
+ "name": "company-website",
1201
+ "summary": "Website URL of your company.",
1202
+ "hasDynamicHelp": false,
1203
+ "multiple": false,
1204
+ "type": "option"
1205
+ },
1206
+ "max-topics": {
1207
+ "name": "max-topics",
1208
+ "summary": "Maximum number of topics to generate in the agent spec; default is 5.",
1209
+ "hasDynamicHelp": false,
1210
+ "multiple": false,
1211
+ "type": "option"
1212
+ },
1213
+ "agent-user": {
1214
+ "name": "agent-user",
1215
+ "summary": "Username of a user in your org to assign to your agent; determines what your agent can access and do.",
1216
+ "hasDynamicHelp": false,
1217
+ "multiple": false,
1218
+ "type": "option"
1219
+ },
1220
+ "enrich-logs": {
1221
+ "name": "enrich-logs",
1222
+ "summary": "Adds agent conversation data to event logs so you can view all agent session activity in one place.",
1199
1223
  "hasDynamicHelp": false,
1200
1224
  "multiple": false,
1201
1225
  "options": [
1202
- "OAUTH",
1203
- "NO_AUTH"
1226
+ "true",
1227
+ "false"
1204
1228
  ],
1205
1229
  "type": "option"
1206
1230
  },
1207
- "identity-provider": {
1208
- "name": "identity-provider",
1209
- "summary": "Identity provider to use for OAuth authorization. Required when auth-type is OAUTH.",
1231
+ "tone": {
1232
+ "name": "tone",
1233
+ "summary": "Conversational style of the agent, such as how it expresses your brand personality in its messages through word choice, punctuation, and sentence structure.",
1210
1234
  "hasDynamicHelp": false,
1211
1235
  "multiple": false,
1236
+ "options": [
1237
+ "formal",
1238
+ "casual",
1239
+ "neutral"
1240
+ ],
1212
1241
  "type": "option"
1213
1242
  },
1214
- "client-id": {
1215
- "name": "client-id",
1216
- "summary": "OAuth client ID. Required when auth-type is OAUTH.",
1243
+ "spec": {
1244
+ "name": "spec",
1245
+ "summary": "Agent spec file, in YAML format, to use as input to the command.",
1217
1246
  "hasDynamicHelp": false,
1218
1247
  "multiple": false,
1219
1248
  "type": "option"
1220
1249
  },
1221
- "client-secret": {
1222
- "name": "client-secret",
1223
- "summary": "OAuth client secret. Required when auth-type is OAUTH. Pass \"-\" to read it from stdin (piped) and keep it out of shell history.",
1250
+ "output-file": {
1251
+ "name": "output-file",
1252
+ "summary": "Path for the generated YAML agent spec file; can be an absolute or relative path.",
1253
+ "default": "specs/agentSpec.yaml",
1224
1254
  "hasDynamicHelp": false,
1225
1255
  "multiple": false,
1226
1256
  "type": "option"
1227
1257
  },
1228
- "scope": {
1229
- "name": "scope",
1230
- "summary": "OAuth scope to request. Required when auth-type is OAUTH.",
1258
+ "full-interview": {
1259
+ "name": "full-interview",
1260
+ "summary": "Prompt for both required and optional flags.",
1261
+ "allowNo": false,
1262
+ "type": "boolean"
1263
+ },
1264
+ "prompt-template": {
1265
+ "name": "prompt-template",
1266
+ "summary": "API name of a customized prompt template to use instead of the default prompt template.",
1267
+ "hasDynamicHelp": false,
1268
+ "multiple": false,
1269
+ "type": "option"
1270
+ },
1271
+ "grounding-context": {
1272
+ "dependsOn": [
1273
+ "prompt-template"
1274
+ ],
1275
+ "name": "grounding-context",
1276
+ "summary": "Context information and personalization that's added to your prompts when using a custom prompt template.",
1231
1277
  "hasDynamicHelp": false,
1232
1278
  "multiple": false,
1233
1279
  "type": "option"
1280
+ },
1281
+ "force-overwrite": {
1282
+ "name": "force-overwrite",
1283
+ "summary": "Don't prompt the user to confirm that an existing spec file will be overwritten.",
1284
+ "allowNo": false,
1285
+ "type": "boolean"
1234
1286
  }
1235
1287
  },
1236
1288
  "hasDynamicHelp": true,
1237
1289
  "hiddenAliases": [],
1238
- "id": "agent:mcp:create",
1290
+ "id": "agent:generate:agent-spec",
1239
1291
  "pluginAlias": "@salesforce/plugin-agent",
1240
1292
  "pluginName": "@salesforce/plugin-agent",
1241
1293
  "pluginType": "core",
1242
- "state": "preview",
1243
1294
  "strict": true,
1244
- "summary": "Create an MCP server in the API Catalog.",
1295
+ "summary": "Generate an agent spec, which is a YAML file that captures what an agent can do.",
1245
1296
  "enableJsonFlag": true,
1297
+ "requiresProject": true,
1246
1298
  "isESM": true,
1247
1299
  "relativePath": [
1248
1300
  "lib",
1249
1301
  "commands",
1250
1302
  "agent",
1251
- "mcp",
1252
- "create.js"
1303
+ "generate",
1304
+ "agent-spec.js"
1253
1305
  ],
1254
1306
  "aliasPermutations": [],
1255
1307
  "permutations": [
1256
- "agent:mcp:create",
1257
- "mcp:agent:create",
1258
- "mcp:create:agent",
1259
- "agent:create:mcp",
1260
- "create:agent:mcp",
1261
- "create:mcp:agent"
1308
+ "agent:generate:agent-spec",
1309
+ "generate:agent:agent-spec",
1310
+ "generate:agent-spec:agent",
1311
+ "agent:agent-spec:generate",
1312
+ "agent-spec:agent:generate",
1313
+ "agent-spec:generate:agent"
1262
1314
  ]
1263
1315
  },
1264
- "agent:mcp:delete": {
1316
+ "agent:generate:authoring-bundle": {
1265
1317
  "aliases": [],
1266
1318
  "args": {},
1267
- "description": "Permanently removes an MCP (Model Context Protocol) server registration from the API Catalog, identified by its ID. By default you are prompted to confirm the deletion; pass --no-prompt to skip the confirmation (for example in scripts and CI).",
1319
+ "description": "Authoring bundles are metadata components that contain an agent's Agent Script file. The Agent Script file is the agent's blueprint; it fully describes what the agent can do using the Agent Script language.\n\nUse this command to generate a new authoring bundle based on an agent spec YAML file, which you create with the \"agent generate agent-spec\" command. The agent spec YAML file is a high-level description of the agent; it describes its essence rather than exactly what it can do. The resulting Agent Script file is customized to reflect what's in the agent spec file. You can also create an authoring bundle without an agent spec file by specifying the \"--no-spec\" flag; in this case, the resulting Agent Script file is just the default boilerplate.\n\nThe metadata type for authoring bundles is aiAuthoringBundle, which consist of a standard \"<bundle-api-name>.bundle-meta.xml\" metadata file and the Agent Script file (with extension \".agent\"). When you run this command, the new authoring bundle is generated in the force-app/main/default/aiAuthoringBundles/<bundle-api-name> directory. Use the --output-dir flag to generate them elsewhere.\n\nAfter you generate the initial authoring bundle, code the Agent Script file so your agent behaves exactly as you want. The Agent Script file generated by this command is just a first draft of your agent! Interactively test the agent by conversing with it using the \"agent preview\" command. Then publish the agent to your org with the \"agent publish authoring-bundle\" command.\n\nThis command requires an org because it uses it to access an LLM for generating the Agent Script file.",
1268
1320
  "examples": [
1269
- "Delete an MCP server, confirming interactively:\n<%= config.bin %> <%= command.id %> --mcp-server-id 0XSxx0000000001 --target-org myOrg",
1270
- "Delete an MCP server without a confirmation prompt:\n<%= config.bin %> <%= command.id %> --mcp-server-id 0XSxx0000000001 --target-org myOrg --no-prompt"
1321
+ "Generate an authoring bundle by being prompted for all required values, such as the agent spec YAML file, the bundle name, and the API name; use your default org:\n<%= config.bin %> <%= command.id %>",
1322
+ "Generate an authoring bundle without using an agent spec file; give the bundle the label \"My Authoring Bundle\" and use your default org:\n<%= config.bin %> <%= command.id %> --no-spec --name \"My Authoring Bundle\"",
1323
+ "Generate an authoring bundle from the \"specs/agentSpec.yaml\" agent spec YAML file and give it the label \"My Authoring Bundle\"; use your default org:\n<%= config.bin %> <%= command.id %> --spec specs/agentSpec.yaml --name \"My Authoring Bundle\"",
1324
+ "Similar to previous example, but generate the authoring bundle files in the \"other-package-dir/main/default\" package directory; use the org with alias \"my-dev-org\":\n<%= config.bin %> <%= command.id %> --spec specs/agentSpec.yaml --name \"My Authoring Bundle\" --output-dir other-package-dir/main/default --target-org my-dev-org"
1271
1325
  ],
1272
1326
  "flags": {
1273
1327
  "json": {
@@ -1295,6 +1349,13 @@
1295
1349
  "multiple": false,
1296
1350
  "type": "option"
1297
1351
  },
1352
+ "api-name": {
1353
+ "name": "api-name",
1354
+ "summary": "API name of the new authoring bundle; if not specified, the API name is derived from the authoring bundle name (label); the API name can't exist in the org.",
1355
+ "hasDynamicHelp": false,
1356
+ "multiple": false,
1357
+ "type": "option"
1358
+ },
1298
1359
  "api-version": {
1299
1360
  "description": "Override the api version used for api requests made by this command",
1300
1361
  "name": "api-version",
@@ -1302,57 +1363,77 @@
1302
1363
  "multiple": false,
1303
1364
  "type": "option"
1304
1365
  },
1305
- "mcp-server-id": {
1306
- "char": "i",
1307
- "name": "mcp-server-id",
1308
- "required": true,
1309
- "summary": "ID of the MCP server to delete.",
1366
+ "spec": {
1367
+ "char": "f",
1368
+ "name": "spec",
1369
+ "summary": "Path to the agent spec YAML file. If you don't specify the flag, the command provides a list that you can choose from. Use the --no-spec flag to skip using an agent spec entirely.",
1310
1370
  "hasDynamicHelp": false,
1311
1371
  "multiple": false,
1312
1372
  "type": "option"
1313
1373
  },
1314
- "no-prompt": {
1315
- "name": "no-prompt",
1316
- "summary": "Skip the confirmation prompt and delete the MCP server immediately.",
1374
+ "no-spec": {
1375
+ "name": "no-spec",
1376
+ "summary": "Skip prompting for an agent spec and use the default Agent Script boilerplate in the generated authoring bundle.",
1377
+ "allowNo": false,
1378
+ "type": "boolean"
1379
+ },
1380
+ "output-dir": {
1381
+ "char": "d",
1382
+ "name": "output-dir",
1383
+ "summary": "Directory where the authoring bundle files are generated.",
1384
+ "hasDynamicHelp": false,
1385
+ "multiple": false,
1386
+ "type": "option"
1387
+ },
1388
+ "name": {
1389
+ "char": "n",
1390
+ "name": "name",
1391
+ "summary": "Name (label) of the authoring bundle; if not specified, you're prompted for the name.",
1392
+ "hasDynamicHelp": false,
1393
+ "multiple": false,
1394
+ "type": "option"
1395
+ },
1396
+ "force-overwrite": {
1397
+ "name": "force-overwrite",
1398
+ "summary": "Overwrite the existing authoring bundle if one with the same API name already exists locally.",
1317
1399
  "allowNo": false,
1318
1400
  "type": "boolean"
1319
1401
  }
1320
1402
  },
1321
1403
  "hasDynamicHelp": true,
1322
1404
  "hiddenAliases": [],
1323
- "id": "agent:mcp:delete",
1405
+ "id": "agent:generate:authoring-bundle",
1324
1406
  "pluginAlias": "@salesforce/plugin-agent",
1325
1407
  "pluginName": "@salesforce/plugin-agent",
1326
1408
  "pluginType": "core",
1327
- "state": "preview",
1328
1409
  "strict": true,
1329
- "summary": "Delete an MCP server from the API Catalog.",
1410
+ "summary": "Generate an authoring bundle from an existing agent spec YAML file.",
1330
1411
  "enableJsonFlag": true,
1412
+ "requiresProject": true,
1331
1413
  "isESM": true,
1332
1414
  "relativePath": [
1333
1415
  "lib",
1334
1416
  "commands",
1335
1417
  "agent",
1336
- "mcp",
1337
- "delete.js"
1418
+ "generate",
1419
+ "authoring-bundle.js"
1338
1420
  ],
1339
1421
  "aliasPermutations": [],
1340
1422
  "permutations": [
1341
- "agent:mcp:delete",
1342
- "mcp:agent:delete",
1343
- "mcp:delete:agent",
1344
- "agent:delete:mcp",
1345
- "delete:agent:mcp",
1346
- "delete:mcp:agent"
1423
+ "agent:generate:authoring-bundle",
1424
+ "generate:agent:authoring-bundle",
1425
+ "generate:authoring-bundle:agent",
1426
+ "agent:authoring-bundle:generate",
1427
+ "authoring-bundle:agent:generate",
1428
+ "authoring-bundle:generate:agent"
1347
1429
  ]
1348
1430
  },
1349
- "agent:mcp:fetch": {
1431
+ "agent:generate:template": {
1350
1432
  "aliases": [],
1351
1433
  "args": {},
1352
- "description": "Performs a live fetch against the configured MCP server identified by its ID, returning the assets (MCP tools, prompts, and resources) it currently advertises along with their status and activation state. Use this to refresh the view of what an MCP server exposes before activating its assets as agent actions.",
1434
+ "description": "WARNING: This command doesn't work for agents that were created from an Agent Script file. In other words, you can't currently package an agent template for agents that use Agent Script.\n\nAt a high-level, agents are defined by the Bot, BotVersion, and GenAiPlannerBundle metadata types. The GenAiPlannerBundle type in turn defines the agent's topics and actions. This command uses the metadata files for these three types, located in your local DX project, to generate a BotTemplate metadata file for a specific agent (Bot). You then use the BotTemplate metadata file, along with the GenAiPlannerBundle metadata file that references the BotTemplate, to package the template in a managed package that you can share between orgs or on AppExchange.\n\nUse the --agent-file flag to specify the relative or full pathname of the Bot metadata file, such as force-app/main/default/bots/My_Awesome_Agent/My_Awesome_Agent.bot-meta.xml. A single Bot can have multiple BotVersions, so use the --agent-version flag to specify the version. The corresponding BotVersion metadata file must exist locally. For example, if you specify \"--agent-version 4\", then the file force-app/main/default/bots/My_Awesome_Agent/v4.botVersion-meta.xml must exist.\n\nThe new BotTemplate metadata file is generated in the \"botTemplates\" directory in the output directory specified with the --output-dir flag, and has the name <Agent_API_name>\\_v<Version>\\_Template.botTemplate-meta.xml, such as my-package/botTemplates/My_Awesome_Agent_v4_Template.botTemplate-meta.xml. The command displays the full pathname of the generated files when it completes.\n\nSee \"Develop and Package Agent Templates Using Scratch Orgs\" (https://developer.salesforce.com/docs/atlas.en-us.pkg2_dev.meta/pkg2_dev/dev2gp_package_agent_templates.htm) for details about the complete process, which includes using a scratch org to create and test the agent, retrieving the agent metadata to your DX project, running this command to create the agent template, and then packaging the template.",
1353
1435
  "examples": [
1354
- "Fetch the assets advertised by an MCP server in the default target org:\n<%= config.bin %> <%= command.id %> --target-org myOrg --mcp-server-id 0XSxx0000000001",
1355
- "Fetch MCP server assets and output as JSON:\n<%= config.bin %> <%= command.id %> --target-org myOrg --mcp-server-id 0XSxx0000000001 --json"
1436
+ "Generate an agent template from the My_Awesome_Agent Bot metadata file in your DX project and save the BotTemplate and GenAiPlannerBundle to the specified directory; use version 1 of the agent. The agent that the template is based on is in the org with alias \"my-scratch-org\":\n<%= config.bin %> <%= command.id %> --agent-file force-app/main/default/bots/My_Awesome_Agent/My_Awesome_Agent.bot-meta.xml --agent-version 1 --output-dir my-package --source-org my-scratch-org"
1356
1437
  ],
1357
1438
  "flags": {
1358
1439
  "json": {
@@ -1370,16 +1451,6 @@
1370
1451
  "multiple": false,
1371
1452
  "type": "option"
1372
1453
  },
1373
- "target-org": {
1374
- "char": "o",
1375
- "name": "target-org",
1376
- "noCacheDefault": true,
1377
- "required": true,
1378
- "summary": "Username or alias of the target org. Not required if the `target-org` configuration variable is already set.",
1379
- "hasDynamicHelp": true,
1380
- "multiple": false,
1381
- "type": "option"
1382
- },
1383
1454
  "api-version": {
1384
1455
  "description": "Override the api version used for api requests made by this command",
1385
1456
  "name": "api-version",
@@ -1387,90 +1458,37 @@
1387
1458
  "multiple": false,
1388
1459
  "type": "option"
1389
1460
  },
1390
- "mcp-server-id": {
1391
- "char": "i",
1392
- "name": "mcp-server-id",
1461
+ "source-org": {
1462
+ "char": "s",
1463
+ "name": "source-org",
1464
+ "noCacheDefault": true,
1393
1465
  "required": true,
1394
- "summary": "ID of the MCP server to fetch assets from.",
1395
- "hasDynamicHelp": false,
1466
+ "summary": "Username or alias of the namespaced scratch org that contains the agent which this template is based on.",
1467
+ "hasDynamicHelp": true,
1396
1468
  "multiple": false,
1397
1469
  "type": "option"
1398
- }
1399
- },
1400
- "hasDynamicHelp": true,
1401
- "hiddenAliases": [],
1402
- "id": "agent:mcp:fetch",
1403
- "pluginAlias": "@salesforce/plugin-agent",
1404
- "pluginName": "@salesforce/plugin-agent",
1405
- "pluginType": "core",
1406
- "state": "preview",
1407
- "strict": true,
1408
- "summary": "Fetch the live assets (tools, prompts, resources) advertised by an MCP server.",
1409
- "enableJsonFlag": true,
1410
- "isESM": true,
1411
- "relativePath": [
1412
- "lib",
1413
- "commands",
1414
- "agent",
1415
- "mcp",
1416
- "fetch.js"
1417
- ],
1418
- "aliasPermutations": [],
1419
- "permutations": [
1420
- "agent:mcp:fetch",
1421
- "mcp:agent:fetch",
1422
- "mcp:fetch:agent",
1423
- "agent:fetch:mcp",
1424
- "fetch:agent:mcp",
1425
- "fetch:mcp:agent"
1426
- ]
1427
- },
1428
- "agent:mcp:get": {
1429
- "aliases": [],
1430
- "args": {},
1431
- "description": "Retrieves the details of an MCP (Model Context Protocol) server by its identifier, including its name, label, type, status, and server URL.",
1432
- "examples": [
1433
- "Get an MCP server by id in the default target org:\n<%= config.bin %> <%= command.id %> --target-org myOrg --mcp-server-id 0Mx000000000001",
1434
- "Get an MCP server and output as JSON:\n<%= config.bin %> <%= command.id %> --target-org myOrg --mcp-server-id 0Mx000000000001 --json"
1435
- ],
1436
- "flags": {
1437
- "json": {
1438
- "description": "Format output as json.",
1439
- "helpGroup": "GLOBAL",
1440
- "name": "json",
1441
- "allowNo": false,
1442
- "type": "boolean"
1443
1470
  },
1444
- "flags-dir": {
1445
- "helpGroup": "GLOBAL",
1446
- "name": "flags-dir",
1447
- "summary": "Import flag values from a directory.",
1471
+ "agent-version": {
1472
+ "name": "agent-version",
1473
+ "required": true,
1474
+ "summary": "Version of the agent (BotVersion).",
1448
1475
  "hasDynamicHelp": false,
1449
1476
  "multiple": false,
1450
1477
  "type": "option"
1451
1478
  },
1452
- "target-org": {
1453
- "char": "o",
1454
- "name": "target-org",
1455
- "noCacheDefault": true,
1479
+ "agent-file": {
1480
+ "char": "f",
1481
+ "name": "agent-file",
1456
1482
  "required": true,
1457
- "summary": "Username or alias of the target org. Not required if the `target-org` configuration variable is already set.",
1458
- "hasDynamicHelp": true,
1459
- "multiple": false,
1460
- "type": "option"
1461
- },
1462
- "api-version": {
1463
- "description": "Override the api version used for api requests made by this command",
1464
- "name": "api-version",
1483
+ "summary": "Path to an agent (Bot) metadata file.",
1465
1484
  "hasDynamicHelp": false,
1466
1485
  "multiple": false,
1467
1486
  "type": "option"
1468
1487
  },
1469
- "mcp-server-id": {
1470
- "char": "i",
1471
- "name": "mcp-server-id",
1472
- "required": true,
1473
- "summary": "The identifier of the MCP server to retrieve.",
1488
+ "output-dir": {
1489
+ "char": "r",
1490
+ "name": "output-dir",
1491
+ "summary": "Directory where the generated BotTemplate and GenAiPlannerBundle files are saved.",
1474
1492
  "hasDynamicHelp": false,
1475
1493
  "multiple": false,
1476
1494
  "type": "option"
@@ -1478,48 +1496,44 @@
1478
1496
  },
1479
1497
  "hasDynamicHelp": true,
1480
1498
  "hiddenAliases": [],
1481
- "id": "agent:mcp:get",
1499
+ "id": "agent:generate:template",
1482
1500
  "pluginAlias": "@salesforce/plugin-agent",
1483
1501
  "pluginName": "@salesforce/plugin-agent",
1484
1502
  "pluginType": "core",
1485
- "state": "preview",
1486
1503
  "strict": true,
1487
- "summary": "Get a single MCP server registered in the API Catalog.",
1504
+ "summary": "Generate an agent template from an existing agent in your DX project so you can then package the template in a second-generation managed package.",
1488
1505
  "enableJsonFlag": true,
1506
+ "requiresProject": true,
1489
1507
  "isESM": true,
1490
1508
  "relativePath": [
1491
1509
  "lib",
1492
1510
  "commands",
1493
1511
  "agent",
1494
- "mcp",
1495
- "get.js"
1512
+ "generate",
1513
+ "template.js"
1496
1514
  ],
1497
1515
  "aliasPermutations": [],
1498
1516
  "permutations": [
1499
- "agent:mcp:get",
1500
- "mcp:agent:get",
1501
- "mcp:get:agent",
1502
- "agent:get:mcp",
1503
- "get:agent:mcp",
1504
- "get:mcp:agent"
1517
+ "agent:generate:template",
1518
+ "generate:agent:template",
1519
+ "generate:template:agent",
1520
+ "agent:template:generate",
1521
+ "template:agent:generate",
1522
+ "template:generate:agent"
1505
1523
  ]
1506
1524
  },
1507
- "agent:mcp:list": {
1525
+ "agent:generate:test-spec": {
1508
1526
  "aliases": [],
1509
1527
  "args": {},
1510
- "description": "Returns the Model Context Protocol (MCP) servers registered in the API Catalog, optionally filtered by label, type, or status. Use this to discover which MCP servers are available and inspect their server URLs and current status.",
1528
+ "description": "The first step when using Salesforce CLI to create an agent test in your org is to use this interactive command to generate a local YAML-formatted test spec file. The test spec YAML file contains information about the agent being tested, such as its API name, and then one or more test cases. This command uses the metadata components in your DX project when prompting for information, such as the agent API name; it doesn't look in your org.\n\nTo generate a specific agent test case, this command prompts you for this information; when possible, the command provides a list of options for you to choose from:\n\n- Utterance: Natural language statement, question, or command used to test the agent.\n- Expected topic: API name of the topic you expect the agent to use when responding to the utterance.\n- Expected actions: One or more API names of the expection actions the agent takes.\n- Expected outcome: Natural language description of the outcome you expect.\n- (Optional) Custom evaluation: Test an agent's response for specific strings or numbers.\n- (Optional) Conversation history: Boilerplate for additional context you can add to the test in the form of a conversation history.\n\nYou can manually add contextVariables to test cases in the generated YAML file to inject contextual data (such as CaseId or RoutableId) into agent sessions. This is useful for testing agent behavior with different contextual information.\n\nWhen your test spec is ready, you then run the \"agent test create\" command to actually create the test in your org and synchronize the metadata with your DX project. The metadata type for an agent test is `AiEvaluationDefinition` (legacy testing-center) or `AiTestingDefinition` (Agentforce Studio / NGT), selected via --test-runner.\n\nIf you have an existing AiEvaluationDefinition or AiTestingDefinition metadata XML file in your DX project, you can generate its equivalent YAML test spec file with the --from-definition flag. The runner is inferred from the file extension; pass --test-runner to override.",
1511
1529
  "examples": [
1512
- "List all MCP servers in the default target org:\n<%= config.bin %> <%= command.id %> --target-org myOrg",
1513
- "List external MCP servers filtered by status and output as JSON:\n<%= config.bin %> <%= command.id %> --target-org myOrg --type EXTERNAL --status ACTIVE --json"
1530
+ "Generate an agent test spec YAML file interactively:\n<%= config.bin %> <%= command.id %>",
1531
+ "Generate an Agentforce Studio (NGT) test spec YAML file interactively:\n<%= config.bin %> <%= command.id %> --test-runner agentforce-studio",
1532
+ "Generate an agent test spec YAML file and specify a name for the new file; if the file exists, overwrite it without confirmation:\n<%= config.bin %> <%= command.id %> --output-file specs/Resort_Manager-new-version-testSpec.yaml --force-overwrite",
1533
+ "Generate an agent test spec YAML file from an existing AiEvaluationDefinition metadata XML file in your DX project:\n<%= config.bin %> <%= command.id %> --from-definition force-app/main/default/aiEvaluationDefinitions/Resort_Manager_Tests.aiEvaluationDefinition-meta.xml",
1534
+ "Generate an Agentforce Studio (NGT) test spec YAML file from an existing AiTestingDefinition metadata XML file:\n<%= config.bin %> <%= command.id %> --from-definition force-app/main/default/aiTestingDefinitions/Returns_Checkout_Tests.aiTestingDefinition-meta.xml"
1514
1535
  ],
1515
1536
  "flags": {
1516
- "json": {
1517
- "description": "Format output as json.",
1518
- "helpGroup": "GLOBAL",
1519
- "name": "json",
1520
- "allowNo": false,
1521
- "type": "boolean"
1522
- },
1523
1537
  "flags-dir": {
1524
1538
  "helpGroup": "GLOBAL",
1525
1539
  "name": "flags-dir",
@@ -1528,87 +1542,75 @@
1528
1542
  "multiple": false,
1529
1543
  "type": "option"
1530
1544
  },
1531
- "target-org": {
1532
- "char": "o",
1533
- "name": "target-org",
1534
- "noCacheDefault": true,
1535
- "required": true,
1536
- "summary": "Username or alias of the target org. Not required if the `target-org` configuration variable is already set.",
1537
- "hasDynamicHelp": true,
1538
- "multiple": false,
1539
- "type": "option"
1540
- },
1541
- "api-version": {
1542
- "description": "Override the api version used for api requests made by this command",
1543
- "name": "api-version",
1545
+ "from-definition": {
1546
+ "char": "d",
1547
+ "name": "from-definition",
1548
+ "summary": "Filepath to an AiEvaluationDefinition or AiTestingDefinition metadata XML file in your DX project that you want to convert to a test spec YAML file.",
1544
1549
  "hasDynamicHelp": false,
1545
1550
  "multiple": false,
1546
1551
  "type": "option"
1547
1552
  },
1548
- "label": {
1549
- "name": "label",
1550
- "summary": "Filter the MCP servers by label.",
1551
- "hasDynamicHelp": false,
1552
- "multiple": false,
1553
- "type": "option"
1553
+ "force-overwrite": {
1554
+ "name": "force-overwrite",
1555
+ "summary": "Don't prompt for confirmation when overwriting an existing test spec YAML file.",
1556
+ "allowNo": false,
1557
+ "type": "boolean"
1554
1558
  },
1555
- "type": {
1556
- "name": "type",
1557
- "summary": "Filter the MCP servers by type.",
1559
+ "output-file": {
1560
+ "char": "f",
1561
+ "name": "output-file",
1562
+ "summary": "Name of the generated test spec YAML file. Default value is \"specs/<AGENT_API_NAME>-testSpec.yaml\" (legacy) or \"specs/<AGENT_API_NAME>-ngtTestSpec.yaml\" (Agentforce Studio).",
1558
1563
  "hasDynamicHelp": false,
1559
1564
  "multiple": false,
1560
- "options": [
1561
- "EXTERNAL"
1562
- ],
1563
1565
  "type": "option"
1564
1566
  },
1565
- "status": {
1566
- "name": "status",
1567
- "summary": "Filter the MCP servers by connection status. Only ACTIVE and DISCONNECTED are supported as filters.",
1567
+ "test-runner": {
1568
+ "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.",
1569
+ "name": "test-runner",
1570
+ "summary": "Explicitly specify which test runner to use (agentforce-studio or testing-center).",
1568
1571
  "hasDynamicHelp": false,
1569
1572
  "multiple": false,
1570
1573
  "options": [
1571
- "ACTIVE",
1572
- "DISCONNECTED"
1574
+ "agentforce-studio",
1575
+ "testing-center"
1573
1576
  ],
1574
1577
  "type": "option"
1575
1578
  }
1576
1579
  },
1577
- "hasDynamicHelp": true,
1580
+ "hasDynamicHelp": false,
1578
1581
  "hiddenAliases": [],
1579
- "id": "agent:mcp:list",
1582
+ "id": "agent:generate:test-spec",
1580
1583
  "pluginAlias": "@salesforce/plugin-agent",
1581
1584
  "pluginName": "@salesforce/plugin-agent",
1582
1585
  "pluginType": "core",
1583
- "state": "preview",
1584
1586
  "strict": true,
1585
- "summary": "List the MCP servers registered in the API Catalog.",
1586
- "enableJsonFlag": true,
1587
+ "summary": "Generate an agent test spec, which is a YAML file that lists the test cases for testing a specific agent.",
1588
+ "enableJsonFlag": false,
1587
1589
  "isESM": true,
1588
1590
  "relativePath": [
1589
1591
  "lib",
1590
1592
  "commands",
1591
1593
  "agent",
1592
- "mcp",
1593
- "list.js"
1594
+ "generate",
1595
+ "test-spec.js"
1594
1596
  ],
1595
1597
  "aliasPermutations": [],
1596
1598
  "permutations": [
1597
- "agent:mcp:list",
1598
- "mcp:agent:list",
1599
- "mcp:list:agent",
1600
- "agent:list:mcp",
1601
- "list:agent:mcp",
1602
- "list:mcp:agent"
1599
+ "agent:generate:test-spec",
1600
+ "generate:agent:test-spec",
1601
+ "generate:test-spec:agent",
1602
+ "agent:test-spec:generate",
1603
+ "test-spec:agent:generate",
1604
+ "test-spec:generate:agent"
1603
1605
  ]
1604
1606
  },
1605
- "agent:mcp:update": {
1607
+ "agent:mcp:create": {
1606
1608
  "aliases": [],
1607
1609
  "args": {},
1608
- "description": "Updates an existing MCP server in the API Catalog. Only the fields you provide are changed; omitted fields are left untouched. You can update the label, description, and server URL, and replace the authorization configuration. When setting `--auth-type OAUTH`, you must also provide `--identity-provider`, `--client-id`, `--client-secret`, and `--scope`. When setting `--auth-type NO_AUTH`, no authorization credentials are required. At least one updatable field must be supplied.",
1610
+ "description": "Registers an external Model Context Protocol (MCP) server with the API Catalog and discovers its assets (tools, prompts, and resources). Provide the server URL and, when the server requires it, OAuth authorization details. When the authorization type is OAUTH you must supply the identity provider, client ID, client secret, and scope.",
1609
1611
  "examples": [
1610
- "Update the label and description of an MCP server in the default target org:\n<%= config.bin %> <%= command.id %> --mcp-server-id 0XSxx0000000001 --label \"Orders MCP\" --description \"Order tooling\" --target-org myOrg",
1611
- "Update the server URL and switch the authorization to OAuth, piping the client secret from stdin and outputting as JSON:\ncat secret.txt | <%= config.bin %> <%= command.id %> --mcp-server-id 0XSxx0000000001 --server-url https://mcp.example.com --auth-type OAUTH --identity-provider MyIdp --client-id abc --client-secret - --scope \"read write\" --target-org myOrg --json"
1612
+ "Create an MCP server with no authentication:\n<%= config.bin %> <%= command.id %> --name myServer --server-url https://mcp.example.com --target-org myOrg",
1613
+ "Create an MCP server that uses OAuth authentication, piping the client secret from stdin to keep it out of shell history:\ncat secret.txt | <%= config.bin %> <%= command.id %> --name myServer --server-url https://mcp.example.com --auth-type OAUTH --identity-provider myIdp --client-id abc123 --client-secret - --scope \"read write\" --target-org myOrg"
1612
1614
  ],
1613
1615
  "flags": {
1614
1616
  "json": {
@@ -1643,39 +1645,41 @@
1643
1645
  "multiple": false,
1644
1646
  "type": "option"
1645
1647
  },
1646
- "mcp-server-id": {
1647
- "char": "i",
1648
- "name": "mcp-server-id",
1648
+ "name": {
1649
+ "char": "n",
1650
+ "name": "name",
1649
1651
  "required": true,
1650
- "summary": "ID of the MCP server to update.",
1652
+ "summary": "Unique name of the MCP server.",
1651
1653
  "hasDynamicHelp": false,
1652
1654
  "multiple": false,
1653
1655
  "type": "option"
1654
1656
  },
1655
1657
  "label": {
1656
1658
  "name": "label",
1657
- "summary": "New display label for the MCP server.",
1659
+ "summary": "Human-readable label for the MCP server.",
1658
1660
  "hasDynamicHelp": false,
1659
1661
  "multiple": false,
1660
1662
  "type": "option"
1661
1663
  },
1662
1664
  "description": {
1663
1665
  "name": "description",
1664
- "summary": "New description for the MCP server.",
1666
+ "summary": "Description of the MCP server.",
1665
1667
  "hasDynamicHelp": false,
1666
1668
  "multiple": false,
1667
1669
  "type": "option"
1668
1670
  },
1669
1671
  "server-url": {
1670
1672
  "name": "server-url",
1671
- "summary": "New endpoint URL of the MCP server.",
1673
+ "required": true,
1674
+ "summary": "URL of the external MCP server.",
1672
1675
  "hasDynamicHelp": false,
1673
1676
  "multiple": false,
1674
1677
  "type": "option"
1675
1678
  },
1676
1679
  "auth-type": {
1677
1680
  "name": "auth-type",
1678
- "summary": "Authorization type to apply to the MCP server (OAUTH or NO_AUTH).",
1681
+ "summary": "Authorization type to use when connecting to the MCP server.",
1682
+ "default": "NO_AUTH",
1679
1683
  "hasDynamicHelp": false,
1680
1684
  "multiple": false,
1681
1685
  "options": [
@@ -1686,28 +1690,28 @@
1686
1690
  },
1687
1691
  "identity-provider": {
1688
1692
  "name": "identity-provider",
1689
- "summary": "Identity provider name for OAuth authorization (required when --auth-type is OAUTH).",
1693
+ "summary": "Identity provider to use for OAuth authorization. Required when auth-type is OAUTH.",
1690
1694
  "hasDynamicHelp": false,
1691
1695
  "multiple": false,
1692
1696
  "type": "option"
1693
1697
  },
1694
1698
  "client-id": {
1695
1699
  "name": "client-id",
1696
- "summary": "OAuth client ID (required when --auth-type is OAUTH).",
1700
+ "summary": "OAuth client ID. Required when auth-type is OAUTH.",
1697
1701
  "hasDynamicHelp": false,
1698
1702
  "multiple": false,
1699
1703
  "type": "option"
1700
1704
  },
1701
1705
  "client-secret": {
1702
1706
  "name": "client-secret",
1703
- "summary": "OAuth client secret (required when --auth-type is OAUTH). Pass \"-\" to read it from stdin (piped) and keep it out of shell history.",
1707
+ "summary": "OAuth client secret. Required when auth-type is OAUTH. Pass \"-\" to read it from stdin (piped) and keep it out of shell history.",
1704
1708
  "hasDynamicHelp": false,
1705
1709
  "multiple": false,
1706
1710
  "type": "option"
1707
1711
  },
1708
1712
  "scope": {
1709
1713
  "name": "scope",
1710
- "summary": "OAuth scope (required when --auth-type is OAUTH).",
1714
+ "summary": "OAuth scope to request. Required when auth-type is OAUTH.",
1711
1715
  "hasDynamicHelp": false,
1712
1716
  "multiple": false,
1713
1717
  "type": "option"
@@ -1715,13 +1719,13 @@
1715
1719
  },
1716
1720
  "hasDynamicHelp": true,
1717
1721
  "hiddenAliases": [],
1718
- "id": "agent:mcp:update",
1722
+ "id": "agent:mcp:create",
1719
1723
  "pluginAlias": "@salesforce/plugin-agent",
1720
1724
  "pluginName": "@salesforce/plugin-agent",
1721
1725
  "pluginType": "core",
1722
1726
  "state": "preview",
1723
1727
  "strict": true,
1724
- "summary": "Update an MCP server registered in the API Catalog.",
1728
+ "summary": "Create an MCP server in the API Catalog.",
1725
1729
  "enableJsonFlag": true,
1726
1730
  "isESM": true,
1727
1731
  "relativePath": [
@@ -1729,28 +1733,25 @@
1729
1733
  "commands",
1730
1734
  "agent",
1731
1735
  "mcp",
1732
- "update.js"
1736
+ "create.js"
1733
1737
  ],
1734
1738
  "aliasPermutations": [],
1735
1739
  "permutations": [
1736
- "agent:mcp:update",
1737
- "mcp:agent:update",
1738
- "mcp:update:agent",
1739
- "agent:update:mcp",
1740
- "update:agent:mcp",
1741
- "update:mcp:agent"
1740
+ "agent:mcp:create",
1741
+ "mcp:agent:create",
1742
+ "mcp:create:agent",
1743
+ "agent:create:mcp",
1744
+ "create:agent:mcp",
1745
+ "create:mcp:agent"
1742
1746
  ]
1743
1747
  },
1744
- "agent:generate:agent-spec": {
1748
+ "agent:mcp:delete": {
1745
1749
  "aliases": [],
1746
1750
  "args": {},
1747
- "description": "An agent spec is a YAML-formatted file that contains basic information about the agent, such as its role, company description, and an AI-generated list of topics based on this information. Topics define the range of jobs your agent can handle.\n\nUse flags, such as --role and --company-description, to provide details about your company and the role that the agent plays in your company. If you prefer, you can also be prompted for the basic information; use --full-interview to be prompted for all required and optional properties. Upon command execution, the large language model (LLM) associated with your org uses the provided information to generate a list of topics for the agent. Because the LLM uses the company and role information to generate the topics, we recommend that you provide accurate, complete, and specific details so the LLM generates the best and most relevant topics. Once generated, you can edit the spec file; for example, you can remove topics that don't apply or change a topic's description.\n\nYou can also iterate the spec generation process by using the --spec flag to pass an existing agent spec file to this command, and then using the --role, --company-description, etc, flags to refine your agent properties. Iteratively improving the description of your agent allows the LLM to generate progressively better topics.\n\nYou can also specify other agent properties, such as a custom prompt template, how to ground the prompt template to add context to the agent's prompts, the tone of the prompts, and the username of a user in the org to assign to the agent.\n\nWhen your agent spec is ready, generate an authoring bundle from it by passing the spec file to the --spec flag of the \"agent generate authoring-bundle\" CLI command. An authoring bundle is a metadata type that contains an Agent Script file, which is the blueprint for an agent. (While not recommended, you can also use the agent spec file to immediately create an agent with the \"agent create\" command. We don't recommend this workflow because these types of agents don't use Agent Script, and are thus less flexible and more difficult to maintain.)",
1751
+ "description": "Permanently removes an MCP (Model Context Protocol) server registration from the API Catalog, identified by its ID. By default you are prompted to confirm the deletion; pass --no-prompt to skip the confirmation (for example in scripts and CI).",
1748
1752
  "examples": [
1749
- "Generate an agent spec in the default location and use flags to specify the agent properties, such as its role and your company details; use your default org:\n<%= config.bin %> <%= command.id %> --type customer --role \"Field customer complaints and manage employee schedules.\" --company-name \"Coral Cloud Resorts\" --company-description \"Provide customers with exceptional destination activities, unforgettable experiences, and reservation services.\"",
1750
- "Generate an agent spec by being prompted for the required agent properties and generate a maxiumum of 5 topics; write the generated file to the \"specs/resortManagerSpec.yaml\" file and use the org with alias \"my-org\":\n<%= config.bin %> <%= command.id %> --max-topics 5 --output-file specs/resortManagerAgent.yaml --target-org my-org",
1751
- "Be prompted for all required and optional agent properties; use your default org:\n<%= config.bin %> <%= command.id %> --full-interview",
1752
- "Specify an existing agent spec file called \"specs/resortManagerAgent.yaml\", and then overwrite it with a new version that contains newly AI-generated topics based on the updated role information passed in with the --role flag:\n<%= config.bin %> <%= command.id %> --spec specs/resortManagerAgent.yaml --output-file specs/resortManagerAgent.yaml --role \"Field customer complaints, manage employee schedules, and ensure all resort operations are running smoothly\"",
1753
- "Specify that the conversational tone of the agent is formal and to attach the \"resortmanager@myorg.com\" username to it; be prompted for the required properties and use your default org:\n<%= config.bin %> <%= command.id %> --tone formal --agent-user resortmanager@myorg.com"
1753
+ "Delete an MCP server, confirming interactively:\n<%= config.bin %> <%= command.id %> --mcp-server-id 0XSxx0000000001 --target-org myOrg",
1754
+ "Delete an MCP server without a confirmation prompt:\n<%= config.bin %> <%= command.id %> --mcp-server-id 0XSxx0000000001 --target-org myOrg --no-prompt"
1754
1755
  ],
1755
1756
  "flags": {
1756
1757
  "json": {
@@ -1785,164 +1786,57 @@
1785
1786
  "multiple": false,
1786
1787
  "type": "option"
1787
1788
  },
1788
- "type": {
1789
- "name": "type",
1790
- "summary": "Type of agent to create. Internal types are copilots used internally by your company and customer types are the agents you create for your customers.",
1791
- "hasDynamicHelp": false,
1792
- "multiple": false,
1793
- "options": [
1794
- "customer",
1795
- "internal"
1796
- ],
1797
- "type": "option"
1798
- },
1799
- "role": {
1800
- "name": "role",
1801
- "summary": "Role of the agent.",
1802
- "hasDynamicHelp": false,
1803
- "multiple": false,
1804
- "type": "option"
1805
- },
1806
- "company-name": {
1807
- "name": "company-name",
1808
- "summary": "Name of your company.",
1809
- "hasDynamicHelp": false,
1810
- "multiple": false,
1811
- "type": "option"
1812
- },
1813
- "company-description": {
1814
- "name": "company-description",
1815
- "summary": "Description of your company.",
1816
- "hasDynamicHelp": false,
1817
- "multiple": false,
1818
- "type": "option"
1819
- },
1820
- "company-website": {
1821
- "name": "company-website",
1822
- "summary": "Website URL of your company.",
1823
- "hasDynamicHelp": false,
1824
- "multiple": false,
1825
- "type": "option"
1826
- },
1827
- "max-topics": {
1828
- "name": "max-topics",
1829
- "summary": "Maximum number of topics to generate in the agent spec; default is 5.",
1830
- "hasDynamicHelp": false,
1831
- "multiple": false,
1832
- "type": "option"
1833
- },
1834
- "agent-user": {
1835
- "name": "agent-user",
1836
- "summary": "Username of a user in your org to assign to your agent; determines what your agent can access and do.",
1837
- "hasDynamicHelp": false,
1838
- "multiple": false,
1839
- "type": "option"
1840
- },
1841
- "enrich-logs": {
1842
- "name": "enrich-logs",
1843
- "summary": "Adds agent conversation data to event logs so you can view all agent session activity in one place.",
1844
- "hasDynamicHelp": false,
1845
- "multiple": false,
1846
- "options": [
1847
- "true",
1848
- "false"
1849
- ],
1850
- "type": "option"
1851
- },
1852
- "tone": {
1853
- "name": "tone",
1854
- "summary": "Conversational style of the agent, such as how it expresses your brand personality in its messages through word choice, punctuation, and sentence structure.",
1855
- "hasDynamicHelp": false,
1856
- "multiple": false,
1857
- "options": [
1858
- "formal",
1859
- "casual",
1860
- "neutral"
1861
- ],
1862
- "type": "option"
1863
- },
1864
- "spec": {
1865
- "name": "spec",
1866
- "summary": "Agent spec file, in YAML format, to use as input to the command.",
1867
- "hasDynamicHelp": false,
1868
- "multiple": false,
1869
- "type": "option"
1870
- },
1871
- "output-file": {
1872
- "name": "output-file",
1873
- "summary": "Path for the generated YAML agent spec file; can be an absolute or relative path.",
1874
- "default": "specs/agentSpec.yaml",
1875
- "hasDynamicHelp": false,
1876
- "multiple": false,
1877
- "type": "option"
1878
- },
1879
- "full-interview": {
1880
- "name": "full-interview",
1881
- "summary": "Prompt for both required and optional flags.",
1882
- "allowNo": false,
1883
- "type": "boolean"
1884
- },
1885
- "prompt-template": {
1886
- "name": "prompt-template",
1887
- "summary": "API name of a customized prompt template to use instead of the default prompt template.",
1888
- "hasDynamicHelp": false,
1889
- "multiple": false,
1890
- "type": "option"
1891
- },
1892
- "grounding-context": {
1893
- "dependsOn": [
1894
- "prompt-template"
1895
- ],
1896
- "name": "grounding-context",
1897
- "summary": "Context information and personalization that's added to your prompts when using a custom prompt template.",
1789
+ "mcp-server-id": {
1790
+ "char": "i",
1791
+ "name": "mcp-server-id",
1792
+ "required": true,
1793
+ "summary": "ID of the MCP server to delete.",
1898
1794
  "hasDynamicHelp": false,
1899
1795
  "multiple": false,
1900
1796
  "type": "option"
1901
1797
  },
1902
- "force-overwrite": {
1903
- "name": "force-overwrite",
1904
- "summary": "Don't prompt the user to confirm that an existing spec file will be overwritten.",
1798
+ "no-prompt": {
1799
+ "name": "no-prompt",
1800
+ "summary": "Skip the confirmation prompt and delete the MCP server immediately.",
1905
1801
  "allowNo": false,
1906
1802
  "type": "boolean"
1907
1803
  }
1908
1804
  },
1909
1805
  "hasDynamicHelp": true,
1910
1806
  "hiddenAliases": [],
1911
- "id": "agent:generate:agent-spec",
1807
+ "id": "agent:mcp:delete",
1912
1808
  "pluginAlias": "@salesforce/plugin-agent",
1913
1809
  "pluginName": "@salesforce/plugin-agent",
1914
1810
  "pluginType": "core",
1811
+ "state": "preview",
1915
1812
  "strict": true,
1916
- "summary": "Generate an agent spec, which is a YAML file that captures what an agent can do.",
1813
+ "summary": "Delete an MCP server from the API Catalog.",
1917
1814
  "enableJsonFlag": true,
1918
- "requiresProject": true,
1919
1815
  "isESM": true,
1920
1816
  "relativePath": [
1921
1817
  "lib",
1922
1818
  "commands",
1923
1819
  "agent",
1924
- "generate",
1925
- "agent-spec.js"
1820
+ "mcp",
1821
+ "delete.js"
1926
1822
  ],
1927
1823
  "aliasPermutations": [],
1928
1824
  "permutations": [
1929
- "agent:generate:agent-spec",
1930
- "generate:agent:agent-spec",
1931
- "generate:agent-spec:agent",
1932
- "agent:agent-spec:generate",
1933
- "agent-spec:agent:generate",
1934
- "agent-spec:generate:agent"
1825
+ "agent:mcp:delete",
1826
+ "mcp:agent:delete",
1827
+ "mcp:delete:agent",
1828
+ "agent:delete:mcp",
1829
+ "delete:agent:mcp",
1830
+ "delete:mcp:agent"
1935
1831
  ]
1936
1832
  },
1937
- "agent:generate:authoring-bundle": {
1833
+ "agent:mcp:fetch": {
1938
1834
  "aliases": [],
1939
1835
  "args": {},
1940
- "description": "Authoring bundles are metadata components that contain an agent's Agent Script file. The Agent Script file is the agent's blueprint; it fully describes what the agent can do using the Agent Script language.\n\nUse this command to generate a new authoring bundle based on an agent spec YAML file, which you create with the \"agent generate agent-spec\" command. The agent spec YAML file is a high-level description of the agent; it describes its essence rather than exactly what it can do. The resulting Agent Script file is customized to reflect what's in the agent spec file. You can also create an authoring bundle without an agent spec file by specifying the \"--no-spec\" flag; in this case, the resulting Agent Script file is just the default boilerplate.\n\nThe metadata type for authoring bundles is aiAuthoringBundle, which consist of a standard \"<bundle-api-name>.bundle-meta.xml\" metadata file and the Agent Script file (with extension \".agent\"). When you run this command, the new authoring bundle is generated in the force-app/main/default/aiAuthoringBundles/<bundle-api-name> directory. Use the --output-dir flag to generate them elsewhere.\n\nAfter you generate the initial authoring bundle, code the Agent Script file so your agent behaves exactly as you want. The Agent Script file generated by this command is just a first draft of your agent! Interactively test the agent by conversing with it using the \"agent preview\" command. Then publish the agent to your org with the \"agent publish authoring-bundle\" command.\n\nThis command requires an org because it uses it to access an LLM for generating the Agent Script file.",
1836
+ "description": "Performs a live fetch against the configured MCP server identified by its ID, returning the assets (MCP tools, prompts, and resources) it currently advertises along with their status and activation state. Use this to refresh the view of what an MCP server exposes before activating its assets as agent actions.",
1941
1837
  "examples": [
1942
- "Generate an authoring bundle by being prompted for all required values, such as the agent spec YAML file, the bundle name, and the API name; use your default org:\n<%= config.bin %> <%= command.id %>",
1943
- "Generate an authoring bundle without using an agent spec file; give the bundle the label \"My Authoring Bundle\" and use your default org:\n<%= config.bin %> <%= command.id %> --no-spec --name \"My Authoring Bundle\"",
1944
- "Generate an authoring bundle from the \"specs/agentSpec.yaml\" agent spec YAML file and give it the label \"My Authoring Bundle\"; use your default org:\n<%= config.bin %> <%= command.id %> --spec specs/agentSpec.yaml --name \"My Authoring Bundle\"",
1945
- "Similar to previous example, but generate the authoring bundle files in the \"other-package-dir/main/default\" package directory; use the org with alias \"my-dev-org\":\n<%= config.bin %> <%= command.id %> --spec specs/agentSpec.yaml --name \"My Authoring Bundle\" --output-dir other-package-dir/main/default --target-org my-dev-org"
1838
+ "Fetch the assets advertised by an MCP server in the default target org:\n<%= config.bin %> <%= command.id %> --target-org myOrg --mcp-server-id 0XSxx0000000001",
1839
+ "Fetch MCP server assets and output as JSON:\n<%= config.bin %> <%= command.id %> --target-org myOrg --mcp-server-id 0XSxx0000000001 --json"
1946
1840
  ],
1947
1841
  "flags": {
1948
1842
  "json": {
@@ -1970,13 +1864,6 @@
1970
1864
  "multiple": false,
1971
1865
  "type": "option"
1972
1866
  },
1973
- "api-name": {
1974
- "name": "api-name",
1975
- "summary": "API name of the new authoring bundle; if not specified, the API name is derived from the authoring bundle name (label); the API name can't exist in the org.",
1976
- "hasDynamicHelp": false,
1977
- "multiple": false,
1978
- "type": "option"
1979
- },
1980
1867
  "api-version": {
1981
1868
  "description": "Override the api version used for api requests made by this command",
1982
1869
  "name": "api-version",
@@ -1984,77 +1871,51 @@
1984
1871
  "multiple": false,
1985
1872
  "type": "option"
1986
1873
  },
1987
- "spec": {
1988
- "char": "f",
1989
- "name": "spec",
1990
- "summary": "Path to the agent spec YAML file. If you don't specify the flag, the command provides a list that you can choose from. Use the --no-spec flag to skip using an agent spec entirely.",
1991
- "hasDynamicHelp": false,
1992
- "multiple": false,
1993
- "type": "option"
1994
- },
1995
- "no-spec": {
1996
- "name": "no-spec",
1997
- "summary": "Skip prompting for an agent spec and use the default Agent Script boilerplate in the generated authoring bundle.",
1998
- "allowNo": false,
1999
- "type": "boolean"
2000
- },
2001
- "output-dir": {
2002
- "char": "d",
2003
- "name": "output-dir",
2004
- "summary": "Directory where the authoring bundle files are generated.",
2005
- "hasDynamicHelp": false,
2006
- "multiple": false,
2007
- "type": "option"
2008
- },
2009
- "name": {
2010
- "char": "n",
2011
- "name": "name",
2012
- "summary": "Name (label) of the authoring bundle; if not specified, you're prompted for the name.",
1874
+ "mcp-server-id": {
1875
+ "char": "i",
1876
+ "name": "mcp-server-id",
1877
+ "required": true,
1878
+ "summary": "ID of the MCP server to fetch assets from.",
2013
1879
  "hasDynamicHelp": false,
2014
1880
  "multiple": false,
2015
1881
  "type": "option"
2016
- },
2017
- "force-overwrite": {
2018
- "name": "force-overwrite",
2019
- "summary": "Overwrite the existing authoring bundle if one with the same API name already exists locally.",
2020
- "allowNo": false,
2021
- "type": "boolean"
2022
1882
  }
2023
1883
  },
2024
1884
  "hasDynamicHelp": true,
2025
1885
  "hiddenAliases": [],
2026
- "id": "agent:generate:authoring-bundle",
1886
+ "id": "agent:mcp:fetch",
2027
1887
  "pluginAlias": "@salesforce/plugin-agent",
2028
1888
  "pluginName": "@salesforce/plugin-agent",
2029
1889
  "pluginType": "core",
1890
+ "state": "preview",
2030
1891
  "strict": true,
2031
- "summary": "Generate an authoring bundle from an existing agent spec YAML file.",
1892
+ "summary": "Fetch the live assets (tools, prompts, resources) advertised by an MCP server.",
2032
1893
  "enableJsonFlag": true,
2033
- "requiresProject": true,
2034
1894
  "isESM": true,
2035
1895
  "relativePath": [
2036
1896
  "lib",
2037
1897
  "commands",
2038
1898
  "agent",
2039
- "generate",
2040
- "authoring-bundle.js"
1899
+ "mcp",
1900
+ "fetch.js"
2041
1901
  ],
2042
1902
  "aliasPermutations": [],
2043
1903
  "permutations": [
2044
- "agent:generate:authoring-bundle",
2045
- "generate:agent:authoring-bundle",
2046
- "generate:authoring-bundle:agent",
2047
- "agent:authoring-bundle:generate",
2048
- "authoring-bundle:agent:generate",
2049
- "authoring-bundle:generate:agent"
1904
+ "agent:mcp:fetch",
1905
+ "mcp:agent:fetch",
1906
+ "mcp:fetch:agent",
1907
+ "agent:fetch:mcp",
1908
+ "fetch:agent:mcp",
1909
+ "fetch:mcp:agent"
2050
1910
  ]
2051
1911
  },
2052
- "agent:generate:template": {
1912
+ "agent:mcp:get": {
2053
1913
  "aliases": [],
2054
1914
  "args": {},
2055
- "description": "WARNING: This command doesn't work for agents that were created from an Agent Script file. In other words, you can't currently package an agent template for agents that use Agent Script.\n\nAt a high-level, agents are defined by the Bot, BotVersion, and GenAiPlannerBundle metadata types. The GenAiPlannerBundle type in turn defines the agent's topics and actions. This command uses the metadata files for these three types, located in your local DX project, to generate a BotTemplate metadata file for a specific agent (Bot). You then use the BotTemplate metadata file, along with the GenAiPlannerBundle metadata file that references the BotTemplate, to package the template in a managed package that you can share between orgs or on AppExchange.\n\nUse the --agent-file flag to specify the relative or full pathname of the Bot metadata file, such as force-app/main/default/bots/My_Awesome_Agent/My_Awesome_Agent.bot-meta.xml. A single Bot can have multiple BotVersions, so use the --agent-version flag to specify the version. The corresponding BotVersion metadata file must exist locally. For example, if you specify \"--agent-version 4\", then the file force-app/main/default/bots/My_Awesome_Agent/v4.botVersion-meta.xml must exist.\n\nThe new BotTemplate metadata file is generated in the \"botTemplates\" directory in the output directory specified with the --output-dir flag, and has the name <Agent_API_name>\\_v<Version>\\_Template.botTemplate-meta.xml, such as my-package/botTemplates/My_Awesome_Agent_v4_Template.botTemplate-meta.xml. The command displays the full pathname of the generated files when it completes.\n\nSee \"Develop and Package Agent Templates Using Scratch Orgs\" (https://developer.salesforce.com/docs/atlas.en-us.pkg2_dev.meta/pkg2_dev/dev2gp_package_agent_templates.htm) for details about the complete process, which includes using a scratch org to create and test the agent, retrieving the agent metadata to your DX project, running this command to create the agent template, and then packaging the template.",
1915
+ "description": "Retrieves the details of an MCP (Model Context Protocol) server by its identifier, including its name, label, type, status, and server URL.",
2056
1916
  "examples": [
2057
- "Generate an agent template from the My_Awesome_Agent Bot metadata file in your DX project and save the BotTemplate and GenAiPlannerBundle to the specified directory; use version 1 of the agent. The agent that the template is based on is in the org with alias \"my-scratch-org\":\n<%= config.bin %> <%= command.id %> --agent-file force-app/main/default/bots/My_Awesome_Agent/My_Awesome_Agent.bot-meta.xml --agent-version 1 --output-dir my-package --source-org my-scratch-org"
1917
+ "Get an MCP server by id in the default target org:\n<%= config.bin %> <%= command.id %> --target-org myOrg --mcp-server-id 0Mx000000000001",
1918
+ "Get an MCP server and output as JSON:\n<%= config.bin %> <%= command.id %> --target-org myOrg --mcp-server-id 0Mx000000000001 --json"
2058
1919
  ],
2059
1920
  "flags": {
2060
1921
  "json": {
@@ -2072,89 +1933,175 @@
2072
1933
  "multiple": false,
2073
1934
  "type": "option"
2074
1935
  },
2075
- "api-version": {
2076
- "description": "Override the api version used for api requests made by this command",
2077
- "name": "api-version",
2078
- "hasDynamicHelp": false,
2079
- "multiple": false,
2080
- "type": "option"
2081
- },
2082
- "source-org": {
2083
- "char": "s",
2084
- "name": "source-org",
1936
+ "target-org": {
1937
+ "char": "o",
1938
+ "name": "target-org",
2085
1939
  "noCacheDefault": true,
2086
1940
  "required": true,
2087
- "summary": "Username or alias of the namespaced scratch org that contains the agent which this template is based on.",
1941
+ "summary": "Username or alias of the target org. Not required if the `target-org` configuration variable is already set.",
2088
1942
  "hasDynamicHelp": true,
2089
1943
  "multiple": false,
2090
1944
  "type": "option"
2091
1945
  },
2092
- "agent-version": {
2093
- "name": "agent-version",
2094
- "required": true,
2095
- "summary": "Version of the agent (BotVersion).",
1946
+ "api-version": {
1947
+ "description": "Override the api version used for api requests made by this command",
1948
+ "name": "api-version",
2096
1949
  "hasDynamicHelp": false,
2097
1950
  "multiple": false,
2098
1951
  "type": "option"
2099
1952
  },
2100
- "agent-file": {
2101
- "char": "f",
2102
- "name": "agent-file",
1953
+ "mcp-server-id": {
1954
+ "char": "i",
1955
+ "name": "mcp-server-id",
2103
1956
  "required": true,
2104
- "summary": "Path to an agent (Bot) metadata file.",
1957
+ "summary": "The identifier of the MCP server to retrieve.",
2105
1958
  "hasDynamicHelp": false,
2106
1959
  "multiple": false,
2107
1960
  "type": "option"
2108
- },
2109
- "output-dir": {
2110
- "char": "r",
2111
- "name": "output-dir",
2112
- "summary": "Directory where the generated BotTemplate and GenAiPlannerBundle files are saved.",
1961
+ }
1962
+ },
1963
+ "hasDynamicHelp": true,
1964
+ "hiddenAliases": [],
1965
+ "id": "agent:mcp:get",
1966
+ "pluginAlias": "@salesforce/plugin-agent",
1967
+ "pluginName": "@salesforce/plugin-agent",
1968
+ "pluginType": "core",
1969
+ "state": "preview",
1970
+ "strict": true,
1971
+ "summary": "Get a single MCP server registered in the API Catalog.",
1972
+ "enableJsonFlag": true,
1973
+ "isESM": true,
1974
+ "relativePath": [
1975
+ "lib",
1976
+ "commands",
1977
+ "agent",
1978
+ "mcp",
1979
+ "get.js"
1980
+ ],
1981
+ "aliasPermutations": [],
1982
+ "permutations": [
1983
+ "agent:mcp:get",
1984
+ "mcp:agent:get",
1985
+ "mcp:get:agent",
1986
+ "agent:get:mcp",
1987
+ "get:agent:mcp",
1988
+ "get:mcp:agent"
1989
+ ]
1990
+ },
1991
+ "agent:mcp:list": {
1992
+ "aliases": [],
1993
+ "args": {},
1994
+ "description": "Returns the Model Context Protocol (MCP) servers registered in the API Catalog, optionally filtered by label, type, or status. Use this to discover which MCP servers are available and inspect their server URLs and current status.",
1995
+ "examples": [
1996
+ "List all MCP servers in the default target org:\n<%= config.bin %> <%= command.id %> --target-org myOrg",
1997
+ "List external MCP servers filtered by status and output as JSON:\n<%= config.bin %> <%= command.id %> --target-org myOrg --type EXTERNAL --status ACTIVE --json"
1998
+ ],
1999
+ "flags": {
2000
+ "json": {
2001
+ "description": "Format output as json.",
2002
+ "helpGroup": "GLOBAL",
2003
+ "name": "json",
2004
+ "allowNo": false,
2005
+ "type": "boolean"
2006
+ },
2007
+ "flags-dir": {
2008
+ "helpGroup": "GLOBAL",
2009
+ "name": "flags-dir",
2010
+ "summary": "Import flag values from a directory.",
2011
+ "hasDynamicHelp": false,
2012
+ "multiple": false,
2013
+ "type": "option"
2014
+ },
2015
+ "target-org": {
2016
+ "char": "o",
2017
+ "name": "target-org",
2018
+ "noCacheDefault": true,
2019
+ "required": true,
2020
+ "summary": "Username or alias of the target org. Not required if the `target-org` configuration variable is already set.",
2021
+ "hasDynamicHelp": true,
2022
+ "multiple": false,
2023
+ "type": "option"
2024
+ },
2025
+ "api-version": {
2026
+ "description": "Override the api version used for api requests made by this command",
2027
+ "name": "api-version",
2028
+ "hasDynamicHelp": false,
2029
+ "multiple": false,
2030
+ "type": "option"
2031
+ },
2032
+ "label": {
2033
+ "name": "label",
2034
+ "summary": "Filter the MCP servers by label.",
2035
+ "hasDynamicHelp": false,
2036
+ "multiple": false,
2037
+ "type": "option"
2038
+ },
2039
+ "type": {
2040
+ "name": "type",
2041
+ "summary": "Filter the MCP servers by type.",
2042
+ "hasDynamicHelp": false,
2043
+ "multiple": false,
2044
+ "options": [
2045
+ "EXTERNAL"
2046
+ ],
2047
+ "type": "option"
2048
+ },
2049
+ "status": {
2050
+ "name": "status",
2051
+ "summary": "Filter the MCP servers by connection status. Only ACTIVE and DISCONNECTED are supported as filters.",
2113
2052
  "hasDynamicHelp": false,
2114
2053
  "multiple": false,
2054
+ "options": [
2055
+ "ACTIVE",
2056
+ "DISCONNECTED"
2057
+ ],
2115
2058
  "type": "option"
2116
2059
  }
2117
2060
  },
2118
2061
  "hasDynamicHelp": true,
2119
2062
  "hiddenAliases": [],
2120
- "id": "agent:generate:template",
2063
+ "id": "agent:mcp:list",
2121
2064
  "pluginAlias": "@salesforce/plugin-agent",
2122
2065
  "pluginName": "@salesforce/plugin-agent",
2123
2066
  "pluginType": "core",
2067
+ "state": "preview",
2124
2068
  "strict": true,
2125
- "summary": "Generate an agent template from an existing agent in your DX project so you can then package the template in a second-generation managed package.",
2069
+ "summary": "List the MCP servers registered in the API Catalog.",
2126
2070
  "enableJsonFlag": true,
2127
- "requiresProject": true,
2128
2071
  "isESM": true,
2129
2072
  "relativePath": [
2130
2073
  "lib",
2131
2074
  "commands",
2132
2075
  "agent",
2133
- "generate",
2134
- "template.js"
2076
+ "mcp",
2077
+ "list.js"
2135
2078
  ],
2136
2079
  "aliasPermutations": [],
2137
2080
  "permutations": [
2138
- "agent:generate:template",
2139
- "generate:agent:template",
2140
- "generate:template:agent",
2141
- "agent:template:generate",
2142
- "template:agent:generate",
2143
- "template:generate:agent"
2081
+ "agent:mcp:list",
2082
+ "mcp:agent:list",
2083
+ "mcp:list:agent",
2084
+ "agent:list:mcp",
2085
+ "list:agent:mcp",
2086
+ "list:mcp:agent"
2144
2087
  ]
2145
2088
  },
2146
- "agent:generate:test-spec": {
2089
+ "agent:mcp:update": {
2147
2090
  "aliases": [],
2148
2091
  "args": {},
2149
- "description": "The first step when using Salesforce CLI to create an agent test in your org is to use this interactive command to generate a local YAML-formatted test spec file. The test spec YAML file contains information about the agent being tested, such as its API name, and then one or more test cases. This command uses the metadata components in your DX project when prompting for information, such as the agent API name; it doesn't look in your org.\n\nTo generate a specific agent test case, this command prompts you for this information; when possible, the command provides a list of options for you to choose from:\n\n- Utterance: Natural language statement, question, or command used to test the agent.\n- Expected topic: API name of the topic you expect the agent to use when responding to the utterance.\n- Expected actions: One or more API names of the expection actions the agent takes.\n- Expected outcome: Natural language description of the outcome you expect.\n- (Optional) Custom evaluation: Test an agent's response for specific strings or numbers.\n- (Optional) Conversation history: Boilerplate for additional context you can add to the test in the form of a conversation history.\n\nYou can manually add contextVariables to test cases in the generated YAML file to inject contextual data (such as CaseId or RoutableId) into agent sessions. This is useful for testing agent behavior with different contextual information.\n\nWhen your test spec is ready, you then run the \"agent test create\" command to actually create the test in your org and synchronize the metadata with your DX project. The metadata type for an agent test is `AiEvaluationDefinition` (legacy testing-center) or `AiTestingDefinition` (Agentforce Studio / NGT), selected via --test-runner.\n\nIf you have an existing AiEvaluationDefinition or AiTestingDefinition metadata XML file in your DX project, you can generate its equivalent YAML test spec file with the --from-definition flag. The runner is inferred from the file extension; pass --test-runner to override.",
2092
+ "description": "Updates an existing MCP server in the API Catalog. Only the fields you provide are changed; omitted fields are left untouched. You can update the label, description, and server URL, and replace the authorization configuration. When setting `--auth-type OAUTH`, you must also provide `--identity-provider`, `--client-id`, `--client-secret`, and `--scope`. When setting `--auth-type NO_AUTH`, no authorization credentials are required. At least one updatable field must be supplied.",
2150
2093
  "examples": [
2151
- "Generate an agent test spec YAML file interactively:\n<%= config.bin %> <%= command.id %>",
2152
- "Generate an Agentforce Studio (NGT) test spec YAML file interactively:\n<%= config.bin %> <%= command.id %> --test-runner agentforce-studio",
2153
- "Generate an agent test spec YAML file and specify a name for the new file; if the file exists, overwrite it without confirmation:\n<%= config.bin %> <%= command.id %> --output-file specs/Resort_Manager-new-version-testSpec.yaml --force-overwrite",
2154
- "Generate an agent test spec YAML file from an existing AiEvaluationDefinition metadata XML file in your DX project:\n<%= config.bin %> <%= command.id %> --from-definition force-app/main/default/aiEvaluationDefinitions/Resort_Manager_Tests.aiEvaluationDefinition-meta.xml",
2155
- "Generate an Agentforce Studio (NGT) test spec YAML file from an existing AiTestingDefinition metadata XML file:\n<%= config.bin %> <%= command.id %> --from-definition force-app/main/default/aiTestingDefinitions/Returns_Checkout_Tests.aiTestingDefinition-meta.xml"
2094
+ "Update the label and description of an MCP server in the default target org:\n<%= config.bin %> <%= command.id %> --mcp-server-id 0XSxx0000000001 --label \"Orders MCP\" --description \"Order tooling\" --target-org myOrg",
2095
+ "Update the server URL and switch the authorization to OAuth, piping the client secret from stdin and outputting as JSON:\ncat secret.txt | <%= config.bin %> <%= command.id %> --mcp-server-id 0XSxx0000000001 --server-url https://mcp.example.com --auth-type OAUTH --identity-provider MyIdp --client-id abc --client-secret - --scope \"read write\" --target-org myOrg --json"
2156
2096
  ],
2157
2097
  "flags": {
2098
+ "json": {
2099
+ "description": "Format output as json.",
2100
+ "helpGroup": "GLOBAL",
2101
+ "name": "json",
2102
+ "allowNo": false,
2103
+ "type": "boolean"
2104
+ },
2158
2105
  "flags-dir": {
2159
2106
  "helpGroup": "GLOBAL",
2160
2107
  "name": "flags-dir",
@@ -2163,66 +2110,119 @@
2163
2110
  "multiple": false,
2164
2111
  "type": "option"
2165
2112
  },
2166
- "from-definition": {
2167
- "char": "d",
2168
- "name": "from-definition",
2169
- "summary": "Filepath to an AiEvaluationDefinition or AiTestingDefinition metadata XML file in your DX project that you want to convert to a test spec YAML file.",
2113
+ "target-org": {
2114
+ "char": "o",
2115
+ "name": "target-org",
2116
+ "noCacheDefault": true,
2117
+ "required": true,
2118
+ "summary": "Username or alias of the target org. Not required if the `target-org` configuration variable is already set.",
2119
+ "hasDynamicHelp": true,
2120
+ "multiple": false,
2121
+ "type": "option"
2122
+ },
2123
+ "api-version": {
2124
+ "description": "Override the api version used for api requests made by this command",
2125
+ "name": "api-version",
2170
2126
  "hasDynamicHelp": false,
2171
2127
  "multiple": false,
2172
2128
  "type": "option"
2173
2129
  },
2174
- "force-overwrite": {
2175
- "name": "force-overwrite",
2176
- "summary": "Don't prompt for confirmation when overwriting an existing test spec YAML file.",
2177
- "allowNo": false,
2178
- "type": "boolean"
2130
+ "mcp-server-id": {
2131
+ "char": "i",
2132
+ "name": "mcp-server-id",
2133
+ "required": true,
2134
+ "summary": "ID of the MCP server to update.",
2135
+ "hasDynamicHelp": false,
2136
+ "multiple": false,
2137
+ "type": "option"
2179
2138
  },
2180
- "output-file": {
2181
- "char": "f",
2182
- "name": "output-file",
2183
- "summary": "Name of the generated test spec YAML file. Default value is \"specs/<AGENT_API_NAME>-testSpec.yaml\" (legacy) or \"specs/<AGENT_API_NAME>-ngtTestSpec.yaml\" (Agentforce Studio).",
2139
+ "label": {
2140
+ "name": "label",
2141
+ "summary": "New display label for the MCP server.",
2184
2142
  "hasDynamicHelp": false,
2185
2143
  "multiple": false,
2186
2144
  "type": "option"
2187
2145
  },
2188
- "test-runner": {
2189
- "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.",
2190
- "name": "test-runner",
2191
- "summary": "Explicitly specify which test runner to use (agentforce-studio or testing-center).",
2146
+ "description": {
2147
+ "name": "description",
2148
+ "summary": "New description for the MCP server.",
2149
+ "hasDynamicHelp": false,
2150
+ "multiple": false,
2151
+ "type": "option"
2152
+ },
2153
+ "server-url": {
2154
+ "name": "server-url",
2155
+ "summary": "New endpoint URL of the MCP server.",
2156
+ "hasDynamicHelp": false,
2157
+ "multiple": false,
2158
+ "type": "option"
2159
+ },
2160
+ "auth-type": {
2161
+ "name": "auth-type",
2162
+ "summary": "Authorization type to apply to the MCP server (OAUTH or NO_AUTH).",
2192
2163
  "hasDynamicHelp": false,
2193
2164
  "multiple": false,
2194
2165
  "options": [
2195
- "agentforce-studio",
2196
- "testing-center"
2166
+ "OAUTH",
2167
+ "NO_AUTH"
2197
2168
  ],
2198
2169
  "type": "option"
2170
+ },
2171
+ "identity-provider": {
2172
+ "name": "identity-provider",
2173
+ "summary": "Identity provider name for OAuth authorization (required when --auth-type is OAUTH).",
2174
+ "hasDynamicHelp": false,
2175
+ "multiple": false,
2176
+ "type": "option"
2177
+ },
2178
+ "client-id": {
2179
+ "name": "client-id",
2180
+ "summary": "OAuth client ID (required when --auth-type is OAUTH).",
2181
+ "hasDynamicHelp": false,
2182
+ "multiple": false,
2183
+ "type": "option"
2184
+ },
2185
+ "client-secret": {
2186
+ "name": "client-secret",
2187
+ "summary": "OAuth client secret (required when --auth-type is OAUTH). Pass \"-\" to read it from stdin (piped) and keep it out of shell history.",
2188
+ "hasDynamicHelp": false,
2189
+ "multiple": false,
2190
+ "type": "option"
2191
+ },
2192
+ "scope": {
2193
+ "name": "scope",
2194
+ "summary": "OAuth scope (required when --auth-type is OAUTH).",
2195
+ "hasDynamicHelp": false,
2196
+ "multiple": false,
2197
+ "type": "option"
2199
2198
  }
2200
2199
  },
2201
- "hasDynamicHelp": false,
2200
+ "hasDynamicHelp": true,
2202
2201
  "hiddenAliases": [],
2203
- "id": "agent:generate:test-spec",
2202
+ "id": "agent:mcp:update",
2204
2203
  "pluginAlias": "@salesforce/plugin-agent",
2205
2204
  "pluginName": "@salesforce/plugin-agent",
2206
2205
  "pluginType": "core",
2206
+ "state": "preview",
2207
2207
  "strict": true,
2208
- "summary": "Generate an agent test spec, which is a YAML file that lists the test cases for testing a specific agent.",
2209
- "enableJsonFlag": false,
2208
+ "summary": "Update an MCP server registered in the API Catalog.",
2209
+ "enableJsonFlag": true,
2210
2210
  "isESM": true,
2211
2211
  "relativePath": [
2212
2212
  "lib",
2213
2213
  "commands",
2214
2214
  "agent",
2215
- "generate",
2216
- "test-spec.js"
2215
+ "mcp",
2216
+ "update.js"
2217
2217
  ],
2218
2218
  "aliasPermutations": [],
2219
2219
  "permutations": [
2220
- "agent:generate:test-spec",
2221
- "generate:agent:test-spec",
2222
- "generate:test-spec:agent",
2223
- "agent:test-spec:generate",
2224
- "test-spec:agent:generate",
2225
- "test-spec:generate:agent"
2220
+ "agent:mcp:update",
2221
+ "mcp:agent:update",
2222
+ "mcp:update:agent",
2223
+ "agent:update:mcp",
2224
+ "update:agent:mcp",
2225
+ "update:mcp:agent"
2226
2226
  ]
2227
2227
  },
2228
2228
  "agent:preview:end": {
@@ -2860,17 +2860,15 @@
2860
2860
  "authoring-bundle:publish:agent"
2861
2861
  ]
2862
2862
  },
2863
- "agent:trace:delete": {
2863
+ "agent:test:create": {
2864
2864
  "aliases": [],
2865
2865
  "args": {},
2866
- "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).",
2866
+ "description": "To run this command, you must have an agent test spec file, which is a YAML file that lists the test cases for testing a specific agent. Use the \"agent generate test-spec\" CLI command to generate a test spec file. Then specify the file to this command with the --spec flag, or run this command with no flags to be prompted.\n\nWhen this command completes, your org contains the new agent test, which you can view and edit using the Testing Center UI (legacy) or Agentforce Studio (NGT). This command also retrieves the metadata component associated with the new test to your local Salesforce DX project and displays its filename. By default, the legacy AiEvaluationDefinition is created; use --test-runner agentforce-studio to author an AiTestingDefinition (NGT) instead.\n\nAfter you've created the test in the org, use the \"agent test run\" command to run it.",
2867
2867
  "examples": [
2868
- "Delete all traces for all agents and sessions; prompt for confirmation:\n<%= config.bin %> <%= command.id %>",
2869
- "Delete all traces for a specific agent:\n<%= config.bin %> <%= command.id %> --agent My_Agent",
2870
- "Delete traces from a specific session:\n<%= config.bin %> <%= command.id %> --session-id <SESSION_ID>",
2871
- "Delete traces older than 7 days:\n<%= config.bin %> <%= command.id %> --older-than 7d",
2872
- "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",
2873
- "Delete all traces for all agents and sessions; don't prompt for confirmation:\n<%= config.bin %> <%= command.id %> --no-prompt"
2868
+ "Create an agent test interactively and be prompted for the test spec and API name of the test in the org; use the default org:\n<%= config.bin %> <%= command.id %>",
2869
+ "Create an agent test and use flags to specify all required information; if a test with same API name already exists in the org, overwrite it without confirmation. Use the org with alias \"my-org\":\n<%= config.bin %> <%= command.id %> --spec specs/Resort_Manager-testSpec.yaml --api-name Resort_Manager_Test --force-overwrite --target-org my-org",
2870
+ "Preview what the agent test metadata (AiEvaluationDefinition) looks like without deploying it to your default org:\n<%= config.bin %> <%= command.id %> --spec specs/Resort_Manager-testSpec.yaml --api-name Resort_Manager_Test --preview",
2871
+ "Author an Agentforce Studio (NGT) test from an NGT-shaped YAML; writes an AiTestingDefinition metadata file:\n<%= config.bin %> <%= command.id %> --spec specs/ReturnsCheckout.ngt.yaml --api-name Returns_Checkout --test-runner agentforce-studio --target-org my-org"
2874
2872
  ],
2875
2873
  "flags": {
2876
2874
  "json": {
@@ -2888,51 +2886,98 @@
2888
2886
  "multiple": false,
2889
2887
  "type": "option"
2890
2888
  },
2891
- "agent": {
2892
- "char": "a",
2893
- "name": "agent",
2894
- "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.",
2889
+ "api-name": {
2890
+ "name": "api-name",
2891
+ "summary": "API name of the new test; the API name must not exist in the org.",
2895
2892
  "hasDynamicHelp": false,
2896
2893
  "multiple": false,
2897
2894
  "type": "option"
2898
2895
  },
2899
- "session-id": {
2900
- "name": "session-id",
2901
- "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.",
2896
+ "spec": {
2897
+ "name": "spec",
2898
+ "summary": "Path to the test spec YAML file.",
2902
2899
  "hasDynamicHelp": false,
2903
2900
  "multiple": false,
2904
2901
  "type": "option"
2905
2902
  },
2906
- "older-than": {
2907
- "name": "older-than",
2908
- "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.",
2903
+ "target-org": {
2904
+ "char": "o",
2905
+ "name": "target-org",
2906
+ "noCacheDefault": true,
2907
+ "required": true,
2908
+ "summary": "Username or alias of the target org. Not required if the `target-org` configuration variable is already set.",
2909
+ "hasDynamicHelp": true,
2910
+ "multiple": false,
2911
+ "type": "option"
2912
+ },
2913
+ "api-version": {
2914
+ "description": "Override the api version used for api requests made by this command",
2915
+ "name": "api-version",
2909
2916
  "hasDynamicHelp": false,
2910
2917
  "multiple": false,
2911
2918
  "type": "option"
2912
2919
  },
2913
- "no-prompt": {
2914
- "name": "no-prompt",
2915
- "summary": "Skip the confirmation prompt and delete immediately.",
2920
+ "preview": {
2921
+ "name": "preview",
2922
+ "summary": "Preview the test metadata file without deploying to your org.",
2923
+ "allowNo": false,
2924
+ "type": "boolean"
2925
+ },
2926
+ "force-overwrite": {
2927
+ "name": "force-overwrite",
2928
+ "summary": "Don't prompt for confirmation when overwriting an existing test (based on API name) in your org.",
2916
2929
  "allowNo": false,
2917
2930
  "type": "boolean"
2931
+ },
2932
+ "test-runner": {
2933
+ "description": "By default, the command automatically detects which test runner to use based on the test definition metadata type in your org. Use this flag to explicitly specify the runner type. 'agentforce-studio' uses AiTestingDefinition metadata. 'testing-center' uses AiEvaluationDefinition metadata.",
2934
+ "name": "test-runner",
2935
+ "summary": "Explicitly specify which test runner to use (agentforce-studio or testing-center).",
2936
+ "hasDynamicHelp": false,
2937
+ "multiple": false,
2938
+ "options": [
2939
+ "agentforce-studio",
2940
+ "testing-center"
2941
+ ],
2942
+ "type": "option"
2918
2943
  }
2919
2944
  },
2920
- "hasDynamicHelp": false,
2945
+ "hasDynamicHelp": true,
2921
2946
  "hiddenAliases": [],
2922
- "id": "agent:trace:delete",
2947
+ "id": "agent:test:create",
2923
2948
  "pluginAlias": "@salesforce/plugin-agent",
2924
2949
  "pluginName": "@salesforce/plugin-agent",
2925
2950
  "pluginType": "core",
2926
2951
  "strict": true,
2927
- "summary": "Delete trace files from an agent preview session.",
2952
+ "summary": "Create an agent test in your org using a local test spec YAML file.",
2928
2953
  "enableJsonFlag": true,
2929
- "requiresProject": true,
2954
+ "envVariablesSection": {
2955
+ "header": "ENVIRONMENT VARIABLES",
2956
+ "body": [
2957
+ {
2958
+ "name": "SF_TARGET_ORG",
2959
+ "description": "Username or alias of your default org. Overrides the target-org configuration variable."
2960
+ }
2961
+ ]
2962
+ },
2930
2963
  "errorCodes": {
2931
2964
  "header": "ERROR CODES",
2932
2965
  "body": [
2933
2966
  {
2934
2967
  "name": "Succeeded (0)",
2935
- "description": "Traces deleted successfully (or no traces matched)."
2968
+ "description": "Test created and deployed successfully."
2969
+ },
2970
+ {
2971
+ "name": "Failed (1)",
2972
+ "description": "Test validation errors or metadata format issues."
2973
+ },
2974
+ {
2975
+ "name": "NotFound (2)",
2976
+ "description": "Test spec file not found or org connection failed."
2977
+ },
2978
+ {
2979
+ "name": "DeploymentFailed (4)",
2980
+ "description": "Deployment failed due to API or network errors."
2936
2981
  }
2937
2982
  ]
2938
2983
  },
@@ -2941,31 +2986,26 @@
2941
2986
  "lib",
2942
2987
  "commands",
2943
2988
  "agent",
2944
- "trace",
2945
- "delete.js"
2989
+ "test",
2990
+ "create.js"
2946
2991
  ],
2947
2992
  "aliasPermutations": [],
2948
2993
  "permutations": [
2949
- "agent:trace:delete",
2950
- "trace:agent:delete",
2951
- "trace:delete:agent",
2952
- "agent:delete:trace",
2953
- "delete:agent:trace",
2954
- "delete:trace:agent"
2994
+ "agent:test:create",
2995
+ "test:agent:create",
2996
+ "test:create:agent",
2997
+ "agent:create:test",
2998
+ "create:agent:test",
2999
+ "create:test:agent"
2955
3000
  ]
2956
3001
  },
2957
- "agent:trace:list": {
3002
+ "agent:test:list": {
2958
3003
  "aliases": [],
2959
3004
  "args": {},
2960
- "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.",
3005
+ "description": "The command outputs a table with the name (API name) of each test along with its unique ID, type ('agentforce-studio' or 'testing-center'), and the date it was created in the org.",
2961
3006
  "examples": [
2962
- "List all trace files for all agents and sessions:\n<%= config.bin %> <%= command.id %>",
2963
- "List all trace files for a specific agent:\n<%= config.bin %> <%= command.id %> --agent My_Agent",
2964
- "List trace files for a specific session:\n<%= config.bin %> <%= command.id %> --session-id <SESSION_ID>",
2965
- "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",
2966
- "List trace files recorded on or after a specific UTC time:\n<%= config.bin %> <%= command.id %> --since 2026-04-20T14:00:00Z",
2967
- "Filter by agent and date together:\n<%= config.bin %> <%= command.id %> --agent My_Agent --since 2026-04-20",
2968
- "Return results as JSON:\n<%= config.bin %> <%= command.id %> --json"
3007
+ "List the agent tests in your default org:\n<%= config.bin %> <%= command.id %>",
3008
+ "List the agent tests in an org with alias \"my-org\"\"\n<%= config.bin %> <%= command.id %> --target-org my-org"
2969
3009
  ],
2970
3010
  "flags": {
2971
3011
  "json": {
@@ -2983,46 +3023,52 @@
2983
3023
  "multiple": false,
2984
3024
  "type": "option"
2985
3025
  },
2986
- "session-id": {
2987
- "name": "session-id",
2988
- "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.",
2989
- "hasDynamicHelp": false,
2990
- "multiple": false,
2991
- "type": "option"
2992
- },
2993
- "agent": {
2994
- "char": "a",
2995
- "name": "agent",
2996
- "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.",
2997
- "hasDynamicHelp": false,
3026
+ "target-org": {
3027
+ "char": "o",
3028
+ "name": "target-org",
3029
+ "noCacheDefault": true,
3030
+ "required": true,
3031
+ "summary": "Username or alias of the target org. Not required if the `target-org` configuration variable is already set.",
3032
+ "hasDynamicHelp": true,
2998
3033
  "multiple": false,
2999
3034
  "type": "option"
3000
3035
  },
3001
- "since": {
3002
- "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.",
3003
- "name": "since",
3004
- "summary": "Date used to filter the list of trace files; only those recorded on or after the date are listed.",
3036
+ "api-version": {
3037
+ "description": "Override the api version used for api requests made by this command",
3038
+ "name": "api-version",
3005
3039
  "hasDynamicHelp": false,
3006
3040
  "multiple": false,
3007
3041
  "type": "option"
3008
3042
  }
3009
3043
  },
3010
- "hasDynamicHelp": false,
3044
+ "hasDynamicHelp": true,
3011
3045
  "hiddenAliases": [],
3012
- "id": "agent:trace:list",
3046
+ "id": "agent:test:list",
3013
3047
  "pluginAlias": "@salesforce/plugin-agent",
3014
3048
  "pluginName": "@salesforce/plugin-agent",
3015
3049
  "pluginType": "core",
3016
3050
  "strict": true,
3017
- "summary": "List the available trace files that were recorded during all agent preview sessions.",
3051
+ "summary": "List the available agent tests in your org.",
3018
3052
  "enableJsonFlag": true,
3019
- "requiresProject": true,
3053
+ "envVariablesSection": {
3054
+ "header": "ENVIRONMENT VARIABLES",
3055
+ "body": [
3056
+ {
3057
+ "name": "SF_TARGET_ORG",
3058
+ "description": "Username or alias of your default org. Overrides the target-org configuration variable."
3059
+ }
3060
+ ]
3061
+ },
3020
3062
  "errorCodes": {
3021
3063
  "header": "ERROR CODES",
3022
3064
  "body": [
3023
3065
  {
3024
3066
  "name": "Succeeded (0)",
3025
- "description": "Trace files listed successfully (or empty list if none found)."
3067
+ "description": "Agent tests listed successfully."
3068
+ },
3069
+ {
3070
+ "name": "Failed (4)",
3071
+ "description": "Failed to retrieve agent tests due to API or network errors."
3026
3072
  }
3027
3073
  ]
3028
3074
  },
@@ -3031,31 +3077,27 @@
3031
3077
  "lib",
3032
3078
  "commands",
3033
3079
  "agent",
3034
- "trace",
3080
+ "test",
3035
3081
  "list.js"
3036
3082
  ],
3037
3083
  "aliasPermutations": [],
3038
3084
  "permutations": [
3039
- "agent:trace:list",
3040
- "trace:agent:list",
3041
- "trace:list:agent",
3042
- "agent:list:trace",
3043
- "list:agent:trace",
3044
- "list:trace:agent"
3085
+ "agent:test:list",
3086
+ "test:agent:list",
3087
+ "test:list:agent",
3088
+ "agent:list:test",
3089
+ "list:agent:test",
3090
+ "list:test:agent"
3045
3091
  ]
3046
3092
  },
3047
- "agent:trace:read": {
3093
+ "agent:test:results": {
3048
3094
  "aliases": [],
3049
3095
  "args": {},
3050
- "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.",
3096
+ "description": "This command requires a job ID, which the original \"agent test run\" command displays when it completes. You can also use the --use-most-recent flag to see results for the most recently run agent test.\n\nBy default, this command outputs test results in human-readable tables for each test case. The tables show whether the test case passed, the expected and actual values, the test score, how long the test took, and more. Use the --result-format to display the test results in JSON or Junit format. Use the --output-dir flag to write the results to a file rather than to the terminal.",
3051
3097
  "examples": [
3052
- "Show a session trace summary for all turns in the session with the specified ID:\n<%= config.bin %> <%= command.id %> --session-id <SESSION_ID>",
3053
- "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",
3054
- "Drill into action execution across all turns:\n<%= config.bin %> <%= command.id %> --session-id <SESSION_ID> --format detail --dimension actions",
3055
- "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",
3056
- "Show all errors across the session:\n<%= config.bin %> <%= command.id %> --session-id <SESSION_ID> --format detail --dimension errors",
3057
- "Output raw trace JSON for custom parsing:\n<%= config.bin %> <%= command.id %> --session-id <SESSION_ID> --format raw",
3058
- "Return results as JSON:\n<%= config.bin %> <%= command.id %> --session-id <SESSION_ID> --json"
3098
+ "Get the results of an agent test run in your default org using its job ID:\n<%= config.bin %> <%= command.id %> --job-id 4KBfake0000003F4AQ",
3099
+ "Get the results of the most recently run agent test in an org with alias \"my-org\":\n<%= config.bin %> <%= command.id %> --use-most-recent --target-org my-org",
3100
+ "Get the results of the most recently run agent test in your default org, and write the JSON-formatted results into a directory called \"test-results\":\n<%= config.bin %> <%= command.id %> --use-most-recent --output-dir ./test-results --result-format json"
3059
3101
  ],
3060
3102
  "flags": {
3061
3103
  "json": {
@@ -3073,89 +3115,136 @@
3073
3115
  "multiple": false,
3074
3116
  "type": "option"
3075
3117
  },
3076
- "session-id": {
3077
- "char": "s",
3078
- "name": "session-id",
3118
+ "target-org": {
3119
+ "char": "o",
3120
+ "name": "target-org",
3121
+ "noCacheDefault": true,
3079
3122
  "required": true,
3080
- "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",
3123
+ "summary": "Username or alias of the target org. Not required if the `target-org` configuration variable is already set.",
3124
+ "hasDynamicHelp": true,
3125
+ "multiple": false,
3126
+ "type": "option"
3127
+ },
3128
+ "api-version": {
3129
+ "description": "Override the api version used for api requests made by this command",
3130
+ "name": "api-version",
3081
3131
  "hasDynamicHelp": false,
3082
3132
  "multiple": false,
3083
3133
  "type": "option"
3084
3134
  },
3085
- "format": {
3086
- "char": "f",
3087
- "name": "format",
3088
- "summary": "Output format of the trace data; specifies the level of detail you want in the trace files.",
3089
- "default": "summary",
3135
+ "job-id": {
3136
+ "char": "i",
3137
+ "name": "job-id",
3138
+ "required": true,
3139
+ "summary": "Job ID of the completed agent test run.",
3090
3140
  "hasDynamicHelp": false,
3091
3141
  "multiple": false,
3092
- "options": [
3093
- "summary",
3094
- "detail",
3095
- "raw"
3096
- ],
3097
3142
  "type": "option"
3098
3143
  },
3099
- "dimension": {
3100
- "char": "d",
3101
- "name": "dimension",
3102
- "summary": "Dimension to drill into when using \"--format detail\"; used to filter and organize the trace data to answer a specific type of question.",
3144
+ "result-format": {
3145
+ "name": "result-format",
3146
+ "summary": "Format of the agent test run results.",
3147
+ "default": "human",
3103
3148
  "hasDynamicHelp": false,
3104
3149
  "multiple": false,
3105
3150
  "options": [
3106
- "actions",
3107
- "grounding",
3108
- "routing",
3109
- "errors"
3151
+ "json",
3152
+ "human",
3153
+ "junit",
3154
+ "tap"
3110
3155
  ],
3111
3156
  "type": "option"
3112
3157
  },
3113
- "turn": {
3114
- "char": "t",
3115
- "name": "turn",
3116
- "summary": "Turn number for which you want trace data. A turn is a single utterance or response in a conversation, starting with 1.",
3158
+ "output-dir": {
3159
+ "char": "d",
3160
+ "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.",
3161
+ "name": "output-dir",
3162
+ "summary": "Directory to write the agent test results into.",
3117
3163
  "hasDynamicHelp": false,
3118
3164
  "multiple": false,
3119
3165
  "type": "option"
3120
- }
3121
- },
3122
- "hasDynamicHelp": false,
3123
- "hiddenAliases": [],
3124
- "id": "agent:trace:read",
3166
+ },
3167
+ "test-runner": {
3168
+ "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.",
3169
+ "name": "test-runner",
3170
+ "summary": "Explicitly specify which test runner to use (agentforce-studio or testing-center).",
3171
+ "hasDynamicHelp": false,
3172
+ "multiple": false,
3173
+ "options": [
3174
+ "agentforce-studio",
3175
+ "testing-center"
3176
+ ],
3177
+ "type": "option"
3178
+ },
3179
+ "verbose": {
3180
+ "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.",
3181
+ "name": "verbose",
3182
+ "summary": "Show generated data in the test results output.",
3183
+ "allowNo": false,
3184
+ "type": "boolean"
3185
+ }
3186
+ },
3187
+ "hasDynamicHelp": true,
3188
+ "hiddenAliases": [],
3189
+ "id": "agent:test:results",
3125
3190
  "pluginAlias": "@salesforce/plugin-agent",
3126
3191
  "pluginName": "@salesforce/plugin-agent",
3127
3192
  "pluginType": "core",
3128
3193
  "strict": true,
3129
- "summary": "Read trace files from an agent preview session.",
3194
+ "summary": "Get the results of a completed agent test run.",
3130
3195
  "enableJsonFlag": true,
3131
- "requiresProject": true,
3196
+ "envVariablesSection": {
3197
+ "header": "ENVIRONMENT VARIABLES",
3198
+ "body": [
3199
+ {
3200
+ "name": "SF_TARGET_ORG",
3201
+ "description": "Username or alias of your default org. Overrides the target-org configuration variable."
3202
+ }
3203
+ ]
3204
+ },
3205
+ "errorCodes": {
3206
+ "header": "ERROR CODES",
3207
+ "body": [
3208
+ {
3209
+ "name": "Succeeded (0)",
3210
+ "description": "Results retrieved successfully. Test results (passed/failed) are in the output."
3211
+ },
3212
+ {
3213
+ "name": "NotFound (2)",
3214
+ "description": "Job ID not found or invalid."
3215
+ },
3216
+ {
3217
+ "name": "Failed (4)",
3218
+ "description": "Failed to retrieve results due to API or network errors."
3219
+ }
3220
+ ]
3221
+ },
3132
3222
  "isESM": true,
3133
3223
  "relativePath": [
3134
3224
  "lib",
3135
3225
  "commands",
3136
3226
  "agent",
3137
- "trace",
3138
- "read.js"
3227
+ "test",
3228
+ "results.js"
3139
3229
  ],
3140
3230
  "aliasPermutations": [],
3141
3231
  "permutations": [
3142
- "agent:trace:read",
3143
- "trace:agent:read",
3144
- "trace:read:agent",
3145
- "agent:read:trace",
3146
- "read:agent:trace",
3147
- "read:trace:agent"
3232
+ "agent:test:results",
3233
+ "test:agent:results",
3234
+ "test:results:agent",
3235
+ "agent:results:test",
3236
+ "results:agent:test",
3237
+ "results:test:agent"
3148
3238
  ]
3149
3239
  },
3150
- "agent:test:create": {
3240
+ "agent:test:resume": {
3151
3241
  "aliases": [],
3152
3242
  "args": {},
3153
- "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.",
3243
+ "description": "This command requires a job ID, which the original \"agent test run\" command displays when it completes. You can also use the --use-most-recent flag to see results for the most recently run agent test.\n\nUse the --wait flag to specify the number of minutes for this command to wait for the agent test to complete; if the test completes by the end of the wait time, the command displays the test results. If not, the CLI returns control of the terminal to you, and you must run \"agent test resume\" again.\n\nBy default, this command outputs test results in human-readable tables for each test case. The tables show whether the test case passed, the expected and actual values, the test score, how long the test took, and more. Use the --result-format to display the test results in JSON or Junit format. Use the --output-dir flag to write the results to a file rather than to the terminal.",
3154
3244
  "examples": [
3155
- "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 %>",
3156
- "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",
3157
- "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",
3158
- "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"
3245
+ "Resume an agent test in your default org using a job ID:\n<%= config.bin %> <%= command.id %> --job-id 4KBfake0000003F4AQ",
3246
+ "Resume the most recently-run agent test in an org with alias \"my-org\" org; wait 10 minutes for the tests to finish:\n<%= config.bin %> <%= command.id %> --use-most-recent --wait 10 --target-org my-org",
3247
+ "Resume the most recent agent test in your default org, and write the JSON-formatted results into a directory called \"test-results\":\n<%= config.bin %> <%= command.id %> --use-most-recent --output-dir ./test-results --result-format json"
3159
3248
  ],
3160
3249
  "flags": {
3161
3250
  "json": {
@@ -3173,20 +3262,6 @@
3173
3262
  "multiple": false,
3174
3263
  "type": "option"
3175
3264
  },
3176
- "api-name": {
3177
- "name": "api-name",
3178
- "summary": "API name of the new test; the API name must not exist in the org.",
3179
- "hasDynamicHelp": false,
3180
- "multiple": false,
3181
- "type": "option"
3182
- },
3183
- "spec": {
3184
- "name": "spec",
3185
- "summary": "Path to the test spec YAML file.",
3186
- "hasDynamicHelp": false,
3187
- "multiple": false,
3188
- "type": "option"
3189
- },
3190
3265
  "target-org": {
3191
3266
  "char": "o",
3192
3267
  "name": "target-org",
@@ -3204,18 +3279,53 @@
3204
3279
  "multiple": false,
3205
3280
  "type": "option"
3206
3281
  },
3207
- "preview": {
3208
- "name": "preview",
3209
- "summary": "Preview the test metadata file without deploying to your org.",
3210
- "allowNo": false,
3211
- "type": "boolean"
3282
+ "job-id": {
3283
+ "char": "i",
3284
+ "name": "job-id",
3285
+ "summary": "Job ID of the original agent test run.",
3286
+ "hasDynamicHelp": false,
3287
+ "multiple": false,
3288
+ "type": "option"
3212
3289
  },
3213
- "force-overwrite": {
3214
- "name": "force-overwrite",
3215
- "summary": "Don't prompt for confirmation when overwriting an existing test (based on API name) in your org.",
3290
+ "use-most-recent": {
3291
+ "char": "r",
3292
+ "name": "use-most-recent",
3293
+ "summary": "Use the job ID of the most recent agent test run.",
3216
3294
  "allowNo": false,
3217
3295
  "type": "boolean"
3218
3296
  },
3297
+ "wait": {
3298
+ "char": "w",
3299
+ "name": "wait",
3300
+ "summary": "Number of minutes to wait for the command to complete and display results to the terminal window.",
3301
+ "default": "5 minutes",
3302
+ "hasDynamicHelp": true,
3303
+ "multiple": false,
3304
+ "type": "option"
3305
+ },
3306
+ "result-format": {
3307
+ "name": "result-format",
3308
+ "summary": "Format of the agent test run results.",
3309
+ "default": "human",
3310
+ "hasDynamicHelp": false,
3311
+ "multiple": false,
3312
+ "options": [
3313
+ "json",
3314
+ "human",
3315
+ "junit",
3316
+ "tap"
3317
+ ],
3318
+ "type": "option"
3319
+ },
3320
+ "output-dir": {
3321
+ "char": "d",
3322
+ "description": "If the agent test run completes, write the results to the specified directory. If the test is still running, the test results aren't written.",
3323
+ "name": "output-dir",
3324
+ "summary": "Directory to write the agent test results into.",
3325
+ "hasDynamicHelp": false,
3326
+ "multiple": false,
3327
+ "type": "option"
3328
+ },
3219
3329
  "test-runner": {
3220
3330
  "description": "By default, the command automatically detects which test runner to use based on the test definition metadata type in your org. Use this flag to explicitly specify the runner type. 'agentforce-studio' uses AiTestingDefinition metadata. 'testing-center' uses AiEvaluationDefinition metadata.",
3221
3331
  "name": "test-runner",
@@ -3227,16 +3337,23 @@
3227
3337
  "testing-center"
3228
3338
  ],
3229
3339
  "type": "option"
3340
+ },
3341
+ "verbose": {
3342
+ "description": "When enabled, includes detailed generated data (such as invoked actions) in the human-readable test results output. This is useful for debugging test failures and understanding what actions were actually invoked during the test run.\n\nThe generated data is in JSON format and includes the Apex classes or Flows that were invoked, the Salesforce objects that were touched, and so on. Use the JSON structure of this information to build the test case JSONPath expression when using custom evaluations.",
3343
+ "name": "verbose",
3344
+ "summary": "Show generated data in the test results output.",
3345
+ "allowNo": false,
3346
+ "type": "boolean"
3230
3347
  }
3231
3348
  },
3232
3349
  "hasDynamicHelp": true,
3233
3350
  "hiddenAliases": [],
3234
- "id": "agent:test:create",
3351
+ "id": "agent:test:resume",
3235
3352
  "pluginAlias": "@salesforce/plugin-agent",
3236
3353
  "pluginName": "@salesforce/plugin-agent",
3237
3354
  "pluginType": "core",
3238
3355
  "strict": true,
3239
- "summary": "Create an agent test in your org using a local test spec YAML file.",
3356
+ "summary": "Resume an agent test that you previously started in your org so you can view the test results.",
3240
3357
  "enableJsonFlag": true,
3241
3358
  "envVariablesSection": {
3242
3359
  "header": "ENVIRONMENT VARIABLES",
@@ -3252,19 +3369,19 @@
3252
3369
  "body": [
3253
3370
  {
3254
3371
  "name": "Succeeded (0)",
3255
- "description": "Test created and deployed successfully."
3372
+ "description": "Test completed successfully (with test results in the output)."
3256
3373
  },
3257
3374
  {
3258
3375
  "name": "Failed (1)",
3259
- "description": "Test validation errors or metadata format issues."
3376
+ "description": "Tests encountered execution errors (test cases with ERROR status)."
3260
3377
  },
3261
3378
  {
3262
3379
  "name": "NotFound (2)",
3263
- "description": "Test spec file not found or org connection failed."
3380
+ "description": "Job ID not found or invalid."
3264
3381
  },
3265
3382
  {
3266
- "name": "DeploymentFailed (4)",
3267
- "description": "Deployment failed due to API or network errors."
3383
+ "name": "OperationFailed (4)",
3384
+ "description": "Failed to poll test due to API or network errors."
3268
3385
  }
3269
3386
  ]
3270
3387
  },
@@ -3274,25 +3391,29 @@
3274
3391
  "commands",
3275
3392
  "agent",
3276
3393
  "test",
3277
- "create.js"
3394
+ "resume.js"
3278
3395
  ],
3279
3396
  "aliasPermutations": [],
3280
3397
  "permutations": [
3281
- "agent:test:create",
3282
- "test:agent:create",
3283
- "test:create:agent",
3284
- "agent:create:test",
3285
- "create:agent:test",
3286
- "create:test:agent"
3398
+ "agent:test:resume",
3399
+ "test:agent:resume",
3400
+ "test:resume:agent",
3401
+ "agent:resume:test",
3402
+ "resume:agent:test",
3403
+ "resume:test:agent"
3287
3404
  ]
3288
3405
  },
3289
- "agent:test:list": {
3406
+ "agent:test:run-eval": {
3290
3407
  "aliases": [],
3291
3408
  "args": {},
3292
- "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.",
3409
+ "description": "Specify the tests you want to run with one of these inputs to the --spec flag:\n\n- YAML test spec generated by the `agent generate test-spec` CLI command\n- JSON payload\n\nWhen you provide a YAML test spec, this command automatically translates test cases into internal state-based evaluation framework calls and infers the agent name from the test spec's `subjectName` field. As a result, you can use the same test spec with both the `agent test run` and `agent test run-eval` commands. YAML test specs also support context variables, which allow you to inject contextual data (such as CaseId or RoutableId) into agent sessions for testing with different contexts.\n\nWhen you provide a JSON payload, it's sent directly to the evaluation framework with optional normalization. The normalizer auto-corrects common field name mistakes, converts shorthand references to JSONPath, and injects defaults. Use `--no-normalize` to disable this auto-normalization. JSON payloads can also include context_variables on agent.create_session steps for the same contextual testing capabilities as when you use a YAML test spec.\n\nThis command supports more than 8 evaluator types, including subagent routing assertions, action invocation checks, string/numeric assertions, semantic similarity scoring, and LLM-based quality ratings.",
3293
3410
  "examples": [
3294
- "List the agent tests in your default org:\n<%= config.bin %> <%= command.id %>",
3295
- "List the agent tests in an org with alias \"my-org\"\"\n<%= config.bin %> <%= command.id %> --target-org my-org"
3411
+ "Run tests using a YAML test spec on the org with alias \"my-org\":\n<%= config.bin %> <%= command.id %> --spec specs/my-agent-testSpec.yaml --target-org my-org",
3412
+ "Run tests using a YAML spec with explicit agent name override; use your default org:\n<%= config.bin %> <%= command.id %> --spec specs/my-agent-testSpec.yaml --api-name My_Agent",
3413
+ "Run tests using a JSON payload:\n<%= config.bin %> <%= command.id %> --spec specs/eval-payload.json --target-org my-org",
3414
+ "Run tests and output results in JUnit format; useful for continuous integration and deployment (CI/CD):\n<%= config.bin %> <%= command.id %> --spec specs/my-agent-testSpec.yaml --target-org my-org --result-format junit",
3415
+ "Run tests with contextVariables to inject contextual data into agent sessions (add contextVariables to test cases in your YAML spec):\n<%= config.bin %> <%= command.id %> --spec specs/agent-with-context.yaml --target-org my-org",
3416
+ "Pipe JSON payload from stdin (--spec flag is automatically populated from stdin):\n$ echo '{\"tests\":[...]}' | <%= config.bin %> <%= command.id %> --spec --target-org my-org"
3296
3417
  ],
3297
3418
  "flags": {
3298
3419
  "json": {
@@ -3326,16 +3447,62 @@
3326
3447
  "hasDynamicHelp": false,
3327
3448
  "multiple": false,
3328
3449
  "type": "option"
3450
+ },
3451
+ "spec": {
3452
+ "char": "s",
3453
+ "name": "spec",
3454
+ "required": true,
3455
+ "summary": "Path to test spec file (YAML or JSON). Supports reading from stdin when piping content.",
3456
+ "hasDynamicHelp": false,
3457
+ "multiple": false,
3458
+ "type": "option"
3459
+ },
3460
+ "api-name": {
3461
+ "char": "n",
3462
+ "name": "api-name",
3463
+ "summary": "Agent API name (also called DeveloperName) used to resolve agent_id and agent_version_id. Auto-inferred from the YAML spec's subjectName.",
3464
+ "hasDynamicHelp": false,
3465
+ "multiple": false,
3466
+ "type": "option"
3467
+ },
3468
+ "result-format": {
3469
+ "name": "result-format",
3470
+ "summary": "Format of the agent test run results.",
3471
+ "default": "human",
3472
+ "hasDynamicHelp": false,
3473
+ "multiple": false,
3474
+ "options": [
3475
+ "json",
3476
+ "human",
3477
+ "junit",
3478
+ "tap"
3479
+ ],
3480
+ "type": "option"
3481
+ },
3482
+ "batch-size": {
3483
+ "name": "batch-size",
3484
+ "summary": "Number of tests per API request (max 5).",
3485
+ "default": 5,
3486
+ "hasDynamicHelp": false,
3487
+ "multiple": false,
3488
+ "type": "option"
3489
+ },
3490
+ "no-normalize": {
3491
+ "name": "no-normalize",
3492
+ "summary": "Disable auto-normalization of field names and shorthand references.",
3493
+ "allowNo": false,
3494
+ "type": "boolean"
3329
3495
  }
3330
3496
  },
3331
3497
  "hasDynamicHelp": true,
3332
3498
  "hiddenAliases": [],
3333
- "id": "agent:test:list",
3499
+ "id": "agent:test:run-eval",
3334
3500
  "pluginAlias": "@salesforce/plugin-agent",
3335
3501
  "pluginName": "@salesforce/plugin-agent",
3336
3502
  "pluginType": "core",
3503
+ "state": "beta",
3337
3504
  "strict": true,
3338
- "summary": "List the available agent tests in your org.",
3505
+ "summary": "Run rich evaluation tests against an Agentforce agent.",
3339
3506
  "enableJsonFlag": true,
3340
3507
  "envVariablesSection": {
3341
3508
  "header": "ENVIRONMENT VARIABLES",
@@ -3351,40 +3518,48 @@
3351
3518
  "body": [
3352
3519
  {
3353
3520
  "name": "Succeeded (0)",
3354
- "description": "Agent tests listed successfully."
3521
+ "description": "Tests completed successfully. Test results (passed/failed) are in the JSON output."
3355
3522
  },
3356
3523
  {
3357
- "name": "Failed (4)",
3358
- "description": "Failed to retrieve agent tests due to API or network errors."
3359
- }
3360
- ]
3361
- },
3362
- "isESM": true,
3363
- "relativePath": [
3364
- "lib",
3365
- "commands",
3366
- "agent",
3367
- "test",
3368
- "list.js"
3524
+ "name": "Failed (1)",
3525
+ "description": "Tests encountered execution errors (tests couldn't run properly)."
3526
+ },
3527
+ {
3528
+ "name": "NotFound (2)",
3529
+ "description": "Agent not found, spec file not found, or invalid agent name."
3530
+ },
3531
+ {
3532
+ "name": "OperationFailed (4)",
3533
+ "description": "Failed to execute tests due to API or network errors."
3534
+ }
3535
+ ]
3536
+ },
3537
+ "isESM": true,
3538
+ "relativePath": [
3539
+ "lib",
3540
+ "commands",
3541
+ "agent",
3542
+ "test",
3543
+ "run-eval.js"
3369
3544
  ],
3370
3545
  "aliasPermutations": [],
3371
3546
  "permutations": [
3372
- "agent:test:list",
3373
- "test:agent:list",
3374
- "test:list:agent",
3375
- "agent:list:test",
3376
- "list:agent:test",
3377
- "list:test:agent"
3547
+ "agent:test:run-eval",
3548
+ "test:agent:run-eval",
3549
+ "test:run-eval:agent",
3550
+ "agent:run-eval:test",
3551
+ "run-eval:agent:test",
3552
+ "run-eval:test:agent"
3378
3553
  ]
3379
3554
  },
3380
- "agent:test:results": {
3555
+ "agent:test:run": {
3381
3556
  "aliases": [],
3382
3557
  "args": {},
3383
- "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.",
3558
+ "description": "Use the --api-name flag to specify the name of the agent test you want to run. Use the output of the \"agent test list\" command to get the names of all the available agent tests in your org.\n\nBy default, this command starts the agent test in your org, but it doesn't wait for the test to finish. Instead, it displays the \"agent test resume\" command, with a job ID, that you execute to see the results of the test run, and then returns control of the terminal window to you. Use the --wait flag to specify the number of minutes for the command to wait for the agent test to complete; if the test completes by the end of the wait time, the command displays the test results. If not, run \"agent test resume\".\n\nBy default, this command outputs test results in human-readable tables for each test case, if the test completes in time. The tables show whether the test case passed, the expected and actual values, the test score, how long the test took, and more. Use the --result-format to display the test results in JSON or Junit format. Use the --output-dir flag to write the results to a file rather than to the terminal.",
3384
3559
  "examples": [
3385
- "Get the results of an agent test run in your default org using its job ID:\n<%= config.bin %> <%= command.id %> --job-id 4KBfake0000003F4AQ",
3386
- "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",
3387
- "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"
3560
+ "Start an agent test called Resort_Manager_Test for an agent in your default org, don't wait for the test to finish:\n<%= config.bin %> <%= command.id %> --api-name Resort_Manager_Test",
3561
+ "Start an agent test for an agent in an org with alias \"my-org\" and wait for 10 minutes for the test to finish:\n<%= config.bin %> <%= command.id %> --api-name Resort_Manager_Test --wait 10 --target-org my-org",
3562
+ "Start an agent test and write the JSON-formatted results into a directory called \"test-results\":\n<%= config.bin %> <%= command.id %> --api-name Resort_Manager_Test --wait 10 --output-dir ./test-results --result-format json"
3388
3563
  ],
3389
3564
  "flags": {
3390
3565
  "json": {
@@ -3419,15 +3594,22 @@
3419
3594
  "multiple": false,
3420
3595
  "type": "option"
3421
3596
  },
3422
- "job-id": {
3423
- "char": "i",
3424
- "name": "job-id",
3425
- "required": true,
3426
- "summary": "Job ID of the completed agent test run.",
3597
+ "api-name": {
3598
+ "char": "n",
3599
+ "name": "api-name",
3600
+ "summary": "API name of the agent test to run; corresponds to the name of the AiEvaluationDefinition metadata component that implements the agent test.",
3427
3601
  "hasDynamicHelp": false,
3428
3602
  "multiple": false,
3429
3603
  "type": "option"
3430
3604
  },
3605
+ "wait": {
3606
+ "char": "w",
3607
+ "name": "wait",
3608
+ "summary": "Number of minutes to wait for the command to complete and display results to the terminal window.",
3609
+ "hasDynamicHelp": true,
3610
+ "multiple": false,
3611
+ "type": "option"
3612
+ },
3431
3613
  "result-format": {
3432
3614
  "name": "result-format",
3433
3615
  "summary": "Format of the agent test run results.",
@@ -3473,12 +3655,12 @@
3473
3655
  },
3474
3656
  "hasDynamicHelp": true,
3475
3657
  "hiddenAliases": [],
3476
- "id": "agent:test:results",
3658
+ "id": "agent:test:run",
3477
3659
  "pluginAlias": "@salesforce/plugin-agent",
3478
3660
  "pluginName": "@salesforce/plugin-agent",
3479
3661
  "pluginType": "core",
3480
3662
  "strict": true,
3481
- "summary": "Get the results of a completed agent test run.",
3663
+ "summary": "Start an agent test in your org.",
3482
3664
  "enableJsonFlag": true,
3483
3665
  "envVariablesSection": {
3484
3666
  "header": "ENVIRONMENT VARIABLES",
@@ -3494,15 +3676,19 @@
3494
3676
  "body": [
3495
3677
  {
3496
3678
  "name": "Succeeded (0)",
3497
- "description": "Results retrieved successfully. Test results (passed/failed) are in the output."
3679
+ "description": "Test started successfully (without --wait), or test completed successfully (with --wait)."
3680
+ },
3681
+ {
3682
+ "name": "Failed (1)",
3683
+ "description": "Tests encountered execution errors (test cases with ERROR status when using --wait)."
3498
3684
  },
3499
3685
  {
3500
3686
  "name": "NotFound (2)",
3501
- "description": "Job ID not found or invalid."
3687
+ "description": "Test definition not found or invalid test name."
3502
3688
  },
3503
3689
  {
3504
- "name": "Failed (4)",
3505
- "description": "Failed to retrieve results due to API or network errors."
3690
+ "name": "OperationFailed (4)",
3691
+ "description": "Failed to start or poll test due to API or network errors."
3506
3692
  }
3507
3693
  ]
3508
3694
  },
@@ -3512,26 +3698,29 @@
3512
3698
  "commands",
3513
3699
  "agent",
3514
3700
  "test",
3515
- "results.js"
3701
+ "run.js"
3516
3702
  ],
3517
3703
  "aliasPermutations": [],
3518
3704
  "permutations": [
3519
- "agent:test:results",
3520
- "test:agent:results",
3521
- "test:results:agent",
3522
- "agent:results:test",
3523
- "results:agent:test",
3524
- "results:test:agent"
3705
+ "agent:test:run",
3706
+ "test:agent:run",
3707
+ "test:run:agent",
3708
+ "agent:run:test",
3709
+ "run:agent:test",
3710
+ "run:test:agent"
3525
3711
  ]
3526
3712
  },
3527
- "agent:test:resume": {
3713
+ "agent:trace:delete": {
3528
3714
  "aliases": [],
3529
3715
  "args": {},
3530
- "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.",
3716
+ "description": "When you run an agent preview conversation (either interactive or programmatic), trace files are automatically recorded and saved in your local DX project. Use this command to delete some or all of the trace files.\n\nBy default, this command shows a preview of what will be deleted and prompts for confirmation. Use --no-prompt to skip confirmation.\n\nWithout filters, this comamnd deletes all trace files for all agents and sessions. Use flags to narrow the scope: filter by agent API name (--agent), by session (--session-id), or by age (--older-than).",
3531
3717
  "examples": [
3532
- "Resume an agent test in your default org using a job ID:\n<%= config.bin %> <%= command.id %> --job-id 4KBfake0000003F4AQ",
3533
- "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",
3534
- "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"
3718
+ "Delete all traces for all agents and sessions; prompt for confirmation:\n<%= config.bin %> <%= command.id %>",
3719
+ "Delete all traces for a specific agent:\n<%= config.bin %> <%= command.id %> --agent My_Agent",
3720
+ "Delete traces from a specific session:\n<%= config.bin %> <%= command.id %> --session-id <SESSION_ID>",
3721
+ "Delete traces older than 7 days:\n<%= config.bin %> <%= command.id %> --older-than 7d",
3722
+ "Delete traces older than 24 hours for a specific agent; don't prompt for confirmation:\n<%= config.bin %> <%= command.id %> --agent My_Agent --older-than 24h --no-prompt",
3723
+ "Delete all traces for all agents and sessions; don't prompt for confirmation:\n<%= config.bin %> <%= command.id %> --no-prompt"
3535
3724
  ],
3536
3725
  "flags": {
3537
3726
  "json": {
@@ -3549,126 +3738,51 @@
3549
3738
  "multiple": false,
3550
3739
  "type": "option"
3551
3740
  },
3552
- "target-org": {
3553
- "char": "o",
3554
- "name": "target-org",
3555
- "noCacheDefault": true,
3556
- "required": true,
3557
- "summary": "Username or alias of the target org. Not required if the `target-org` configuration variable is already set.",
3558
- "hasDynamicHelp": true,
3559
- "multiple": false,
3560
- "type": "option"
3561
- },
3562
- "api-version": {
3563
- "description": "Override the api version used for api requests made by this command",
3564
- "name": "api-version",
3565
- "hasDynamicHelp": false,
3566
- "multiple": false,
3567
- "type": "option"
3568
- },
3569
- "job-id": {
3570
- "char": "i",
3571
- "name": "job-id",
3572
- "summary": "Job ID of the original agent test run.",
3573
- "hasDynamicHelp": false,
3574
- "multiple": false,
3575
- "type": "option"
3576
- },
3577
- "use-most-recent": {
3578
- "char": "r",
3579
- "name": "use-most-recent",
3580
- "summary": "Use the job ID of the most recent agent test run.",
3581
- "allowNo": false,
3582
- "type": "boolean"
3583
- },
3584
- "wait": {
3585
- "char": "w",
3586
- "name": "wait",
3587
- "summary": "Number of minutes to wait for the command to complete and display results to the terminal window.",
3588
- "default": "5 minutes",
3589
- "hasDynamicHelp": true,
3590
- "multiple": false,
3591
- "type": "option"
3592
- },
3593
- "result-format": {
3594
- "name": "result-format",
3595
- "summary": "Format of the agent test run results.",
3596
- "default": "human",
3741
+ "agent": {
3742
+ "char": "a",
3743
+ "name": "agent",
3744
+ "summary": "API name of the agent used to filter the list of trace files you want to delete. Matches against the API name used when starting the session, either an authoring bundle or a published agent API name.",
3597
3745
  "hasDynamicHelp": false,
3598
3746
  "multiple": false,
3599
- "options": [
3600
- "json",
3601
- "human",
3602
- "junit",
3603
- "tap"
3604
- ],
3605
3747
  "type": "option"
3606
3748
  },
3607
- "output-dir": {
3608
- "char": "d",
3609
- "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.",
3610
- "name": "output-dir",
3611
- "summary": "Directory to write the agent test results into.",
3749
+ "session-id": {
3750
+ "name": "session-id",
3751
+ "summary": "Session ID used to filter the list of trace files you want to delete. Use the \"agent preview sessions\" CLI command to list all known agent preview sessions along with their session IDs.",
3612
3752
  "hasDynamicHelp": false,
3613
3753
  "multiple": false,
3614
3754
  "type": "option"
3615
3755
  },
3616
- "test-runner": {
3617
- "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.",
3618
- "name": "test-runner",
3619
- "summary": "Explicitly specify which test runner to use (agentforce-studio or testing-center).",
3756
+ "older-than": {
3757
+ "name": "older-than",
3758
+ "summary": "Duration used to filter the list of trace files; only files older than the duration are deleted. Accepts a number followed by a unit: m/minutes, h/hours, d/days, w/weeks. Examples: 7d, 24h, 2w.",
3620
3759
  "hasDynamicHelp": false,
3621
3760
  "multiple": false,
3622
- "options": [
3623
- "agentforce-studio",
3624
- "testing-center"
3625
- ],
3626
3761
  "type": "option"
3627
3762
  },
3628
- "verbose": {
3629
- "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.",
3630
- "name": "verbose",
3631
- "summary": "Show generated data in the test results output.",
3763
+ "no-prompt": {
3764
+ "name": "no-prompt",
3765
+ "summary": "Skip the confirmation prompt and delete immediately.",
3632
3766
  "allowNo": false,
3633
3767
  "type": "boolean"
3634
3768
  }
3635
3769
  },
3636
- "hasDynamicHelp": true,
3770
+ "hasDynamicHelp": false,
3637
3771
  "hiddenAliases": [],
3638
- "id": "agent:test:resume",
3772
+ "id": "agent:trace:delete",
3639
3773
  "pluginAlias": "@salesforce/plugin-agent",
3640
3774
  "pluginName": "@salesforce/plugin-agent",
3641
3775
  "pluginType": "core",
3642
3776
  "strict": true,
3643
- "summary": "Resume an agent test that you previously started in your org so you can view the test results.",
3777
+ "summary": "Delete trace files from an agent preview session.",
3644
3778
  "enableJsonFlag": true,
3645
- "envVariablesSection": {
3646
- "header": "ENVIRONMENT VARIABLES",
3647
- "body": [
3648
- {
3649
- "name": "SF_TARGET_ORG",
3650
- "description": "Username or alias of your default org. Overrides the target-org configuration variable."
3651
- }
3652
- ]
3653
- },
3779
+ "requiresProject": true,
3654
3780
  "errorCodes": {
3655
3781
  "header": "ERROR CODES",
3656
3782
  "body": [
3657
3783
  {
3658
3784
  "name": "Succeeded (0)",
3659
- "description": "Test completed successfully (with test results in the output)."
3660
- },
3661
- {
3662
- "name": "Failed (1)",
3663
- "description": "Tests encountered execution errors (test cases with ERROR status)."
3664
- },
3665
- {
3666
- "name": "NotFound (2)",
3667
- "description": "Job ID not found or invalid."
3668
- },
3669
- {
3670
- "name": "OperationFailed (4)",
3671
- "description": "Failed to poll test due to API or network errors."
3785
+ "description": "Traces deleted successfully (or no traces matched)."
3672
3786
  }
3673
3787
  ]
3674
3788
  },
@@ -3677,30 +3791,31 @@
3677
3791
  "lib",
3678
3792
  "commands",
3679
3793
  "agent",
3680
- "test",
3681
- "resume.js"
3794
+ "trace",
3795
+ "delete.js"
3682
3796
  ],
3683
3797
  "aliasPermutations": [],
3684
3798
  "permutations": [
3685
- "agent:test:resume",
3686
- "test:agent:resume",
3687
- "test:resume:agent",
3688
- "agent:resume:test",
3689
- "resume:agent:test",
3690
- "resume:test:agent"
3799
+ "agent:trace:delete",
3800
+ "trace:agent:delete",
3801
+ "trace:delete:agent",
3802
+ "agent:delete:trace",
3803
+ "delete:agent:trace",
3804
+ "delete:trace:agent"
3691
3805
  ]
3692
3806
  },
3693
- "agent:test:run-eval": {
3807
+ "agent:trace:list": {
3694
3808
  "aliases": [],
3695
3809
  "args": {},
3696
- "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.",
3810
+ "description": "When you run an agent preview conversation (either interactive or programmatic), trace files are automatically recorded and saved in your local DX project. By default, this command lists all trace files for all agents and all of their sessions. Use flags to narrow results: filter by agent name (--agent), by session (--session-id), or by date (--since).\n\nEach row in the output corresponds to one trace file, which in turn corresponds to one agent session. The Agent column shows the authoring bundle or API name used when starting the session.",
3697
3811
  "examples": [
3698
- "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",
3699
- "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",
3700
- "Run tests using a JSON payload:\n<%= config.bin %> <%= command.id %> --spec specs/eval-payload.json --target-org my-org",
3701
- "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",
3702
- "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",
3703
- "Pipe JSON payload from stdin (--spec flag is automatically populated from stdin):\n$ echo '{\"tests\":[...]}' | <%= config.bin %> <%= command.id %> --spec --target-org my-org"
3812
+ "List all trace files for all agents and sessions:\n<%= config.bin %> <%= command.id %>",
3813
+ "List all trace files for a specific agent:\n<%= config.bin %> <%= command.id %> --agent My_Agent",
3814
+ "List trace files for a specific session:\n<%= config.bin %> <%= command.id %> --session-id <SESSION_ID>",
3815
+ "List trace files recorded on or after April 20, 2026 (date-only, interpreted as UTC midnight):\n<%= config.bin %> <%= command.id %> --since 2026-04-20",
3816
+ "List trace files recorded on or after a specific UTC time:\n<%= config.bin %> <%= command.id %> --since 2026-04-20T14:00:00Z",
3817
+ "Filter by agent and date together:\n<%= config.bin %> <%= command.id %> --agent My_Agent --since 2026-04-20",
3818
+ "Return results as JSON:\n<%= config.bin %> <%= command.id %> --json"
3704
3819
  ],
3705
3820
  "flags": {
3706
3821
  "json": {
@@ -3718,106 +3833,46 @@
3718
3833
  "multiple": false,
3719
3834
  "type": "option"
3720
3835
  },
3721
- "target-org": {
3722
- "char": "o",
3723
- "name": "target-org",
3724
- "noCacheDefault": true,
3725
- "required": true,
3726
- "summary": "Username or alias of the target org. Not required if the `target-org` configuration variable is already set.",
3727
- "hasDynamicHelp": true,
3728
- "multiple": false,
3729
- "type": "option"
3730
- },
3731
- "api-version": {
3732
- "description": "Override the api version used for api requests made by this command",
3733
- "name": "api-version",
3734
- "hasDynamicHelp": false,
3735
- "multiple": false,
3736
- "type": "option"
3737
- },
3738
- "spec": {
3739
- "char": "s",
3740
- "name": "spec",
3741
- "required": true,
3742
- "summary": "Path to test spec file (YAML or JSON). Supports reading from stdin when piping content.",
3743
- "hasDynamicHelp": false,
3744
- "multiple": false,
3745
- "type": "option"
3746
- },
3747
- "api-name": {
3748
- "char": "n",
3749
- "name": "api-name",
3750
- "summary": "Agent API name (also called DeveloperName) used to resolve agent_id and agent_version_id. Auto-inferred from the YAML spec's subjectName.",
3836
+ "session-id": {
3837
+ "name": "session-id",
3838
+ "summary": "Session ID used to filter the list of trace files. Use the \"agent preview sessions\" CLI command to list all known agent preview sessions along with their session IDs.",
3751
3839
  "hasDynamicHelp": false,
3752
3840
  "multiple": false,
3753
3841
  "type": "option"
3754
3842
  },
3755
- "result-format": {
3756
- "name": "result-format",
3757
- "summary": "Format of the agent test run results.",
3758
- "default": "human",
3843
+ "agent": {
3844
+ "char": "a",
3845
+ "name": "agent",
3846
+ "summary": "API name of the agent used to filter the list of available trace files. Matches against the API name used when starting the session, either an authoring bundle or a published agent API name.",
3759
3847
  "hasDynamicHelp": false,
3760
3848
  "multiple": false,
3761
- "options": [
3762
- "json",
3763
- "human",
3764
- "junit",
3765
- "tap"
3766
- ],
3767
3849
  "type": "option"
3768
3850
  },
3769
- "batch-size": {
3770
- "name": "batch-size",
3771
- "summary": "Number of tests per API request (max 5).",
3772
- "default": 5,
3851
+ "since": {
3852
+ "description": "Accepts ISO 8601 format: date-only (2026-04-20), date-time (2026-04-20T14:00:00Z), or date-time with milliseconds (2026-04-20T14:00:00.000Z). The \"Recorded At\" values shown in the table output are valid inputs.",
3853
+ "name": "since",
3854
+ "summary": "Date used to filter the list of trace files; only those recorded on or after the date are listed.",
3773
3855
  "hasDynamicHelp": false,
3774
3856
  "multiple": false,
3775
3857
  "type": "option"
3776
- },
3777
- "no-normalize": {
3778
- "name": "no-normalize",
3779
- "summary": "Disable auto-normalization of field names and shorthand references.",
3780
- "allowNo": false,
3781
- "type": "boolean"
3782
3858
  }
3783
3859
  },
3784
- "hasDynamicHelp": true,
3860
+ "hasDynamicHelp": false,
3785
3861
  "hiddenAliases": [],
3786
- "id": "agent:test:run-eval",
3862
+ "id": "agent:trace:list",
3787
3863
  "pluginAlias": "@salesforce/plugin-agent",
3788
3864
  "pluginName": "@salesforce/plugin-agent",
3789
3865
  "pluginType": "core",
3790
- "state": "beta",
3791
3866
  "strict": true,
3792
- "summary": "Run rich evaluation tests against an Agentforce agent.",
3867
+ "summary": "List the available trace files that were recorded during all agent preview sessions.",
3793
3868
  "enableJsonFlag": true,
3794
- "envVariablesSection": {
3795
- "header": "ENVIRONMENT VARIABLES",
3796
- "body": [
3797
- {
3798
- "name": "SF_TARGET_ORG",
3799
- "description": "Username or alias of your default org. Overrides the target-org configuration variable."
3800
- }
3801
- ]
3802
- },
3869
+ "requiresProject": true,
3803
3870
  "errorCodes": {
3804
3871
  "header": "ERROR CODES",
3805
3872
  "body": [
3806
3873
  {
3807
3874
  "name": "Succeeded (0)",
3808
- "description": "Tests completed successfully. Test results (passed/failed) are in the JSON output."
3809
- },
3810
- {
3811
- "name": "Failed (1)",
3812
- "description": "Tests encountered execution errors (tests couldn't run properly)."
3813
- },
3814
- {
3815
- "name": "NotFound (2)",
3816
- "description": "Agent not found, spec file not found, or invalid agent name."
3817
- },
3818
- {
3819
- "name": "OperationFailed (4)",
3820
- "description": "Failed to execute tests due to API or network errors."
3875
+ "description": "Trace files listed successfully (or empty list if none found)."
3821
3876
  }
3822
3877
  ]
3823
3878
  },
@@ -3826,27 +3881,31 @@
3826
3881
  "lib",
3827
3882
  "commands",
3828
3883
  "agent",
3829
- "test",
3830
- "run-eval.js"
3884
+ "trace",
3885
+ "list.js"
3831
3886
  ],
3832
3887
  "aliasPermutations": [],
3833
3888
  "permutations": [
3834
- "agent:test:run-eval",
3835
- "test:agent:run-eval",
3836
- "test:run-eval:agent",
3837
- "agent:run-eval:test",
3838
- "run-eval:agent:test",
3839
- "run-eval:test:agent"
3889
+ "agent:trace:list",
3890
+ "trace:agent:list",
3891
+ "trace:list:agent",
3892
+ "agent:list:trace",
3893
+ "list:agent:trace",
3894
+ "list:trace:agent"
3840
3895
  ]
3841
3896
  },
3842
- "agent:test:run": {
3897
+ "agent:trace:read": {
3843
3898
  "aliases": [],
3844
3899
  "args": {},
3845
- "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.",
3900
+ "description": "When you run an agent preview conversation (either interactive or programmatic), trace files are automatically recorded and saved in your local DX project. Each turn (utterance or response) of a conversation creates trace data. Use this command to view trace data for a specific preview session, so you can then analyze the trace data to observe, monitor, investigate, and troubleshoot agent events and behavior.\n\nUse the --format flag to specify one of these formats of the outputted trace data:\n\n- summary (Default): A per-turn narrative showing topic routing, actions executed, and the agent's response. Use this to quickly understand what happened in a preview session.\n- detail: Diagnostic drill-down into a specific dimension. Filters output to only the trace steps relevant to that dimension, minimizing noise.\n- raw: Unprocessed trace JSON. Use this as a fallback when the trace schema has changed or you need to perform custom analysis.\n\nIf you specify \"--format detail\", you must also specify a dimension with the --dimension flag. Dimensions are a way to slice and analyze the agent execution trace from a specific angle or concern. Instead of looking at the raw sequence of everything that happened, each dimension filters and organizes the trace data to answer a specific type of question. These are the available dimensions and the information they provide:\n\n- actions: The actions the agent executed. Includes action name, input parameters, output, and latency. Use this dimension to understand what the agent actually did when answering an utterance in the preview session.\n- grounding: The reasoning steps used by the LLM. Use this dimension to see how the agent \"thought\" about the problem - the AI reasoning that determined which actions to take.\n- routing: How the agent navigated between subagents. Use this dimension to understand conversation flow - when and why the agent switched between different subagents or contexts during the conversation.\n- errors: Aggregates all errors during the session. Use this dimension to quickly identify and debug issues across all steps.",
3846
3901
  "examples": [
3847
- "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",
3848
- "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",
3849
- "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"
3902
+ "Show a session trace summary for all turns in the session with the specified ID:\n<%= config.bin %> <%= command.id %> --session-id <SESSION_ID>",
3903
+ "Show a trace summary for the second turn (utterance or response) of the conversation:\n<%= config.bin %> <%= command.id %> --session-id <SESSION_ID> --turn 2",
3904
+ "Drill into action execution across all turns:\n<%= config.bin %> <%= command.id %> --session-id <SESSION_ID> --format detail --dimension actions",
3905
+ "Drill into routing decisions for the first turn of the conversation:\n<%= config.bin %> <%= command.id %> --session-id <SESSION_ID> --format detail --dimension routing --turn 1",
3906
+ "Show all errors across the session:\n<%= config.bin %> <%= command.id %> --session-id <SESSION_ID> --format detail --dimension errors",
3907
+ "Output raw trace JSON for custom parsing:\n<%= config.bin %> <%= command.id %> --session-id <SESSION_ID> --format raw",
3908
+ "Return results as JSON:\n<%= config.bin %> <%= command.id %> --session-id <SESSION_ID> --json"
3850
3909
  ],
3851
3910
  "flags": {
3852
3911
  "json": {
@@ -3864,137 +3923,78 @@
3864
3923
  "multiple": false,
3865
3924
  "type": "option"
3866
3925
  },
3867
- "target-org": {
3868
- "char": "o",
3869
- "name": "target-org",
3870
- "noCacheDefault": true,
3926
+ "session-id": {
3927
+ "char": "s",
3928
+ "name": "session-id",
3871
3929
  "required": true,
3872
- "summary": "Username or alias of the target org. Not required if the `target-org` configuration variable is already set.",
3873
- "hasDynamicHelp": true,
3874
- "multiple": false,
3875
- "type": "option"
3876
- },
3877
- "api-version": {
3878
- "description": "Override the api version used for api requests made by this command",
3879
- "name": "api-version",
3880
- "hasDynamicHelp": false,
3881
- "multiple": false,
3882
- "type": "option"
3883
- },
3884
- "api-name": {
3885
- "char": "n",
3886
- "name": "api-name",
3887
- "summary": "API name of the agent test to run; corresponds to the name of the AiEvaluationDefinition metadata component that implements the agent test.",
3930
+ "summary": "Session ID to read traces for. Use the \"agent preview sessions\" CLI command to list all known agent preview sessions along with their session IDs",
3888
3931
  "hasDynamicHelp": false,
3889
3932
  "multiple": false,
3890
3933
  "type": "option"
3891
3934
  },
3892
- "wait": {
3893
- "char": "w",
3894
- "name": "wait",
3895
- "summary": "Number of minutes to wait for the command to complete and display results to the terminal window.",
3896
- "hasDynamicHelp": true,
3897
- "multiple": false,
3898
- "type": "option"
3899
- },
3900
- "result-format": {
3901
- "name": "result-format",
3902
- "summary": "Format of the agent test run results.",
3903
- "default": "human",
3935
+ "format": {
3936
+ "char": "f",
3937
+ "name": "format",
3938
+ "summary": "Output format of the trace data; specifies the level of detail you want in the trace files.",
3939
+ "default": "summary",
3904
3940
  "hasDynamicHelp": false,
3905
3941
  "multiple": false,
3906
3942
  "options": [
3907
- "json",
3908
- "human",
3909
- "junit",
3910
- "tap"
3943
+ "summary",
3944
+ "detail",
3945
+ "raw"
3911
3946
  ],
3912
3947
  "type": "option"
3913
3948
  },
3914
- "output-dir": {
3949
+ "dimension": {
3915
3950
  "char": "d",
3916
- "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.",
3917
- "name": "output-dir",
3918
- "summary": "Directory to write the agent test results into.",
3951
+ "name": "dimension",
3952
+ "summary": "Dimension to drill into when using \"--format detail\"; used to filter and organize the trace data to answer a specific type of question.",
3919
3953
  "hasDynamicHelp": false,
3920
3954
  "multiple": false,
3955
+ "options": [
3956
+ "actions",
3957
+ "grounding",
3958
+ "routing",
3959
+ "errors"
3960
+ ],
3921
3961
  "type": "option"
3922
3962
  },
3923
- "test-runner": {
3924
- "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.",
3925
- "name": "test-runner",
3926
- "summary": "Explicitly specify which test runner to use (agentforce-studio or testing-center).",
3963
+ "turn": {
3964
+ "char": "t",
3965
+ "name": "turn",
3966
+ "summary": "Turn number for which you want trace data. A turn is a single utterance or response in a conversation, starting with 1.",
3927
3967
  "hasDynamicHelp": false,
3928
3968
  "multiple": false,
3929
- "options": [
3930
- "agentforce-studio",
3931
- "testing-center"
3932
- ],
3933
3969
  "type": "option"
3934
- },
3935
- "verbose": {
3936
- "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.",
3937
- "name": "verbose",
3938
- "summary": "Show generated data in the test results output.",
3939
- "allowNo": false,
3940
- "type": "boolean"
3941
3970
  }
3942
3971
  },
3943
- "hasDynamicHelp": true,
3972
+ "hasDynamicHelp": false,
3944
3973
  "hiddenAliases": [],
3945
- "id": "agent:test:run",
3974
+ "id": "agent:trace:read",
3946
3975
  "pluginAlias": "@salesforce/plugin-agent",
3947
3976
  "pluginName": "@salesforce/plugin-agent",
3948
3977
  "pluginType": "core",
3949
3978
  "strict": true,
3950
- "summary": "Start an agent test in your org.",
3979
+ "summary": "Read trace files from an agent preview session.",
3951
3980
  "enableJsonFlag": true,
3952
- "envVariablesSection": {
3953
- "header": "ENVIRONMENT VARIABLES",
3954
- "body": [
3955
- {
3956
- "name": "SF_TARGET_ORG",
3957
- "description": "Username or alias of your default org. Overrides the target-org configuration variable."
3958
- }
3959
- ]
3960
- },
3961
- "errorCodes": {
3962
- "header": "ERROR CODES",
3963
- "body": [
3964
- {
3965
- "name": "Succeeded (0)",
3966
- "description": "Test started successfully (without --wait), or test completed successfully (with --wait)."
3967
- },
3968
- {
3969
- "name": "Failed (1)",
3970
- "description": "Tests encountered execution errors (test cases with ERROR status when using --wait)."
3971
- },
3972
- {
3973
- "name": "NotFound (2)",
3974
- "description": "Test definition not found or invalid test name."
3975
- },
3976
- {
3977
- "name": "OperationFailed (4)",
3978
- "description": "Failed to start or poll test due to API or network errors."
3979
- }
3980
- ]
3981
- },
3981
+ "requiresProject": true,
3982
3982
  "isESM": true,
3983
3983
  "relativePath": [
3984
3984
  "lib",
3985
3985
  "commands",
3986
3986
  "agent",
3987
- "test",
3988
- "run.js"
3987
+ "trace",
3988
+ "read.js"
3989
3989
  ],
3990
3990
  "aliasPermutations": [],
3991
3991
  "permutations": [
3992
- "agent:test:run",
3993
- "test:agent:run",
3994
- "test:run:agent",
3995
- "agent:run:test",
3996
- "run:agent:test",
3997
- "run:test:agent"
3992
+ "agent:trace:read",
3993
+ "trace:agent:read",
3994
+ "trace:read:agent",
3995
+ "agent:read:trace",
3996
+ "read:agent:trace",
3997
+ "read:trace:agent"
3998
3998
  ]
3999
3999
  },
4000
4000
  "agent:validate:authoring-bundle": {
@@ -4667,5 +4667,5 @@
4667
4667
  ]
4668
4668
  }
4669
4669
  },
4670
- "version": "2.0.0"
4670
+ "version": "2.0.2"
4671
4671
  }