https://github.com/salesforcecli/plugin-agent
Commands to interact with Salesforce agents
https://github.com/salesforcecli/plugin-agent
Last synced: 18 days ago
JSON representation
Commands to interact with Salesforce agents
- Host: GitHub
- URL: https://github.com/salesforcecli/plugin-agent
- Owner: salesforcecli
- License: apache-2.0
- Created: 2024-10-24T03:59:18.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2026-05-24T04:05:42.000Z (28 days ago)
- Last Synced: 2026-05-24T06:20:16.811Z (27 days ago)
- Language: TypeScript
- Size: 4.44 MB
- Stars: 9
- Watchers: 3
- Forks: 6
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.txt
- Code of conduct: CODE_OF_CONDUCT.md
- Codeowners: CODEOWNERS
- Security: SECURITY.md
Awesome Lists containing this project
README
# plugin-agent
[](https://www.npmjs.com/package/@salesforce/plugin-agent) [](https://npmjs.org/package/@salesforce/plugin-agent) [](https://opensource.org/license/apache-2-0)
## Install
```bash
sf plugins install @salesforce/plugin-agent@x.y.z
```
## Contributing
1. Please read our [Code of Conduct](CODE_OF_CONDUCT.md)
2. Create a new issue before starting your project so that we can keep track of
what you are trying to add/fix. That way, we can also offer suggestions or
let you know if there is already an effort in progress.
3. Fork this repository.
4. [Build the plugin locally](#build)
5. Create a _topic_ branch in your fork. Note, this step is recommended but technically not required if contributing using a fork.
6. Edit the code in your fork.
7. Write appropriate tests for your changes. Try to achieve at least 95% code coverage on any new code. No pull request will be accepted without unit tests.
8. Sign CLA (see [CLA](#cla) below).
9. Send us a pull request when you are done. We'll review your code, suggest any needed changes, and merge it in.
### CLA
External contributors will be required to sign a Contributor's License
Agreement. You can do so by going to https://cla.salesforce.com/sign-cla.
### Build
To build the plugin locally, make sure to have yarn installed and run the following commands:
```bash
# Clone the repository
git clone git@github.com:salesforcecli/plugin-agent
# Install the dependencies and compile
yarn && yarn build
```
To use your plugin, run using the local `./bin/dev.js` or `./bin/dev.cmd` file.
```bash
# Run using local run file.
./bin/dev.js agent
```
There should be no differences when running via the Salesforce CLI or using the local run file. However, it can be useful to link the plugin to do some additional testing or run your commands from anywhere on your machine.
```bash
# Link your plugin to the sf cli
sf plugins link .
# To verify
sf plugins
```
## Commands
- [`sf agent activate`](#sf-agent-activate)
- [`sf agent adl create`](#sf-agent-adl-create)
- [`sf agent adl delete`](#sf-agent-adl-delete)
- [`sf agent adl file add`](#sf-agent-adl-file-add)
- [`sf agent adl file delete`](#sf-agent-adl-file-delete)
- [`sf agent adl file list`](#sf-agent-adl-file-list)
- [`sf agent adl get`](#sf-agent-adl-get)
- [`sf agent adl list`](#sf-agent-adl-list)
- [`sf agent adl status`](#sf-agent-adl-status)
- [`sf agent adl update`](#sf-agent-adl-update)
- [`sf agent adl upload`](#sf-agent-adl-upload)
- [`sf agent create`](#sf-agent-create)
- [`sf agent deactivate`](#sf-agent-deactivate)
- [`sf agent generate agent-spec`](#sf-agent-generate-agent-spec)
- [`sf agent generate authoring-bundle`](#sf-agent-generate-authoring-bundle)
- [`sf agent generate template`](#sf-agent-generate-template)
- [`sf agent generate test-spec`](#sf-agent-generate-test-spec)
- [`sf agent preview`](#sf-agent-preview)
- [`sf agent preview end`](#sf-agent-preview-end)
- [`sf agent preview send`](#sf-agent-preview-send)
- [`sf agent preview sessions`](#sf-agent-preview-sessions)
- [`sf agent preview start`](#sf-agent-preview-start)
- [`sf agent publish authoring-bundle`](#sf-agent-publish-authoring-bundle)
- [`sf agent test create`](#sf-agent-test-create)
- [`sf agent test list`](#sf-agent-test-list)
- [`sf agent test results`](#sf-agent-test-results)
- [`sf agent test resume`](#sf-agent-test-resume)
- [`sf agent test run`](#sf-agent-test-run)
- [`sf agent test run-eval`](#sf-agent-test-run-eval)
- [`sf agent trace delete`](#sf-agent-trace-delete)
- [`sf agent trace list`](#sf-agent-trace-list)
- [`sf agent trace read`](#sf-agent-trace-read)
- [`sf agent validate authoring-bundle`](#sf-agent-validate-authoring-bundle)
## `sf agent activate`
Activate an agent in an org.
```
USAGE
$ sf agent activate -o [--json] [--flags-dir ] [--api-version ] [-n ] [--version
]
FLAGS
-n, --api-name= API name of the agent to activate; if not specified, the command provides a list that you
choose from.
-o, --target-org= (required) Username or alias of the target org. Not required if the `target-org`
configuration variable is already set.
--api-version= Override the api version used for api requests made by this command
--version= Version number of the agent to activate; if not specified, the command provides a list that
you choose from.
GLOBAL FLAGS
--flags-dir= Import flag values from a directory.
--json Format output as json.
DESCRIPTION
Activate an agent in an org.
Activating an agent makes it immediately available to your users. A published agent must be active before you can
preview it with the "agent preview" CLI command or VS Code. Agents can have multiple versions; only one version can be
active at a time.
If you run the command without the --api-name or --version flags, the command provides a list of agent API names and
versions for you to choose from. Use the flags to specify the exact agent and version without being prompted. If you
use the --json flag and not --version, then the latest agent version is automatically activated.
The value of the --version flag is always a number, corresponding to the "vX" part of the "BotVersion" metadata in
your project. For example, if you have a force-app/main/default/bots/My_Agent/v4.botVersion-meta.xml file in your
project, then you activate this version with the "--version 4" flag.
EXAMPLES
Activate an agent in your default target org by being prompted for both its API name and version:
$ sf agent activate
Activate version 2 of an agent with API name Resort_Manager in the org with alias "my-org":
$ sf agent activate --api-name Resort_Manager --version 2 --target-org my-org
```
_See code: [src/commands/agent/activate.ts](https://github.com/salesforcecli/plugin-agent/blob/1.42.0/src/commands/agent/activate.ts)_
## `sf agent adl create`
Create an Agentforce Data Library.
```
USAGE
$ sf agent adl create -o -n --developer-name --source-type sfdrive|knowledge|retriever
[--json] [--flags-dir ] [--api-version ] [--description ] [--index-mode basic|enhanced]
[--retriever-id ] [--primary-index-field1 ] [--primary-index-field2 ]
FLAGS
-n, --name= (required) Display name for the data library (max 80 characters).
-o, --target-org= (required) Username or alias of the target org. Not required if the `target-org`
configuration variable is already set.
--api-version= Override the api version used for api requests made by this command
--description= Description of the data library (max 255 characters).
--developer-name= (required) API name for the data library (max 80 characters, alphanumeric and
underscores only, must start with a letter).
--index-mode= Index mode for SFDRIVE libraries: basic or enhanced.
--primary-index-field1= Primary index field 1 for KNOWLEDGE libraries (required, immutable after
creation).
--primary-index-field2= Primary index field 2 for KNOWLEDGE libraries (required, immutable after
creation).
--retriever-id= ID of an active Custom Retriever (required for RETRIEVER source type; retriever
must be active).
--source-type= (required) Type of grounding source: sfdrive (file upload), knowledge (Salesforce
Knowledge articles), or retriever (existing active Custom Retriever).
GLOBAL FLAGS
--flags-dir= Import flag values from a directory.
--json Format output as json.
DESCRIPTION
Create an Agentforce Data Library.
Creates a new data library in the target org. The --source-type flag determines the type of library: SFDRIVE (file
upload), KNOWLEDGE (Salesforce Knowledge articles), or RETRIEVER (existing active Custom Retriever).
EXAMPLES
Create an SFDRIVE library:
$ sf agent adl create --target-org myOrg --name "My Docs" --developer-name My_Docs --source-type sfdrive
Create a KNOWLEDGE library with index fields:
$ sf agent adl create --target-org myOrg --name "KB Library" --developer-name KB_Library --source-type knowledge \
--primary-index-field1 Title --primary-index-field2 Summary
Create a RETRIEVER library:
$ sf agent adl create --target-org myOrg --name "Existing Retriever" --developer-name Existing_Retriever \
--source-type retriever --retriever-id 0ppXX0000000001
```
_See code: [src/commands/agent/adl/create.ts](https://github.com/salesforcecli/plugin-agent/blob/1.42.0/src/commands/agent/adl/create.ts)_
## `sf agent adl delete`
Delete an Agentforce Data Library.
```
USAGE
$ sf agent adl delete -o -i [--json] [--flags-dir ] [--api-version ]
FLAGS
-i, --library-id= (required) Agentforce Data Library ID (18-char Salesforce ID with prefix 1JD).
-o, --target-org= (required) Username or alias of the target org. Not required if the `target-org`
configuration variable is already set.
--api-version= Override the api version used for api requests made by this command
GLOBAL FLAGS
--flags-dir= Import flag values from a directory.
--json Format output as json.
DESCRIPTION
Delete an Agentforce Data Library.
Permanently deletes a data library and all associated files and indexing data.
EXAMPLES
Delete a data library:
$ sf agent adl delete --library-id 1JDSG000007IbWX4A0 --target-org myOrg
```
_See code: [src/commands/agent/adl/delete.ts](https://github.com/salesforcecli/plugin-agent/blob/1.42.0/src/commands/agent/adl/delete.ts)_
## `sf agent adl file add`
Add files to an existing Agentforce Data Library.
```
USAGE
$ sf agent adl file add -o -i -f [--json] [--flags-dir ] [--api-version ]
FLAGS
-f, --file= (required) Path to the file to add to the library.
-i, --library-id= (required) Agentforce Data Library ID (18-char Salesforce ID with prefix 1JD).
-o, --target-org= (required) Username or alias of the target org. Not required if the `target-org`
configuration variable is already set.
--api-version= Override the api version used for api requests made by this command
GLOBAL FLAGS
--flags-dir= Import flag values from a directory.
--json Format output as json.
DESCRIPTION
Add files to an existing Agentforce Data Library.
Adds one or more files to an existing SFDRIVE data library and triggers SearchIndex re-hydration. This is the day-2
operation for adding files to an already-provisioned library.
Constraints: at least 1 file required, no duplicate file names in a batch, maximum 1000 files per library.
EXAMPLES
Add a file to an existing library:
$ sf agent adl file add --library-id 1JDSG000007IbWX4A0 --file ./docs/new-guide.pdf --target-org myOrg
```
_See code: [src/commands/agent/adl/file/add.ts](https://github.com/salesforcecli/plugin-agent/blob/1.42.0/src/commands/agent/adl/file/add.ts)_
## `sf agent adl file delete`
Delete a file from an Agentforce Data Library.
```
USAGE
$ sf agent adl file delete -o -i --file-id [--json] [--flags-dir ] [--api-version
]
FLAGS
-i, --library-id= (required) Agentforce Data Library ID (18-char Salesforce ID with prefix 1JD).
-o, --target-org= (required) Username or alias of the target org. Not required if the `target-org`
configuration variable is already set.
--api-version= Override the api version used for api requests made by this command
--file-id= (required) ID of the file to delete (AiGroundingFileRef record ID).
GLOBAL FLAGS
--flags-dir= Import flag values from a directory.
--json Format output as json.
DESCRIPTION
Delete a file from an Agentforce Data Library.
Permanently removes a file from an SFDRIVE data library and triggers re-indexing of the search index.
EXAMPLES
Delete a file from a data library:
$ sf agent adl file delete --library-id 1JDSG000007IbWX4A0 --file-id a1B2C3D4E5F6G7H8I9 --target-org myOrg
```
_See code: [src/commands/agent/adl/file/delete.ts](https://github.com/salesforcecli/plugin-agent/blob/1.42.0/src/commands/agent/adl/file/delete.ts)_
## `sf agent adl file list`
List files in an Agentforce Data Library.
```
USAGE
$ sf agent adl file list -o -i [--json] [--flags-dir ] [--api-version ]
FLAGS
-i, --library-id= (required) Agentforce Data Library ID (18-char Salesforce ID with prefix 1JD).
-o, --target-org= (required) Username or alias of the target org. Not required if the `target-org`
configuration variable is already set.
--api-version= Override the api version used for api requests made by this command
GLOBAL FLAGS
--flags-dir= Import flag values from a directory.
--json Format output as json.
DESCRIPTION
List files in an Agentforce Data Library.
Returns the list of files in an SFDRIVE library including file name, size, and creation date.
EXAMPLES
List files in a data library:
$ sf agent adl file list --library-id 1JDSG000007IbWX4A0 --target-org myOrg
List files and output as JSON:
$ sf agent adl file list --library-id 1JDSG000007IbWX4A0 --target-org myOrg --json
```
_See code: [src/commands/agent/adl/file/list.ts](https://github.com/salesforcecli/plugin-agent/blob/1.42.0/src/commands/agent/adl/file/list.ts)_
## `sf agent adl get`
Get details of an Agentforce Data Library.
```
USAGE
$ sf agent adl get -o -i [--json] [--flags-dir ] [--api-version ]
FLAGS
-i, --library-id= (required) Agentforce Data Library ID (18-char Salesforce ID with prefix 1JD).
-o, --target-org= (required) Username or alias of the target org. Not required if the `target-org`
configuration variable is already set.
--api-version= Override the api version used for api requests made by this command
GLOBAL FLAGS
--flags-dir= Import flag values from a directory.
--json Format output as json.
DESCRIPTION
Get details of an Agentforce Data Library.
Returns the full detail of a data library including its grounding source configuration, status, and retriever ID.
EXAMPLES
Get details of a data library:
$ sf agent adl get --library-id 1JDSG000007IbWX4A0 --target-org myOrg
```
_See code: [src/commands/agent/adl/get.ts](https://github.com/salesforcecli/plugin-agent/blob/1.42.0/src/commands/agent/adl/get.ts)_
## `sf agent adl list`
List Agentforce Data Libraries in an org.
```
USAGE
$ sf agent adl list -o [--json] [--flags-dir ] [--api-version ]
FLAGS
-o, --target-org= (required) Username or alias of the target org. Not required if the `target-org`
configuration variable is already set.
--api-version= Override the api version used for api requests made by this command
GLOBAL FLAGS
--flags-dir= Import flag values from a directory.
--json Format output as json.
DESCRIPTION
List Agentforce Data Libraries in an org.
Returns all data libraries in the target org, including their source type, status, and library ID.
EXAMPLES
List all data libraries in the default target org:
$ sf agent adl list --target-org myOrg
List data libraries and output as JSON:
$ sf agent adl list --target-org myOrg --json
```
_See code: [src/commands/agent/adl/list.ts](https://github.com/salesforcecli/plugin-agent/blob/1.42.0/src/commands/agent/adl/list.ts)_
## `sf agent adl status`
Get indexing status of an Agentforce Data Library.
```
USAGE
$ sf agent adl status -o -i [--json] [--flags-dir ] [--api-version ]
FLAGS
-i, --library-id= (required) Agentforce Data Library ID (18-char Salesforce ID with prefix 1JD).
-o, --target-org= (required) Username or alias of the target org. Not required if the `target-org`
configuration variable is already set.
--api-version= Override the api version used for api requests made by this command
GLOBAL FLAGS
--flags-dir= Import flag values from a directory.
--json Format output as json.
DESCRIPTION
Get indexing status of an Agentforce Data Library.
Returns the current indexing status including stage details (DATA_LAKE_OBJECT, SEARCH_INDEX, RETRIEVER) and any
errors.
EXAMPLES
Get status of a data library:
$ sf agent adl status --library-id 1JDSG000007IbWX4A0 --target-org myOrg
```
_See code: [src/commands/agent/adl/status.ts](https://github.com/salesforcecli/plugin-agent/blob/1.42.0/src/commands/agent/adl/status.ts)_
## `sf agent adl update`
Update an Agentforce Data Library.
```
USAGE
$ sf agent adl update -o -i [--json] [--flags-dir ] [--api-version ] [-n ]
[--description ] [--content-fields ] [--restrict-to-public-articles]
FLAGS
-i, --library-id= (required) Agentforce Data Library ID (18-char Salesforce ID with prefix 1JD).
-n, --name= New display name for the data library (max 80 characters).
-o, --target-org= (required) Username or alias of the target org. Not required if the
`target-org` configuration variable is already set.
--api-version= Override the api version used for api requests made by this command
--content-fields= Comma-separated list of content fields for KNOWLEDGE libraries (triggers
re-indexing).
--description= New description for the data library (max 255 characters).
--[no-]restrict-to-public-articles Restrict to public Knowledge articles only (KNOWLEDGE libraries, triggers
re-indexing).
GLOBAL FLAGS
--flags-dir= Import flag values from a directory.
--json Format output as json.
DESCRIPTION
Update an Agentforce Data Library.
Updates the label, description, or other mutable properties of an existing data library.
EXAMPLES
Update the label of a data library:
$ sf agent adl update --library-id 1JDSG000007IbWX4A0 --name "New Name" --target-org myOrg
Update the description:
$ sf agent adl update --library-id 1JDSG000007IbWX4A0 --description "Updated description" --target-org myOrg
Update Knowledge library content fields (triggers re-indexing):
$ sf agent adl update --library-id 1JDSG000007IbWX4A0 --content-fields "Answer**c,Summary**c" --target-org myOrg
Restrict Knowledge library to public articles:
$ sf agent adl update --library-id 1JDSG000007IbWX4A0 --restrict-to-public-articles --target-org myOrg
```
_See code: [src/commands/agent/adl/update.ts](https://github.com/salesforcecli/plugin-agent/blob/1.42.0/src/commands/agent/adl/update.ts)_
## `sf agent adl upload`
Upload a file to an SFDRIVE Agentforce Data Library.
```
USAGE
$ sf agent adl upload -o -i -f [--json] [--flags-dir ] [--api-version ] [-w
]
FLAGS
-f, --file= (required) Path to the file to upload.
-i, --library-id= (required) Agentforce Data Library ID (18-char Salesforce ID with prefix 1JD).
-o, --target-org= (required) Username or alias of the target org. Not required if the `target-org`
configuration variable is already set.
-w, --wait= Number of minutes to wait for indexing to complete. If not specified, returns after
triggering indexing.
--api-version= Override the api version used for api requests made by this command
GLOBAL FLAGS
--flags-dir= Import flag values from a directory.
--json Format output as json.
DESCRIPTION
Upload a file to an SFDRIVE Agentforce Data Library.
Performs the multi-step upload workflow: checks upload readiness, obtains a pre-signed S3 URL, uploads the file,
triggers indexing, and optionally polls until the library is ready (retrieverId is populated).
This command only works with SFDRIVE libraries. KNOWLEDGE libraries index automatically after creation, and RETRIEVER
libraries require no file upload.
EXAMPLES
Upload a file and wait for indexing to complete:
$ sf agent adl upload --library-id 1JDSG000007IbWX4A0 --file ./docs/guide.pdf --target-org myOrg --wait 10
Upload a file without waiting:
$ sf agent adl upload --library-id 1JDSG000007IbWX4A0 --file ./docs/guide.pdf --target-org myOrg
```
_See code: [src/commands/agent/adl/upload.ts](https://github.com/salesforcecli/plugin-agent/blob/1.42.0/src/commands/agent/adl/upload.ts)_
## `sf agent create`
Create an agent in your org using a local agent spec file.
```
USAGE
$ sf agent create -o [--json] [--flags-dir ] [--api-version ] [--name ] [--api-name
] [--spec ] [--preview]
FLAGS
-o, --target-org= (required) Username or alias of the target org. Not required if the `target-org`
configuration variable is already set.
--api-name= API name of the new agent; if not specified, the API name is derived from the agent name
(label); the API name must not exist in the org.
--api-version= Override the api version used for api requests made by this command
--name= Name (label) of the new agent.
--preview Preview the agent without saving it in your org.
--spec= Path to an agent spec file.
GLOBAL FLAGS
--flags-dir= Import flag values from a directory.
--json Format output as json.
DESCRIPTION
Create an agent in your org using a local agent spec file.
NOTE: This command creates an agent that doesn't use Agent Script as its blueprint. We generally don't recommend you
use this workflow to create an agent. Rather, use the "agent generate|validate|publish authoring-bundle" commands to
author agents that use the Agent Script language. See "Author an Agent"
(https://developer.salesforce.com/docs/einstein/genai/guide/agent-dx-nga-author-agent.html) for details.
To run this command, you must have an agent spec file, which is a YAML file that define the agent properties and
contains a list of AI-generated topics. Topics define the range of jobs the agent can handle. Use the "agent generate
agent-spec" CLI command to generate an agent spec file. Then specify the file to this command using the --spec flag,
along with the name (label) of the new agent with the --name flag. If you don't specify any of the required flags, the
command prompts you.
When this command completes, your org contains the new agent, which you can then edit and customize in the Agent
Builder UI. The new agent's topics are the same as the ones listed in the agent spec file. The agent might also have
some AI-generated actions, or you can add them. This command also retrieves all the metadata files associated with the
new agent to your local Salesforce DX project.
Use the --preview flag to review what the agent looks like without actually saving it in your org. When previewing,
the command creates a JSON file in the current directory with all the agent details. The name of the JSON file is the
agent's API name and a timestamp.
To open the new agent in your org's Agent Builder UI, run this command: "sf org open agent --api-name ".
EXAMPLES
Create an agent by being prompted for the required information, such as the agent spec file and agent name, and then
create it in your default org:
$ sf agent create
Create an agent by specifying the agent name, API name, and spec file with flags; use the org with alias "my-org";
the command fails if the API name is already being used in your org:
$ sf agent create --name "Resort Manager" --api-name Resort_Manager --spec specs/resortManagerAgent.yaml \
--target-org my-org
Preview the creation of an agent named "Resort Manager" and use your default org:
$ sf agent create --name "Resort Manager" --spec specs/resortManagerAgent.yaml --preview
```
_See code: [src/commands/agent/create.ts](https://github.com/salesforcecli/plugin-agent/blob/1.42.0/src/commands/agent/create.ts)_
## `sf agent deactivate`
Deactivate an agent in an org.
```
USAGE
$ sf agent deactivate -o [--json] [--flags-dir ] [--api-version ] [-n ]
FLAGS
-n, --api-name= API name of the agent to deactivate; if not specified, the command provides a list that you
choose from.
-o, --target-org= (required) Username or alias of the target org. Not required if the `target-org`
configuration variable is already set.
--api-version= Override the api version used for api requests made by this command
GLOBAL FLAGS
--flags-dir= Import flag values from a directory.
--json Format output as json.
DESCRIPTION
Deactivate an agent in an org.
Deactivating an agent makes it unavailable to your users. To make changes to an agent, such as adding or removing
topics or actions, you must deactivate it. You can't preview an agent with the "agent preview" CLI command or VS Code
if it's deactivated.
If you run the command without the --api-name flag, the command provides a list of agent API names for you to choose
from. Use the flag to specify the exact agent without being prompted.
EXAMPLES
Deactivate an agent in your default target org by being prompted:
$ sf agent deactivate
Deactivate the agent Resort_Manager in the org with alias "my_org":
$ sf agent deactivate --api-name Resort_Manager --target-org my-org
```
_See code: [src/commands/agent/deactivate.ts](https://github.com/salesforcecli/plugin-agent/blob/1.42.0/src/commands/agent/deactivate.ts)_
## `sf agent generate agent-spec`
Generate an agent spec, which is a YAML file that captures what an agent can do.
```
USAGE
$ sf agent generate agent-spec -o [--json] [--flags-dir ] [--api-version ] [--type customer|internal]
[--role ] [--company-name ] [--company-description ] [--company-website ] [--max-topics
] [--agent-user ] [--enrich-logs true|false] [--tone formal|casual|neutral] [--spec ]
[--output-file ] [--full-interview] [--grounding-context --prompt-template ]
[--force-overwrite]
FLAGS
-o, --target-org= (required) Username or alias of the target org. Not required if the `target-org`
configuration variable is already set.
--agent-user= Username of a user in your org to assign to your agent; determines what your agent
can access and do.
--api-version= Override the api version used for api requests made by this command
--company-description= Description of your company.
--company-name= Name of your company.
--company-website= Website URL of your company.
--enrich-logs= Adds agent conversation data to event logs so you can view all agent session
activity in one place.
--force-overwrite Don't prompt the user to confirm that an existing spec file will be overwritten.
--full-interview Prompt for both required and optional flags.
--grounding-context= Context information and personalization that's added to your prompts when using a
custom prompt template.
--max-topics= Maximum number of topics to generate in the agent spec; default is 5.
--output-file= [default: specs/agentSpec.yaml] Path for the generated YAML agent spec file; can be
an absolute or relative path.
--prompt-template= API name of a customized prompt template to use instead of the default prompt
template.
--role= Role of the agent.
--spec= Agent spec file, in YAML format, to use as input to the command.
--tone= Conversational style of the agent, such as how it expresses your brand personality
in its messages through word choice, punctuation, and sentence structure.
--type= 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.
GLOBAL FLAGS
--flags-dir= Import flag values from a directory.
--json Format output as json.
DESCRIPTION
Generate an agent spec, which is a YAML file that captures what an agent can do.
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.
Use 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.
You 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.
You 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.
When 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.)
EXAMPLES
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:
$ sf agent generate agent-spec --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."
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":
$ sf agent generate agent-spec --max-topics 5 --output-file specs/resortManagerAgent.yaml --target-org my-org
Be prompted for all required and optional agent properties; use your default org:
$ sf agent generate agent-spec --full-interview
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:
$ sf agent generate agent-spec --spec specs/resortManagerAgent.yaml --output-file specs/resortManagerAgent.yaml \
--role "Field customer complaints, manage employee schedules, and ensure all resort operations are running \
smoothly"
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:
$ sf agent generate agent-spec --tone formal --agent-user resortmanager@myorg.com
```
_See code: [src/commands/agent/generate/agent-spec.ts](https://github.com/salesforcecli/plugin-agent/blob/1.42.0/src/commands/agent/generate/agent-spec.ts)_
## `sf agent generate authoring-bundle`
Generate an authoring bundle from an existing agent spec YAML file.
```
USAGE
$ sf agent generate authoring-bundle -o [--json] [--flags-dir ] [--api-name ] [--api-version ] [-f
] [--no-spec] [-d ] [-n ] [--force-overwrite]
FLAGS
-d, --output-dir= Directory where the authoring bundle files are generated.
-f, --spec= 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.
-n, --name= Name (label) of the authoring bundle; if not specified, you're prompted for the name.
-o, --target-org= (required) Username or alias of the target org. Not required if the `target-org`
configuration variable is already set.
--api-name= 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.
--api-version= Override the api version used for api requests made by this command
--force-overwrite Overwrite the existing authoring bundle if one with the same API name already exists
locally.
--no-spec Skip prompting for an agent spec and use the default Agent Script boilerplate in the
generated authoring bundle.
GLOBAL FLAGS
--flags-dir= Import flag values from a directory.
--json Format output as json.
DESCRIPTION
Generate an authoring bundle from an existing agent spec YAML file.
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.
Use 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.
The metadata type for authoring bundles is aiAuthoringBundle, which consist of a standard
".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/
directory. Use the --output-dir flag to generate them elsewhere.
After 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.
This command requires an org because it uses it to access an LLM for generating the Agent Script file.
EXAMPLES
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:
$ sf agent generate authoring-bundle
Generate an authoring bundle without using an agent spec file; give the bundle the label "My Authoring Bundle" and
use your default org:
$ sf agent generate authoring-bundle --no-spec --name "My Authoring Bundle"
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:
$ sf agent generate authoring-bundle --spec specs/agentSpec.yaml --name "My Authoring Bundle"
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":
$ sf agent generate authoring-bundle --spec specs/agentSpec.yaml --name "My Authoring Bundle" --output-dir \
other-package-dir/main/default --target-org my-dev-org
```
_See code: [src/commands/agent/generate/authoring-bundle.ts](https://github.com/salesforcecli/plugin-agent/blob/1.42.0/src/commands/agent/generate/authoring-bundle.ts)_
## `sf agent generate template`
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.
```
USAGE
$ sf agent generate template -s --agent-version -f [--json] [--flags-dir ] [--api-version
] [-r ]
FLAGS
-f, --agent-file= (required) Path to an agent (Bot) metadata file.
-r, --output-dir= Directory where the generated BotTemplate and GenAiPlannerBundle files are saved.
-s, --source-org= (required) Username or alias of the namespaced scratch org that contains the agent which
this template is based on.
--agent-version= (required) Version of the agent (BotVersion).
--api-version= Override the api version used for api requests made by this command
GLOBAL FLAGS
--flags-dir= Import flag values from a directory.
--json Format output as json.
DESCRIPTION
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.
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.
At 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.
Use 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.
The new BotTemplate metadata file is generated in the "botTemplates" directory in the output directory specified with
the --output-dir flag, and has the name \_v\_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.
See "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.
EXAMPLES
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":
$ sf agent generate template --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
```
_See code: [src/commands/agent/generate/template.ts](https://github.com/salesforcecli/plugin-agent/blob/1.42.0/src/commands/agent/generate/template.ts)_
## `sf agent generate test-spec`
Generate an agent test spec, which is a YAML file that lists the test cases for testing a specific agent.
```
USAGE
$ sf agent generate test-spec [--flags-dir ] [-d ] [--force-overwrite] [-f ]
FLAGS
-d, --from-definition= Filepath to the AIEvaluationDefinition metadata XML file in your DX project that you
want to convert to a test spec YAML file.
-f, --output-file= Name of the generated test spec YAML file. Default value is
"specs/-testSpec.yaml".
--force-overwrite Don't prompt for confirmation when overwriting an existing test spec YAML file.
GLOBAL FLAGS
--flags-dir= Import flag values from a directory.
DESCRIPTION
Generate an agent test spec, which is a YAML file that lists the test cases for testing a specific agent.
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.
To 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:
- Utterance: Natural language statement, question, or command used to test the agent.
- Expected topic: API name of the topic you expect the agent to use when responding to the utterance.
- Expected actions: One or more API names of the expection actions the agent takes.
- Expected outcome: Natural language description of the outcome you expect.
- (Optional) Custom evaluation: Test an agent's response for specific strings or numbers.
- (Optional) Conversation history: Boilerplate for additional context you can add to the test in the form of a
conversation history.
You 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.
When 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.
If you have an existing AiEvaluationDefinition metadata XML file in your DX project, you can generate its equivalent
YAML test spec file with the --from-definition flag.
EXAMPLES
Generate an agent test spec YAML file interactively:
$ sf agent generate test-spec
Generate an agent test spec YAML file and specify a name for the new file; if the file exists, overwrite it without
confirmation:
$ sf agent generate test-spec --output-file specs/Resort_Manager-new-version-testSpec.yaml --force-overwrite
Generate an agent test spec YAML file from an existing AiEvaluationDefinition metadata XML file in your DX project:
$ sf agent generate test-spec --from-definition \
force-app//main/default/aiEvaluationDefinitions/Resort_Manager_Tests.aiEvaluationDefinition-meta.xml
```
_See code: [src/commands/agent/generate/test-spec.ts](https://github.com/salesforcecli/plugin-agent/blob/1.42.0/src/commands/agent/generate/test-spec.ts)_
## `sf agent preview`
Interact with an agent to preview how it responds to your statements, questions, and commands (utterances).
```
USAGE
$ sf agent preview -o [--flags-dir ] [--api-version ] [-n ] [--authoring-bundle
] [-d ] [-x] [--use-live-actions]
FLAGS
-d, --output-dir= Directory where conversation transcripts are saved.
-n, --api-name= API name of the activated published agent you want to interact with.
-o, --target-org= (required) Username or alias of the target org. Not required if the `target-org`
configuration variable is already set.
-x, --apex-debug Enable Apex debug logging during the agent preview conversation.
--api-version= Override the api version used for api requests made by this command
--authoring-bundle= API name of the authoring bundle metadata component that contains the agent's Agent
Script file.
--use-live-actions Use real actions in the org; if not specified, preview uses AI to simulate (mock)
actions.
GLOBAL FLAGS
--flags-dir= Import flag values from a directory.
DESCRIPTION
Interact with an agent to preview how it responds to your statements, questions, and commands (utterances).
Use this command to have a natural language conversation with an agent, either while you code its local Agent Script
file or when it's published to an org. Previewing an agent acts like an initial test to make sure it responds to your
utterances as you expect. For example, you can test that the agent uses a particular topic when asked a question, and
then whether it invokes the correct action associated with that topic. This command is the CLI-equivalent of the
Preview panel in your org's Agentforce Builder UI.
Run without flags, this command provides a list of agents to preview, divided into two categories: "Agent Script",
which are agents that have a local authoring bundle in your DX project, or "Published", which are agents that are
published and activated in your org. Authoring bundles contain an agent's Agent Script file. You then choose the agent
you want to preview from the list. Or you can use the --authoring-bundle flag to specify a local authoring bundle's
API name or --api-name to specify an activated published agent.
When previewing an agent from its Agent Script file, you can use these two modes:
- Simulated mode (Default): Uses only the Agent Script file to converse, and it simulates (mocks) all the actions. Use
this mode if none of the Apex classes, flows, or prompt templates that implement your actions are available yet. The
LLM uses the information about topics in the Agent Script file to simulate what the action does or how it responds.
- Live mode: Uses the actual Apex classes, flows, and prompt templates in your development org in the agent preview.
If you've changed the Apex classe, flows, or prompt templates in your local DX project, then you must deploy them to
your development org if you want to use them in your live preview.
You can use the Apex Replay Debugger to debug your Apex classes when using live mode for Agent Script files and for
activated published agents; specify the --apex-debug flag.
Once connected to your agent, the preview interface is simple: in the "Start typing..." prompt, enter a statement,
question, or command; when you're done, enter Return. Your utterance is posted on the right along with a timestamp.
The agent then responds on the left. To exit the conversation, hit ESC or Control+C.
When the session concludes, the command asks if you want to save the API responses and chat transcripts. By default,
the files are saved to the "./temp/agent-preview" directory. Specify a new default directory with the --output-dir
flag.
EXAMPLES
Preview an agent by choosing from the list of available local Agent Script or published agents. If previewing a
local Agent Script agent, use simulated mode. Use the org with alias "my-dev-org".
$ sf agent preview --target-org my-dev-org
Preview an agent in live mode by choosing from a list of authoring bundles. Save the conversation transcripts to the
"./transcripts/my-preview" directory, enable the Apex debug logs, and use your default org:
$ sf agent preview --use-live-actions --apex-debug --output-dir transcripts/my-preview
```
_See code: [src/commands/agent/preview.ts](https://github.com/salesforcecli/plugin-agent/blob/1.42.0/src/commands/agent/preview.ts)_
## `sf agent preview end`
End an existing programmatic agent preview session and get trace location.
```
USAGE
$ sf agent preview end -o [--json] [--flags-dir ] [--api-version ] [--session-id |
--all] [-n | --authoring-bundle ] [-p]
FLAGS
-n, --api-name= API name of the activated published agent you want to preview.
-o, --target-org= (required) Username or alias of the target org. Not required if the `target-org`
configuration variable is already set.
-p, --no-prompt Don't prompt for confirmation before ending sessions. Has an effect only when used
with --all.
--all 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.
--api-version= Override the api version used for api requests made by this command
--authoring-bundle= API name of the authoring bundle metadata component that contains the agent's Agent
Script file.
--session-id= 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.
GLOBAL FLAGS
--flags-dir= Import flag values from a directory.
--json Format output as json.
DESCRIPTION
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 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.
Use 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.
EXAMPLES
End a preview session of a published agent by specifying its session ID and API name; use the default org:
$ sf agent preview end --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":
$ sf agent preview end --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.
$ sf agent preview end --authoring-bundle My_Local_Agent
End all active preview sessions for a specific agent without prompting:
$ sf agent preview end --all --authoring-bundle My_Local_Agent --target-org --no-prompt
End all active preview sessions across every agent in the local session cache for an org:
$ sf agent preview end --all --target-org
```
_See code: [src/commands/agent/preview/end.ts](https://github.com/salesforcecli/plugin-agent/blob/1.42.0/src/commands/agent/preview/end.ts)_
## `sf agent preview send`
Send a message to an existing agent preview session.
```
USAGE
$ sf agent preview send -o -u [--json] [--flags-dir ] [--api-version ] [--session-id
] [-n ] [--authoring-bundle ]
FLAGS
-n, --api-name= API name of the activated published agent you want to preview.
-o, --target-org= (required) Username or alias of the target org. Not required if the `target-org`
configuration variable is already set.
-u, --utterance= (required) Utterance to send to the agent, enclosed in double quotes.
--api-version= Override the api version used for api requests made by this command
--authoring-bundle= API name of the authoring bundle metadata component that contains the agent's Agent
Script file.
--session-id= 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.
GLOBAL FLAGS
--flags-dir= Import flag values from a directory.
--json Format output as json.
DESCRIPTION
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 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:
$ sf agent preview send --utterance "What can you help me with?" --api-name My_Published_Agent --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":
$ sf agent preview send --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:
$ sf agent preview send --utterance "what can you help me with?" --authoring-bundle My_Local_Agent
```
_See code: [src/commands/agent/preview/send.ts](https://github.com/salesforcecli/plugin-agent/blob/1.42.0/src/commands/agent/preview/send.ts)_
## `sf agent preview sessions`
List all known programmatic agent preview sessions.
```
USAGE
$ sf agent preview sessions [--json] [--flags-dir ]
GLOBAL FLAGS
--flags-dir= Import flag values from a directory.
--json Format output as json.
DESCRIPTION
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 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:
$ sf agent preview sessions
```
_See code: [src/commands/agent/preview/sessions.ts](https://github.com/salesforcecli/plugin-agent/blob/1.42.0/src/commands/agent/preview/sessions.ts)_
## `sf agent preview start`
Start a programmatic agent preview session.
```
USAGE
$ sf agent preview start -o [--json] [--flags-dir ] [--api-version ] [-n ]
[--authoring-bundle ] [--use-live-actions | --simulate-actions]
FLAGS
-n, --api-name=