agent preview start
Start a programmatic agent preview session.
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.
Identify 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.
When starting a preview session with –authoring-bundle, you must explicitly specify the execution mode using one of these flags:
- --use-live-actions: Executes real Apex classes, flows, and other actions in the org. This surfaces compile and validation errors during preview.
- --simulate-actions: Uses AI to simulate action execution without calling real implementations.
Published agents (–api-name) always use live actions. The mode flags are optional and have no effect for published agents.
| Flag Name (Long) | Flag Name (Short) | Description |
|---|---|---|
‑‑api‑name | ‑n | Type: Value API name of the activated published agent you want to preview. |
‑‑api‑version | N/A | Type: Value Override the api version used for api requests made by this command |
‑‑authoring‑bundle | N/A | Type: Value API name of the authoring bundle metadata component that contains the agent’s Agent Script file. |
‑‑flags‑dir | N/A | Type: Value Import flag values from a directory. |
‑‑json | N/A | Type: Boolean Format output as json. |
‑‑simulate‑actions | N/A | Type: Boolean Use AI to simulate action execution instead of calling real actions. Required with –authoring-bundle. |
‑‑target‑org | ‑o | Type: Value Required Username or alias of the target org. Not required if the target-org configuration variable is already set. |
‑‑use‑live‑actions | N/A | Type: Boolean Execute real actions in the org (Apex classes, flows, etc.). Required with –authoring-bundle. |
Start a programmatic agent preview session by specifying an authoring bundle; use simulated actions. Use the org with alias “my-dev-org”:
Similar to previous example but use live actions and the default org:
Start a preview session with an activated published agent (always uses live actions):