@salesforce/plugin-agent 1.27.7 → 1.28.0

package/oclif.manifest.json

@@ -282,7 +282,7 @@
         "api-name": {
           "char": "n",
           "name": "api-name",
-          "summary": "API name of the published and active agent you want to interact with.",
+          "summary": "API name of the activated published agent you want to interact with.",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
@@ -891,13 +891,14 @@
         "authoring-bundle:publish:agent"
       ]
     },
-    "agent:validate:authoring-bundle": {
+    "agent:preview:end": {
       "aliases": [],
       "args": {},
-      "description": "An authoring bundle is a metadata type (named aiAuthoringBundle) that provides the blueprint for an agent. The metadata type contains two files: the standard metatada XML file and an Agent Script file (extension \".agent\") that fully describes the agent using the Agent Script language.\n\nThis command validates that the Agent Script file in the authoring bundle compiles without errors so that you can later publish the bundle to your org. Use this command while you code the Agent Script file to ensure that it's valid. If the validation fails, the command outputs the list of syntax errors, a brief description of the error, and the location in the Agent Script file where the error occurred.\n\nThis command uses the API name of the authoring bundle. If you don't provide an API name with the --api-name flag, the command searches the current DX project and outputs a list of authoring bundles that it found for you to choose from.",
+      "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, 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.",
       "examples": [
-        "Validate an authoring bundle by being prompted for its API name; use your default org:\n<%= config.bin %> <%= command.id %>",
-        "Validate an authoring bundle with API name MyAuthoringBundle; use the org with alias \"my-dev-org\":\n<%= config.bin %> <%= command.id %> --api-name MyAuthoringBundle --target-org my-dev-org"
+        "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",
+        "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",
+        "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"
       ],
       "flags": {
         "json": {
@@ -932,10 +933,25 @@
           "multiple": false,
           "type": "option"
         },
+        "session-id": {
+          "name": "session-id",
+          "required": false,
+          "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.",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
         "api-name": {
           "char": "n",
           "name": "api-name",
-          "summary": "API name of the authoring bundle you want to validate; if not specified, the command provides a list that you can choose from.",
+          "summary": "API name of the activated published agent you want to preview.",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "authoring-bundle": {
+          "name": "authoring-bundle",
+          "summary": "API name of the authoring bundle metadata component that contains the agent's Agent Script file.",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
@@ -943,36 +959,281 @@
       },
       "hasDynamicHelp": true,
       "hiddenAliases": [],
-      "id": "agent:validate:authoring-bundle",
+      "id": "agent:preview:end",
       "pluginAlias": "@salesforce/plugin-agent",
       "pluginName": "@salesforce/plugin-agent",
       "pluginType": "core",
+      "state": "beta",
       "strict": true,
-      "summary": "Validate an authoring bundle to ensure its Agent Script file compiles successfully and can be used to publish an agent.",
+      "summary": "End an existing programmatic agent preview session and get trace location.",
       "enableJsonFlag": true,
       "requiresProject": true,
-      "FLAGGABLE_PROMPTS": {
+      "isESM": true,
+      "relativePath": [
+        "lib",
+        "commands",
+        "agent",
+        "preview",
+        "end.js"
+      ],
+      "aliasPermutations": [],
+      "permutations": [
+        "agent:preview:end",
+        "preview:agent:end",
+        "preview:end:agent",
+        "agent:end:preview",
+        "end:agent:preview",
+        "end:preview:agent"
+      ]
+    },
+    "agent:preview:send": {
+      "aliases": [],
+      "args": {},
+      "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.",
+      "examples": [
+        "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>",
+        "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",
+        "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"
+      ],
+      "flags": {
+        "json": {
+          "description": "Format output as json.",
+          "helpGroup": "GLOBAL",
+          "name": "json",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "flags-dir": {
+          "helpGroup": "GLOBAL",
+          "name": "flags-dir",
+          "summary": "Import flag values from a directory.",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "target-org": {
+          "char": "o",
+          "name": "target-org",
+          "noCacheDefault": true,
+          "required": true,
+          "summary": "Username or alias of the target org. Not required if the `target-org` configuration variable is already set.",
+          "hasDynamicHelp": true,
+          "multiple": false,
+          "type": "option"
+        },
+        "api-version": {
+          "description": "Override the api version used for api requests made by this command",
+          "name": "api-version",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "session-id": {
+          "name": "session-id",
+          "required": false,
+          "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.",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "utterance": {
+          "char": "u",
+          "name": "utterance",
+          "required": true,
+          "summary": "Utterance to send to the agent, enclosed in double quotes.",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
         "api-name": {
-          "message": "API name of the authoring bundle you want to validate; if not specified, the command provides a list that you can choose from.",
-          "promptMessage": "API name of the authoring bundle to validate"
+          "char": "n",
+          "name": "api-name",
+          "summary": "API name of the activated published agent you want to preview.",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "authoring-bundle": {
+          "name": "authoring-bundle",
+          "summary": "API name of the authoring bundle metadata component that contains the agent's Agent Script file.",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
         }
       },
+      "hasDynamicHelp": true,
+      "hiddenAliases": [],
+      "id": "agent:preview:send",
+      "pluginAlias": "@salesforce/plugin-agent",
+      "pluginName": "@salesforce/plugin-agent",
+      "pluginType": "core",
+      "state": "beta",
+      "strict": true,
+      "summary": "Send a message to an existing agent preview session.",
+      "enableJsonFlag": true,
+      "requiresProject": true,
       "isESM": true,
       "relativePath": [
         "lib",
         "commands",
         "agent",
-        "validate",
-        "authoring-bundle.js"
+        "preview",
+        "send.js"
       ],
       "aliasPermutations": [],
       "permutations": [
-        "agent:validate:authoring-bundle",
-        "validate:agent:authoring-bundle",
-        "validate:authoring-bundle:agent",
-        "agent:authoring-bundle:validate",
-        "authoring-bundle:agent:validate",
-        "authoring-bundle:validate:agent"
+        "agent:preview:send",
+        "preview:agent:send",
+        "preview:send:agent",
+        "agent:send:preview",
+        "send:agent:preview",
+        "send:preview:agent"
+      ]
+    },
+    "agent:preview:sessions": {
+      "aliases": [],
+      "args": {},
+      "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.",
+      "examples": [
+        "List all cached agent preview sessions:\n<%= config.bin %> <%= command.id %>"
+      ],
+      "flags": {
+        "json": {
+          "description": "Format output as json.",
+          "helpGroup": "GLOBAL",
+          "name": "json",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "flags-dir": {
+          "helpGroup": "GLOBAL",
+          "name": "flags-dir",
+          "summary": "Import flag values from a directory.",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "agent:preview:sessions",
+      "pluginAlias": "@salesforce/plugin-agent",
+      "pluginName": "@salesforce/plugin-agent",
+      "pluginType": "core",
+      "state": "beta",
+      "strict": true,
+      "summary": "List all known programmatic agent preview sessions.",
+      "enableJsonFlag": true,
+      "requiresProject": true,
+      "isESM": true,
+      "relativePath": [
+        "lib",
+        "commands",
+        "agent",
+        "preview",
+        "sessions.js"
+      ],
+      "aliasPermutations": [],
+      "permutations": [
+        "agent:preview:sessions",
+        "preview:agent:sessions",
+        "preview:sessions:agent",
+        "agent:sessions:preview",
+        "sessions:agent:preview",
+        "sessions:preview:agent"
+      ]
+    },
+    "agent:preview:start": {
+      "aliases": [],
+      "args": {},
+      "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 using the authoring bundle, which contains the agent's Agent Script file, the preview uses mocked actions by default.  Specify --use-live-actions for live mode, which uses the real Apex classes, flows, etc, in the org for the actions.",
+      "examples": [
+        "Start a programmatic agent preview session by specifying an authoring bundle; uses mocked actions by default. Use the org with alias \"my-dev-org\":\n<%= config.bin %> <%= command.id %> --authoring-bundle My_Agent_Bundle --target-org my-dev-org",
+        "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",
+        "Start a preview session with an activated published agent:\n<%= config.bin %> <%= command.id %> --api-name My_Published_Agent"
+      ],
+      "flags": {
+        "json": {
+          "description": "Format output as json.",
+          "helpGroup": "GLOBAL",
+          "name": "json",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "flags-dir": {
+          "helpGroup": "GLOBAL",
+          "name": "flags-dir",
+          "summary": "Import flag values from a directory.",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "target-org": {
+          "char": "o",
+          "name": "target-org",
+          "noCacheDefault": true,
+          "required": true,
+          "summary": "Username or alias of the target org. Not required if the `target-org` configuration variable is already set.",
+          "hasDynamicHelp": true,
+          "multiple": false,
+          "type": "option"
+        },
+        "api-version": {
+          "description": "Override the api version used for api requests made by this command",
+          "name": "api-version",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "api-name": {
+          "char": "n",
+          "name": "api-name",
+          "summary": "API name of the activated published agent you want to preview.",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "authoring-bundle": {
+          "name": "authoring-bundle",
+          "summary": "API name of the authoring bundle metadata component that contains the agent's Agent Script file.",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "use-live-actions": {
+          "name": "use-live-actions",
+          "summary": "Use real actions in the org; if not specified, preview uses AI to simulate (mock) actions.",
+          "allowNo": false,
+          "type": "boolean"
+        }
+      },
+      "hasDynamicHelp": true,
+      "hiddenAliases": [],
+      "id": "agent:preview:start",
+      "pluginAlias": "@salesforce/plugin-agent",
+      "pluginName": "@salesforce/plugin-agent",
+      "pluginType": "core",
+      "state": "beta",
+      "strict": true,
+      "summary": "Start a programmatic agent preview session.",
+      "enableJsonFlag": true,
+      "requiresProject": true,
+      "isESM": true,
+      "relativePath": [
+        "lib",
+        "commands",
+        "agent",
+        "preview",
+        "start.js"
+      ],
+      "aliasPermutations": [],
+      "permutations": [
+        "agent:preview:start",
+        "preview:agent:start",
+        "preview:start:agent",
+        "agent:start:preview",
+        "start:agent:preview",
+        "start:preview:agent"
       ]
     },
     "agent:test:create": {
@@ -1488,7 +1749,91 @@
         "run:agent:test",
         "run:test:agent"
       ]
+    },
+    "agent:validate:authoring-bundle": {
+      "aliases": [],
+      "args": {},
+      "description": "An authoring bundle is a metadata type (named aiAuthoringBundle) that provides the blueprint for an agent. The metadata type contains two files: the standard metatada XML file and an Agent Script file (extension \".agent\") that fully describes the agent using the Agent Script language.\n\nThis command validates that the Agent Script file in the authoring bundle compiles without errors so that you can later publish the bundle to your org. Use this command while you code the Agent Script file to ensure that it's valid. If the validation fails, the command outputs the list of syntax errors, a brief description of the error, and the location in the Agent Script file where the error occurred.\n\nThis command uses the API name of the authoring bundle. If you don't provide an API name with the --api-name flag, the command searches the current DX project and outputs a list of authoring bundles that it found for you to choose from.",
+      "examples": [
+        "Validate an authoring bundle by being prompted for its API name; use your default org:\n<%= config.bin %> <%= command.id %>",
+        "Validate an authoring bundle with API name MyAuthoringBundle; use the org with alias \"my-dev-org\":\n<%= config.bin %> <%= command.id %> --api-name MyAuthoringBundle --target-org my-dev-org"
+      ],
+      "flags": {
+        "json": {
+          "description": "Format output as json.",
+          "helpGroup": "GLOBAL",
+          "name": "json",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "flags-dir": {
+          "helpGroup": "GLOBAL",
+          "name": "flags-dir",
+          "summary": "Import flag values from a directory.",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "target-org": {
+          "char": "o",
+          "name": "target-org",
+          "noCacheDefault": true,
+          "required": true,
+          "summary": "Username or alias of the target org. Not required if the `target-org` configuration variable is already set.",
+          "hasDynamicHelp": true,
+          "multiple": false,
+          "type": "option"
+        },
+        "api-version": {
+          "description": "Override the api version used for api requests made by this command",
+          "name": "api-version",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "api-name": {
+          "char": "n",
+          "name": "api-name",
+          "summary": "API name of the authoring bundle you want to validate; if not specified, the command provides a list that you can choose from.",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        }
+      },
+      "hasDynamicHelp": true,
+      "hiddenAliases": [],
+      "id": "agent:validate:authoring-bundle",
+      "pluginAlias": "@salesforce/plugin-agent",
+      "pluginName": "@salesforce/plugin-agent",
+      "pluginType": "core",
+      "strict": true,
+      "summary": "Validate an authoring bundle to ensure its Agent Script file compiles successfully and can be used to publish an agent.",
+      "enableJsonFlag": true,
+      "requiresProject": true,
+      "FLAGGABLE_PROMPTS": {
+        "api-name": {
+          "message": "API name of the authoring bundle you want to validate; if not specified, the command provides a list that you can choose from.",
+          "promptMessage": "API name of the authoring bundle to validate"
+        }
+      },
+      "isESM": true,
+      "relativePath": [
+        "lib",
+        "commands",
+        "agent",
+        "validate",
+        "authoring-bundle.js"
+      ],
+      "aliasPermutations": [],
+      "permutations": [
+        "agent:validate:authoring-bundle",
+        "validate:agent:authoring-bundle",
+        "validate:authoring-bundle:agent",
+        "agent:authoring-bundle:validate",
+        "authoring-bundle:agent:validate",
+        "authoring-bundle:validate:agent"
+      ]
     }
   },
-  "version": "1.27.7"
+  "version": "1.28.0"
 }

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@salesforce/plugin-agent",
     "description": "Commands to interact with Salesforce agents",
-    "version": "1.27.7",
+    "version": "1.28.0",
     "author": "Salesforce",
     "bugs": "https://github.com/forcedotcom/cli/issues",
     "enableO11y": true,
@@ -239,7 +239,7 @@
     "exports": "./lib/index.js",
     "type": "module",
     "sfdx": {
-        "publicKeyUrl": "https://developer.salesforce.com/media/salesforce-cli/security/@salesforce/plugin-agent/1.27.7.crt",
-        "signatureUrl": "https://developer.salesforce.com/media/salesforce-cli/security/@salesforce/plugin-agent/1.27.7.sig"
+        "publicKeyUrl": "https://developer.salesforce.com/media/salesforce-cli/security/@salesforce/plugin-agent/1.28.0.crt",
+        "signatureUrl": "https://developer.salesforce.com/media/salesforce-cli/security/@salesforce/plugin-agent/1.28.0.sig"
     }
 }

package/schemas/agent-preview-end.json

@@ -0,0 +1,19 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$ref": "#/definitions/AgentPreviewEndResult",
+  "definitions": {
+    "AgentPreviewEndResult": {
+      "type": "object",
+      "properties": {
+        "sessionId": {
+          "type": "string"
+        },
+        "tracesPath": {
+          "type": "string"
+        }
+      },
+      "required": ["sessionId", "tracesPath"],
+      "additionalProperties": false
+    }
+  }
+}

package/schemas/agent-preview-send.json

@@ -0,0 +1,28 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$ref": "#/definitions/AgentPreviewSendResult",
+  "definitions": {
+    "AgentPreviewSendResult": {
+      "type": "object",
+      "properties": {
+        "messages": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "message": {
+                "type": "string"
+              },
+              "role": {
+                "type": "string"
+              }
+            },
+            "additionalProperties": false
+          }
+        }
+      },
+      "required": ["messages"],
+      "additionalProperties": false
+    }
+  }
+}

package/schemas/agent-preview-sessions.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$ref": "#/definitions/AgentPreviewSessionsResult",
+  "definitions": {
+    "AgentPreviewSessionsResult": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "agentId": {
+            "type": "string"
+          },
+          "displayName": {
+            "type": "string"
+          },
+          "sessionId": {
+            "type": "string"
+          }
+        },
+        "required": ["agentId", "sessionId"],
+        "additionalProperties": false
+      }
+    }
+  }
+}

package/schemas/agent-preview-start.json

@@ -0,0 +1,16 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$ref": "#/definitions/AgentPreviewStartResult",
+  "definitions": {
+    "AgentPreviewStartResult": {
+      "type": "object",
+      "properties": {
+        "sessionId": {
+          "type": "string"
+        }
+      },
+      "required": ["sessionId"],
+      "additionalProperties": false
+    }
+  }
+}