@salesforce/plugin-agent 2.0.1 → 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 +606 -606
  3. package/package.json +4 -4
@@ -1120,16 +1120,16 @@
1120
1120
  "upload:adl:agent"
1121
1121
  ]
1122
1122
  },
1123
- "agent:preview:end": {
1123
+ "agent:generate:agent-spec": {
1124
1124
  "aliases": [],
1125
1125
  "args": {},
1126
- "description": "You must have previously started a programmatic agent preview session with the \"agent preview start\" command to then use this command to end it. This command also displays the local directory where the session trace files are stored.\n\nThe original \"agent preview start\" command outputs a session ID which you then use with the --session-id flag of this command to end the session. You don't have to specify the --session-id flag if an agent has only one active preview session. You must also use either the --authoring-bundle or --api-name flag to specify the API name of the authoring bundle or the published agent, respectively. To find either API name, navigate to your package directory in your DX project. The API name of an authoring bundle is the same as its directory name under the \"aiAuthoringBundles\" metadata directory. Similarly, the published agent's API name is the same as its directory name under the \"Bots\" metadata directory.\n\nUse the --all flag to end all active preview sessions at once. You can combine --all with --api-name or --authoring-bundle to end only sessions for a specific agent, or use --all on its own to end every session across all agents in the project.",
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
- "End a preview session of a published agent by specifying its session ID and API name; use the default org:\n<%= config.bin %> <%= command.id %> --session-id <SESSION_ID> --api-name My_Published_Agent",
1129
- "Similar to previous example, but don't specify a session ID; you get an error if the published agent has more than one active session. Use the org with alias \"my-dev-org\":\n<%= config.bin %> <%= command.id %> --api-name My_Published_Agent --target-org my-dev-org",
1130
- "End a preview session of an agent using its authoring bundle API name; you get an error if the agent has more than one active session.\n<%= config.bin %> <%= command.id %> --authoring-bundle My_Local_Agent",
1131
- "End all active preview sessions for a specific agent without prompting:\n<%= config.bin %> <%= command.id %> --all --authoring-bundle My_Local_Agent --target-org <target_org> --no-prompt",
1132
- "End all active preview sessions across every agent in the local session cache for an org:\n<%= config.bin %> <%= command.id %> --all --target-org <target_org>"
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"
1133
1133
  ],
1134
1134
  "flags": {
1135
1135
  "json": {
@@ -1164,129 +1164,164 @@
1164
1164
  "multiple": false,
1165
1165
  "type": "option"
1166
1166
  },
1167
- "session-id": {
1168
- "exclusive": [
1169
- "all"
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.",
1170
+ "hasDynamicHelp": false,
1171
+ "multiple": false,
1172
+ "options": [
1173
+ "customer",
1174
+ "internal"
1170
1175
  ],
1171
- "name": "session-id",
1172
- "required": false,
1173
- "summary": "Session ID outputted by \"agent preview start\". Not required when the agent has exactly one active session. Run \"agent preview sessions\" to see the list of all sessions.",
1176
+ "type": "option"
1177
+ },
1178
+ "role": {
1179
+ "name": "role",
1180
+ "summary": "Role of the agent.",
1174
1181
  "hasDynamicHelp": false,
1175
1182
  "multiple": false,
1176
1183
  "type": "option"
1177
1184
  },
1178
- "api-name": {
1179
- "char": "n",
1180
- "exclusive": [
1181
- "authoring-bundle"
1182
- ],
1183
- "name": "api-name",
1184
- "summary": "API name of the activated published agent you want to preview.",
1185
+ "company-name": {
1186
+ "name": "company-name",
1187
+ "summary": "Name of your company.",
1185
1188
  "hasDynamicHelp": false,
1186
1189
  "multiple": false,
1187
1190
  "type": "option"
1188
1191
  },
1189
- "authoring-bundle": {
1190
- "exclusive": [
1191
- "api-name"
1192
- ],
1193
- "name": "authoring-bundle",
1194
- "summary": "API name of the authoring bundle metadata component that contains the agent's Agent Script file.",
1192
+ "company-description": {
1193
+ "name": "company-description",
1194
+ "summary": "Description of your company.",
1195
1195
  "hasDynamicHelp": false,
1196
1196
  "multiple": false,
1197
1197
  "type": "option"
1198
1198
  },
1199
- "all": {
1200
- "exclusive": [
1201
- "session-id"
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.",
1223
+ "hasDynamicHelp": false,
1224
+ "multiple": false,
1225
+ "options": [
1226
+ "true",
1227
+ "false"
1202
1228
  ],
1203
- "name": "all",
1204
- "summary": "End all active preview sessions. Combine with --api-name or --authoring-bundle to limit to a specific agent, or use with only --target-org to end sessions for all agents found in the local session cache. Requires --target-org.",
1229
+ "type": "option"
1230
+ },
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.",
1234
+ "hasDynamicHelp": false,
1235
+ "multiple": false,
1236
+ "options": [
1237
+ "formal",
1238
+ "casual",
1239
+ "neutral"
1240
+ ],
1241
+ "type": "option"
1242
+ },
1243
+ "spec": {
1244
+ "name": "spec",
1245
+ "summary": "Agent spec file, in YAML format, to use as input to the command.",
1246
+ "hasDynamicHelp": false,
1247
+ "multiple": false,
1248
+ "type": "option"
1249
+ },
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",
1254
+ "hasDynamicHelp": false,
1255
+ "multiple": false,
1256
+ "type": "option"
1257
+ },
1258
+ "full-interview": {
1259
+ "name": "full-interview",
1260
+ "summary": "Prompt for both required and optional flags.",
1205
1261
  "allowNo": false,
1206
1262
  "type": "boolean"
1207
1263
  },
1208
- "no-prompt": {
1209
- "char": "p",
1210
- "name": "no-prompt",
1211
- "summary": "Don't prompt for confirmation before ending sessions. Has an effect only when used with --all.",
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.",
1277
+ "hasDynamicHelp": false,
1278
+ "multiple": false,
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.",
1212
1284
  "allowNo": false,
1213
1285
  "type": "boolean"
1214
1286
  }
1215
1287
  },
1216
1288
  "hasDynamicHelp": true,
1217
1289
  "hiddenAliases": [],
1218
- "id": "agent:preview:end",
1290
+ "id": "agent:generate:agent-spec",
1219
1291
  "pluginAlias": "@salesforce/plugin-agent",
1220
1292
  "pluginName": "@salesforce/plugin-agent",
1221
1293
  "pluginType": "core",
1222
1294
  "strict": true,
1223
- "summary": "End an existing programmatic agent preview session and get trace location.",
1295
+ "summary": "Generate an agent spec, which is a YAML file that captures what an agent can do.",
1224
1296
  "enableJsonFlag": true,
1225
1297
  "requiresProject": true,
1226
- "envVariablesSection": {
1227
- "header": "ENVIRONMENT VARIABLES",
1228
- "body": [
1229
- {
1230
- "name": "SF_TARGET_ORG",
1231
- "description": "Username or alias of your default org. Overrides the target-org configuration variable."
1232
- }
1233
- ]
1234
- },
1235
- "errorCodes": {
1236
- "header": "ERROR CODES",
1237
- "body": [
1238
- {
1239
- "name": "Succeeded (0)",
1240
- "description": "Preview session ended successfully and traces saved."
1241
- },
1242
- {
1243
- "name": "ExactlyOneRequired (2)",
1244
- "description": "Neither --api-name nor --authoring-bundle was provided (required when --all is not set)."
1245
- },
1246
- {
1247
- "name": "NotFound (2)",
1248
- "description": "Agent not found, or no preview session exists for this agent."
1249
- },
1250
- {
1251
- "name": "PreviewEndFailed (4)",
1252
- "description": "Failed to end the preview session."
1253
- },
1254
- {
1255
- "name": "PreviewEndPartialFailure (68)",
1256
- "description": "With --all, one or more sessions failed to end while others succeeded."
1257
- },
1258
- {
1259
- "name": "SessionAmbiguous (5)",
1260
- "description": "Multiple preview sessions found; specify --session-id to choose one."
1261
- }
1262
- ]
1263
- },
1264
1298
  "isESM": true,
1265
1299
  "relativePath": [
1266
1300
  "lib",
1267
1301
  "commands",
1268
1302
  "agent",
1269
- "preview",
1270
- "end.js"
1303
+ "generate",
1304
+ "agent-spec.js"
1271
1305
  ],
1272
1306
  "aliasPermutations": [],
1273
1307
  "permutations": [
1274
- "agent:preview:end",
1275
- "preview:agent:end",
1276
- "preview:end:agent",
1277
- "agent:end:preview",
1278
- "end:agent:preview",
1279
- "end:preview: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"
1280
1314
  ]
1281
1315
  },
1282
- "agent:preview:send": {
1316
+ "agent:generate:authoring-bundle": {
1283
1317
  "aliases": [],
1284
1318
  "args": {},
1285
- "description": "You must have previously started a programmatic agent preview session with the \"agent preview start\" command to then use this command to send the agent a message (utterance). This command then displays the agent's response.\n\nThe original \"agent preview start\" command outputs a session ID which you then use with the --session-id flag of this command to send a message. You don't have to specify the --session-id flag if an agent has only one active preview session. You must also use either the --authoring-bundle or --api-name flag to specify the API name of the authoring bundle or the published agent, respecitvely. To find either API name, navigate to your package directory in your DX project. The API name of an authoring bundle is the same as its directory name under the \"aiAuthoringBundles\" metadata directory. Similarly, the published agent's API name is the same as its directory name under the \"Bots\" metadata directory.",
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.",
1286
1320
  "examples": [
1287
- "Send a message to an activated published agent using its API name and session ID; use the default org:\n<%= config.bin %> <%= command.id %> --utterance \"What can you help me with?\" --api-name My_Published_Agent --session-id <SESSION_ID>",
1288
- "Similar to previous example, but don't specify a session ID; you get an error if the agent has more than one active session. Use the org with alias \"my-dev-org\":\n<%= config.bin %> <%= command.id %> --utterance \"What can you help me with?\" --api-name My_Published_Agent --target-org my-dev-org",
1289
- "Send a message to an agent using its authoring bundle API name; you get an error if the agent has more than one active session:\n<%= config.bin %> <%= command.id %> --utterance \"what can you help me with?\" --authoring-bundle My_Local_Agent"
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"
1290
1325
  ],
1291
1326
  "flags": {
1292
1327
  "json": {
@@ -1314,6 +1349,13 @@
1314
1349
  "multiple": false,
1315
1350
  "type": "option"
1316
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
+ },
1317
1359
  "api-version": {
1318
1360
  "description": "Override the api version used for api requests made by this command",
1319
1361
  "name": "api-version",
@@ -1321,103 +1363,77 @@
1321
1363
  "multiple": false,
1322
1364
  "type": "option"
1323
1365
  },
1324
- "session-id": {
1325
- "name": "session-id",
1326
- "required": false,
1327
- "summary": "Session ID outputted by \"agent preview start\". Not required when the agent has exactly one active session. Run \"agent preview sessions\" to see list of all sessions.",
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.",
1328
1370
  "hasDynamicHelp": false,
1329
1371
  "multiple": false,
1330
1372
  "type": "option"
1331
1373
  },
1332
- "utterance": {
1333
- "char": "u",
1334
- "name": "utterance",
1335
- "required": true,
1336
- "summary": "Utterance to send to the agent, enclosed in double quotes.",
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.",
1337
1384
  "hasDynamicHelp": false,
1338
1385
  "multiple": false,
1339
1386
  "type": "option"
1340
1387
  },
1341
- "api-name": {
1388
+ "name": {
1342
1389
  "char": "n",
1343
- "name": "api-name",
1344
- "summary": "API name of the activated published agent you want to preview.",
1390
+ "name": "name",
1391
+ "summary": "Name (label) of the authoring bundle; if not specified, you're prompted for the name.",
1345
1392
  "hasDynamicHelp": false,
1346
1393
  "multiple": false,
1347
1394
  "type": "option"
1348
1395
  },
1349
- "authoring-bundle": {
1350
- "name": "authoring-bundle",
1351
- "summary": "API name of the authoring bundle metadata component that contains the agent's Agent Script file.",
1352
- "hasDynamicHelp": false,
1353
- "multiple": false,
1354
- "type": "option"
1355
- }
1356
- },
1357
- "hasDynamicHelp": true,
1396
+ "force-overwrite": {
1397
+ "name": "force-overwrite",
1398
+ "summary": "Overwrite the existing authoring bundle if one with the same API name already exists locally.",
1399
+ "allowNo": false,
1400
+ "type": "boolean"
1401
+ }
1402
+ },
1403
+ "hasDynamicHelp": true,
1358
1404
  "hiddenAliases": [],
1359
- "id": "agent:preview:send",
1405
+ "id": "agent:generate:authoring-bundle",
1360
1406
  "pluginAlias": "@salesforce/plugin-agent",
1361
1407
  "pluginName": "@salesforce/plugin-agent",
1362
1408
  "pluginType": "core",
1363
1409
  "strict": true,
1364
- "summary": "Send a message to an existing agent preview session.",
1410
+ "summary": "Generate an authoring bundle from an existing agent spec YAML file.",
1365
1411
  "enableJsonFlag": true,
1366
1412
  "requiresProject": true,
1367
- "envVariablesSection": {
1368
- "header": "ENVIRONMENT VARIABLES",
1369
- "body": [
1370
- {
1371
- "name": "SF_TARGET_ORG",
1372
- "description": "Username or alias of your default org. Overrides the target-org configuration variable."
1373
- }
1374
- ]
1375
- },
1376
- "errorCodes": {
1377
- "header": "ERROR CODES",
1378
- "body": [
1379
- {
1380
- "name": "Succeeded (0)",
1381
- "description": "Message sent successfully and agent response received."
1382
- },
1383
- {
1384
- "name": "NotFound (2)",
1385
- "description": "Agent not found, or no preview session exists for this agent."
1386
- },
1387
- {
1388
- "name": "PreviewSendFailed (4)",
1389
- "description": "Failed to send message or receive response from the preview session."
1390
- },
1391
- {
1392
- "name": "SessionAmbiguous (5)",
1393
- "description": "Multiple preview sessions found; specify --session-id to choose one."
1394
- }
1395
- ]
1396
- },
1397
1413
  "isESM": true,
1398
1414
  "relativePath": [
1399
1415
  "lib",
1400
1416
  "commands",
1401
1417
  "agent",
1402
- "preview",
1403
- "send.js"
1418
+ "generate",
1419
+ "authoring-bundle.js"
1404
1420
  ],
1405
1421
  "aliasPermutations": [],
1406
1422
  "permutations": [
1407
- "agent:preview:send",
1408
- "preview:agent:send",
1409
- "preview:send:agent",
1410
- "agent:send:preview",
1411
- "send:agent:preview",
1412
- "send:preview: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"
1413
1429
  ]
1414
1430
  },
1415
- "agent:preview:sessions": {
1431
+ "agent:generate:template": {
1416
1432
  "aliases": [],
1417
1433
  "args": {},
1418
- "description": "This command lists the agent preview sessions that were started with the \"agent preview start\" command and are still in the local cache. Use this command to discover specific session IDs that you can pass to the \"agent preview send\" or \"agent preview end\" commands with the --session-id flag.\n\nProgrammatic agent preview sessions can be started for both published activated agents and by using an agent's local authoring bundle, which contains its Agent Script file. In this command's output table, the Agent column contains either the API name of the authoring bundle or the published agent, whichever was used when starting the session. In the table, if the same API name has multiple rows with different session IDs, then it means that you previously started multiple preview sessions with the associated agent.",
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.",
1419
1435
  "examples": [
1420
- "List all cached agent preview sessions:\n<%= config.bin %> <%= command.id %>"
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"
1421
1437
  ],
1422
1438
  "flags": {
1423
1439
  "json": {
@@ -1434,53 +1450,167 @@
1434
1450
  "hasDynamicHelp": false,
1435
1451
  "multiple": false,
1436
1452
  "type": "option"
1453
+ },
1454
+ "api-version": {
1455
+ "description": "Override the api version used for api requests made by this command",
1456
+ "name": "api-version",
1457
+ "hasDynamicHelp": false,
1458
+ "multiple": false,
1459
+ "type": "option"
1460
+ },
1461
+ "source-org": {
1462
+ "char": "s",
1463
+ "name": "source-org",
1464
+ "noCacheDefault": true,
1465
+ "required": true,
1466
+ "summary": "Username or alias of the namespaced scratch org that contains the agent which this template is based on.",
1467
+ "hasDynamicHelp": true,
1468
+ "multiple": false,
1469
+ "type": "option"
1470
+ },
1471
+ "agent-version": {
1472
+ "name": "agent-version",
1473
+ "required": true,
1474
+ "summary": "Version of the agent (BotVersion).",
1475
+ "hasDynamicHelp": false,
1476
+ "multiple": false,
1477
+ "type": "option"
1478
+ },
1479
+ "agent-file": {
1480
+ "char": "f",
1481
+ "name": "agent-file",
1482
+ "required": true,
1483
+ "summary": "Path to an agent (Bot) metadata file.",
1484
+ "hasDynamicHelp": false,
1485
+ "multiple": false,
1486
+ "type": "option"
1487
+ },
1488
+ "output-dir": {
1489
+ "char": "r",
1490
+ "name": "output-dir",
1491
+ "summary": "Directory where the generated BotTemplate and GenAiPlannerBundle files are saved.",
1492
+ "hasDynamicHelp": false,
1493
+ "multiple": false,
1494
+ "type": "option"
1437
1495
  }
1438
1496
  },
1439
- "hasDynamicHelp": false,
1497
+ "hasDynamicHelp": true,
1440
1498
  "hiddenAliases": [],
1441
- "id": "agent:preview:sessions",
1499
+ "id": "agent:generate:template",
1442
1500
  "pluginAlias": "@salesforce/plugin-agent",
1443
1501
  "pluginName": "@salesforce/plugin-agent",
1444
1502
  "pluginType": "core",
1445
1503
  "strict": true,
1446
- "summary": "List all known programmatic agent preview sessions.",
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.",
1447
1505
  "enableJsonFlag": true,
1448
1506
  "requiresProject": true,
1449
- "errorCodes": {
1450
- "header": "ERROR CODES",
1451
- "body": [
1452
- {
1453
- "name": "Succeeded (0)",
1454
- "description": "Sessions listed successfully (or empty list if no active sessions)."
1455
- }
1456
- ]
1507
+ "isESM": true,
1508
+ "relativePath": [
1509
+ "lib",
1510
+ "commands",
1511
+ "agent",
1512
+ "generate",
1513
+ "template.js"
1514
+ ],
1515
+ "aliasPermutations": [],
1516
+ "permutations": [
1517
+ "agent:generate:template",
1518
+ "generate:agent:template",
1519
+ "generate:template:agent",
1520
+ "agent:template:generate",
1521
+ "template:agent:generate",
1522
+ "template:generate:agent"
1523
+ ]
1524
+ },
1525
+ "agent:generate:test-spec": {
1526
+ "aliases": [],
1527
+ "args": {},
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.",
1529
+ "examples": [
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"
1535
+ ],
1536
+ "flags": {
1537
+ "flags-dir": {
1538
+ "helpGroup": "GLOBAL",
1539
+ "name": "flags-dir",
1540
+ "summary": "Import flag values from a directory.",
1541
+ "hasDynamicHelp": false,
1542
+ "multiple": false,
1543
+ "type": "option"
1544
+ },
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.",
1549
+ "hasDynamicHelp": false,
1550
+ "multiple": false,
1551
+ "type": "option"
1552
+ },
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"
1558
+ },
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).",
1563
+ "hasDynamicHelp": false,
1564
+ "multiple": false,
1565
+ "type": "option"
1566
+ },
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).",
1571
+ "hasDynamicHelp": false,
1572
+ "multiple": false,
1573
+ "options": [
1574
+ "agentforce-studio",
1575
+ "testing-center"
1576
+ ],
1577
+ "type": "option"
1578
+ }
1457
1579
  },
