From 2a2d74ab453d98b77c55f365e80809542e38d08a Mon Sep 17 00:00:00 2001 From: Juliet Shackell <63259011+jshackell-sfdc@users.noreply.github.com> Date: Mon, 9 Feb 2026 13:20:18 -0800 Subject: [PATCH 01/11] fix: teeny edit to existing "agent preview" messages file --- messages/agent.preview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/messages/agent.preview.md b/messages/agent.preview.md index 0e62bfae..d4d38ea8 100644 --- a/messages/agent.preview.md +++ b/messages/agent.preview.md @@ -21,7 +21,7 @@ When the session concludes, the command asks if you want to save the API respons # flags.api-name.summary -API name of the published and active agent you want to interact with. +API name of the activated published agent you want to interact with. # flags.authoring-bundle.summary From 90c924e977613d5be9697e72734d7cccd174a9de Mon Sep 17 00:00:00 2001 From: Juliet Shackell <63259011+jshackell-sfdc@users.noreply.github.com> Date: Mon, 9 Feb 2026 13:22:43 -0800 Subject: [PATCH 02/11] fix: edit --- messages/agent.preview.end.md | 28 +++++++++++++++------------- 1 file changed, 15 insertions(+), 13 deletions(-) diff --git a/messages/agent.preview.end.md b/messages/agent.preview.end.md index ad25725d..967d1230 100644 --- a/messages/agent.preview.end.md +++ b/messages/agent.preview.end.md @@ -1,30 +1,32 @@ # summary -End a preview session and get trace location (beta). +End an existing programmatic agent preview session and get trace location. # description -End an existing preview session and print the local path where session traces are stored. Use the session ID returned by "agent preview start". Specify the same agent with --api-name or --authoring-bundle as used when starting the session; one is required. +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. + +The original "agent preview start" command outputs a session ID which you then use with this command. Alternatively, you can use the --authoring-bundle or --api-name flags to specify the API name of the authoring bundle, or the agent itself, as long as the agent has only one active preview session. If it has multiple sessions, then you must instead use --session-id to identify the exact one you want to end. # flags.session-id.summary -Session ID from "agent preview start". Omit when the agent has exactly one active session. +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. # flags.api-name.summary -API name or ID of the published agent. +API name of the activated published agent you want to preview. # flags.authoring-bundle.summary -API name of the authoring bundle (Agent Script). +API name of the authoring bundle metadata component that contains the agent's Agent Script file. # error.noSession -No preview session found. Run "sf agent preview start" first. +No agent preview session found. Run "sf agent preview start" to start a new agent preview session. # error.multipleSessions -Multiple preview sessions found for this agent. Specify --session-id. Sessions: %s +Multiple preview sessions found for this agent. Use the --session-id flag to identify a specific session. Sessions: %s # output.tracesPath @@ -32,14 +34,14 @@ Session traces: %s # examples -- End the single active preview session for a simulated agent: +- End an agent preview session by specifying its session ID; use the default org: - <%= config.bin %> <%= command.id %> --target-org my-dev-org --authoring-bundle My_Local + <%= config.bin %> <%= command.id %> --session-id -- End the single active preview session for a published agent: +- End an agent preview session using the API name of the published agent; you get an error if the agent has more than one active session. Use the org with alias "my-dev-org": -<%= config.bin %> <%= command.id %> --target-org my-dev-org --api-name My_Published_Agent + <%= config.bin %> <%= command.id %> --api-name My_Published_Agent --target-org my-dev-org -- End a specific session when multiple exist: +- End an agent preview session using its authoring bundle API name; you get an error if the agent has more than one active session. - <%= config.bin %> <%= command.id %> --session-id --target-org my-dev-org + <%= config.bin %> <%= command.id %> --authoring-bundle My_Local_Agent From 47040f0bfd74bdcc6c805765af67f5e70987f439 Mon Sep 17 00:00:00 2001 From: Juliet Shackell <63259011+jshackell-sfdc@users.noreply.github.com> Date: Mon, 9 Feb 2026 13:23:36 -0800 Subject: [PATCH 03/11] Update agent preview send command documentation --- messages/agent.preview.send.md | 30 ++++++++++++++++-------------- 1 file changed, 16 insertions(+), 14 deletions(-) diff --git a/messages/agent.preview.send.md b/messages/agent.preview.send.md index 187d4fca..1ca76a64 100644 --- a/messages/agent.preview.send.md +++ b/messages/agent.preview.send.md @@ -1,45 +1,47 @@ # summary -Send a message in a preview session (beta). +Send a message to an existing agent preview session. # description -Send an utterance to an existing preview session and get the agent response. Use the session ID returned by "agent preview start". Specify the same agent with --api-name or --authoring-bundle as used when starting the session; one is required. +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. + +The original "agent preview start" command outputs a session ID which you then use with this command. Alternatively, you can use the --authoring-bundle or --api-name flags to specify the API name of the authoring bundle, or the agent itself, as long as the agent has only one active preview session. If it has multiple sessions, then you must instead use --session-id to identify the exact one you want to send a message to. # flags.session-id.summary -Session ID from "agent preview start". Omit when the agent has exactly one active session. +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. # flags.utterance.summary -Utterance to send to the agent. +Utterance to send to the agent, enclosed in double quotes. # flags.api-name.summary -API name or ID of the published agent. +API name of the activated published agent you want to preview. # flags.authoring-bundle.summary -API name of the authoring bundle (Agent Script). +API name of the authoring bundle metadata component that contains the agent's Agent Script file. # error.noSession -No preview session found. Run "sf agent preview start" first. +No agent preview session found. Run "sf agent preview start" to start a new agent preview session. # error.multipleSessions -Multiple preview sessions found for this agent. Specify --session-id. Sessions: %s +Multiple preview sessions found for this agent. Use the --session-id flag to identify a specific session. Sessions: %s # examples -- Send a message to a simulated Agent: +- Send a message to an agent identified by its session ID; use the default org: - <%= config.bin %> <%= command.id %> --utterance "What can you help me with?" --authoring-bundle My_Agent + <%= config.bin %> <%= command.id %> --utterance "What can you help me with?" --session-id -Send a message to a published Agent: +- Send a message to an activated published agent using its API name; you get an error if the agent has more than one active session. Use the org with alias "my-dev-org": -<%= config.bin %> <%= command.id %> --utterance "What can you help me with?" --api-name My_Published_Agent + <%= config.bin %> <%= command.id %> --utterance "What can you help me with?" --api-name My_Published_Agent --target-org my-dev-org -- Send to a specific session when multiple exist: +- 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: - <%= config.bin %> <%= command.id %> --session-id --utterance "What can you help me with?" --target-org my-dev-org + <%= config.bin %> <%= command.id %> --utterance "what can you help me with?" --authoring-bundle My_Local_Agent From d5b27f581ba45a83ffe460cff872bfb37dea1b31 Mon Sep 17 00:00:00 2001 From: Juliet Shackell <63259011+jshackell-sfdc@users.noreply.github.com> Date: Mon, 9 Feb 2026 13:24:59 -0800 Subject: [PATCH 04/11] Clarify agent preview sessions documentation Updated documentation to clarify that the command lists all known programmatic agent preview sessions and provides more details on usage. --- messages/agent.preview.sessions.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/messages/agent.preview.sessions.md b/messages/agent.preview.sessions.md index ac064d1f..8a79790a 100644 --- a/messages/agent.preview.sessions.md +++ b/messages/agent.preview.sessions.md @@ -1,14 +1,16 @@ # summary -List cached preview sessions (beta). +List all known programmatic agent preview sessions. # description -List preview sessions that were started with "agent preview start" and are still in the cache. Use this to see which sessions exist so you can end them with "agent preview end" (e.g. to clean up or resolve "multiple sessions" when using send without --session-id). Agent ID is the authoring bundle name for Agent Script agents, or the agent ID for published agents. +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. + +Programmatic agent preview sessions can be started for 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 published agent, whichever was used when starting the session. # output.empty -No cached preview sessions found. +No cached agent preview sessions found. # output.tableHeader.agent @@ -20,6 +22,6 @@ Session ID # examples -- List all cached preview sessions: +- List all cached agent preview sessions: - <%= config.bin %> <%= command.id %> + <%= config.bin %> <%= command.id %> From 5f929dbbe9907ebcbffb1b0aa9ac1b095ac6d471 Mon Sep 17 00:00:00 2001 From: Juliet Shackell <63259011+jshackell-sfdc@users.noreply.github.com> Date: Mon, 9 Feb 2026 13:25:53 -0800 Subject: [PATCH 05/11] Revise agent preview session documentation Updated the documentation for starting a programmatic agent preview session, clarifying the use of flags and examples. --- messages/agent.preview.start.md | 24 +++++++++++++----------- 1 file changed, 13 insertions(+), 11 deletions(-) diff --git a/messages/agent.preview.start.md b/messages/agent.preview.start.md index 4a70b001..a6f08789 100644 --- a/messages/agent.preview.start.md +++ b/messages/agent.preview.start.md @@ -1,22 +1,24 @@ # summary -Start a programmatic preview session (beta). +Start a programmatic agent preview session. # description -Start an agent preview session and get a session ID. Use the session ID with "agent preview send" and "agent preview end". Specify the agent with --api-name (published agent) or --authoring-bundle (Agent Script); one is required. Use --use-live-actions for live mode; otherwise preview uses mock (simulated) actions. +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. When 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. # flags.api-name.summary -API name or ID of the published agent. +API name of the activated published agent you want to preview. # flags.authoring-bundle.summary -API name of the authoring bundle (Agent Script) to preview. +API name of the authoring bundle metadata component that contains the agent's Agent Script file. # flags.use-live-actions.summary -Use real actions in the org; if not specified, preview uses mock (simulated) actions. +Use real actions in the org; if not specified, preview uses AI to simulate (mock) actions. # output.sessionId @@ -24,14 +26,14 @@ Session ID: %s # examples -- Start a preview session with an authoring bundle and use mock actions: +- Start a programmatic agent preview session by specifying an authoring bundle; uses mocked actions by default. Use the org with alias "my-dev-org": - <%= config.bin %> <%= command.id %> --authoring-bundle My_Agent_Bundle --target-org my-dev-org + <%= config.bin %> <%= command.id %> --authoring-bundle My_Agent_Bundle --target-org my-dev-org -- Start a preview session with an authoring bundle and use real actions: +- Similar to previous example but use live actions and the default org: - <%= config.bin %> <%= command.id %> --authoring-bundle My_Agent_Bundle --use-live-actions --target-org my-dev-org + <%= config.bin %> <%= command.id %> --authoring-bundle My_Agent_Bundle --use-live-actions -- Start a preview session with a published agent: +- Start a preview session with an activated published agent: - <%= config.bin %> <%= command.id %> --api-name My_Published_Agent + <%= config.bin %> <%= command.id %> --api-name My_Published_Agent From c1e047f2eacc55baa42ef9591ebd9fbd577aa74c Mon Sep 17 00:00:00 2001 From: Juliet Shackell <63259011+jshackell-sfdc@users.noreply.github.com> Date: Mon, 9 Feb 2026 13:46:02 -0800 Subject: [PATCH 06/11] Update agent preview sessions documentation Clarified the description of programmatic agent preview sessions and their output. --- messages/agent.preview.sessions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/messages/agent.preview.sessions.md b/messages/agent.preview.sessions.md index 8a79790a..27dc69c8 100644 --- a/messages/agent.preview.sessions.md +++ b/messages/agent.preview.sessions.md @@ -6,7 +6,7 @@ List all known programmatic agent preview sessions. 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. -Programmatic agent preview sessions can be started for 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 published agent, whichever was used when starting the session. +Programmatic 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. # output.empty From 0d8f5b9af69ef37bfd80f811607674bfbdbf579e Mon Sep 17 00:00:00 2001 From: Juliet Shackell <63259011+jshackell-sfdc@users.noreply.github.com> Date: Mon, 9 Feb 2026 14:11:56 -0800 Subject: [PATCH 07/11] Clarify usage of session ID and API name flags --- messages/agent.preview.end.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/messages/agent.preview.end.md b/messages/agent.preview.end.md index 967d1230..8de9e790 100644 --- a/messages/agent.preview.end.md +++ b/messages/agent.preview.end.md @@ -6,7 +6,7 @@ End an existing programmatic agent preview session and get trace location. 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. -The original "agent preview start" command outputs a session ID which you then use with this command. Alternatively, you can use the --authoring-bundle or --api-name flags to specify the API name of the authoring bundle, or the agent itself, as long as the agent has only one active preview session. If it has multiple sessions, then you must instead use --session-id to identify the exact one you want to end. +The original "agent preview start" command outputs a session ID which you then use with the --session-id flag of this command. You don't have to specify the --session-id flag if an agent has only one active preview session. You must also specify 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. # flags.session-id.summary @@ -14,7 +14,7 @@ Session ID outputted by "agent preview start". Not required when the agent has e # flags.api-name.summary -API name of the activated published agent you want to preview. +API name of the activated published agent you want to preview. # flags.authoring-bundle.summary @@ -34,11 +34,11 @@ Session traces: %s # examples -- End an agent preview session by specifying its session ID; use the default org: +- End an agent preview session by specifying its session ID and the API name of the published agent; use the default org: - <%= config.bin %> <%= command.id %> --session-id + <%= config.bin %> <%= command.id %> --session-id --api-name My_Published_Agent -- End an agent preview session using the API name of the published agent; you get an error if the agent has more than one active session. Use the org with alias "my-dev-org": +- 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": <%= config.bin %> <%= command.id %> --api-name My_Published_Agent --target-org my-dev-org From a15af70575f84358d773588d132057cd9b805530 Mon Sep 17 00:00:00 2001 From: Juliet Shackell <63259011+jshackell-sfdc@users.noreply.github.com> Date: Mon, 9 Feb 2026 14:16:04 -0800 Subject: [PATCH 08/11] Clarify agent message sending command usage Updated command usage instructions for sending messages to agents, clarifying the use of session ID and API name flags. --- messages/agent.preview.send.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/messages/agent.preview.send.md b/messages/agent.preview.send.md index 1ca76a64..428ce765 100644 --- a/messages/agent.preview.send.md +++ b/messages/agent.preview.send.md @@ -6,7 +6,7 @@ Send a message to an existing agent preview session. 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. -The original "agent preview start" command outputs a session ID which you then use with this command. Alternatively, you can use the --authoring-bundle or --api-name flags to specify the API name of the authoring bundle, or the agent itself, as long as the agent has only one active preview session. If it has multiple sessions, then you must instead use --session-id to identify the exact one you want to send a message to. +The 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. # flags.session-id.summary @@ -34,11 +34,11 @@ Multiple preview sessions found for this agent. Use the --session-id flag to ide # examples -- Send a message to an agent identified by its session ID; use the default org: +- Send a message to an activated published agent using its API name and session ID; use the default org: - <%= config.bin %> <%= command.id %> --utterance "What can you help me with?" --session-id + <%= config.bin %> <%= command.id %> --utterance "What can you help me with?" --api-name My_Published_Agent --session-id -- Send a message to an activated published agent using its API name; you get an error if the agent has more than one active session. Use the org with alias "my-dev-org": +- 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": <%= config.bin %> <%= command.id %> --utterance "What can you help me with?" --api-name My_Published_Agent --target-org my-dev-org From 2a8866d80006b5138836c594402fd0ae0494ec79 Mon Sep 17 00:00:00 2001 From: Juliet Shackell <63259011+jshackell-sfdc@users.noreply.github.com> Date: Mon, 9 Feb 2026 14:16:57 -0800 Subject: [PATCH 09/11] Fix wording for session ID usage in agent preview end --- messages/agent.preview.end.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/messages/agent.preview.end.md b/messages/agent.preview.end.md index 8de9e790..79cd7e74 100644 --- a/messages/agent.preview.end.md +++ b/messages/agent.preview.end.md @@ -6,7 +6,7 @@ End an existing programmatic agent preview session and get trace location. 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. -The original "agent preview start" command outputs a session ID which you then use with the --session-id flag of this command. You don't have to specify the --session-id flag if an agent has only one active preview session. You must also specify 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. +The 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. # flags.session-id.summary From 8fffc2e7daf3b90149858eb3597a680cf63dcd8f Mon Sep 17 00:00:00 2001 From: Juliet Shackell <63259011+jshackell-sfdc@users.noreply.github.com> Date: Mon, 9 Feb 2026 14:18:57 -0800 Subject: [PATCH 10/11] Enhance agent preview session instructions Clarify instructions for identifying agent API names and using live actions. --- messages/agent.preview.start.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/messages/agent.preview.start.md b/messages/agent.preview.start.md index a6f08789..3d840163 100644 --- a/messages/agent.preview.start.md +++ b/messages/agent.preview.start.md @@ -6,7 +6,9 @@ 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. When 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. +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 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. # flags.api-name.summary From 4dd5e0c6e3832b9e59e1d9e6e396b820e0709d02 Mon Sep 17 00:00:00 2001 From: Juliet Shackell <63259011+jshackell-sfdc@users.noreply.github.com> Date: Mon, 9 Feb 2026 14:22:04 -0800 Subject: [PATCH 11/11] Clarify language in agent preview session instructions --- messages/agent.preview.end.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/messages/agent.preview.end.md b/messages/agent.preview.end.md index 79cd7e74..09a4d2f5 100644 --- a/messages/agent.preview.end.md +++ b/messages/agent.preview.end.md @@ -34,14 +34,14 @@ Session traces: %s # examples -- End an agent preview session by specifying its session ID and the API name of the published agent; use the default org: +- End a preview session of a published agent by specifying its session ID and API name ; use the default org: <%= config.bin %> <%= command.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 agent has more than one active session. Use the org with alias "my-dev-org": +- 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": <%= config.bin %> <%= command.id %> --api-name My_Published_Agent --target-org my-dev-org -- End an agent preview session using its authoring bundle API name; you get an error if the agent has more than one active session. +- 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. <%= config.bin %> <%= command.id %> --authoring-bundle My_Local_Agent