1580
+ "hasDynamicHelp": false,
1581
+ "hiddenAliases": [],
1582
+ "id": "agent:generate:test-spec",
1583
+ "pluginAlias": "@salesforce/plugin-agent",
1584
+ "pluginName": "@salesforce/plugin-agent",
1585
+ "pluginType": "core",
1586
+ "strict": 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,
1458
1589
  "isESM": true,
1459
1590
  "relativePath": [
1460
1591
  "lib",
1461
1592
  "commands",
1462
1593
  "agent",
1463
- "preview",
1464
- "sessions.js"
1594
+ "generate",
1595
+ "test-spec.js"
1465
1596
  ],
1466
1597
  "aliasPermutations": [],
1467
1598
  "permutations": [
1468
- "agent:preview:sessions",
1469
- "preview:agent:sessions",
1470
- "preview:sessions:agent",
1471
- "agent:sessions:preview",
1472
- "sessions:agent:preview",
1473
- "sessions:preview: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"
1474
1605
  ]
1475
1606
  },
1476
- "agent:preview:start": {
1607
+ "agent:mcp:create": {
1477
1608
  "aliases": [],
1478
1609
  "args": {},
1479
- "description": "This command outputs a session ID that you then use with the \"agent preview send\" command to send an utterance to the agent. Use the \"agent preview sessions\" command to list all active sessions and the \"agent preview end\" command to end a specific session.\n\nIdentify the agent you want to start previewing with either the --authoring-bundle flag to specify a local authoring bundle's API name or --api-name to specify an activated published agent's API name. To find either API name, navigate to your package directory in your DX project. The API name of an authoring bundle is the same as its directory name under the \"aiAuthoringBundles\" metadata directory. Similarly, the published agent's API name is the same as its directory name under the \"Bots\" metadata directory.\n\nWhen starting a preview session with --authoring-bundle, you must explicitly specify the execution mode using one of these flags:\n\n- --use-live-actions: Executes real Apex classes, flows, and other actions in the org. This surfaces compile and validation errors during preview.\n- --simulate-actions: Uses AI to simulate action execution without calling real implementations.\n\nPublished agents (--api-name) always use live actions. The mode flags are optional and have no effect for published agents.",
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.",
1480
1611
  "examples": [
1481
- "Start a programmatic agent preview session by specifying an authoring bundle; use simulated actions. Use the org with alias \"my-dev-org\":\n<%= config.bin %> <%= command.id %> --authoring-bundle My_Agent_Bundle --target-org my-dev-org --simulate-actions",
1482
- "Similar to previous example but use live actions and the default org:\n<%= config.bin %> <%= command.id %> --authoring-bundle My_Agent_Bundle --use-live-actions",
1483
- "Start a preview session with an activated published agent (always uses live actions):\n<%= config.bin %> <%= command.id %> --api-name My_Published_Agent"
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"
1484
1614
  ],
1485
1615
  "flags": {
1486
1616
  "json": {
@@ -1515,185 +1645,28 @@
1515
1645
  "multiple": false,
1516
1646
  "type": "option"
1517
1647
  },
1518
- "api-name": {
1648
+ "name": {
1519
1649
  "char": "n",
1520
- "name": "api-name",
1521
- "summary": "API name of the activated published agent you want to preview.",
1650
+ "name": "name",
1651
+ "required": true,
1652
+ "summary": "Unique name of the MCP server.",
1522
1653
  "hasDynamicHelp": false,
1523
1654
  "multiple": false,
1524
1655
  "type": "option"
1525
1656
  },
1526
- "authoring-bundle": {
1527
- "name": "authoring-bundle",
1528
- "summary": "API name of the authoring bundle metadata component that contains the agent's Agent Script file.",
1657
+ "label": {
1658
+ "name": "label",
1659
+ "summary": "Human-readable label for the MCP server.",
1529
1660
  "hasDynamicHelp": false,
1530
1661
  "multiple": false,
1531
1662
  "type": "option"
1532
1663
  },
1533
- "use-live-actions": {
1534
- "exclusive": [
1535
- "simulate-actions"
1536
- ],
1537
- "name": "use-live-actions",
1538
- "summary": "Execute real actions in the org (Apex classes, flows, etc.). Required with --authoring-bundle.",
1539
- "allowNo": false,
1540
- "type": "boolean"
1541
- },
1542
- "simulate-actions": {
1543
- "exclusive": [
1544
- "use-live-actions"
1545
- ],
1546
- "name": "simulate-actions",
1547
- "summary": "Use AI to simulate action execution instead of calling real actions. Required with --authoring-bundle.",
1548
- "allowNo": false,
1549
- "type": "boolean"
1550
- },
1551
- "context-variables": {
1552
- "description": "Sets variables on the agent preview session, mirroring what the in-org Agentforce Builder UI does when you override variables before sending a message. Specify this flag multiple times or use comma-separated values. Two namespaces are supported, distinguished by the name shape. Names pass through to the runtime verbatim — the CLI doesn't transform them.\n\nLinked context variables use the \"$Context.\" prefix. These map to externally-provided fields that the runtime resolves (declared in the bundle's globalConfiguration.contextVariables) and are read by live actions and topic-routing expressions via $Context.Name. Example: $Context.MyLinkedVar=some-value.\n\nState variables use the bare developerName, no prefix. These seed mutable agent state declared in agentVersion.stateVariables. Example: MyStateVar=some-value.\n\nBoth namespaces can be mixed in one value. Example: --context-variables '$Context.MyLinkedVar=foo,MyStateVar=bar'.\n\nTips: (1) Quote the whole value in single quotes so $Context isn't shell-expanded. (2) Names are sent verbatim — a bare name is treated as a state variable, not a linked context variable, so live actions that bind via $Context.Name will see null. (3) Type defaults to Text.",
1553
- "name": "context-variables",
1554
- "summary": "Session variables for the agent preview session, in the form Name=Value.",
1555
- "delimiter": ",",
1556
- "hasDynamicHelp": false,
1557
- "multiple": true,
1558
- "type": "option"
1559
- },
1560
- "agent-json": {
1561
- "dependsOn": [
1562
- "authoring-bundle"
1563
- ],
1564
- "hidden": true,
1565
- "name": "agent-json",
1566
- "summary": "Path to a pre-compiled AgentJSON file to use instead of compiling the Agent Script file. Intended for internal use and testing.",
1567
- "hasDynamicHelp": false,
1568
- "multiple": false,
1569
- "type": "option"
1570
- }
1571
- },
1572
- "hasDynamicHelp": true,
1573
- "hiddenAliases": [],
1574
- "id": "agent:preview:start",
1575
- "pluginAlias": "@salesforce/plugin-agent",
1576
- "pluginName": "@salesforce/plugin-agent",
1577
- "pluginType": "core",
1578
- "strict": true,
1579
- "summary": "Start a programmatic agent preview session.",
1580
- "enableJsonFlag": true,
1581
- "requiresProject": true,
1582
- "envVariablesSection": {
1583
- "header": "ENVIRONMENT VARIABLES",
1584
- "body": [
1585
- {
1586
- "name": "SF_TARGET_ORG",
1587
- "description": "Username or alias of your default org. Overrides the target-org configuration variable."
1588
- }
1589
- ]
1590
- },
1591
- "errorCodes": {
1592
- "header": "ERROR CODES",
1593
- "body": [
1594
- {
1595
- "name": "Succeeded (0)",
1596
- "description": "Preview session started successfully."
1597
- },
1598
- {
1599
- "name": "Failed (1)",
1600
- "description": "Agent Script compilation failed (syntax errors in the script)."
1601
- },
1602
- {
1603
- "name": "NotFound (2)",
1604
- "description": "Agent not found, or compilation API returned HTTP 404 (endpoint may not be available in your org or region)."
1605
- },
1606
- {
1607
- "name": "ServerError (3)",
1608
- "description": "Compilation API returned HTTP 500 (server error during compilation)."
1609
- },
1610
- {
1611
- "name": "PreviewStartFailed (4)",
1612
- "description": "Preview session failed to start due to API or network errors."
1613
- }
1614
- ]
1615
- },
1616
- "isESM": true,
1617
- "relativePath": [
1618
- "lib",
1619
- "commands",
1620
- "agent",
1621
- "preview",
1622
- "start.js"
1623
- ],
1624
- "aliasPermutations": [],
1625
- "permutations": [
1626
- "agent:preview:start",
1627
- "preview:agent:start",
1628
- "preview:start:agent",
1629
- "agent:start:preview",
1630
- "start:agent:preview",
1631
- "start:preview:agent"
1632
- ]
1633
- },
1634
- "agent:mcp:create": {
1635
- "aliases": [],
1636
- "args": {},
1637
- "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.",
1638
- "examples": [
1639
- "Create an MCP server with no authentication:\n<%= config.bin %> <%= command.id %> --name myServer --server-url https://mcp.example.com --target-org myOrg",
1640
- "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"
1641
- ],
1642
- "flags": {
1643
- "json": {
1644
- "description": "Format output as json.",
1645
- "helpGroup": "GLOBAL",
1646
- "name": "json",
1647
- "allowNo": false,
1648
- "type": "boolean"
1649
- },
1650
- "flags-dir": {
1651
- "helpGroup": "GLOBAL",
1652
- "name": "flags-dir",
1653
- "summary": "Import flag values from a directory.",
1654
- "hasDynamicHelp": false,
1655
- "multiple": false,
1656
- "type": "option"
1657
- },
1658
- "target-org": {
1659
- "char": "o",
1660
- "name": "target-org",
1661
- "noCacheDefault": true,
1662
- "required": true,
1663
- "summary": "Username or alias of the target org. Not required if the `target-org` configuration variable is already set.",
1664
- "hasDynamicHelp": true,
1665
- "multiple": false,
1666
- "type": "option"
1667
- },
1668
- "api-version": {
1669
- "description": "Override the api version used for api requests made by this command",
1670
- "name": "api-version",
1671
- "hasDynamicHelp": false,
1672
- "multiple": false,
1673
- "type": "option"
1674
- },
1675
- "name": {
1676
- "char": "n",
1677
- "name": "name",
1678
- "required": true,
1679
- "summary": "Unique name of the MCP server.",
1680
- "hasDynamicHelp": false,
1681
- "multiple": false,
1682
- "type": "option"
1683
- },
1684
- "label": {
1685
- "name": "label",
1686
- "summary": "Human-readable label for the MCP server.",
1687
- "hasDynamicHelp": false,
1688
- "multiple": false,
1689
- "type": "option"
1690
- },
1691
- "description": {
1692
- "name": "description",
1693
- "summary": "Description of the MCP server.",
1694
- "hasDynamicHelp": false,
1695
- "multiple": false,
1696
- "type": "option"
1664
+ "description": {
1665
+ "name": "description",
1666
+ "summary": "Description of the MCP server.",
1667
+ "hasDynamicHelp": false,
1668
+ "multiple": false,
1669
+ "type": "option"
1697
1670
  },
1698
1671
  "server-url": {
1699
1672
  "name": "server-url",
@@ -2252,16 +2225,16 @@
2252
2225
  "update:mcp:agent"
2253
2226
  ]
2254
2227
  },
2255
- "agent:generate:agent-spec": {
2228
+ "agent:preview:end": {
2256
2229
  "aliases": [],
2257
2230
  "args": {},
2258
- "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.)",
2231
+ "description": "You must have previously started a programmatic agent preview session with the \"agent preview start\" command to then use this command to end it. This command also displays the local directory where the session trace files are stored.\n\nThe original \"agent preview start\" command outputs a session ID which you then use with the --session-id flag of this command to end the session. You don't have to specify the --session-id flag if an agent has only one active preview session. You must also use either the --authoring-bundle or --api-name flag to specify the API name of the authoring bundle or the published agent, respectively. To find either API name, navigate to your package directory in your DX project. The API name of an authoring bundle is the same as its directory name under the \"aiAuthoringBundles\" metadata directory. Similarly, the published agent's API name is the same as its directory name under the \"Bots\" metadata directory.\n\nUse the --all flag to end all active preview sessions at once. You can combine --all with --api-name or --authoring-bundle to end only sessions for a specific agent, or use --all on its own to end every session across all agents in the project.",
2259
2232
  "examples": [
2260
- "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.\"",
2261
- "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",
2262
- "Be prompted for all required and optional agent properties; use your default org:\n<%= config.bin %> <%= command.id %> --full-interview",
2263
- "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\"",
2264
- "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"
2233
+ "End a preview session of a published agent by specifying its session ID and API name; use the default org:\n<%= config.bin %> <%= command.id %> --session-id <SESSION_ID> --api-name My_Published_Agent",
2234
+ "Similar to previous example, but don't specify a session ID; you get an error if the published agent has more than one active session. Use the org with alias \"my-dev-org\":\n<%= config.bin %> <%= command.id %> --api-name My_Published_Agent --target-org my-dev-org",
2235
+ "End a preview session of an agent using its authoring bundle API name; you get an error if the agent has more than one active session.\n<%= config.bin %> <%= command.id %> --authoring-bundle My_Local_Agent",
2236
+ "End all active preview sessions for a specific agent without prompting:\n<%= config.bin %> <%= command.id %> --all --authoring-bundle My_Local_Agent --target-org <target_org> --no-prompt",
2237
+ "End all active preview sessions across every agent in the local session cache for an org:\n<%= config.bin %> <%= command.id %> --all --target-org <target_org>"
2265
2238
  ],
2266
2239
  "flags": {
2267
2240
  "json": {
@@ -2296,164 +2269,129 @@
2296
2269
  "multiple": false,
2297
2270
  "type": "option"
2298
2271
  },
2299
- "type": {
2300
- "name": "type",
2301
- "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.",
2302
- "hasDynamicHelp": false,
2303
- "multiple": false,
2304
- "options": [
2305
- "customer",
2306
- "internal"
2272
+ "session-id": {
2273
+ "exclusive": [
2274
+ "all"
2307
2275
  ],
2308
- "type": "option"
2309
- },
2310
- "role": {
2311
- "name": "role",
2312
- "summary": "Role of the agent.",
2313
- "hasDynamicHelp": false,
2314
- "multiple": false,
2315
- "type": "option"
2316
- },
2317
- "company-name": {
2318
- "name": "company-name",
2319
- "summary": "Name of your company.",
2320
- "hasDynamicHelp": false,
2321
- "multiple": false,
2322
- "type": "option"
2323
- },
2324
- "company-description": {
2325
- "name": "company-description",
2326
- "summary": "Description of your company.",
2327
- "hasDynamicHelp": false,
2328
- "multiple": false,
2329
- "type": "option"
2330
- },
2331
- "company-website": {
2332
- "name": "company-website",
2333
- "summary": "Website URL of your company.",
2334
- "hasDynamicHelp": false,
2335
- "multiple": false,
2336
- "type": "option"
2337
- },
2338
- "max-topics": {
2339
- "name": "max-topics",
2340
- "summary": "Maximum number of topics to generate in the agent spec; default is 5.",
2276
+ "name": "session-id",
2277
+ "required": false,
2278
+ "summary": "Session ID outputted by \"agent preview start\". Not required when the agent has exactly one active session. Run \"agent preview sessions\" to see the list of all sessions.",
2341
2279
  "hasDynamicHelp": false,
2342
2280
  "multiple": false,
2343
2281
  "type": "option"
2344
2282
  },
2345
- "agent-user": {
2346
- "name": "agent-user",
2347
- "summary": "Username of a user in your org to assign to your agent; determines what your agent can access and do.",
2283
+ "api-name": {
2284
+ "char": "n",
2285
+ "exclusive": [
2286
+ "authoring-bundle"
2287
+ ],
2288
+ "name": "api-name",
2289
+ "summary": "API name of the activated published agent you want to preview.",
2348
2290
  "hasDynamicHelp": false,
2349
2291
  "multiple": false,
2350
2292
  "type": "option"
2351
2293
  },
2352
- "enrich-logs": {
2353
- "name": "enrich-logs",
2354
- "summary": "Adds agent conversation data to event logs so you can view all agent session activity in one place.",
2294
+ "authoring-bundle": {
2295
+ "exclusive": [
2296
+ "api-name"
2297
+ ],
2298
+ "name": "authoring-bundle",
2299
+ "summary": "API name of the authoring bundle metadata component that contains the agent's Agent Script file.",
2355
2300
  "hasDynamicHelp": false,
2356
2301
  "multiple": false,
2357
- "options": [
2358
- "true",
2359
- "false"
2360
- ],
2361
2302
  "type": "option"
2362
2303
  },
2363
- "tone": {
2364
- "name": "tone",
2365
- "summary": "Conversational style of the agent, such as how it expresses your brand personality in its messages through word choice, punctuation, and sentence structure.",
2366
- "hasDynamicHelp": false,
2367
- "multiple": false,
2368
- "options": [
2369
- "formal",
2370
- "casual",
2371
- "neutral"
2304
+ "all": {
2305
+ "exclusive": [
2306
+ "session-id"
2372
2307
  ],
2373
- "type": "option"
2308
+ "name": "all",
2309
+ "summary": "End all active preview sessions. Combine with --api-name or --authoring-bundle to limit to a specific agent, or use with only --target-org to end sessions for all agents found in the local session cache. Requires --target-org.",
2310
+ "allowNo": false,
2311
+ "type": "boolean"
2374
2312
  },
2375
- "spec": {
2376
- "name": "spec",
2377
- "summary": "Agent spec file, in YAML format, to use as input to the command.",
2378
- "hasDynamicHelp": false,
2379
- "multiple": false,
2380
- "type": "option"
2381
- },
2382
- "output-file": {
2383
- "name": "output-file",
2384
- "summary": "Path for the generated YAML agent spec file; can be an absolute or relative path.",
2385
- "default": "specs/agentSpec.yaml",
2386
- "hasDynamicHelp": false,
2387
- "multiple": false,
2388
- "type": "option"
2389
- },
2390
- "full-interview": {
2391
- "name": "full-interview",
2392
- "summary": "Prompt for both required and optional flags.",
2393
- "allowNo": false,
2394
- "type": "boolean"
2395
- },
2396
- "prompt-template": {
2397
- "name": "prompt-template",
2398
- "summary": "API name of a customized prompt template to use instead of the default prompt template.",
2399
- "hasDynamicHelp": false,
2400
- "multiple": false,
2401
- "type": "option"
2402
- },
2403
- "grounding-context": {
2404
- "dependsOn": [
2405
- "prompt-template"
2406
- ],
2407
- "name": "grounding-context",
2408
- "summary": "Context information and personalization that's added to your prompts when using a custom prompt template.",
2409
- "hasDynamicHelp": false,
2410
- "multiple": false,
2411
- "type": "option"
2412
- },
2413
- "force-overwrite": {
2414
- "name": "force-overwrite",
2415
- "summary": "Don't prompt the user to confirm that an existing spec file will be overwritten.",
2313
+ "no-prompt": {
2314
+ "char": "p",
2315
+ "name": "no-prompt",
2316
+ "summary": "Don't prompt for confirmation before ending sessions. Has an effect only when used with --all.",
2416
2317
  "allowNo": false,
2417
2318
  "type": "boolean"
2418
2319
  }
2419
2320
  },
2420
2321
  "hasDynamicHelp": true,
2421
2322
  "hiddenAliases": [],
2422
- "id": "agent:generate:agent-spec",
2323
+ "id": "agent:preview:end",
2423
2324
  "pluginAlias": "@salesforce/plugin-agent",
2424
2325
  "pluginName": "@salesforce/plugin-agent",
2425
2326
  "pluginType": "core",
2426
2327
  "strict": true,
2427
- "summary": "Generate an agent spec, which is a YAML file that captures what an agent can do.",
2328
+ "summary": "End an existing programmatic agent preview session and get trace location.",
2428
2329
  "enableJsonFlag": true,
2429
2330
  "requiresProject": true,
2331
+ "envVariablesSection": {
2332
+ "header": "ENVIRONMENT VARIABLES",
2333
+ "body": [
2334
+ {
2335
+ "name": "SF_TARGET_ORG",
2336
+ "description": "Username or alias of your default org. Overrides the target-org configuration variable."
2337
+ }
2338
+ ]
2339
+ },
2340
+ "errorCodes": {
2341
+ "header": "ERROR CODES",
2342
+ "body": [
2343
+ {
2344
+ "name": "Succeeded (0)",
2345
+ "description": "Preview session ended successfully and traces saved."
2346
+ },
2347
+ {
2348
+ "name": "ExactlyOneRequired (2)",
2349
+ "description": "Neither --api-name nor --authoring-bundle was provided (required when --all is not set)."
2350
+ },
2351
+ {
2352
+ "name": "NotFound (2)",
2353
+ "description": "Agent not found, or no preview session exists for this agent."
2354
+ },
2355
+ {
2356
+ "name": "PreviewEndFailed (4)",
2357
+ "description": "Failed to end the preview session."
2358
+ },
2359
+ {
2360
+ "name": "PreviewEndPartialFailure (68)",
2361
+ "description": "With --all, one or more sessions failed to end while others succeeded."
2362
+ },
2363
+ {
2364
+ "name": "SessionAmbiguous (5)",
2365
+ "description": "Multiple preview sessions found; specify --session-id to choose one."
2366
+ }
2367
+ ]
2368
+ },
2430
2369
  "isESM": true,
2431
2370
  "relativePath": [
2432
2371
  "lib",
2433
2372
  "commands",
2434
2373
  "agent",
2435
- "generate",
2436
- "agent-spec.js"
2374
+ "preview",
2375
+ "end.js"
2437
2376
  ],
2438
2377
  "aliasPermutations": [],
2439
2378
  "permutations": [
2440
- "agent:generate:agent-spec",
2441
- "generate:agent:agent-spec",
2442
- "generate:agent-spec:agent",
2443
- "agent:agent-spec:generate",
2444
- "agent-spec:agent:generate",
2445
- "agent-spec:generate:agent"
2379
+ "agent:preview:end",
2380
+ "preview:agent:end",
2381
+ "preview:end:agent",
2382
+ "agent:end:preview",
2383
+ "end:agent:preview",
2384
+ "end:preview:agent"
2446
2385
  ]
2447
2386
  },
2448
- "agent:generate:authoring-bundle": {
2387
+ "agent:preview:send": {
2449
2388
  "aliases": [],
2450
2389
  "args": {},
2451
- "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.",
2390
+ "description": "You must have previously started a programmatic agent preview session with the \"agent preview start\" command to then use this command to send the agent a message (utterance). This command then displays the agent's response.\n\nThe original \"agent preview start\" command outputs a session ID which you then use with the --session-id flag of this command to send a message. You don't have to specify the --session-id flag if an agent has only one active preview session. You must also use either the --authoring-bundle or --api-name flag to specify the API name of the authoring bundle or the published agent, respecitvely. To find either API name, navigate to your package directory in your DX project. The API name of an authoring bundle is the same as its directory name under the \"aiAuthoringBundles\" metadata directory. Similarly, the published agent's API name is the same as its directory name under the \"Bots\" metadata directory.",
2452
2391
  "examples": [
2453
- "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 %>",
2454
- "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\"",
2455
- "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\"",
2456
- "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"
2392
+ "Send a message to an activated published agent using its API name and session ID; use the default org:\n<%= config.bin %> <%= command.id %> --utterance \"What can you help me with?\" --api-name My_Published_Agent --session-id <SESSION_ID>",
2393
+ "Similar to previous example, but don't specify a session ID; you get an error if the agent has more than one active session. Use the org with alias \"my-dev-org\":\n<%= config.bin %> <%= command.id %> --utterance \"What can you help me with?\" --api-name My_Published_Agent --target-org my-dev-org",
2394
+ "Send a message to an agent using its authoring bundle API name; you get an error if the agent has more than one active session:\n<%= config.bin %> <%= command.id %> --utterance \"what can you help me with?\" --authoring-bundle My_Local_Agent"
2457
2395
  ],
2458
2396
  "flags": {
2459
2397
  "json": {
@@ -2481,13 +2419,6 @@
2481
2419
  "multiple": false,
2482
2420
  "type": "option"
2483
2421
  },
2484
- "api-name": {
2485
- "name": "api-name",
2486
- "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.",
2487
- "hasDynamicHelp": false,
2488
- "multiple": false,
2489
- "type": "option"
2490
- },
2491
2422
  "api-version": {
2492
2423
  "description": "Override the api version used for api requests made by this command",
2493
2424
  "name": "api-version",
@@ -2495,77 +2426,103 @@
2495
2426
  "multiple": false,
2496
2427
  "type": "option"
2497
2428
  },
2498
- "spec": {
2499
- "char": "f",
2500
- "name": "spec",
2501
- "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.",
2429
+ "session-id": {
2430
+ "name": "session-id",
2431
+ "required": false,
2432
+ "summary": "Session ID outputted by \"agent preview start\". Not required when the agent has exactly one active session. Run \"agent preview sessions\" to see list of all sessions.",
2502
2433
  "hasDynamicHelp": false,
2503
2434
  "multiple": false,
2504
2435
  "type": "option"
2505
2436
  },
2506
- "no-spec": {
2507
- "name": "no-spec",
2508
- "summary": "Skip prompting for an agent spec and use the default Agent Script boilerplate in the generated authoring bundle.",
2509
- "allowNo": false,
2510
- "type": "boolean"
2511
- },
2512
- "output-dir": {
2513
- "char": "d",
2514
- "name": "output-dir",
2515
- "summary": "Directory where the authoring bundle files are generated.",
2437
+ "utterance": {
2438
+ "char": "u",
2439
+ "name": "utterance",
2440
+ "required": true,
2441
+ "summary": "Utterance to send to the agent, enclosed in double quotes.",
2516
2442
  "hasDynamicHelp": false,
2517
2443
  "multiple": false,
2518
2444
  "type": "option"
2519
2445
  },
2520
- "name": {
2446
+ "api-name": {
2521
2447
  "char": "n",
2522
- "name": "name",
2523
- "summary": "Name (label) of the authoring bundle; if not specified, you're prompted for the name.",
2448
+ "name": "api-name",
2449
+ "summary": "API name of the activated published agent you want to preview.",
2524
2450
  "hasDynamicHelp": false,
2525
2451
  "multiple": false,
2526
2452
  "type": "option"
2527
2453
  },
2528
- "force-overwrite": {
2529
- "name": "force-overwrite",
2530
- "summary": "Overwrite the existing authoring bundle if one with the same API name already exists locally.",
2531
- "allowNo": false,
2532
- "type": "boolean"
2454
+ "authoring-bundle": {
2455
+ "name": "authoring-bundle",
2456
+ "summary": "API name of the authoring bundle metadata component that contains the agent's Agent Script file.",
2457
+ "hasDynamicHelp": false,
2458
+ "multiple": false,
2459
+ "type": "option"
2533
2460
  }
2534
2461
  },
2535
2462
  "hasDynamicHelp": true,
2536
2463
  "hiddenAliases": [],
2537
- "id": "agent:generate:authoring-bundle",
2464
+ "id": "agent:preview:send",
2538
2465
  "pluginAlias": "@salesforce/plugin-agent",
2539
2466
  "pluginName": "@salesforce/plugin-agent",
2540
2467
  "pluginType": "core",
2541
2468
  "strict": true,
2542
- "summary": "Generate an authoring bundle from an existing agent spec YAML file.",
2469
+ "summary": "Send a message to an existing agent preview session.",
2543
2470
  "enableJsonFlag": true,
2544
2471
  "requiresProject": true,
2472
+ "envVariablesSection": {
2473
+ "header": "ENVIRONMENT VARIABLES",
2474
+ "body": [
2475
+ {
2476
+ "name": "SF_TARGET_ORG",
2477
+ "description": "Username or alias of your default org. Overrides the target-org configuration variable."
2478
+ }
2479
+ ]
2480
+ },
2481
+ "errorCodes": {
2482
+ "header": "ERROR CODES",
2483
+ "body": [
2484
+ {
2485
+ "name": "Succeeded (0)",
2486
+ "description": "Message sent successfully and agent response received."
2487
+ },
2488
+ {
2489
+ "name": "NotFound (2)",
2490
+ "description": "Agent not found, or no preview session exists for this agent."
2491
+ },
2492
+ {
2493
+ "name": "PreviewSendFailed (4)",
2494
+ "description": "Failed to send message or receive response from the preview session."
2495
+ },
2496
+ {
2497
+ "name": "SessionAmbiguous (5)",
2498
+ "description": "Multiple preview sessions found; specify --session-id to choose one."
2499
+ }
2500
+ ]
2501
+ },
2545
2502
  "isESM": true,
2546
2503
  "relativePath": [
2547
2504
  "lib",
2548
2505
  "commands",
2549
2506
  "agent",
2550
- "generate",
2551
- "authoring-bundle.js"
2507
+ "preview",
2508
+ "send.js"
2552
2509
  ],
2553
2510
  "aliasPermutations": [],
2554
2511
  "permutations": [
2555
- "agent:generate:authoring-bundle",
2556
- "generate:agent:authoring-bundle",
2557
- "generate:authoring-bundle:agent",
2558
- "agent:authoring-bundle:generate",
2559
- "authoring-bundle:agent:generate",
2560
- "authoring-bundle:generate:agent"
2512
+ "agent:preview:send",
2513
+ "preview:agent:send",
2514
+ "preview:send:agent",
2515
+ "agent:send:preview",
2516
+ "send:agent:preview",
2517
+ "send:preview:agent"
2561
2518
  ]
2562
2519
  },
2563
- "agent:generate:template": {
2520
+ "agent:preview:sessions": {
2564
2521
  "aliases": [],
2565
2522
  "args": {},
2566
- "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.",
2523
+ "description": "This command lists the agent preview sessions that were started with the \"agent preview start\" command and are still in the local cache. Use this command to discover specific session IDs that you can pass to the \"agent preview send\" or \"agent preview end\" commands with the --session-id flag.\n\nProgrammatic agent preview sessions can be started for both published activated agents and by using an agent's local authoring bundle, which contains its Agent Script file. In this command's output table, the Agent column contains either the API name of the authoring bundle or the published agent, whichever was used when starting the session. In the table, if the same API name has multiple rows with different session IDs, then it means that you previously started multiple preview sessions with the associated agent.",
2567
2524
  "examples": [
2568
- "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"
2525
+ "List all cached agent preview sessions:\n<%= config.bin %> <%= command.id %>"
2569
2526
  ],
2570
2527
  "flags": {
2571
2528
  "json": {
@@ -2582,90 +2539,62 @@
2582
2539
  "hasDynamicHelp": false,
2583
2540
  "multiple": false,
2584
2541
  "type": "option"
2585
- },
2586
- "api-version": {
2587
- "description": "Override the api version used for api requests made by this command",
2588
- "name": "api-version",
2589
- "hasDynamicHelp": false,
2590
- "multiple": false,
2591
- "type": "option"
2592
- },
2593
- "source-org": {
2594
- "char": "s",
2595
- "name": "source-org",
2596
- "noCacheDefault": true,
2597
- "required": true,
2598
- "summary": "Username or alias of the namespaced scratch org that contains the agent which this template is based on.",
2599
- "hasDynamicHelp": true,
2600
- "multiple": false,
2601
- "type": "option"
2602
- },
2603
- "agent-version": {
2604
- "name": "agent-version",
2605
- "required": true,
2606
- "summary": "Version of the agent (BotVersion).",
2607
- "hasDynamicHelp": false,
2608
- "multiple": false,
2609
- "type": "option"
2610
- },
2611
- "agent-file": {
2612
- "char": "f",
2613
- "name": "agent-file",
2614
- "required": true,
2615
- "summary": "Path to an agent (Bot) metadata file.",
2616
- "hasDynamicHelp": false,
2617
- "multiple": false,
2618
- "type": "option"
2619
- },
2620
- "output-dir": {
2621
- "char": "r",
2622
- "name": "output-dir",
2623
- "summary": "Directory where the generated BotTemplate and GenAiPlannerBundle files are saved.",
2624
- "hasDynamicHelp": false,
2625
- "multiple": false,
2626
- "type": "option"
2627
2542
  }
2628
2543
  },
2629
- "hasDynamicHelp": true,
2544
+ "hasDynamicHelp": false,
2630
2545
  "hiddenAliases": [],
2631
- "id": "agent:generate:template",
2546
+ "id": "agent:preview:sessions",
2632
2547
  "pluginAlias": "@salesforce/plugin-agent",
2633
2548
  "pluginName": "@salesforce/plugin-agent",
2634
2549
  "pluginType": "core",
2635
2550
  "strict": true,
2636
- "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.",
2551
+ "summary": "List all known programmatic agent preview sessions.",
2637
2552
  "enableJsonFlag": true,
2638
2553
  "requiresProject": true,
2554
+ "errorCodes": {
2555
+ "header": "ERROR CODES",
2556
+ "body": [
2557
+ {
2558
+ "name": "Succeeded (0)",
2559
+ "description": "Sessions listed successfully (or empty list if no active sessions)."
2560
+ }
2561
+ ]
2562
+ },
2639
2563
  "isESM": true,
2640
2564
  "relativePath": [
2641
2565
  "lib",
2642
2566
  "commands",
2643
2567
  "agent",
2644
- "generate",
2645
- "template.js"
2568
+ "preview",
2569
+ "sessions.js"
2646
2570
  ],
2647
2571
  "aliasPermutations": [],
2648
2572
  "permutations": [
2649
- "agent:generate:template",
2650
- "generate:agent:template",
2651
- "generate:template:agent",
2652
- "agent:template:generate",
2653
- "template:agent:generate",
2654
- "template:generate:agent"
2573
+ "agent:preview:sessions",
2574
+ "preview:agent:sessions",
2575
+ "preview:sessions:agent",
2576
+ "agent:sessions:preview",
2577
+ "sessions:agent:preview",
2578
+ "sessions:preview:agent"
2655
2579
  ]
2656
2580
  },
2657
- "agent:generate:test-spec": {
2581
+ "agent:preview:start": {
2658
2582
  "aliases": [],
2659
2583
  "args": {},
2660
- "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.",
2584
+ "description": "This command outputs a session ID that you then use with the \"agent preview send\" command to send an utterance to the agent. Use the \"agent preview sessions\" command to list all active sessions and the \"agent preview end\" command to end a specific session.\n\nIdentify the agent you want to start previewing with either the --authoring-bundle flag to specify a local authoring bundle's API name or --api-name to specify an activated published agent's API name. To find either API name, navigate to your package directory in your DX project. The API name of an authoring bundle is the same as its directory name under the \"aiAuthoringBundles\" metadata directory. Similarly, the published agent's API name is the same as its directory name under the \"Bots\" metadata directory.\n\nWhen starting a preview session with --authoring-bundle, you must explicitly specify the execution mode using one of these flags:\n\n- --use-live-actions: Executes real Apex classes, flows, and other actions in the org. This surfaces compile and validation errors during preview.\n- --simulate-actions: Uses AI to simulate action execution without calling real implementations.\n\nPublished agents (--api-name) always use live actions. The mode flags are optional and have no effect for published agents.",
2661
2585
  "examples": [
2662
- "Generate an agent test spec YAML file interactively:\n<%= config.bin %> <%= command.id %>",
2663
- "Generate an Agentforce Studio (NGT) test spec YAML file interactively:\n<%= config.bin %> <%= command.id %> --test-runner agentforce-studio",
2664
- "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",
2665
- "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",
2666
- "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"
2586
+ "Start a programmatic agent preview session by specifying an authoring bundle; use simulated actions. Use the org with alias \"my-dev-org\":\n<%= config.bin %> <%= command.id %> --authoring-bundle My_Agent_Bundle --target-org my-dev-org --simulate-actions",
2587
+ "Similar to previous example but use live actions and the default org:\n<%= config.bin %> <%= command.id %> --authoring-bundle My_Agent_Bundle --use-live-actions",
2588
+ "Start a preview session with an activated published agent (always uses live actions):\n<%= config.bin %> <%= command.id %> --api-name My_Published_Agent"
2667
2589
  ],
2668
2590
  "flags": {
2591
+ "json": {
2592
+ "description": "Format output as json.",
2593
+ "helpGroup": "GLOBAL",
2594
+ "name": "json",
2595
+ "allowNo": false,
2596
+ "type": "boolean"
2597
+ },
2669
2598
  "flags-dir": {
2670
2599
  "helpGroup": "GLOBAL",
2671
2600
  "name": "flags-dir",
@@ -2674,66 +2603,137 @@
2674
2603
  "multiple": false,
2675
2604
  "type": "option"
2676
2605
  },
2677
- "from-definition": {
2678
- "char": "d",
2679
- "name": "from-definition",
2680
- "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.",
2606
+ "target-org": {
2607
+ "char": "o",
2608
+ "name": "target-org",
2609
+ "noCacheDefault": true,
2610
+ "required": true,
2611
+ "summary": "Username or alias of the target org. Not required if the `target-org` configuration variable is already set.",
2612
+ "hasDynamicHelp": true,
2613
+ "multiple": false,
2614
+ "type": "option"
2615
+ },
2616
+ "api-version": {
2617
+ "description": "Override the api version used for api requests made by this command",
2618
+ "name": "api-version",
2681
2619
  "hasDynamicHelp": false,
2682
2620
  "multiple": false,
2683
2621
  "type": "option"
2684
2622
  },
2685
- "force-overwrite": {
2686
- "name": "force-overwrite",
2687
- "summary": "Don't prompt for confirmation when overwriting an existing test spec YAML file.",
2623
+ "api-name": {
2624
+ "char": "n",
2625
+ "name": "api-name",
2626
+ "summary": "API name of the activated published agent you want to preview.",
2627
+ "hasDynamicHelp": false,
2628
+ "multiple": false,
2629
+ "type": "option"
2630
+ },
2631
+ "authoring-bundle": {
2632
+ "name": "authoring-bundle",
2633
+ "summary": "API name of the authoring bundle metadata component that contains the agent's Agent Script file.",
2634
+ "hasDynamicHelp": false,
2635
+ "multiple": false,
2636
+ "type": "option"
2637
+ },
2638
+ "use-live-actions": {
2639
+ "exclusive": [
2640
+ "simulate-actions"
2641
+ ],
2642
+ "name": "use-live-actions",
2643
+ "summary": "Execute real actions in the org (Apex classes, flows, etc.). Required with --authoring-bundle.",
2688
2644
  "allowNo": false,
2689
2645
  "type": "boolean"
2690
2646
  },
2691
- "output-file": {
2692
- "char": "f",
2693
- "name": "output-file",
2694
- "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).",
2647
+ "simulate-actions": {
2648
+ "exclusive": [
2649
+ "use-live-actions"
2650
+ ],
2651
+ "name": "simulate-actions",
2652
+ "summary": "Use AI to simulate action execution instead of calling real actions. Required with --authoring-bundle.",
2653
+ "allowNo": false,
2654
+ "type": "boolean"
2655
+ },
2656
+ "context-variables": {
2657
+ "description": "Sets variables on the agent preview session, mirroring what the in-org Agentforce Builder UI does when you override variables before sending a message. Specify this flag multiple times or use comma-separated values. Two namespaces are supported, distinguished by the name shape. Names pass through to the runtime verbatim — the CLI doesn't transform them.\n\nLinked context variables use the \"$Context.\" prefix. These map to externally-provided fields that the runtime resolves (declared in the bundle's globalConfiguration.contextVariables) and are read by live actions and topic-routing expressions via $Context.Name. Example: $Context.MyLinkedVar=some-value.\n\nState variables use the bare developerName, no prefix. These seed mutable agent state declared in agentVersion.stateVariables. Example: MyStateVar=some-value.\n\nBoth namespaces can be mixed in one value. Example: --context-variables '$Context.MyLinkedVar=foo,MyStateVar=bar'.\n\nTips: (1) Quote the whole value in single quotes so $Context isn't shell-expanded. (2) Names are sent verbatim — a bare name is treated as a state variable, not a linked context variable, so live actions that bind via $Context.Name will see null. (3) Type defaults to Text.",
2658
+ "name": "context-variables",
2659
+ "summary": "Session variables for the agent preview session, in the form Name=Value.",
2660
+ "delimiter": ",",
2695
2661
  "hasDynamicHelp": false,
2696
- "multiple": false,
2662
+ "multiple": true,
2697
2663
  "type": "option"
2698
2664
  },
2699
- "test-runner": {
2700
- "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.",
2701
- "name": "test-runner",
2702
- "summary": "Explicitly specify which test runner to use (agentforce-studio or testing-center).",
2665
+ "agent-json": {
2666
+ "dependsOn": [
2667
+ "authoring-bundle"
2668
+ ],
2669
+ "hidden": true,
2670
+ "name": "agent-json",
2671
+ "summary": "Path to a pre-compiled AgentJSON file to use instead of compiling the Agent Script file. Intended for internal use and testing.",
2703
2672
  "hasDynamicHelp": false,
2704
2673
  "multiple": false,
2705
- "options": [
2706
- "agentforce-studio",
2707
- "testing-center"
2708
- ],
2709
2674
  "type": "option"
2710
2675
  }
2711
2676
  },
2712
- "hasDynamicHelp": false,
2677
+ "hasDynamicHelp": true,
2713
2678
  "hiddenAliases": [],
2714
- "id": "agent:generate:test-spec",
2679
+ "id": "agent:preview:start",
2715
2680
  "pluginAlias": "@salesforce/plugin-agent",
2716
2681
  "pluginName": "@salesforce/plugin-agent",
2717
2682
  "pluginType": "core",
2718
2683
  "strict": true,
2719
- "summary": "Generate an agent test spec, which is a YAML file that lists the test cases for testing a specific agent.",
2720
- "enableJsonFlag": false,
2684
+ "summary": "Start a programmatic agent preview session.",
2685
+ "enableJsonFlag": true,
2686
+ "requiresProject": true,
2687
+ "envVariablesSection": {
2688
+ "header": "ENVIRONMENT VARIABLES",
2689
+ "body": [
2690
+ {
2691
+ "name": "SF_TARGET_ORG",
2692
+ "description": "Username or alias of your default org. Overrides the target-org configuration variable."
2693
+ }
2694
+ ]
2695
+ },
2696
+ "errorCodes": {
2697
+ "header": "ERROR CODES",
2698
+ "body": [
2699
+ {
2700
+ "name": "Succeeded (0)",
2701
+ "description": "Preview session started successfully."
2702
+ },
2703
+ {
2704
+ "name": "Failed (1)",
2705
+ "description": "Agent Script compilation failed (syntax errors in the script)."
2706
+ },
2707
+ {
2708
+ "name": "NotFound (2)",
2709
+ "description": "Agent not found, or compilation API returned HTTP 404 (endpoint may not be available in your org or region)."
2710
+ },
2711
+ {
2712
+ "name": "ServerError (3)",
2713
+ "description": "Compilation API returned HTTP 500 (server error during compilation)."
2714
+ },
2715
+ {
2716
+ "name": "PreviewStartFailed (4)",
2717
+ "description": "Preview session failed to start due to API or network errors."
2718
+ }
2719
+ ]
2720
+ },
2721
2721
  "isESM": true,
2722
2722
  "relativePath": [
2723
2723
  "lib",
2724
2724
  "commands",
2725
2725
  "agent",
2726
- "generate",
2727
- "test-spec.js"
2726
+ "preview",
2727
+ "start.js"
2728
2728
  ],
2729
2729
  "aliasPermutations": [],
2730
2730
  "permutations": [
2731
- "agent:generate:test-spec",
2732
- "generate:agent:test-spec",
2733
- "generate:test-spec:agent",
2734
- "agent:test-spec:generate",
2735
- "test-spec:agent:generate",
2736
- "test-spec:generate:agent"
2731
+ "agent:preview:start",
2732
+ "preview:agent:start",
2733
+ "preview:start:agent",
2734
+ "agent:start:preview",
2735
+ "start:agent:preview",
2736
+ "start:preview:agent"
2737
2737
  ]
2738
2738
  },
2739
2739
  "agent:publish:authoring-bundle": {
@@ -4667,5 +4667,5 @@
4667
4667
  ]
4668
4668
  }
4669
4669
  },
4670
- "version": "2.0.1"
4670
+ "version": "2.0.2"
4671
4671
  }