@salesforce/plugin-agent 1.45.0 → 2.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +41 -41
  2. package/oclif.manifest.json +1151 -1151
  3. package/package.json +9 -9
@@ -1741,16 +1741,16 @@
1741
1741
  "update:mcp:agent"
1742
1742
  ]
1743
1743
  },
1744
- "agent:preview:end": {
1744
+ "agent:generate:agent-spec": {
1745
1745
  "aliases": [],
1746
1746
  "args": {},
1747
- "description": "You must have previously started a programmatic agent preview session with the \"agent preview start\" command to then use this command to end it. This command also displays the local directory where the session trace files are stored.\n\nThe original \"agent preview start\" command outputs a session ID which you then use with the --session-id flag of this command to end the session. You don't have to specify the --session-id flag if an agent has only one active preview session. You must also use either the --authoring-bundle or --api-name flag to specify the API name of the authoring bundle or the published agent, respectively. To find either API name, navigate to your package directory in your DX project. The API name of an authoring bundle is the same as its directory name under the \"aiAuthoringBundles\" metadata directory. Similarly, the published agent's API name is the same as its directory name under the \"Bots\" metadata directory.\n\nUse the --all flag to end all active preview sessions at once. You can combine --all with --api-name or --authoring-bundle to end only sessions for a specific agent, or use --all on its own to end every session across all agents in the project.",
1747
+ "description": "An agent spec is a YAML-formatted file that contains basic information about the agent, such as its role, company description, and an AI-generated list of topics based on this information. Topics define the range of jobs your agent can handle.\n\nUse flags, such as --role and --company-description, to provide details about your company and the role that the agent plays in your company. If you prefer, you can also be prompted for the basic information; use --full-interview to be prompted for all required and optional properties. Upon command execution, the large language model (LLM) associated with your org uses the provided information to generate a list of topics for the agent. Because the LLM uses the company and role information to generate the topics, we recommend that you provide accurate, complete, and specific details so the LLM generates the best and most relevant topics. Once generated, you can edit the spec file; for example, you can remove topics that don't apply or change a topic's description.\n\nYou can also iterate the spec generation process by using the --spec flag to pass an existing agent spec file to this command, and then using the --role, --company-description, etc, flags to refine your agent properties. Iteratively improving the description of your agent allows the LLM to generate progressively better topics.\n\nYou can also specify other agent properties, such as a custom prompt template, how to ground the prompt template to add context to the agent's prompts, the tone of the prompts, and the username of a user in the org to assign to the agent.\n\nWhen your agent spec is ready, generate an authoring bundle from it by passing the spec file to the --spec flag of the \"agent generate authoring-bundle\" CLI command. An authoring bundle is a metadata type that contains an Agent Script file, which is the blueprint for an agent. (While not recommended, you can also use the agent spec file to immediately create an agent with the \"agent create\" command. We don't recommend this workflow because these types of agents don't use Agent Script, and are thus less flexible and more difficult to maintain.)",
1748
1748
  "examples": [
1749
- "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",
1750
- "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",
1751
- "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",
1752
- "End all active preview sessions for a specific agent without prompting:\n<%= config.bin %> <%= command.id %> --all --authoring-bundle My_Local_Agent --target-org <target_org> --no-prompt",
1753
- "End all active preview sessions across every agent in the local session cache for an org:\n<%= config.bin %> <%= command.id %> --all --target-org <target_org>"
1749
+ "Generate an agent spec in the default location and use flags to specify the agent properties, such as its role and your company details; use your default org:\n<%= config.bin %> <%= command.id %> --type customer --role \"Field customer complaints and manage employee schedules.\" --company-name \"Coral Cloud Resorts\" --company-description \"Provide customers with exceptional destination activities, unforgettable experiences, and reservation services.\"",
1750
+ "Generate an agent spec by being prompted for the required agent properties and generate a maxiumum of 5 topics; write the generated file to the \"specs/resortManagerSpec.yaml\" file and use the org with alias \"my-org\":\n<%= config.bin %> <%= command.id %> --max-topics 5 --output-file specs/resortManagerAgent.yaml --target-org my-org",
1751
+ "Be prompted for all required and optional agent properties; use your default org:\n<%= config.bin %> <%= command.id %> --full-interview",
1752
+ "Specify an existing agent spec file called \"specs/resortManagerAgent.yaml\", and then overwrite it with a new version that contains newly AI-generated topics based on the updated role information passed in with the --role flag:\n<%= config.bin %> <%= command.id %> --spec specs/resortManagerAgent.yaml --output-file specs/resortManagerAgent.yaml --role \"Field customer complaints, manage employee schedules, and ensure all resort operations are running smoothly\"",
1753
+ "Specify that the conversational tone of the agent is formal and to attach the \"resortmanager@myorg.com\" username to it; be prompted for the required properties and use your default org:\n<%= config.bin %> <%= command.id %> --tone formal --agent-user resortmanager@myorg.com"
1754
1754
  ],
1755
1755
  "flags": {
1756
1756
  "json": {
@@ -1785,129 +1785,164 @@
1785
1785
  "multiple": false,
1786
1786
  "type": "option"
1787
1787
  },
1788
- "session-id": {
1789
- "exclusive": [
1790
- "all"
1788
+ "type": {
1789
+ "name": "type",
1790
+ "summary": "Type of agent to create. Internal types are copilots used internally by your company and customer types are the agents you create for your customers.",
1791
+ "hasDynamicHelp": false,
1792
+ "multiple": false,
1793
+ "options": [
1794
+ "customer",
1795
+ "internal"
1791
1796
  ],
1792
- "name": "session-id",
1793
- "required": false,
1794
- "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.",
1797
+ "type": "option"
1798
+ },
1799
+ "role": {
1800
+ "name": "role",
1801
+ "summary": "Role of the agent.",
1795
1802
  "hasDynamicHelp": false,
1796
1803
  "multiple": false,
1797
1804
  "type": "option"
1798
1805
  },
1799
- "api-name": {
1800
- "char": "n",
1801
- "exclusive": [
1802
- "authoring-bundle"
1803
- ],
1804
- "name": "api-name",
1805
- "summary": "API name of the activated published agent you want to preview.",
1806
+ "company-name": {
1807
+ "name": "company-name",
1808
+ "summary": "Name of your company.",
1806
1809
  "hasDynamicHelp": false,
1807
1810
  "multiple": false,
1808
1811
  "type": "option"
1809
1812
  },
1810
- "authoring-bundle": {
1811
- "exclusive": [
1812
- "api-name"
1813
- ],
1814
- "name": "authoring-bundle",
1815
- "summary": "API name of the authoring bundle metadata component that contains the agent's Agent Script file.",
1813
+ "company-description": {
1814
+ "name": "company-description",
1815
+ "summary": "Description of your company.",
1816
1816
  "hasDynamicHelp": false,
1817
1817
  "multiple": false,
1818
1818
  "type": "option"
1819
1819
  },
1820
- "all": {
1821
- "exclusive": [
1822
- "session-id"
1820
+ "company-website": {
1821
+ "name": "company-website",
1822
+ "summary": "Website URL of your company.",
1823
+ "hasDynamicHelp": false,
1824
+ "multiple": false,
1825
+ "type": "option"
1826
+ },
1827
+ "max-topics": {
1828
+ "name": "max-topics",
1829
+ "summary": "Maximum number of topics to generate in the agent spec; default is 5.",
1830
+ "hasDynamicHelp": false,
1831
+ "multiple": false,
1832
+ "type": "option"
1833
+ },
1834
+ "agent-user": {
1835
+ "name": "agent-user",
1836
+ "summary": "Username of a user in your org to assign to your agent; determines what your agent can access and do.",
1837
+ "hasDynamicHelp": false,
1838
+ "multiple": false,
1839
+ "type": "option"
1840
+ },
1841
+ "enrich-logs": {
1842
+ "name": "enrich-logs",
1843
+ "summary": "Adds agent conversation data to event logs so you can view all agent session activity in one place.",
1844
+ "hasDynamicHelp": false,
1845
+ "multiple": false,
1846
+ "options": [
1847
+ "true",
1848
+ "false"
1823
1849
  ],
1824
- "name": "all",
1825
- "summary": "End all active preview sessions. Combine with --api-name or --authoring-bundle to limit to a specific agent, or use with only --target-org to end sessions for all agents found in the local session cache. Requires --target-org.",
1850
+ "type": "option"
1851
+ },
1852
+ "tone": {
1853
+ "name": "tone",
1854
+ "summary": "Conversational style of the agent, such as how it expresses your brand personality in its messages through word choice, punctuation, and sentence structure.",
1855
+ "hasDynamicHelp": false,
1856
+ "multiple": false,
1857
+ "options": [
1858
+ "formal",
1859
+ "casual",
1860
+ "neutral"
1861
+ ],
1862
+ "type": "option"
1863
+ },
1864
+ "spec": {
1865
+ "name": "spec",
1866
+ "summary": "Agent spec file, in YAML format, to use as input to the command.",
1867
+ "hasDynamicHelp": false,
1868
+ "multiple": false,
1869
+ "type": "option"
1870
+ },
1871
+ "output-file": {
1872
+ "name": "output-file",
1873
+ "summary": "Path for the generated YAML agent spec file; can be an absolute or relative path.",
1874
+ "default": "specs/agentSpec.yaml",
1875
+ "hasDynamicHelp": false,
1876
+ "multiple": false,
1877
+ "type": "option"
1878
+ },
1879
+ "full-interview": {
1880
+ "name": "full-interview",
1881
+ "summary": "Prompt for both required and optional flags.",
1826
1882
  "allowNo": false,
1827
1883
  "type": "boolean"
1828
1884
  },
1829
- "no-prompt": {
1830
- "char": "p",
1831
- "name": "no-prompt",
1832
- "summary": "Don't prompt for confirmation before ending sessions. Has an effect only when used with --all.",
1885
+ "prompt-template": {
1886
+ "name": "prompt-template",
1887
+ "summary": "API name of a customized prompt template to use instead of the default prompt template.",
1888
+ "hasDynamicHelp": false,
1889
+ "multiple": false,
1890
+ "type": "option"
1891
+ },
1892
+ "grounding-context": {
1893
+ "dependsOn": [
1894
+ "prompt-template"
1895
+ ],
1896
+ "name": "grounding-context",
1897
+ "summary": "Context information and personalization that's added to your prompts when using a custom prompt template.",
1898
+ "hasDynamicHelp": false,
1899
+ "multiple": false,
1900
+ "type": "option"
1901
+ },
1902
+ "force-overwrite": {
1903
+ "name": "force-overwrite",
1904
+ "summary": "Don't prompt the user to confirm that an existing spec file will be overwritten.",
1833
1905
  "allowNo": false,
1834
1906
  "type": "boolean"
1835
1907
  }
1836
1908
  },
1837
1909
  "hasDynamicHelp": true,
1838
1910
  "hiddenAliases": [],
1839
- "id": "agent:preview:end",
1911
+ "id": "agent:generate:agent-spec",
1840
1912
  "pluginAlias": "@salesforce/plugin-agent",
1841
1913
  "pluginName": "@salesforce/plugin-agent",
1842
1914
  "pluginType": "core",
1843
1915
  "strict": true,
1844
- "summary": "End an existing programmatic agent preview session and get trace location.",
1916
+ "summary": "Generate an agent spec, which is a YAML file that captures what an agent can do.",
1845
1917
  "enableJsonFlag": true,
1846
1918
  "requiresProject": true,
1847
- "envVariablesSection": {
1848
- "header": "ENVIRONMENT VARIABLES",
1849
- "body": [
1850
- {
1851
- "name": "SF_TARGET_ORG",
1852
- "description": "Username or alias of your default org. Overrides the target-org configuration variable."
1853
- }
1854
- ]
1855
- },
1856
- "errorCodes": {
1857
- "header": "ERROR CODES",
1858
- "body": [
1859
- {
1860
- "name": "Succeeded (0)",
1861
- "description": "Preview session ended successfully and traces saved."
1862
- },
1863
- {
1864
- "name": "ExactlyOneRequired (2)",
1865
- "description": "Neither --api-name nor --authoring-bundle was provided (required when --all is not set)."
1866
- },
1867
- {
1868
- "name": "NotFound (2)",
1869
- "description": "Agent not found, or no preview session exists for this agent."
1870
- },
1871
- {
1872
- "name": "PreviewEndFailed (4)",
1873
- "description": "Failed to end the preview session."
1874
- },
1875
- {
1876
- "name": "PreviewEndPartialFailure (68)",
1877
- "description": "With --all, one or more sessions failed to end while others succeeded."
1878
- },
1879
- {
1880
- "name": "SessionAmbiguous (5)",
1881
- "description": "Multiple preview sessions found; specify --session-id to choose one."
1882
- }
1883
- ]
1884
- },
1885
1919
  "isESM": true,
1886
1920
  "relativePath": [
1887
1921
  "lib",
1888
1922
  "commands",
1889
1923
  "agent",
1890
- "preview",
1891
- "end.js"
1924
+ "generate",
1925
+ "agent-spec.js"
1892
1926
  ],
1893
1927
  "aliasPermutations": [],
1894
1928
  "permutations": [
1895
- "agent:preview:end",
1896
- "preview:agent:end",
1897
- "preview:end:agent",
1898
- "agent:end:preview",
1899
- "end:agent:preview",
1900
- "end:preview:agent"
1929
+ "agent:generate:agent-spec",
1930
+ "generate:agent:agent-spec",
1931
+ "generate:agent-spec:agent",
1932
+ "agent:agent-spec:generate",
1933
+ "agent-spec:agent:generate",
1934
+ "agent-spec:generate:agent"
1901
1935
  ]
1902
1936
  },
1903
- "agent:preview:send": {
1937
+ "agent:generate:authoring-bundle": {
1904
1938
  "aliases": [],
1905
1939
  "args": {},
1906
- "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.",
1940
+ "description": "Authoring bundles are metadata components that contain an agent's Agent Script file. The Agent Script file is the agent's blueprint; it fully describes what the agent can do using the Agent Script language.\n\nUse this command to generate a new authoring bundle based on an agent spec YAML file, which you create with the \"agent generate agent-spec\" command. The agent spec YAML file is a high-level description of the agent; it describes its essence rather than exactly what it can do. The resulting Agent Script file is customized to reflect what's in the agent spec file. You can also create an authoring bundle without an agent spec file by specifying the \"--no-spec\" flag; in this case, the resulting Agent Script file is just the default boilerplate.\n\nThe metadata type for authoring bundles is aiAuthoringBundle, which consist of a standard \"<bundle-api-name>.bundle-meta.xml\" metadata file and the Agent Script file (with extension \".agent\"). When you run this command, the new authoring bundle is generated in the force-app/main/default/aiAuthoringBundles/<bundle-api-name> directory. Use the --output-dir flag to generate them elsewhere.\n\nAfter you generate the initial authoring bundle, code the Agent Script file so your agent behaves exactly as you want. The Agent Script file generated by this command is just a first draft of your agent! Interactively test the agent by conversing with it using the \"agent preview\" command. Then publish the agent to your org with the \"agent publish authoring-bundle\" command.\n\nThis command requires an org because it uses it to access an LLM for generating the Agent Script file.",
1907
1941
  "examples": [
1908
- "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>",
1909
- "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",
1910
- "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"
1942
+ "Generate an authoring bundle by being prompted for all required values, such as the agent spec YAML file, the bundle name, and the API name; use your default org:\n<%= config.bin %> <%= command.id %>",
1943
+ "Generate an authoring bundle without using an agent spec file; give the bundle the label \"My Authoring Bundle\" and use your default org:\n<%= config.bin %> <%= command.id %> --no-spec --name \"My Authoring Bundle\"",
1944
+ "Generate an authoring bundle from the \"specs/agentSpec.yaml\" agent spec YAML file and give it the label \"My Authoring Bundle\"; use your default org:\n<%= config.bin %> <%= command.id %> --spec specs/agentSpec.yaml --name \"My Authoring Bundle\"",
1945
+ "Similar to previous example, but generate the authoring bundle files in the \"other-package-dir/main/default\" package directory; use the org with alias \"my-dev-org\":\n<%= config.bin %> <%= command.id %> --spec specs/agentSpec.yaml --name \"My Authoring Bundle\" --output-dir other-package-dir/main/default --target-org my-dev-org"
1911
1946
  ],
1912
1947
  "flags": {
1913
1948
  "json": {
@@ -1935,6 +1970,13 @@
1935
1970
  "multiple": false,
1936
1971
  "type": "option"
1937
1972
  },
1973
+ "api-name": {
1974
+ "name": "api-name",
1975
+ "summary": "API name of the new authoring bundle; if not specified, the API name is derived from the authoring bundle name (label); the API name can't exist in the org.",
1976
+ "hasDynamicHelp": false,
1977
+ "multiple": false,
1978
+ "type": "option"
1979
+ },
1938
1980
  "api-version": {
1939
1981
  "description": "Override the api version used for api requests made by this command",
1940
1982
  "name": "api-version",
@@ -1942,103 +1984,77 @@
1942
1984
  "multiple": false,
1943
1985
  "type": "option"
1944
1986
  },
1945
- "session-id": {
1946
- "name": "session-id",
1947
- "required": false,
1948
- "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.",
1987
+ "spec": {
1988
+ "char": "f",
1989
+ "name": "spec",
1990
+ "summary": "Path to the agent spec YAML file. If you don't specify the flag, the command provides a list that you can choose from. Use the --no-spec flag to skip using an agent spec entirely.",
1949
1991
  "hasDynamicHelp": false,
1950
1992
  "multiple": false,
1951
1993
  "type": "option"
1952
1994
  },
1953
- "utterance": {
1954
- "char": "u",
1955
- "name": "utterance",
1956
- "required": true,
1957
- "summary": "Utterance to send to the agent, enclosed in double quotes.",
1995
+ "no-spec": {
1996
+ "name": "no-spec",
1997
+ "summary": "Skip prompting for an agent spec and use the default Agent Script boilerplate in the generated authoring bundle.",
1998
+ "allowNo": false,
1999
+ "type": "boolean"
2000
+ },
2001
+ "output-dir": {
2002
+ "char": "d",
2003
+ "name": "output-dir",
2004
+ "summary": "Directory where the authoring bundle files are generated.",
1958
2005
  "hasDynamicHelp": false,
1959
2006
  "multiple": false,
1960
2007
  "type": "option"
1961
2008
  },
1962
- "api-name": {
2009
+ "name": {
1963
2010
  "char": "n",
1964
- "name": "api-name",
1965
- "summary": "API name of the activated published agent you want to preview.",
2011
+ "name": "name",
2012
+ "summary": "Name (label) of the authoring bundle; if not specified, you're prompted for the name.",
1966
2013
  "hasDynamicHelp": false,
1967
2014
  "multiple": false,
1968
2015
  "type": "option"
1969
2016
  },
1970
- "authoring-bundle": {
1971
- "name": "authoring-bundle",
1972
- "summary": "API name of the authoring bundle metadata component that contains the agent's Agent Script file.",
1973
- "hasDynamicHelp": false,
1974
- "multiple": false,
1975
- "type": "option"
1976
- }
1977
- },
1978
- "hasDynamicHelp": true,
2017
+ "force-overwrite": {
2018
+ "name": "force-overwrite",
2019
+ "summary": "Overwrite the existing authoring bundle if one with the same API name already exists locally.",
2020
+ "allowNo": false,
2021
+ "type": "boolean"
2022
+ }
2023
+ },
2024
+ "hasDynamicHelp": true,
1979
2025
  "hiddenAliases": [],
1980
- "id": "agent:preview:send",
2026
+ "id": "agent:generate:authoring-bundle",
1981
2027
  "pluginAlias": "@salesforce/plugin-agent",
1982
2028
  "pluginName": "@salesforce/plugin-agent",
1983
2029
  "pluginType": "core",
1984
2030
  "strict": true,
1985
- "summary": "Send a message to an existing agent preview session.",
2031
+ "summary": "Generate an authoring bundle from an existing agent spec YAML file.",
1986
2032
  "enableJsonFlag": true,
1987
2033
  "requiresProject": true,
1988
- "envVariablesSection": {
1989
- "header": "ENVIRONMENT VARIABLES",
1990
- "body": [
1991
- {
1992
- "name": "SF_TARGET_ORG",
1993
- "description": "Username or alias of your default org. Overrides the target-org configuration variable."
1994
- }
1995
- ]
1996
- },
1997
- "errorCodes": {
1998
- "header": "ERROR CODES",
1999
- "body": [
2000
- {
2001
- "name": "Succeeded (0)",
2002
- "description": "Message sent successfully and agent response received."
2003
- },
2004
- {
2005
- "name": "NotFound (2)",
2006
- "description": "Agent not found, or no preview session exists for this agent."
2007
- },
2008
- {
2009
- "name": "PreviewSendFailed (4)",
2010
- "description": "Failed to send message or receive response from the preview session."
2011
- },
2012
- {
2013
- "name": "SessionAmbiguous (5)",
2014
- "description": "Multiple preview sessions found; specify --session-id to choose one."
2015
- }
2016
- ]
2017
- },
2018
2034
  "isESM": true,
2019
2035
  "relativePath": [
2020
2036
  "lib",
2021
2037
  "commands",
2022
2038
  "agent",
2023
- "preview",
2024
- "send.js"
2039
+ "generate",
2040
+ "authoring-bundle.js"
2025
2041
  ],
2026
2042
  "aliasPermutations": [],
2027
2043
  "permutations": [
2028
- "agent:preview:send",
2029
- "preview:agent:send",
2030
- "preview:send:agent",
2031
- "agent:send:preview",
2032
- "send:agent:preview",
2033
- "send:preview:agent"
2044
+ "agent:generate:authoring-bundle",
2045
+ "generate:agent:authoring-bundle",
2046
+ "generate:authoring-bundle:agent",
2047
+ "agent:authoring-bundle:generate",
2048
+ "authoring-bundle:agent:generate",
2049
+ "authoring-bundle:generate:agent"
2034
2050
  ]
2035
2051
  },
2036
- "agent:preview:sessions": {
2052
+ "agent:generate:template": {
2037
2053
  "aliases": [],
2038
2054
  "args": {},
2039
- "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.",
2055
+ "description": "WARNING: This command doesn't work for agents that were created from an Agent Script file. In other words, you can't currently package an agent template for agents that use Agent Script.\n\nAt a high-level, agents are defined by the Bot, BotVersion, and GenAiPlannerBundle metadata types. The GenAiPlannerBundle type in turn defines the agent's topics and actions. This command uses the metadata files for these three types, located in your local DX project, to generate a BotTemplate metadata file for a specific agent (Bot). You then use the BotTemplate metadata file, along with the GenAiPlannerBundle metadata file that references the BotTemplate, to package the template in a managed package that you can share between orgs or on AppExchange.\n\nUse the --agent-file flag to specify the relative or full pathname of the Bot metadata file, such as force-app/main/default/bots/My_Awesome_Agent/My_Awesome_Agent.bot-meta.xml. A single Bot can have multiple BotVersions, so use the --agent-version flag to specify the version. The corresponding BotVersion metadata file must exist locally. For example, if you specify \"--agent-version 4\", then the file force-app/main/default/bots/My_Awesome_Agent/v4.botVersion-meta.xml must exist.\n\nThe new BotTemplate metadata file is generated in the \"botTemplates\" directory in the output directory specified with the --output-dir flag, and has the name <Agent_API_name>\\_v<Version>\\_Template.botTemplate-meta.xml, such as my-package/botTemplates/My_Awesome_Agent_v4_Template.botTemplate-meta.xml. The command displays the full pathname of the generated files when it completes.\n\nSee \"Develop and Package Agent Templates Using Scratch Orgs\" (https://developer.salesforce.com/docs/atlas.en-us.pkg2_dev.meta/pkg2_dev/dev2gp_package_agent_templates.htm) for details about the complete process, which includes using a scratch org to create and test the agent, retrieving the agent metadata to your DX project, running this command to create the agent template, and then packaging the template.",
2040
2056
  "examples": [
2041
- "List all cached agent preview sessions:\n<%= config.bin %> <%= command.id %>"
2057
+ "Generate an agent template from the My_Awesome_Agent Bot metadata file in your DX project and save the BotTemplate and GenAiPlannerBundle to the specified directory; use version 1 of the agent. The agent that the template is based on is in the org with alias \"my-scratch-org\":\n<%= config.bin %> <%= command.id %> --agent-file force-app/main/default/bots/My_Awesome_Agent/My_Awesome_Agent.bot-meta.xml --agent-version 1 --output-dir my-package --source-org my-scratch-org"
2042
2058
  ],
2043
2059
  "flags": {
2044
2060
  "json": {
@@ -2055,53 +2071,170 @@
2055
2071
  "hasDynamicHelp": false,
2056
2072
  "multiple": false,
2057
2073
  "type": "option"
2074
+ },
2075
+ "api-version": {
2076
+ "description": "Override the api version used for api requests made by this command",
2077
+ "name": "api-version",
2078
+ "hasDynamicHelp": false,
2079
+ "multiple": false,
2080
+ "type": "option"
2081
+ },
2082
+ "source-org": {
2083
+ "char": "s",
2084
+ "name": "source-org",
2085
+ "noCacheDefault": true,
2086
+ "required": true,
2087
+ "summary": "Username or alias of the namespaced scratch org that contains the agent which this template is based on.",
2088
+ "hasDynamicHelp": true,
2089
+ "multiple": false,
2090
+ "type": "option"
2091
+ },
2092
+ "agent-version": {
2093
+ "name": "agent-version",
2094
+ "required": true,
2095
+ "summary": "Version of the agent (BotVersion).",
2096
+ "hasDynamicHelp": false,
2097
+ "multiple": false,
2098
+ "type": "option"
2099
+ },
2100
+ "agent-file": {
2101
+ "char": "f",
2102
+ "name": "agent-file",
2103
+ "required": true,
2104
+ "summary": "Path to an agent (Bot) metadata file.",
2105
+ "hasDynamicHelp": false,
2106
+ "multiple": false,
2107
+ "type": "option"
2108
+ },
2109
+ "output-dir": {
2110
+ "char": "r",
2111
+ "name": "output-dir",
2112
+ "summary": "Directory where the generated BotTemplate and GenAiPlannerBundle files are saved.",
2113
+ "hasDynamicHelp": false,
2114
+ "multiple": false,
2115
+ "type": "option"
2058
2116
  }
2059
2117
  },
2060
- "hasDynamicHelp": false,
2118
+ "hasDynamicHelp": true,
2061
2119
  "hiddenAliases": [],
2062
- "id": "agent:preview:sessions",
2120
+ "id": "agent:generate:template",
2063
2121
  "pluginAlias": "@salesforce/plugin-agent",
2064
2122
  "pluginName": "@salesforce/plugin-agent",
2065
2123
  "pluginType": "core",
2066
2124
  "strict": true,
2067
- "summary": "List all known programmatic agent preview sessions.",
2125
+ "summary": "Generate an agent template from an existing agent in your DX project so you can then package the template in a second-generation managed package.",
2068
2126
  "enableJsonFlag": true,
2069
2127
  "requiresProject": true,
2070
- "errorCodes": {
2071
- "header": "ERROR CODES",
2072
- "body": [
2073
- {
2074
- "name": "Succeeded (0)",
2075
- "description": "Sessions listed successfully (or empty list if no active sessions)."
2076
- }
2077
- ]
2128
+ "isESM": true,
2129
+ "relativePath": [
2130
+ "lib",
2131
+ "commands",
2132
+ "agent",
2133
+ "generate",
2134
+ "template.js"
2135
+ ],
2136
+ "aliasPermutations": [],
2137
+ "permutations": [
2138
+ "agent:generate:template",
2139
+ "generate:agent:template",
2140
+ "generate:template:agent",
2141
+ "agent:template:generate",
2142
+ "template:agent:generate",
2143
+ "template:generate:agent"
2144
+ ]
2145
+ },
2146
+ "agent:generate:test-spec": {
2147
+ "aliases": [],
2148
+ "args": {},
2149
+ "description": "The first step when using Salesforce CLI to create an agent test in your org is to use this interactive command to generate a local YAML-formatted test spec file. The test spec YAML file contains information about the agent being tested, such as its API name, and then one or more test cases. This command uses the metadata components in your DX project when prompting for information, such as the agent API name; it doesn't look in your org.\n\nTo generate a specific agent test case, this command prompts you for this information; when possible, the command provides a list of options for you to choose from:\n\n- Utterance: Natural language statement, question, or command used to test the agent.\n- Expected topic: API name of the topic you expect the agent to use when responding to the utterance.\n- Expected actions: One or more API names of the expection actions the agent takes.\n- Expected outcome: Natural language description of the outcome you expect.\n- (Optional) Custom evaluation: Test an agent's response for specific strings or numbers.\n- (Optional) Conversation history: Boilerplate for additional context you can add to the test in the form of a conversation history.\n\nYou can manually add contextVariables to test cases in the generated YAML file to inject contextual data (such as CaseId or RoutableId) into agent sessions. This is useful for testing agent behavior with different contextual information.\n\nWhen your test spec is ready, you then run the \"agent test create\" command to actually create the test in your org and synchronize the metadata with your DX project. The metadata type for an agent test is `AiEvaluationDefinition` (legacy testing-center) or `AiTestingDefinition` (Agentforce Studio / NGT), selected via --test-runner.\n\nIf you have an existing AiEvaluationDefinition or AiTestingDefinition metadata XML file in your DX project, you can generate its equivalent YAML test spec file with the --from-definition flag. The runner is inferred from the file extension; pass --test-runner to override.",
2150
+ "examples": [
2151
+ "Generate an agent test spec YAML file interactively:\n<%= config.bin %> <%= command.id %>",
2152
+ "Generate an Agentforce Studio (NGT) test spec YAML file interactively:\n<%= config.bin %> <%= command.id %> --test-runner agentforce-studio",
2153
+ "Generate an agent test spec YAML file and specify a name for the new file; if the file exists, overwrite it without confirmation:\n<%= config.bin %> <%= command.id %> --output-file specs/Resort_Manager-new-version-testSpec.yaml --force-overwrite",
2154
+ "Generate an agent test spec YAML file from an existing AiEvaluationDefinition metadata XML file in your DX project:\n<%= config.bin %> <%= command.id %> --from-definition force-app/main/default/aiEvaluationDefinitions/Resort_Manager_Tests.aiEvaluationDefinition-meta.xml",
2155
+ "Generate an Agentforce Studio (NGT) test spec YAML file from an existing AiTestingDefinition metadata XML file:\n<%= config.bin %> <%= command.id %> --from-definition force-app/main/default/aiTestingDefinitions/Returns_Checkout_Tests.aiTestingDefinition-meta.xml"
2156
+ ],
2157
+ "flags": {
2158
+ "flags-dir": {
2159
+ "helpGroup": "GLOBAL",
2160
+ "name": "flags-dir",
2161
+ "summary": "Import flag values from a directory.",
2162
+ "hasDynamicHelp": false,
2163
+ "multiple": false,
2164
+ "type": "option"
2165
+ },
2166
+ "from-definition": {
2167
+ "char": "d",
2168
+ "name": "from-definition",
2169
+ "summary": "Filepath to an AiEvaluationDefinition or AiTestingDefinition metadata XML file in your DX project that you want to convert to a test spec YAML file.",
2170
+ "hasDynamicHelp": false,
2171
+ "multiple": false,
2172
+ "type": "option"
2173
+ },
2174
+ "force-overwrite": {
2175
+ "name": "force-overwrite",
2176
+ "summary": "Don't prompt for confirmation when overwriting an existing test spec YAML file.",
2177
+ "allowNo": false,
2178
+ "type": "boolean"
2179
+ },
2180
+ "output-file": {
2181
+ "char": "f",
2182
+ "name": "output-file",
2183
+ "summary": "Name of the generated test spec YAML file. Default value is \"specs/<AGENT_API_NAME>-testSpec.yaml\" (legacy) or \"specs/<AGENT_API_NAME>-ngtTestSpec.yaml\" (Agentforce Studio).",
2184
+ "hasDynamicHelp": false,
2185
+ "multiple": false,
2186
+ "type": "option"
2187
+ },
2188
+ "test-runner": {
2189
+ "description": "By default, the command automatically detects which test runner to use based on the test definition metadata type in your org. Use this flag to explicitly specify the runner type. 'agentforce-studio' uses AiTestingDefinition metadata. 'testing-center' uses AiEvaluationDefinition metadata.",
2190
+ "name": "test-runner",
2191
+ "summary": "Explicitly specify which test runner to use (agentforce-studio or testing-center).",
2192
+ "hasDynamicHelp": false,
2193
+ "multiple": false,
2194
+ "options": [
2195
+ "agentforce-studio",
2196
+ "testing-center"
2197
+ ],
2198
+ "type": "option"
2199
+ }
2078
2200
  },
2201
+ "hasDynamicHelp": false,
2202
+ "hiddenAliases": [],
2203
+ "id": "agent:generate:test-spec",
2204
+ "pluginAlias": "@salesforce/plugin-agent",
2205
+ "pluginName": "@salesforce/plugin-agent",
2206
+ "pluginType": "core",
2207
+ "strict": true,
2208
+ "summary": "Generate an agent test spec, which is a YAML file that lists the test cases for testing a specific agent.",
2209
+ "enableJsonFlag": false,
2079
2210
  "isESM": true,
2080
2211
  "relativePath": [
2081
2212
  "lib",
2082
2213
  "commands",
2083
2214
  "agent",
2084
- "preview",
2085
- "sessions.js"
2215
+ "generate",
2216
+ "test-spec.js"
2086
2217
  ],
2087
2218
  "aliasPermutations": [],
2088
2219
  "permutations": [
2089
- "agent:preview:sessions",
2090
- "preview:agent:sessions",
2091
- "preview:sessions:agent",
2092
- "agent:sessions:preview",
2093
- "sessions:agent:preview",
2094
- "sessions:preview:agent"
2220
+ "agent:generate:test-spec",
2221
+ "generate:agent:test-spec",
2222
+ "generate:test-spec:agent",
2223
+ "agent:test-spec:generate",
2224
+ "test-spec:agent:generate",
2225
+ "test-spec:generate:agent"
2095
2226
  ]
2096
2227
  },
2097
- "agent:preview:start": {
2228
+ "agent:preview:end": {
2098
2229
  "aliases": [],
2099
2230
  "args": {},
2100
- "description": "This command outputs a session ID that you then use with the \"agent preview send\" command to send an utterance to the agent. Use the \"agent preview sessions\" command to list all active sessions and the \"agent preview end\" command to end a specific session.\n\nIdentify the agent you want to start previewing with either the --authoring-bundle flag to specify a local authoring bundle's API name or --api-name to specify an activated published agent's API name. To find either API name, navigate to your package directory in your DX project. The API name of an authoring bundle is the same as its directory name under the \"aiAuthoringBundles\" metadata directory. Similarly, the published agent's API name is the same as its directory name under the \"Bots\" metadata directory.\n\nWhen starting a preview session with --authoring-bundle, you must explicitly specify the execution mode using one of these flags:\n\n- --use-live-actions: Executes real Apex classes, flows, and other actions in the org. This surfaces compile and validation errors during preview.\n- --simulate-actions: Uses AI to simulate action execution without calling real implementations.\n\nPublished agents (--api-name) always use live actions. The mode flags are optional and have no effect for published agents.",
2231
+ "description": "You must have previously started a programmatic agent preview session with the \"agent preview start\" command to then use this command to end it. This command also displays the local directory where the session trace files are stored.\n\nThe original \"agent preview start\" command outputs a session ID which you then use with the --session-id flag of this command to end the session. You don't have to specify the --session-id flag if an agent has only one active preview session. You must also use either the --authoring-bundle or --api-name flag to specify the API name of the authoring bundle or the published agent, respectively. To find either API name, navigate to your package directory in your DX project. The API name of an authoring bundle is the same as its directory name under the \"aiAuthoringBundles\" metadata directory. Similarly, the published agent's API name is the same as its directory name under the \"Bots\" metadata directory.\n\nUse the --all flag to end all active preview sessions at once. You can combine --all with --api-name or --authoring-bundle to end only sessions for a specific agent, or use --all on its own to end every session across all agents in the project.",
2101
2232
  "examples": [
2102
- "Start a programmatic agent preview session by specifying an authoring bundle; use simulated actions. Use the org with alias \"my-dev-org\":\n<%= config.bin %> <%= command.id %> --authoring-bundle My_Agent_Bundle --target-org my-dev-org --simulate-actions",
2103
- "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",
2104
- "Start a preview session with an activated published agent (always uses live actions):\n<%= config.bin %> <%= command.id %> --api-name My_Published_Agent"
2233
+ "End a preview session of a published agent by specifying its session ID and API name; use the default org:\n<%= config.bin %> <%= command.id %> --session-id <SESSION_ID> --api-name My_Published_Agent",
2234
+ "Similar to previous example, but don't specify a session ID; you get an error if the published agent has more than one active session. Use the org with alias \"my-dev-org\":\n<%= config.bin %> <%= command.id %> --api-name My_Published_Agent --target-org my-dev-org",
2235
+ "End a preview session of an agent using its authoring bundle API name; you get an error if the agent has more than one active session.\n<%= config.bin %> <%= command.id %> --authoring-bundle My_Local_Agent",
2236
+ "End all active preview sessions for a specific agent without prompting:\n<%= config.bin %> <%= command.id %> --all --authoring-bundle My_Local_Agent --target-org <target_org> --no-prompt",
2237
+ "End all active preview sessions across every agent in the local session cache for an org:\n<%= config.bin %> <%= command.id %> --all --target-org <target_org>"
2105
2238
  ],
2106
2239
  "flags": {
2107
2240
  "json": {
@@ -2136,8 +2269,22 @@
2136
2269
  "multiple": false,
2137
2270
  "type": "option"
2138
2271
  },
2272
+ "session-id": {
2273
+ "exclusive": [
2274
+ "all"
2275
+ ],
2276
+ "name": "session-id",
2277
+ "required": false,
2278
+ "summary": "Session ID outputted by \"agent preview start\". Not required when the agent has exactly one active session. Run \"agent preview sessions\" to see the list of all sessions.",
2279
+ "hasDynamicHelp": false,
2280
+ "multiple": false,
2281
+ "type": "option"
2282
+ },
2139
2283
  "api-name": {
2140
2284
  "char": "n",
2285
+ "exclusive": [
2286
+ "authoring-bundle"
2287
+ ],
2141
2288
  "name": "api-name",
2142
2289
  "summary": "API name of the activated published agent you want to preview.",
2143
2290
  "hasDynamicHelp": false,
@@ -2145,59 +2292,40 @@
2145
2292
  "type": "option"
2146
2293
  },
2147
2294
  "authoring-bundle": {
2295
+ "exclusive": [
2296
+ "api-name"
2297
+ ],
2148
2298
  "name": "authoring-bundle",
2149
2299
  "summary": "API name of the authoring bundle metadata component that contains the agent's Agent Script file.",
2150
2300
  "hasDynamicHelp": false,
2151
2301
  "multiple": false,
2152
2302
  "type": "option"
2153
2303
  },
2154
- "use-live-actions": {
2304
+ "all": {
2155
2305
  "exclusive": [
2156
- "simulate-actions"
2306
+ "session-id"
2157
2307
  ],
2158
- "name": "use-live-actions",
2159
- "summary": "Execute real actions in the org (Apex classes, flows, etc.). Required with --authoring-bundle.",
2308
+ "name": "all",
2309
+ "summary": "End all active preview sessions. Combine with --api-name or --authoring-bundle to limit to a specific agent, or use with only --target-org to end sessions for all agents found in the local session cache. Requires --target-org.",
2160
2310
  "allowNo": false,
2161
2311
  "type": "boolean"
2162
2312
  },
2163
- "simulate-actions": {
2164
- "exclusive": [
2165
- "use-live-actions"
2166
- ],
2167
- "name": "simulate-actions",
2168
- "summary": "Use AI to simulate action execution instead of calling real actions. Required with --authoring-bundle.",
2313
+ "no-prompt": {
2314
+ "char": "p",
2315
+ "name": "no-prompt",
2316
+ "summary": "Don't prompt for confirmation before ending sessions. Has an effect only when used with --all.",
2169
2317
  "allowNo": false,
2170
2318
  "type": "boolean"
2171
- },
2172
- "context-variables": {
2173
- "description": "Sets variables on the agent preview session, mirroring what the in-org Agentforce Builder UI does when you override variables before sending a message. Specify this flag multiple times or use comma-separated values. Two namespaces are supported, distinguished by the name shape. Names pass through to the runtime verbatim — the CLI doesn't transform them.\n\nLinked context variables use the \"$Context.\" prefix. These map to externally-provided fields that the runtime resolves (declared in the bundle's globalConfiguration.contextVariables) and are read by live actions and topic-routing expressions via $Context.Name. Example: $Context.MyLinkedVar=some-value.\n\nState variables use the bare developerName, no prefix. These seed mutable agent state declared in agentVersion.stateVariables. Example: MyStateVar=some-value.\n\nBoth namespaces can be mixed in one value. Example: --context-variables '$Context.MyLinkedVar=foo,MyStateVar=bar'.\n\nTips: (1) Quote the whole value in single quotes so $Context isn't shell-expanded. (2) Names are sent verbatim — a bare name is treated as a state variable, not a linked context variable, so live actions that bind via $Context.Name will see null. (3) Type defaults to Text.",
2174
- "name": "context-variables",
2175
- "summary": "Session variables for the agent preview session, in the form Name=Value.",
2176
- "delimiter": ",",
2177
- "hasDynamicHelp": false,
2178
- "multiple": true,
2179
- "type": "option"
2180
- },
2181
- "agent-json": {
2182
- "dependsOn": [
2183
- "authoring-bundle"
2184
- ],
2185
- "hidden": true,
2186
- "name": "agent-json",
2187
- "summary": "Path to a pre-compiled AgentJSON file to use instead of compiling the Agent Script file. Intended for internal use and testing.",
2188
- "hasDynamicHelp": false,
2189
- "multiple": false,
2190
- "type": "option"
2191
2319
  }
2192
2320
  },
2193
2321
  "hasDynamicHelp": true,
2194
2322
  "hiddenAliases": [],
2195
- "id": "agent:preview:start",
2323
+ "id": "agent:preview:end",
2196
2324
  "pluginAlias": "@salesforce/plugin-agent",
2197
2325
  "pluginName": "@salesforce/plugin-agent",
2198
2326
  "pluginType": "core",
2199
2327
  "strict": true,
2200
- "summary": "Start a programmatic agent preview session.",
2328
+ "summary": "End an existing programmatic agent preview session and get trace location.",
2201
2329
  "enableJsonFlag": true,
2202
2330
  "requiresProject": true,
2203
2331
  "envVariablesSection": {
@@ -2214,23 +2342,27 @@
2214
2342
  "body": [
2215
2343
  {
2216
2344
  "name": "Succeeded (0)",
2217
- "description": "Preview session started successfully."
2345
+ "description": "Preview session ended successfully and traces saved."
2218
2346
  },
2219
2347
  {
2220
- "name": "Failed (1)",
2221
- "description": "Agent Script compilation failed (syntax errors in the script)."
2348
+ "name": "ExactlyOneRequired (2)",
2349
+ "description": "Neither --api-name nor --authoring-bundle was provided (required when --all is not set)."
2222
2350
  },
2223
2351
  {
2224
2352
  "name": "NotFound (2)",
2225
- "description": "Agent not found, or compilation API returned HTTP 404 (endpoint may not be available in your org or region)."
2353
+ "description": "Agent not found, or no preview session exists for this agent."
2226
2354
  },
2227
2355
  {
2228
- "name": "ServerError (3)",
2229
- "description": "Compilation API returned HTTP 500 (server error during compilation)."
2356
+ "name": "PreviewEndFailed (4)",
2357
+ "description": "Failed to end the preview session."
2230
2358
  },
2231
2359
  {
2232
- "name": "PreviewStartFailed (4)",
2233
- "description": "Preview session failed to start due to API or network errors."
2360
+ "name": "PreviewEndPartialFailure (68)",
2361
+ "description": "With --all, one or more sessions failed to end while others succeeded."
2362
+ },
2363
+ {
2364
+ "name": "SessionAmbiguous (5)",
2365
+ "description": "Multiple preview sessions found; specify --session-id to choose one."
2234
2366
  }
2235
2367
  ]
2236
2368
  },
@@ -2240,27 +2372,26 @@
2240
2372
  "commands",
2241
2373
  "agent",
2242
2374
  "preview",
2243
- "start.js"
2375
+ "end.js"
2244
2376
  ],
2245
2377
  "aliasPermutations": [],
2246
2378
  "permutations": [
2247
- "agent:preview:start",
2248
- "preview:agent:start",
2249
- "preview:start:agent",
2250
- "agent:start:preview",
2251
- "start:agent:preview",
2252
- "start:preview:agent"
2379
+ "agent:preview:end",
2380
+ "preview:agent:end",
2381
+ "preview:end:agent",
2382
+ "agent:end:preview",
2383
+ "end:agent:preview",
2384
+ "end:preview:agent"
2253
2385
  ]
2254
2386
  },
2255
- "agent:publish:authoring-bundle": {
2387
+ "agent:preview:send": {
2256
2388
  "aliases": [],
2257
2389
  "args": {},
2258
- "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\nWhen you publish an authoring bundle to your org, a number of things happen. First, this command validates that the Agent Script file successfully compiles. If there are compilation errors, the command exits and you must fix the Agent Script file to continue. Once the Agent Script file compiles, then it's published to the org, which in turn creates new associated metadata (Bot, BotVersion, GenAiX), or new versions of the metadata if the agent already exists. The new or updated metadata is retrieved back to your DX project; specify the --skip-retrieve flag to skip this step. Finally, the authoring bundle metadata (AiAuthoringBundle) is deployed to your org.\n\nThis command uses the API name of the authoring bundle.",
2390
+ "description": "You must have previously started a programmatic agent preview session with the \"agent preview start\" command to then use this command to send the agent a message (utterance). This command then displays the agent's response.\n\nThe original \"agent preview start\" command outputs a session ID which you then use with the --session-id flag of this command to send a message. You don't have to specify the --session-id flag if an agent has only one active preview session. You must also use either the --authoring-bundle or --api-name flag to specify the API name of the authoring bundle or the published agent, respecitvely. To find either API name, navigate to your package directory in your DX project. The API name of an authoring bundle is the same as its directory name under the \"aiAuthoringBundles\" metadata directory. Similarly, the published agent's API name is the same as its directory name under the \"Bots\" metadata directory.",
2259
2391
  "examples": [
2260
- "Publish an authoring bundle by being prompted for its API name; use your default org:\n<%= config.bin %> <%= command.id %>",
2261
- "Publish an authoring bundle with API name MyAuthoringBundle to the org with alias \"my-dev-org\":\n<%= config.bin %> <%= command.id %> --api-name MyAuthoringbundle --target-org my-dev-org",
2262
- "Publish with verbose output to see all retrieved and deployed metadata components:\n<%= config.bin %> <%= command.id %> --api-name MyAuthoringbundle --verbose",
2263
- "Publish with concise output showing only essential information:\n<%= config.bin %> <%= command.id %> --api-name MyAuthoringbundle --concise"
2392
+ "Send a message to an activated published agent using its API name and session ID; use the default org:\n<%= config.bin %> <%= command.id %> --utterance \"What can you help me with?\" --api-name My_Published_Agent --session-id <SESSION_ID>",
2393
+ "Similar to previous example, but don't specify a session ID; you get an error if the agent has more than one active session. Use the org with alias \"my-dev-org\":\n<%= config.bin %> <%= command.id %> --utterance \"What can you help me with?\" --api-name My_Published_Agent --target-org my-dev-org",
2394
+ "Send a message to an agent using its authoring bundle API name; you get an error if the agent has more than one active session:\n<%= config.bin %> <%= command.id %> --utterance \"what can you help me with?\" --authoring-bundle My_Local_Agent"
2264
2395
  ],
2265
2396
  "flags": {
2266
2397
  "json": {
@@ -2295,96 +2426,103 @@
2295
2426
  "multiple": false,
2296
2427
  "type": "option"
2297
2428
  },
2429
+ "session-id": {
2430
+ "name": "session-id",
2431
+ "required": false,
2432
+ "summary": "Session ID outputted by \"agent preview start\". Not required when the agent has exactly one active session. Run \"agent preview sessions\" to see list of all sessions.",
2433
+ "hasDynamicHelp": false,
2434
+ "multiple": false,
2435
+ "type": "option"
2436
+ },
2437
+ "utterance": {
2438
+ "char": "u",
2439
+ "name": "utterance",
2440
+ "required": true,
2441
+ "summary": "Utterance to send to the agent, enclosed in double quotes.",
2442
+ "hasDynamicHelp": false,
2443
+ "multiple": false,
2444
+ "type": "option"
2445
+ },
2298
2446
  "api-name": {
2299
2447
  "char": "n",
2300
2448
  "name": "api-name",
2301
- "summary": "API name of the authoring bundle you want to publish; if not specified, the command provides a list that you can choose from.",
2449
+ "summary": "API name of the activated published agent you want to preview.",
2302
2450
  "hasDynamicHelp": false,
2303
2451
  "multiple": false,
2304
2452
  "type": "option"
2305
2453
  },
2306
- "skip-retrieve": {
2307
- "name": "skip-retrieve",
2308
- "summary": "Don't retrieve the metadata associated with the agent to your DX project.",
2309
- "allowNo": false,
2310
- "type": "boolean"
2311
- },
2312
- "verbose": {
2313
- "char": "v",
2314
- "exclusive": [
2315
- "concise"
2316
- ],
2317
- "name": "verbose",
2318
- "summary": "Display detailed output showing all metadata components retrieved and deployed during the publish process.",
2319
- "allowNo": false,
2320
- "type": "boolean"
2321
- },
2322
- "concise": {
2323
- "exclusive": [
2324
- "verbose"
2325
- ],
2326
- "name": "concise",
2327
- "summary": "Display minimal output with only essential information about the publish operation.",
2328
- "allowNo": false,
2329
- "type": "boolean"
2454
+ "authoring-bundle": {
2455
+ "name": "authoring-bundle",
2456
+ "summary": "API name of the authoring bundle metadata component that contains the agent's Agent Script file.",
2457
+ "hasDynamicHelp": false,
2458
+ "multiple": false,
2459
+ "type": "option"
2330
2460
  }
2331
2461
  },
2332
2462
  "hasDynamicHelp": true,
2333
2463
  "hiddenAliases": [],
2334
- "id": "agent:publish:authoring-bundle",
2464
+ "id": "agent:preview:send",
2335
2465
  "pluginAlias": "@salesforce/plugin-agent",
2336
2466
  "pluginName": "@salesforce/plugin-agent",
2337
2467
  "pluginType": "core",
2338
2468
  "strict": true,
2339
- "summary": "Publish an authoring bundle to your org, which results in a new agent or a new version of an existing agent.",
2469
+ "summary": "Send a message to an existing agent preview session.",
2340
2470
  "enableJsonFlag": true,
2341
2471
  "requiresProject": true,
2472
+ "envVariablesSection": {
2473
+ "header": "ENVIRONMENT VARIABLES",
2474
+ "body": [
2475
+ {
2476
+ "name": "SF_TARGET_ORG",
2477
+ "description": "Username or alias of your default org. Overrides the target-org configuration variable."
2478
+ }
2479
+ ]
2480
+ },
2342
2481
  "errorCodes": {
2343
2482
  "header": "ERROR CODES",
2344
2483
  "body": [
2345
2484
  {
2346
2485
  "name": "Succeeded (0)",
2347
- "description": "Agent published successfully without errors."
2486
+ "description": "Message sent successfully and agent response received."
2348
2487
  },
2349
2488
  {
2350
- "name": "Failed (1)",
2351
- "description": "Compilation errors found in the Agent Script file."
2489
+ "name": "NotFound (2)",
2490
+ "description": "Agent not found, or no preview session exists for this agent."
2491
+ },
2492
+ {
2493
+ "name": "PreviewSendFailed (4)",
2494
+ "description": "Failed to send message or receive response from the preview session."
2495
+ },
2496
+ {
2497
+ "name": "SessionAmbiguous (5)",
2498
+ "description": "Multiple preview sessions found; specify --session-id to choose one."
2352
2499
  }
2353
2500
  ]
2354
2501
  },
2355
- "FLAGGABLE_PROMPTS": {
2356
- "api-name": {
2357
- "message": "API name of the authoring bundle you want to publish; if not specified, the command provides a list that you can choose from.",
2358
- "promptMessage": "API name of the authoring bundle to publish"
2359
- }
2360
- },
2361
2502
  "isESM": true,
2362
2503
  "relativePath": [
2363
2504
  "lib",
2364
2505
  "commands",
2365
2506
  "agent",
2366
- "publish",
2367
- "authoring-bundle.js"
2507
+ "preview",
2508
+ "send.js"
2368
2509
  ],
2369
2510
  "aliasPermutations": [],
2370
2511
  "permutations": [
2371
- "agent:publish:authoring-bundle",
2372
- "publish:agent:authoring-bundle",
2373
- "publish:authoring-bundle:agent",
2374
- "agent:authoring-bundle:publish",
2375
- "authoring-bundle:agent:publish",
2376
- "authoring-bundle:publish:agent"
2512
+ "agent:preview:send",
2513
+ "preview:agent:send",
2514
+ "preview:send:agent",
2515
+ "agent:send:preview",
2516
+ "send:agent:preview",
2517
+ "send:preview:agent"
2377
2518
  ]
2378
2519
  },
2379
- "agent:test:create": {
2520
+ "agent:preview:sessions": {
2380
2521
  "aliases": [],
2381
2522
  "args": {},
2382
- "description": "To run this command, you must have an agent test spec file, which is a YAML file that lists the test cases for testing a specific agent. Use the \"agent generate test-spec\" CLI command to generate a test spec file. Then specify the file to this command with the --spec flag, or run this command with no flags to be prompted.\n\nWhen this command completes, your org contains the new agent test, which you can view and edit using the Testing Center UI (legacy) or Agentforce Studio (NGT). This command also retrieves the metadata component associated with the new test to your local Salesforce DX project and displays its filename. By default, the legacy AiEvaluationDefinition is created; use --test-runner agentforce-studio to author an AiTestingDefinition (NGT) instead.\n\nAfter you've created the test in the org, use the \"agent test run\" command to run it.",
2523
+ "description": "This command lists the agent preview sessions that were started with the \"agent preview start\" command and are still in the local cache. Use this command to discover specific session IDs that you can pass to the \"agent preview send\" or \"agent preview end\" commands with the --session-id flag.\n\nProgrammatic agent preview sessions can be started for both published activated agents and by using an agent's local authoring bundle, which contains its Agent Script file. In this command's output table, the Agent column contains either the API name of the authoring bundle or the published agent, whichever was used when starting the session. In the table, if the same API name has multiple rows with different session IDs, then it means that you previously started multiple preview sessions with the associated agent.",
2383
2524
  "examples": [
2384
- "Create an agent test interactively and be prompted for the test spec and API name of the test in the org; use the default org:\n<%= config.bin %> <%= command.id %>",
2385
- "Create an agent test and use flags to specify all required information; if a test with same API name already exists in the org, overwrite it without confirmation. Use the org with alias \"my-org\":\n<%= config.bin %> <%= command.id %> --spec specs/Resort_Manager-testSpec.yaml --api-name Resort_Manager_Test --force-overwrite --target-org my-org",
2386
- "Preview what the agent test metadata (AiEvaluationDefinition) looks like without deploying it to your default org:\n<%= config.bin %> <%= command.id %> --spec specs/Resort_Manager-testSpec.yaml --api-name Resort_Manager_Test --preview",
2387
- "Author an Agentforce Studio (NGT) test from an NGT-shaped YAML; writes an AiTestingDefinition metadata file:\n<%= config.bin %> <%= command.id %> --spec specs/ReturnsCheckout.ngt.yaml --api-name Returns_Checkout --test-runner agentforce-studio --target-org my-org"
2525
+ "List all cached agent preview sessions:\n<%= config.bin %> <%= command.id %>"
2388
2526
  ],
2389
2527
  "flags": {
2390
2528
  "json": {
@@ -2401,17 +2539,66 @@
2401
2539
  "hasDynamicHelp": false,
2402
2540
  "multiple": false,
2403
2541
  "type": "option"
2542
+ }
2543
+ },
2544
+ "hasDynamicHelp": false,
2545
+ "hiddenAliases": [],
2546
+ "id": "agent:preview:sessions",
2547
+ "pluginAlias": "@salesforce/plugin-agent",
2548
+ "pluginName": "@salesforce/plugin-agent",
2549
+ "pluginType": "core",
2550
+ "strict": true,
2551
+ "summary": "List all known programmatic agent preview sessions.",
2552
+ "enableJsonFlag": true,
2553
+ "requiresProject": true,
2554
+ "errorCodes": {
2555
+ "header": "ERROR CODES",
2556
+ "body": [
2557
+ {
2558
+ "name": "Succeeded (0)",
2559
+ "description": "Sessions listed successfully (or empty list if no active sessions)."
2560
+ }
2561
+ ]
2562
+ },
2563
+ "isESM": true,
2564
+ "relativePath": [
2565
+ "lib",
2566
+ "commands",
2567
+ "agent",
2568
+ "preview",
2569
+ "sessions.js"
2570
+ ],
2571
+ "aliasPermutations": [],
2572
+ "permutations": [
2573
+ "agent:preview:sessions",
2574
+ "preview:agent:sessions",
2575
+ "preview:sessions:agent",
2576
+ "agent:sessions:preview",
2577
+ "sessions:agent:preview",
2578
+ "sessions:preview:agent"
2579
+ ]
2580
+ },
2581
+ "agent:preview:start": {
2582
+ "aliases": [],
2583
+ "args": {},
2584
+ "description": "This command outputs a session ID that you then use with the \"agent preview send\" command to send an utterance to the agent. Use the \"agent preview sessions\" command to list all active sessions and the \"agent preview end\" command to end a specific session.\n\nIdentify the agent you want to start previewing with either the --authoring-bundle flag to specify a local authoring bundle's API name or --api-name to specify an activated published agent's API name. To find either API name, navigate to your package directory in your DX project. The API name of an authoring bundle is the same as its directory name under the \"aiAuthoringBundles\" metadata directory. Similarly, the published agent's API name is the same as its directory name under the \"Bots\" metadata directory.\n\nWhen starting a preview session with --authoring-bundle, you must explicitly specify the execution mode using one of these flags:\n\n- --use-live-actions: Executes real Apex classes, flows, and other actions in the org. This surfaces compile and validation errors during preview.\n- --simulate-actions: Uses AI to simulate action execution without calling real implementations.\n\nPublished agents (--api-name) always use live actions. The mode flags are optional and have no effect for published agents.",
2585
+ "examples": [
2586
+ "Start a programmatic agent preview session by specifying an authoring bundle; use simulated actions. Use the org with alias \"my-dev-org\":\n<%= config.bin %> <%= command.id %> --authoring-bundle My_Agent_Bundle --target-org my-dev-org --simulate-actions",
2587
+ "Similar to previous example but use live actions and the default org:\n<%= config.bin %> <%= command.id %> --authoring-bundle My_Agent_Bundle --use-live-actions",
2588
+ "Start a preview session with an activated published agent (always uses live actions):\n<%= config.bin %> <%= command.id %> --api-name My_Published_Agent"
2589
+ ],
2590
+ "flags": {
2591
+ "json": {
2592
+ "description": "Format output as json.",
2593
+ "helpGroup": "GLOBAL",
2594
+ "name": "json",
2595
+ "allowNo": false,
2596
+ "type": "boolean"
2404
2597
  },
2405
- "api-name": {
2406
- "name": "api-name",
2407
- "summary": "API name of the new test; the API name must not exist in the org.",
2408
- "hasDynamicHelp": false,
2409
- "multiple": false,
2410
- "type": "option"
2411
- },
2412
- "spec": {
2413
- "name": "spec",
2414
- "summary": "Path to the test spec YAML file.",
2598
+ "flags-dir": {
2599
+ "helpGroup": "GLOBAL",
2600
+ "name": "flags-dir",
2601
+ "summary": "Import flag values from a directory.",
2415
2602
  "hasDynamicHelp": false,
2416
2603
  "multiple": false,
2417
2604
  "type": "option"
@@ -2433,40 +2620,70 @@
2433
2620
  "multiple": false,
2434
2621
  "type": "option"
2435
2622
  },
2436
- "preview": {
2437
- "name": "preview",
2438
- "summary": "Preview the test metadata file without deploying to your org.",
2623
+ "api-name": {
2624
+ "char": "n",
2625
+ "name": "api-name",
2626
+ "summary": "API name of the activated published agent you want to preview.",
2627
+ "hasDynamicHelp": false,
2628
+ "multiple": false,
2629
+ "type": "option"
2630
+ },
2631
+ "authoring-bundle": {
2632
+ "name": "authoring-bundle",
2633
+ "summary": "API name of the authoring bundle metadata component that contains the agent's Agent Script file.",
2634
+ "hasDynamicHelp": false,
2635
+ "multiple": false,
2636
+ "type": "option"
2637
+ },
2638
+ "use-live-actions": {
2639
+ "exclusive": [
2640
+ "simulate-actions"
2641
+ ],
2642
+ "name": "use-live-actions",
2643
+ "summary": "Execute real actions in the org (Apex classes, flows, etc.). Required with --authoring-bundle.",
2439
2644
  "allowNo": false,
2440
2645
  "type": "boolean"
2441
2646
  },
2442
- "force-overwrite": {
2443
- "name": "force-overwrite",
2444
- "summary": "Don't prompt for confirmation when overwriting an existing test (based on API name) in your org.",
2647
+ "simulate-actions": {
2648
+ "exclusive": [
2649
+ "use-live-actions"
2650
+ ],
2651
+ "name": "simulate-actions",
2652
+ "summary": "Use AI to simulate action execution instead of calling real actions. Required with --authoring-bundle.",
2445
2653
  "allowNo": false,
2446
2654
  "type": "boolean"
2447
2655
  },
2448
- "test-runner": {
2449
- "description": "By default, the command automatically detects which test runner to use based on the test definition metadata type in your org. Use this flag to explicitly specify the runner type. 'agentforce-studio' uses AiTestingDefinition metadata. 'testing-center' uses AiEvaluationDefinition metadata.",
2450
- "name": "test-runner",
2451
- "summary": "Explicitly specify which test runner to use (agentforce-studio or testing-center).",
2656
+ "context-variables": {
2657
+ "description": "Sets variables on the agent preview session, mirroring what the in-org Agentforce Builder UI does when you override variables before sending a message. Specify this flag multiple times or use comma-separated values. Two namespaces are supported, distinguished by the name shape. Names pass through to the runtime verbatim — the CLI doesn't transform them.\n\nLinked context variables use the \"$Context.\" prefix. These map to externally-provided fields that the runtime resolves (declared in the bundle's globalConfiguration.contextVariables) and are read by live actions and topic-routing expressions via $Context.Name. Example: $Context.MyLinkedVar=some-value.\n\nState variables use the bare developerName, no prefix. These seed mutable agent state declared in agentVersion.stateVariables. Example: MyStateVar=some-value.\n\nBoth namespaces can be mixed in one value. Example: --context-variables '$Context.MyLinkedVar=foo,MyStateVar=bar'.\n\nTips: (1) Quote the whole value in single quotes so $Context isn't shell-expanded. (2) Names are sent verbatim — a bare name is treated as a state variable, not a linked context variable, so live actions that bind via $Context.Name will see null. (3) Type defaults to Text.",
2658
+ "name": "context-variables",
2659
+ "summary": "Session variables for the agent preview session, in the form Name=Value.",
2660
+ "delimiter": ",",
2452
2661
  "hasDynamicHelp": false,
2453
- "multiple": false,
2454
- "options": [
2455
- "agentforce-studio",
2456
- "testing-center"
2662
+ "multiple": true,
2663
+ "type": "option"
2664
+ },
2665
+ "agent-json": {
2666
+ "dependsOn": [
2667
+ "authoring-bundle"
2457
2668
  ],
2669
+ "hidden": true,
2670
+ "name": "agent-json",
2671
+ "summary": "Path to a pre-compiled AgentJSON file to use instead of compiling the Agent Script file. Intended for internal use and testing.",
2672
+ "hasDynamicHelp": false,
2673
+ "multiple": false,
2458
2674
  "type": "option"
2459
2675
  }
2460
2676
  },
2461
2677
  "hasDynamicHelp": true,
2462
2678
  "hiddenAliases": [],
2463
- "id": "agent:test:create",
2679
+ "id": "agent:preview:start",
2464
2680
  "pluginAlias": "@salesforce/plugin-agent",
2465
2681
  "pluginName": "@salesforce/plugin-agent",
2466
2682
  "pluginType": "core",
2467
2683
  "strict": true,
2468
- "summary": "Create an agent test in your org using a local test spec YAML file.",
2684
+ "summary": "Start a programmatic agent preview session.",
2469
2685
  "enableJsonFlag": true,
2686
+ "requiresProject": true,
2470
2687
  "envVariablesSection": {
2471
2688
  "header": "ENVIRONMENT VARIABLES",
2472
2689
  "body": [
@@ -2481,19 +2698,23 @@
2481
2698
  "body": [
2482
2699
  {
2483
2700
  "name": "Succeeded (0)",
2484
- "description": "Test created and deployed successfully."
2701
+ "description": "Preview session started successfully."
2485
2702
  },
2486
2703
  {
2487
2704
  "name": "Failed (1)",
2488
- "description": "Test validation errors or metadata format issues."
2705
+ "description": "Agent Script compilation failed (syntax errors in the script)."
2489
2706
  },
2490
2707
  {
2491
2708
  "name": "NotFound (2)",
2492
- "description": "Test spec file not found or org connection failed."
2709
+ "description": "Agent not found, or compilation API returned HTTP 404 (endpoint may not be available in your org or region)."
2493
2710
  },
2494
2711
  {
2495
- "name": "DeploymentFailed (4)",
2496
- "description": "Deployment failed due to API or network errors."
2712
+ "name": "ServerError (3)",
2713
+ "description": "Compilation API returned HTTP 500 (server error during compilation)."
2714
+ },
2715
+ {
2716
+ "name": "PreviewStartFailed (4)",
2717
+ "description": "Preview session failed to start due to API or network errors."
2497
2718
  }
2498
2719
  ]
2499
2720
  },
@@ -2502,26 +2723,28 @@
2502
2723
  "lib",
2503
2724
  "commands",
2504
2725
  "agent",
2505
- "test",
2506
- "create.js"
2726
+ "preview",
2727
+ "start.js"
2507
2728
  ],
2508
2729
  "aliasPermutations": [],
2509
2730
  "permutations": [
2510
- "agent:test:create",
2511
- "test:agent:create",
2512
- "test:create:agent",
2513
- "agent:create:test",
2514
- "create:agent:test",
2515
- "create:test:agent"
2731
+ "agent:preview:start",
2732
+ "preview:agent:start",
2733
+ "preview:start:agent",
2734
+ "agent:start:preview",
2735
+ "start:agent:preview",
2736
+ "start:preview:agent"
2516
2737
  ]
2517
2738
  },
2518
- "agent:test:list": {
2739
+ "agent:publish:authoring-bundle": {
2519
2740
  "aliases": [],
2520
2741
  "args": {},
2521
- "description": "The command outputs a table with the name (API name) of each test along with its unique ID, type ('agentforce-studio' or 'testing-center'), and the date it was created in the org.",
2742
+ "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\nWhen you publish an authoring bundle to your org, a number of things happen. First, this command validates that the Agent Script file successfully compiles. If there are compilation errors, the command exits and you must fix the Agent Script file to continue. Once the Agent Script file compiles, then it's published to the org, which in turn creates new associated metadata (Bot, BotVersion, GenAiX), or new versions of the metadata if the agent already exists. The new or updated metadata is retrieved back to your DX project; specify the --skip-retrieve flag to skip this step. Finally, the authoring bundle metadata (AiAuthoringBundle) is deployed to your org.\n\nThis command uses the API name of the authoring bundle.",
2522
2743
  "examples": [
2523
- "List the agent tests in your default org:\n<%= config.bin %> <%= command.id %>",
2524
- "List the agent tests in an org with alias \"my-org\"\"\n<%= config.bin %> <%= command.id %> --target-org my-org"
2744
+ "Publish an authoring bundle by being prompted for its API name; use your default org:\n<%= config.bin %> <%= command.id %>",
2745
+ "Publish an authoring bundle with API name MyAuthoringBundle to the org with alias \"my-dev-org\":\n<%= config.bin %> <%= command.id %> --api-name MyAuthoringbundle --target-org my-dev-org",
2746
+ "Publish with verbose output to see all retrieved and deployed metadata components:\n<%= config.bin %> <%= command.id %> --api-name MyAuthoringbundle --verbose",
2747
+ "Publish with concise output showing only essential information:\n<%= config.bin %> <%= command.id %> --api-name MyAuthoringbundle --concise"
2525
2748
  ],
2526
2749
  "flags": {
2527
2750
  "json": {
@@ -2555,65 +2778,99 @@
2555
2778
  "hasDynamicHelp": false,
2556
2779
  "multiple": false,
2557
2780
  "type": "option"
2781
+ },
2782
+ "api-name": {
2783
+ "char": "n",
2784
+ "name": "api-name",
2785
+ "summary": "API name of the authoring bundle you want to publish; if not specified, the command provides a list that you can choose from.",
2786
+ "hasDynamicHelp": false,
2787
+ "multiple": false,
2788
+ "type": "option"
2789
+ },
2790
+ "skip-retrieve": {
2791
+ "name": "skip-retrieve",
2792
+ "summary": "Don't retrieve the metadata associated with the agent to your DX project.",
2793
+ "allowNo": false,
2794
+ "type": "boolean"
2795
+ },
2796
+ "verbose": {
2797
+ "char": "v",
2798
+ "exclusive": [
2799
+ "concise"
2800
+ ],
2801
+ "name": "verbose",
2802
+ "summary": "Display detailed output showing all metadata components retrieved and deployed during the publish process.",
2803
+ "allowNo": false,
2804
+ "type": "boolean"
2805
+ },
2806
+ "concise": {
2807
+ "exclusive": [
2808
+ "verbose"
2809
+ ],
2810
+ "name": "concise",
2811
+ "summary": "Display minimal output with only essential information about the publish operation.",
2812
+ "allowNo": false,
2813
+ "type": "boolean"
2558
2814
  }
2559
2815
  },
2560
2816
  "hasDynamicHelp": true,
2561
2817
  "hiddenAliases": [],
2562
- "id": "agent:test:list",
2818
+ "id": "agent:publish:authoring-bundle",
2563
2819
  "pluginAlias": "@salesforce/plugin-agent",
2564
2820
  "pluginName": "@salesforce/plugin-agent",
2565
2821
  "pluginType": "core",
2566
2822
  "strict": true,
2567
- "summary": "List the available agent tests in your org.",
2823
+ "summary": "Publish an authoring bundle to your org, which results in a new agent or a new version of an existing agent.",
2568
2824
  "enableJsonFlag": true,
2569
- "envVariablesSection": {
2570
- "header": "ENVIRONMENT VARIABLES",
2571
- "body": [
2572
- {
2573
- "name": "SF_TARGET_ORG",
2574
- "description": "Username or alias of your default org. Overrides the target-org configuration variable."
2575
- }
2576
- ]
2577
- },
2825
+ "requiresProject": true,
2578
2826
  "errorCodes": {
2579
2827
  "header": "ERROR CODES",
2580
2828
  "body": [
2581
2829
  {
2582
2830
  "name": "Succeeded (0)",
2583
- "description": "Agent tests listed successfully."
2831
+ "description": "Agent published successfully without errors."
2584
2832
  },
2585
2833
  {
2586
- "name": "Failed (4)",
2587
- "description": "Failed to retrieve agent tests due to API or network errors."
2834
+ "name": "Failed (1)",
2835
+ "description": "Compilation errors found in the Agent Script file."
2588
2836
  }
2589
2837
  ]
2590
2838
  },
2839
+ "FLAGGABLE_PROMPTS": {
2840
+ "api-name": {
2841
+ "message": "API name of the authoring bundle you want to publish; if not specified, the command provides a list that you can choose from.",
2842
+ "promptMessage": "API name of the authoring bundle to publish"
2843
+ }
2844
+ },
2591
2845
  "isESM": true,
2592
2846
  "relativePath": [
2593
2847
  "lib",
2594
2848
  "commands",
2595
2849
  "agent",
2596
- "test",
2597
- "list.js"
2850
+ "publish",
2851
+ "authoring-bundle.js"
2598
2852
  ],
2599
2853
  "aliasPermutations": [],
2600
2854
  "permutations": [
2601
- "agent:test:list",
2602
- "test:agent:list",
2603
- "test:list:agent",
2604
- "agent:list:test",
2605
- "list:agent:test",
2606
- "list:test:agent"
2855
+ "agent:publish:authoring-bundle",
2856
+ "publish:agent:authoring-bundle",
2857
+ "publish:authoring-bundle:agent",
2858
+ "agent:authoring-bundle:publish",
2859
+ "authoring-bundle:agent:publish",
2860
+ "authoring-bundle:publish:agent"
2607
2861
  ]
2608
2862
  },
2609
- "agent:test:results": {
2863
+ "agent:trace:delete": {
2610
2864
  "aliases": [],
2611
2865
  "args": {},
2612
- "description": "This command requires a job ID, which the original \"agent test run\" command displays when it completes. You can also use the --use-most-recent flag to see results for the most recently run agent test.\n\nBy default, this command outputs test results in human-readable tables for each test case. The tables show whether the test case passed, the expected and actual values, the test score, how long the test took, and more. Use the --result-format to display the test results in JSON or Junit format. Use the --output-dir flag to write the results to a file rather than to the terminal.",
2866
+ "description": "When you run an agent preview conversation (either interactive or programmatic), trace files are automatically recorded and saved in your local DX project. Use this command to delete some or all of the trace files.\n\nBy default, this command shows a preview of what will be deleted and prompts for confirmation. Use --no-prompt to skip confirmation.\n\nWithout filters, this comamnd deletes all trace files for all agents and sessions. Use flags to narrow the scope: filter by agent API name (--agent), by session (--session-id), or by age (--older-than).",
2613
2867
  "examples": [
2614
- "Get the results of an agent test run in your default org using its job ID:\n<%= config.bin %> <%= command.id %> --job-id 4KBfake0000003F4AQ",
2615
- "Get the results of the most recently run agent test in an org with alias \"my-org\":\n<%= config.bin %> <%= command.id %> --use-most-recent --target-org my-org",
2616
- "Get the results of the most recently run agent test in your default org, and write the JSON-formatted results into a directory called \"test-results\":\n<%= config.bin %> <%= command.id %> --use-most-recent --output-dir ./test-results --result-format json"
2868
+ "Delete all traces for all agents and sessions; prompt for confirmation:\n<%= config.bin %> <%= command.id %>",
2869
+ "Delete all traces for a specific agent:\n<%= config.bin %> <%= command.id %> --agent My_Agent",
2870
+ "Delete traces from a specific session:\n<%= config.bin %> <%= command.id %> --session-id <SESSION_ID>",
2871
+ "Delete traces older than 7 days:\n<%= config.bin %> <%= command.id %> --older-than 7d",
2872
+ "Delete traces older than 24 hours for a specific agent; don't prompt for confirmation:\n<%= config.bin %> <%= command.id %> --agent My_Agent --older-than 24h --no-prompt",
2873
+ "Delete all traces for all agents and sessions; don't prompt for confirmation:\n<%= config.bin %> <%= command.id %> --no-prompt"
2617
2874
  ],
2618
2875
  "flags": {
2619
2876
  "json": {
@@ -2631,107 +2888,51 @@
2631
2888
  "multiple": false,
2632
2889
  "type": "option"
2633
2890
  },
2634
- "target-org": {
2635
- "char": "o",
2636
- "name": "target-org",
2637
- "noCacheDefault": true,
2638
- "required": true,
2639
- "summary": "Username or alias of the target org. Not required if the `target-org` configuration variable is already set.",
2640
- "hasDynamicHelp": true,
2641
- "multiple": false,
2642
- "type": "option"
2643
- },
2644
- "api-version": {
2645
- "description": "Override the api version used for api requests made by this command",
2646
- "name": "api-version",
2647
- "hasDynamicHelp": false,
2648
- "multiple": false,
2649
- "type": "option"
2650
- },
2651
- "job-id": {
2652
- "char": "i",
2653
- "name": "job-id",
2654
- "required": true,
2655
- "summary": "Job ID of the completed agent test run.",
2656
- "hasDynamicHelp": false,
2657
- "multiple": false,
2658
- "type": "option"
2659
- },
2660
- "result-format": {
2661
- "name": "result-format",
2662
- "summary": "Format of the agent test run results.",
2663
- "default": "human",
2891
+ "agent": {
2892
+ "char": "a",
2893
+ "name": "agent",
2894
+ "summary": "API name of the agent used to filter the list of trace files you want to delete. Matches against the API name used when starting the session, either an authoring bundle or a published agent API name.",
2664
2895
  "hasDynamicHelp": false,
2665
2896
  "multiple": false,
2666
- "options": [
2667
- "json",
2668
- "human",
2669
- "junit",
2670
- "tap"
2671
- ],
2672
2897
  "type": "option"
2673
2898
  },
2674
- "output-dir": {
2675
- "char": "d",
2676
- "description": "If the agent test run completes, write the results to the specified directory. If the test is still running, the test results aren't written.",
2677
- "name": "output-dir",
2678
- "summary": "Directory to write the agent test results into.",
2899
+ "session-id": {
2900
+ "name": "session-id",
2901
+ "summary": "Session ID used to filter the list of trace files you want to delete. Use the \"agent preview sessions\" CLI command to list all known agent preview sessions along with their session IDs.",
2679
2902
  "hasDynamicHelp": false,
2680
2903
  "multiple": false,
2681
2904
  "type": "option"
2682
2905
  },
2683
- "test-runner": {
2684
- "description": "By default, the command automatically detects which test runner to use based on the test definition metadata type in your org. Use this flag to explicitly specify the runner type. 'agentforce-studio' uses AiTestingDefinition metadata. 'testing-center' uses AiEvaluationDefinition metadata.",
2685
- "name": "test-runner",
2686
- "summary": "Explicitly specify which test runner to use (agentforce-studio or testing-center).",
2906
+ "older-than": {
2907
+ "name": "older-than",
2908
+ "summary": "Duration used to filter the list of trace files; only files older than the duration are deleted. Accepts a number followed by a unit: m/minutes, h/hours, d/days, w/weeks. Examples: 7d, 24h, 2w.",
2687
2909
  "hasDynamicHelp": false,
2688
2910
  "multiple": false,
2689
- "options": [
2690
- "agentforce-studio",
2691
- "testing-center"
2692
- ],
2693
2911
  "type": "option"
2694
2912
  },
2695
- "verbose": {
2696
- "description": "When enabled, includes detailed generated data (such as invoked actions) in the human-readable test results output. This is useful for debugging test failures and understanding what actions were actually invoked during the test run.\n\nThe generated data is in JSON format and includes the Apex classes or Flows that were invoked, the Salesforce objects that were touched, and so on. Use the JSON structure of this information to build the test case JSONPath expression when using custom evaluations.",
2697
- "name": "verbose",
2698
- "summary": "Show generated data in the test results output.",
2913
+ "no-prompt": {
2914
+ "name": "no-prompt",
2915
+ "summary": "Skip the confirmation prompt and delete immediately.",
2699
2916
  "allowNo": false,
2700
2917
  "type": "boolean"
2701
2918
  }
2702
2919
  },
2703
- "hasDynamicHelp": true,
2920
+ "hasDynamicHelp": false,
2704
2921
  "hiddenAliases": [],
2705
- "id": "agent:test:results",
2922
+ "id": "agent:trace:delete",
2706
2923
  "pluginAlias": "@salesforce/plugin-agent",
2707
2924
  "pluginName": "@salesforce/plugin-agent",
2708
2925
  "pluginType": "core",
2709
2926
  "strict": true,
2710
- "summary": "Get the results of a completed agent test run.",
2927
+ "summary": "Delete trace files from an agent preview session.",
2711
2928
  "enableJsonFlag": true,
2712
- "envVariablesSection": {
2713
- "header": "ENVIRONMENT VARIABLES",
2714
- "body": [
2715
- {
2716
- "name": "SF_TARGET_ORG",
2717
- "description": "Username or alias of your default org. Overrides the target-org configuration variable."
2718
- }
2719
- ]
2720
- },
2929
+ "requiresProject": true,
2721
2930
  "errorCodes": {
2722
2931
  "header": "ERROR CODES",
2723
2932
  "body": [
2724
2933
  {
2725
2934
  "name": "Succeeded (0)",
2726
- "description": "Results retrieved successfully. Test results (passed/failed) are in the output."
2727
- },
2728
- {
2729
- "name": "NotFound (2)",
2730
- "description": "Job ID not found or invalid."
2731
- },
2732
- {
2733
- "name": "Failed (4)",
2734
- "description": "Failed to retrieve results due to API or network errors."
2935
+ "description": "Traces deleted successfully (or no traces matched)."
2735
2936
  }
2736
2937
  ]
2737
2938
  },
@@ -2740,27 +2941,31 @@
2740
2941
  "lib",
2741
2942
  "commands",
2742
2943
  "agent",
2743
- "test",
2744
- "results.js"
2944
+ "trace",
2945
+ "delete.js"
2745
2946
  ],
2746
2947
  "aliasPermutations": [],
2747
2948
  "permutations": [
2748
- "agent:test:results",
2749
- "test:agent:results",
2750
- "test:results:agent",
2751
- "agent:results:test",
2752
- "results:agent:test",
2753
- "results:test:agent"
2949
+ "agent:trace:delete",
2950
+ "trace:agent:delete",
2951
+ "trace:delete:agent",
2952
+ "agent:delete:trace",
2953
+ "delete:agent:trace",
2954
+ "delete:trace:agent"
2754
2955
  ]
2755
2956
  },
2756
- "agent:test:resume": {
2957
+ "agent:trace:list": {
2757
2958
  "aliases": [],
2758
2959
  "args": {},
2759
- "description": "This command requires a job ID, which the original \"agent test run\" command displays when it completes. You can also use the --use-most-recent flag to see results for the most recently run agent test.\n\nUse the --wait flag to specify the number of minutes for this command to wait for the agent test to complete; if the test completes by the end of the wait time, the command displays the test results. If not, the CLI returns control of the terminal to you, and you must run \"agent test resume\" again.\n\nBy default, this command outputs test results in human-readable tables for each test case. The tables show whether the test case passed, the expected and actual values, the test score, how long the test took, and more. Use the --result-format to display the test results in JSON or Junit format. Use the --output-dir flag to write the results to a file rather than to the terminal.",
2960
+ "description": "When you run an agent preview conversation (either interactive or programmatic), trace files are automatically recorded and saved in your local DX project. By default, this command lists all trace files for all agents and all of their sessions. Use flags to narrow results: filter by agent name (--agent), by session (--session-id), or by date (--since).\n\nEach row in the output corresponds to one trace file, which in turn corresponds to one agent session. The Agent column shows the authoring bundle or API name used when starting the session.",
2760
2961
  "examples": [
2761
- "Resume an agent test in your default org using a job ID:\n<%= config.bin %> <%= command.id %> --job-id 4KBfake0000003F4AQ",
2762
- "Resume the most recently-run agent test in an org with alias \"my-org\" org; wait 10 minutes for the tests to finish:\n<%= config.bin %> <%= command.id %> --use-most-recent --wait 10 --target-org my-org",
2763
- "Resume the most recent agent test in your default org, and write the JSON-formatted results into a directory called \"test-results\":\n<%= config.bin %> <%= command.id %> --use-most-recent --output-dir ./test-results --result-format json"
2962
+ "List all trace files for all agents and sessions:\n<%= config.bin %> <%= command.id %>",
2963
+ "List all trace files for a specific agent:\n<%= config.bin %> <%= command.id %> --agent My_Agent",
2964
+ "List trace files for a specific session:\n<%= config.bin %> <%= command.id %> --session-id <SESSION_ID>",
2965
+ "List trace files recorded on or after April 20, 2026 (date-only, interpreted as UTC midnight):\n<%= config.bin %> <%= command.id %> --since 2026-04-20",
2966
+ "List trace files recorded on or after a specific UTC time:\n<%= config.bin %> <%= command.id %> --since 2026-04-20T14:00:00Z",
2967
+ "Filter by agent and date together:\n<%= config.bin %> <%= command.id %> --agent My_Agent --since 2026-04-20",
2968
+ "Return results as JSON:\n<%= config.bin %> <%= command.id %> --json"
2764
2969
  ],
2765
2970
  "flags": {
2766
2971
  "json": {
@@ -2778,126 +2983,46 @@
2778
2983
  "multiple": false,
2779
2984
  "type": "option"
2780
2985
  },
2781
- "target-org": {
2782
- "char": "o",
2783
- "name": "target-org",
2784
- "noCacheDefault": true,
2785
- "required": true,
2786
- "summary": "Username or alias of the target org. Not required if the `target-org` configuration variable is already set.",
2787
- "hasDynamicHelp": true,
2788
- "multiple": false,
2789
- "type": "option"
2790
- },
2791
- "api-version": {
2792
- "description": "Override the api version used for api requests made by this command",
2793
- "name": "api-version",
2794
- "hasDynamicHelp": false,
2795
- "multiple": false,
2796
- "type": "option"
2797
- },
2798
- "job-id": {
2799
- "char": "i",
2800
- "name": "job-id",
2801
- "summary": "Job ID of the original agent test run.",
2802
- "hasDynamicHelp": false,
2803
- "multiple": false,
2804
- "type": "option"
2805
- },
2806
- "use-most-recent": {
2807
- "char": "r",
2808
- "name": "use-most-recent",
2809
- "summary": "Use the job ID of the most recent agent test run.",
2810
- "allowNo": false,
2811
- "type": "boolean"
2812
- },
2813
- "wait": {
2814
- "char": "w",
2815
- "name": "wait",
2816
- "summary": "Number of minutes to wait for the command to complete and display results to the terminal window.",
2817
- "default": "5 minutes",
2818
- "hasDynamicHelp": true,
2819
- "multiple": false,
2820
- "type": "option"
2821
- },
2822
- "result-format": {
2823
- "name": "result-format",
2824
- "summary": "Format of the agent test run results.",
2825
- "default": "human",
2986
+ "session-id": {
2987
+ "name": "session-id",
2988
+ "summary": "Session ID used to filter the list of trace files. Use the \"agent preview sessions\" CLI command to list all known agent preview sessions along with their session IDs.",
2826
2989
  "hasDynamicHelp": false,
2827
2990
  "multiple": false,
2828
- "options": [
2829
- "json",
2830
- "human",
2831
- "junit",
2832
- "tap"
2833
- ],
2834
2991
  "type": "option"
2835
2992
  },
2836
- "output-dir": {
2837
- "char": "d",
2838
- "description": "If the agent test run completes, write the results to the specified directory. If the test is still running, the test results aren't written.",
2839
- "name": "output-dir",
2840
- "summary": "Directory to write the agent test results into.",
2993
+ "agent": {
2994
+ "char": "a",
2995
+ "name": "agent",
2996
+ "summary": "API name of the agent used to filter the list of available trace files. Matches against the API name used when starting the session, either an authoring bundle or a published agent API name.",
2841
2997
  "hasDynamicHelp": false,
2842
2998
  "multiple": false,
2843
2999
  "type": "option"
2844
3000
  },
2845
- "test-runner": {
2846
- "description": "By default, the command automatically detects which test runner to use based on the test definition metadata type in your org. Use this flag to explicitly specify the runner type. 'agentforce-studio' uses AiTestingDefinition metadata. 'testing-center' uses AiEvaluationDefinition metadata.",
2847
- "name": "test-runner",
2848
- "summary": "Explicitly specify which test runner to use (agentforce-studio or testing-center).",
3001
+ "since": {
3002
+ "description": "Accepts ISO 8601 format: date-only (2026-04-20), date-time (2026-04-20T14:00:00Z), or date-time with milliseconds (2026-04-20T14:00:00.000Z). The \"Recorded At\" values shown in the table output are valid inputs.",
3003
+ "name": "since",
3004
+ "summary": "Date used to filter the list of trace files; only those recorded on or after the date are listed.",
2849
3005
  "hasDynamicHelp": false,
2850
3006
  "multiple": false,
2851
- "options": [
2852
- "agentforce-studio",
2853
- "testing-center"
2854
- ],
2855
3007
  "type": "option"
2856
- },
2857
- "verbose": {
2858
- "description": "When enabled, includes detailed generated data (such as invoked actions) in the human-readable test results output. This is useful for debugging test failures and understanding what actions were actually invoked during the test run.\n\nThe generated data is in JSON format and includes the Apex classes or Flows that were invoked, the Salesforce objects that were touched, and so on. Use the JSON structure of this information to build the test case JSONPath expression when using custom evaluations.",
2859
- "name": "verbose",
2860
- "summary": "Show generated data in the test results output.",
2861
- "allowNo": false,
2862
- "type": "boolean"
2863
3008
  }
2864
3009
  },
2865
- "hasDynamicHelp": true,
3010
+ "hasDynamicHelp": false,
2866
3011
  "hiddenAliases": [],
2867
- "id": "agent:test:resume",
3012
+ "id": "agent:trace:list",
2868
3013
  "pluginAlias": "@salesforce/plugin-agent",
2869
3014
  "pluginName": "@salesforce/plugin-agent",
2870
3015
  "pluginType": "core",
2871
3016
  "strict": true,
2872
- "summary": "Resume an agent test that you previously started in your org so you can view the test results.",
3017
+ "summary": "List the available trace files that were recorded during all agent preview sessions.",
2873
3018
  "enableJsonFlag": true,
2874
- "envVariablesSection": {
2875
- "header": "ENVIRONMENT VARIABLES",
2876
- "body": [
2877
- {
2878
- "name": "SF_TARGET_ORG",
2879
- "description": "Username or alias of your default org. Overrides the target-org configuration variable."
2880
- }
2881
- ]
2882
- },
3019
+ "requiresProject": true,
2883
3020
  "errorCodes": {
2884
3021
  "header": "ERROR CODES",
2885
3022
  "body": [
2886
3023
  {
2887
3024
  "name": "Succeeded (0)",
2888
- "description": "Test completed successfully (with test results in the output)."
2889
- },
2890
- {
2891
- "name": "Failed (1)",
2892
- "description": "Tests encountered execution errors (test cases with ERROR status)."
2893
- },
2894
- {
2895
- "name": "NotFound (2)",
2896
- "description": "Job ID not found or invalid."
2897
- },
2898
- {
2899
- "name": "OperationFailed (4)",
2900
- "description": "Failed to poll test due to API or network errors."
3025
+ "description": "Trace files listed successfully (or empty list if none found)."
2901
3026
  }
2902
3027
  ]
2903
3028
  },
@@ -2906,30 +3031,31 @@
2906
3031
  "lib",
2907
3032
  "commands",
2908
3033
  "agent",
2909
- "test",
2910
- "resume.js"
3034
+ "trace",
3035
+ "list.js"
2911
3036
  ],
2912
3037
  "aliasPermutations": [],
2913
3038
  "permutations": [
2914
- "agent:test:resume",
2915
- "test:agent:resume",
2916
- "test:resume:agent",
2917
- "agent:resume:test",
2918
- "resume:agent:test",
2919
- "resume:test:agent"
3039
+ "agent:trace:list",
3040
+ "trace:agent:list",
3041
+ "trace:list:agent",
3042
+ "agent:list:trace",
3043
+ "list:agent:trace",
3044
+ "list:trace:agent"
2920
3045
  ]
2921
3046
  },
2922
- "agent:test:run-eval": {
3047
+ "agent:trace:read": {
2923
3048
  "aliases": [],
2924
3049
  "args": {},
2925
- "description": "Specify the tests you want to run with one of these inputs to the --spec flag:\n\n- YAML test spec generated by the `agent generate test-spec` CLI command\n- JSON payload\n\nWhen you provide a YAML test spec, this command automatically translates test cases into internal state-based evaluation framework calls and infers the agent name from the test spec's `subjectName` field. As a result, you can use the same test spec with both the `agent test run` and `agent test run-eval` commands. YAML test specs also support context variables, which allow you to inject contextual data (such as CaseId or RoutableId) into agent sessions for testing with different contexts.\n\nWhen you provide a JSON payload, it's sent directly to the evaluation framework with optional normalization. The normalizer auto-corrects common field name mistakes, converts shorthand references to JSONPath, and injects defaults. Use `--no-normalize` to disable this auto-normalization. JSON payloads can also include context_variables on agent.create_session steps for the same contextual testing capabilities as when you use a YAML test spec.\n\nThis command supports more than 8 evaluator types, including subagent routing assertions, action invocation checks, string/numeric assertions, semantic similarity scoring, and LLM-based quality ratings.",
3050
+ "description": "When you run an agent preview conversation (either interactive or programmatic), trace files are automatically recorded and saved in your local DX project. Each turn (utterance or response) of a conversation creates trace data. Use this command to view trace data for a specific preview session, so you can then analyze the trace data to observe, monitor, investigate, and troubleshoot agent events and behavior.\n\nUse the --format flag to specify one of these formats of the outputted trace data:\n\n- summary (Default): A per-turn narrative showing topic routing, actions executed, and the agent's response. Use this to quickly understand what happened in a preview session.\n- detail: Diagnostic drill-down into a specific dimension. Filters output to only the trace steps relevant to that dimension, minimizing noise.\n- raw: Unprocessed trace JSON. Use this as a fallback when the trace schema has changed or you need to perform custom analysis.\n\nIf you specify \"--format detail\", you must also specify a dimension with the --dimension flag. Dimensions are a way to slice and analyze the agent execution trace from a specific angle or concern. Instead of looking at the raw sequence of everything that happened, each dimension filters and organizes the trace data to answer a specific type of question. These are the available dimensions and the information they provide:\n\n- actions: The actions the agent executed. Includes action name, input parameters, output, and latency. Use this dimension to understand what the agent actually did when answering an utterance in the preview session.\n- grounding: The reasoning steps used by the LLM. Use this dimension to see how the agent \"thought\" about the problem - the AI reasoning that determined which actions to take.\n- routing: How the agent navigated between subagents. Use this dimension to understand conversation flow - when and why the agent switched between different subagents or contexts during the conversation.\n- errors: Aggregates all errors during the session. Use this dimension to quickly identify and debug issues across all steps.",
2926
3051
  "examples": [
2927
- "Run tests using a YAML test spec on the org with alias \"my-org\":\n<%= config.bin %> <%= command.id %> --spec specs/my-agent-testSpec.yaml --target-org my-org",
2928
- "Run tests using a YAML spec with explicit agent name override; use your default org:\n<%= config.bin %> <%= command.id %> --spec specs/my-agent-testSpec.yaml --api-name My_Agent",
2929
- "Run tests using a JSON payload:\n<%= config.bin %> <%= command.id %> --spec specs/eval-payload.json --target-org my-org",
2930
- "Run tests and output results in JUnit format; useful for continuous integration and deployment (CI/CD):\n<%= config.bin %> <%= command.id %> --spec specs/my-agent-testSpec.yaml --target-org my-org --result-format junit",
2931
- "Run tests with contextVariables to inject contextual data into agent sessions (add contextVariables to test cases in your YAML spec):\n<%= config.bin %> <%= command.id %> --spec specs/agent-with-context.yaml --target-org my-org",
2932
- "Pipe JSON payload from stdin (--spec flag is automatically populated from stdin):\n$ echo '{\"tests\":[...]}' | <%= config.bin %> <%= command.id %> --spec --target-org my-org"
3052
+ "Show a session trace summary for all turns in the session with the specified ID:\n<%= config.bin %> <%= command.id %> --session-id <SESSION_ID>",
3053
+ "Show a trace summary for the second turn (utterance or response) of the conversation:\n<%= config.bin %> <%= command.id %> --session-id <SESSION_ID> --turn 2",
3054
+ "Drill into action execution across all turns:\n<%= config.bin %> <%= command.id %> --session-id <SESSION_ID> --format detail --dimension actions",
3055
+ "Drill into routing decisions for the first turn of the conversation:\n<%= config.bin %> <%= command.id %> --session-id <SESSION_ID> --format detail --dimension routing --turn 1",
3056
+ "Show all errors across the session:\n<%= config.bin %> <%= command.id %> --session-id <SESSION_ID> --format detail --dimension errors",
3057
+ "Output raw trace JSON for custom parsing:\n<%= config.bin %> <%= command.id %> --session-id <SESSION_ID> --format raw",
3058
+ "Return results as JSON:\n<%= config.bin %> <%= command.id %> --session-id <SESSION_ID> --json"
2933
3059
  ],
2934
3060
  "flags": {
2935
3061
  "json": {
@@ -2947,135 +3073,89 @@
2947
3073
  "multiple": false,
2948
3074
  "type": "option"
2949
3075
  },
2950
- "target-org": {
2951
- "char": "o",
2952
- "name": "target-org",
2953
- "noCacheDefault": true,
2954
- "required": true,
2955
- "summary": "Username or alias of the target org. Not required if the `target-org` configuration variable is already set.",
2956
- "hasDynamicHelp": true,
2957
- "multiple": false,
2958
- "type": "option"
2959
- },
2960
- "api-version": {
2961
- "description": "Override the api version used for api requests made by this command",
2962
- "name": "api-version",
2963
- "hasDynamicHelp": false,
2964
- "multiple": false,
2965
- "type": "option"
2966
- },
2967
- "spec": {
3076
+ "session-id": {
2968
3077
  "char": "s",
2969
- "name": "spec",
3078
+ "name": "session-id",
2970
3079
  "required": true,
2971
- "summary": "Path to test spec file (YAML or JSON). Supports reading from stdin when piping content.",
3080
+ "summary": "Session ID to read traces for. Use the \"agent preview sessions\" CLI command to list all known agent preview sessions along with their session IDs",
2972
3081
  "hasDynamicHelp": false,
2973
3082
  "multiple": false,
2974
3083
  "type": "option"
2975
3084
  },
2976
- "api-name": {
2977
- "char": "n",
2978
- "name": "api-name",
2979
- "summary": "Agent API name (also called DeveloperName) used to resolve agent_id and agent_version_id. Auto-inferred from the YAML spec's subjectName.",
3085
+ "format": {
3086
+ "char": "f",
3087
+ "name": "format",
3088
+ "summary": "Output format of the trace data; specifies the level of detail you want in the trace files.",
3089
+ "default": "summary",
2980
3090
  "hasDynamicHelp": false,
2981
3091
  "multiple": false,
3092
+ "options": [
3093
+ "summary",
3094
+ "detail",
3095
+ "raw"
3096
+ ],
2982
3097
  "type": "option"
2983
3098
  },
2984
- "result-format": {
2985
- "name": "result-format",
2986
- "summary": "Format of the agent test run results.",
2987
- "default": "human",
3099
+ "dimension": {
3100
+ "char": "d",
3101
+ "name": "dimension",
3102
+ "summary": "Dimension to drill into when using \"--format detail\"; used to filter and organize the trace data to answer a specific type of question.",
2988
3103
  "hasDynamicHelp": false,
2989
3104
  "multiple": false,
2990
3105
  "options": [
2991
- "json",
2992
- "human",
2993
- "junit",
2994
- "tap"
3106
+ "actions",
3107
+ "grounding",
3108
+ "routing",
3109
+ "errors"
2995
3110
  ],
2996
3111
  "type": "option"
2997
3112
  },
2998
- "batch-size": {
2999
- "name": "batch-size",
3000
- "summary": "Number of tests per API request (max 5).",
3001
- "default": 5,
3002
- "hasDynamicHelp": false,
3113
+ "turn": {
3114
+ "char": "t",
3115
+ "name": "turn",
3116
+ "summary": "Turn number for which you want trace data. A turn is a single utterance or response in a conversation, starting with 1.",
3117
+ "hasDynamicHelp": false,
3003
3118
  "multiple": false,
3004
3119
  "type": "option"
3005
- },
3006
- "no-normalize": {
3007
- "name": "no-normalize",
3008
- "summary": "Disable auto-normalization of field names and shorthand references.",
3009
- "allowNo": false,
3010
- "type": "boolean"
3011
3120
  }
3012
3121
  },
3013
- "hasDynamicHelp": true,
3122
+ "hasDynamicHelp": false,
3014
3123
  "hiddenAliases": [],
3015
- "id": "agent:test:run-eval",
3124
+ "id": "agent:trace:read",
3016
3125
  "pluginAlias": "@salesforce/plugin-agent",
3017
3126
  "pluginName": "@salesforce/plugin-agent",
3018
3127
  "pluginType": "core",
3019
- "state": "beta",
3020
3128
  "strict": true,
3021
- "summary": "Run rich evaluation tests against an Agentforce agent.",
3129
+ "summary": "Read trace files from an agent preview session.",
3022
3130
  "enableJsonFlag": true,
3023
- "envVariablesSection": {
3024
- "header": "ENVIRONMENT VARIABLES",
3025
- "body": [
3026
- {
3027
- "name": "SF_TARGET_ORG",
3028
- "description": "Username or alias of your default org. Overrides the target-org configuration variable."
3029
- }
3030
- ]
3031
- },
3032
- "errorCodes": {
3033
- "header": "ERROR CODES",
3034
- "body": [
3035
- {
3036
- "name": "Succeeded (0)",
3037
- "description": "Tests completed successfully. Test results (passed/failed) are in the JSON output."
3038
- },
3039
- {
3040
- "name": "Failed (1)",
3041
- "description": "Tests encountered execution errors (tests couldn't run properly)."
3042
- },
3043
- {
3044
- "name": "NotFound (2)",
3045
- "description": "Agent not found, spec file not found, or invalid agent name."
3046
- },
3047
- {
3048
- "name": "OperationFailed (4)",
3049
- "description": "Failed to execute tests due to API or network errors."
3050
- }
3051
- ]
3052
- },
3131
+ "requiresProject": true,
3053
3132
  "isESM": true,
3054
3133
  "relativePath": [
3055
3134
  "lib",
3056
3135
  "commands",
3057
3136
  "agent",
3058
- "test",
3059
- "run-eval.js"
3137
+ "trace",
3138
+ "read.js"
3060
3139
  ],
3061
3140
  "aliasPermutations": [],
3062
3141
  "permutations": [
3063
- "agent:test:run-eval",
3064
- "test:agent:run-eval",
3065
- "test:run-eval:agent",
3066
- "agent:run-eval:test",
3067
- "run-eval:agent:test",
3068
- "run-eval:test:agent"
3142
+ "agent:trace:read",
3143
+ "trace:agent:read",
3144
+ "trace:read:agent",
3145
+ "agent:read:trace",
3146
+ "read:agent:trace",
3147
+ "read:trace:agent"
3069
3148
  ]
3070
3149
  },
3071
- "agent:test:run": {
3150
+ "agent:test:create": {
3072
3151
  "aliases": [],
3073
3152
  "args": {},
3074
- "description": "Use the --api-name flag to specify the name of the agent test you want to run. Use the output of the \"agent test list\" command to get the names of all the available agent tests in your org.\n\nBy default, this command starts the agent test in your org, but it doesn't wait for the test to finish. Instead, it displays the \"agent test resume\" command, with a job ID, that you execute to see the results of the test run, and then returns control of the terminal window to you. Use the --wait flag to specify the number of minutes for the command to wait for the agent test to complete; if the test completes by the end of the wait time, the command displays the test results. If not, run \"agent test resume\".\n\nBy default, this command outputs test results in human-readable tables for each test case, if the test completes in time. The tables show whether the test case passed, the expected and actual values, the test score, how long the test took, and more. Use the --result-format to display the test results in JSON or Junit format. Use the --output-dir flag to write the results to a file rather than to the terminal.",
3153
+ "description": "To run this command, you must have an agent test spec file, which is a YAML file that lists the test cases for testing a specific agent. Use the \"agent generate test-spec\" CLI command to generate a test spec file. Then specify the file to this command with the --spec flag, or run this command with no flags to be prompted.\n\nWhen this command completes, your org contains the new agent test, which you can view and edit using the Testing Center UI (legacy) or Agentforce Studio (NGT). This command also retrieves the metadata component associated with the new test to your local Salesforce DX project and displays its filename. By default, the legacy AiEvaluationDefinition is created; use --test-runner agentforce-studio to author an AiTestingDefinition (NGT) instead.\n\nAfter you've created the test in the org, use the \"agent test run\" command to run it.",
3075
3154
  "examples": [
3076
- "Start an agent test called Resort_Manager_Test for an agent in your default org, don't wait for the test to finish:\n<%= config.bin %> <%= command.id %> --api-name Resort_Manager_Test",
3077
- "Start an agent test for an agent in an org with alias \"my-org\" and wait for 10 minutes for the test to finish:\n<%= config.bin %> <%= command.id %> --api-name Resort_Manager_Test --wait 10 --target-org my-org",
3078
- "Start an agent test and write the JSON-formatted results into a directory called \"test-results\":\n<%= config.bin %> <%= command.id %> --api-name Resort_Manager_Test --wait 10 --output-dir ./test-results --result-format json"
3155
+ "Create an agent test interactively and be prompted for the test spec and API name of the test in the org; use the default org:\n<%= config.bin %> <%= command.id %>",
3156
+ "Create an agent test and use flags to specify all required information; if a test with same API name already exists in the org, overwrite it without confirmation. Use the org with alias \"my-org\":\n<%= config.bin %> <%= command.id %> --spec specs/Resort_Manager-testSpec.yaml --api-name Resort_Manager_Test --force-overwrite --target-org my-org",
3157
+ "Preview what the agent test metadata (AiEvaluationDefinition) looks like without deploying it to your default org:\n<%= config.bin %> <%= command.id %> --spec specs/Resort_Manager-testSpec.yaml --api-name Resort_Manager_Test --preview",
3158
+ "Author an Agentforce Studio (NGT) test from an NGT-shaped YAML; writes an AiTestingDefinition metadata file:\n<%= config.bin %> <%= command.id %> --spec specs/ReturnsCheckout.ngt.yaml --api-name Returns_Checkout --test-runner agentforce-studio --target-org my-org"
3079
3159
  ],
3080
3160
  "flags": {
3081
3161
  "json": {
@@ -3093,6 +3173,20 @@
3093
3173
  "multiple": false,
3094
3174
  "type": "option"
3095
3175
  },
3176
+ "api-name": {
3177
+ "name": "api-name",
3178
+ "summary": "API name of the new test; the API name must not exist in the org.",
3179
+ "hasDynamicHelp": false,
3180
+ "multiple": false,
3181
+ "type": "option"
3182
+ },
3183
+ "spec": {
3184
+ "name": "spec",
3185
+ "summary": "Path to the test spec YAML file.",
3186
+ "hasDynamicHelp": false,
3187
+ "multiple": false,
3188
+ "type": "option"
3189
+ },
3096
3190
  "target-org": {
3097
3191
  "char": "o",
3098
3192
  "name": "target-org",
@@ -3110,44 +3204,17 @@
3110
3204
  "multiple": false,
3111
3205
  "type": "option"
3112
3206
  },
3113
- "api-name": {
3114
- "char": "n",
3115
- "name": "api-name",
3116
- "summary": "API name of the agent test to run; corresponds to the name of the AiEvaluationDefinition metadata component that implements the agent test.",
3117
- "hasDynamicHelp": false,
3118
- "multiple": false,
3119
- "type": "option"
3120
- },
3121
- "wait": {
3122
- "char": "w",
3123
- "name": "wait",
3124
- "summary": "Number of minutes to wait for the command to complete and display results to the terminal window.",
3125
- "hasDynamicHelp": true,
3126
- "multiple": false,
3127
- "type": "option"
3128
- },
3129
- "result-format": {
3130
- "name": "result-format",
3131
- "summary": "Format of the agent test run results.",
3132
- "default": "human",
3133
- "hasDynamicHelp": false,
3134
- "multiple": false,
3135
- "options": [
3136
- "json",
3137
- "human",
3138
- "junit",
3139
- "tap"
3140
- ],
3141
- "type": "option"
3207
+ "preview": {
3208
+ "name": "preview",
3209
+ "summary": "Preview the test metadata file without deploying to your org.",
3210
+ "allowNo": false,
3211
+ "type": "boolean"
3142
3212
  },
3143
- "output-dir": {
3144
- "char": "d",
3145
- "description": "If the agent test run completes, write the results to the specified directory. If the test is still running, the test results aren't written.",
3146
- "name": "output-dir",
3147
- "summary": "Directory to write the agent test results into.",
3148
- "hasDynamicHelp": false,
3149
- "multiple": false,
3150
- "type": "option"
3213
+ "force-overwrite": {
3214
+ "name": "force-overwrite",
3215
+ "summary": "Don't prompt for confirmation when overwriting an existing test (based on API name) in your org.",
3216
+ "allowNo": false,
3217
+ "type": "boolean"
3151
3218
  },
3152
3219
  "test-runner": {
3153
3220
  "description": "By default, the command automatically detects which test runner to use based on the test definition metadata type in your org. Use this flag to explicitly specify the runner type. 'agentforce-studio' uses AiTestingDefinition metadata. 'testing-center' uses AiEvaluationDefinition metadata.",
@@ -3160,23 +3227,16 @@
3160
3227
  "testing-center"
3161
3228
  ],
3162
3229
  "type": "option"
3163
- },
3164
- "verbose": {
3165
- "description": "When enabled, includes detailed generated data (such as invoked actions) in the human-readable test results output. This is useful for debugging test failures and understanding what actions were actually invoked during the test run.\n\nThe generated data is in JSON format and includes the Apex classes or Flows that were invoked, the Salesforce objects that were touched, and so on. Use the JSON structure of this information to build the test case JSONPath expression when using custom evaluations.",
3166
- "name": "verbose",
3167
- "summary": "Show generated data in the test results output.",
3168
- "allowNo": false,
3169
- "type": "boolean"
3170
3230
  }
3171
3231
  },
3172
3232
  "hasDynamicHelp": true,
3173
3233
  "hiddenAliases": [],
3174
- "id": "agent:test:run",
3234
+ "id": "agent:test:create",
3175
3235
  "pluginAlias": "@salesforce/plugin-agent",
3176
3236
  "pluginName": "@salesforce/plugin-agent",
3177
3237
  "pluginType": "core",
3178
3238
  "strict": true,
3179
- "summary": "Start an agent test in your org.",
3239
+ "summary": "Create an agent test in your org using a local test spec YAML file.",
3180
3240
  "enableJsonFlag": true,
3181
3241
  "envVariablesSection": {
3182
3242
  "header": "ENVIRONMENT VARIABLES",
@@ -3192,19 +3252,19 @@
3192
3252
  "body": [
3193
3253
  {
3194
3254
  "name": "Succeeded (0)",
3195
- "description": "Test started successfully (without --wait), or test completed successfully (with --wait)."
3255
+ "description": "Test created and deployed successfully."
3196
3256
  },
3197
3257
  {
3198
3258
  "name": "Failed (1)",
3199
- "description": "Tests encountered execution errors (test cases with ERROR status when using --wait)."
3259
+ "description": "Test validation errors or metadata format issues."
3200
3260
  },
3201
3261
  {
3202
3262
  "name": "NotFound (2)",
3203
- "description": "Test definition not found or invalid test name."
3263
+ "description": "Test spec file not found or org connection failed."
3204
3264
  },
3205
3265
  {
3206
- "name": "OperationFailed (4)",
3207
- "description": "Failed to start or poll test due to API or network errors."
3266
+ "name": "DeploymentFailed (4)",
3267
+ "description": "Deployment failed due to API or network errors."
3208
3268
  }
3209
3269
  ]
3210
3270
  },
@@ -3214,29 +3274,25 @@
3214
3274
  "commands",
3215
3275
  "agent",
3216
3276
  "test",
3217
- "run.js"
3277
+ "create.js"
3218
3278
  ],
3219
3279
  "aliasPermutations": [],
3220
3280
  "permutations": [
3221
- "agent:test:run",
3222
- "test:agent:run",
3223
- "test:run:agent",
3224
- "agent:run:test",
3225
- "run:agent:test",
3226
- "run:test:agent"
3281
+ "agent:test:create",
3282
+ "test:agent:create",
3283
+ "test:create:agent",
3284
+ "agent:create:test",
3285
+ "create:agent:test",
3286
+ "create:test:agent"
3227
3287
  ]
3228
3288
  },
3229
- "agent:trace:delete": {
3289
+ "agent:test:list": {
3230
3290
  "aliases": [],
3231
3291
  "args": {},
3232
- "description": "When you run an agent preview conversation (either interactive or programmatic), trace files are automatically recorded and saved in your local DX project. Use this command to delete some or all of the trace files.\n\nBy default, this command shows a preview of what will be deleted and prompts for confirmation. Use --no-prompt to skip confirmation.\n\nWithout filters, this comamnd deletes all trace files for all agents and sessions. Use flags to narrow the scope: filter by agent API name (--agent), by session (--session-id), or by age (--older-than).",
3292
+ "description": "The command outputs a table with the name (API name) of each test along with its unique ID, type ('agentforce-studio' or 'testing-center'), and the date it was created in the org.",
3233
3293
  "examples": [
3234
- "Delete all traces for all agents and sessions; prompt for confirmation:\n<%= config.bin %> <%= command.id %>",
3235
- "Delete all traces for a specific agent:\n<%= config.bin %> <%= command.id %> --agent My_Agent",
3236
- "Delete traces from a specific session:\n<%= config.bin %> <%= command.id %> --session-id <SESSION_ID>",
3237
- "Delete traces older than 7 days:\n<%= config.bin %> <%= command.id %> --older-than 7d",
3238
- "Delete traces older than 24 hours for a specific agent; don't prompt for confirmation:\n<%= config.bin %> <%= command.id %> --agent My_Agent --older-than 24h --no-prompt",
3239
- "Delete all traces for all agents and sessions; don't prompt for confirmation:\n<%= config.bin %> <%= command.id %> --no-prompt"
3294
+ "List the agent tests in your default org:\n<%= config.bin %> <%= command.id %>",
3295
+ "List the agent tests in an org with alias \"my-org\"\"\n<%= config.bin %> <%= command.id %> --target-org my-org"
3240
3296
  ],
3241
3297
  "flags": {
3242
3298
  "json": {
@@ -3254,51 +3310,52 @@
3254
3310
  "multiple": false,
3255
3311
  "type": "option"
3256
3312
  },
3257
- "agent": {
3258
- "char": "a",
3259
- "name": "agent",
3260
- "summary": "API name of the agent used to filter the list of trace files you want to delete. Matches against the API name used when starting the session, either an authoring bundle or a published agent API name.",
3261
- "hasDynamicHelp": false,
3262
- "multiple": false,
3263
- "type": "option"
3264
- },
3265
- "session-id": {
3266
- "name": "session-id",
3267
- "summary": "Session ID used to filter the list of trace files you want to delete. Use the \"agent preview sessions\" CLI command to list all known agent preview sessions along with their session IDs.",
3268
- "hasDynamicHelp": false,
3313
+ "target-org": {
3314
+ "char": "o",
3315
+ "name": "target-org",
3316
+ "noCacheDefault": true,
3317
+ "required": true,
3318
+ "summary": "Username or alias of the target org. Not required if the `target-org` configuration variable is already set.",
3319
+ "hasDynamicHelp": true,
3269
3320
  "multiple": false,
3270
3321
  "type": "option"
3271
3322
  },
3272
- "older-than": {
3273
- "name": "older-than",
3274
- "summary": "Duration used to filter the list of trace files; only files older than the duration are deleted. Accepts a number followed by a unit: m/minutes, h/hours, d/days, w/weeks. Examples: 7d, 24h, 2w.",
3323
+ "api-version": {
3324
+ "description": "Override the api version used for api requests made by this command",
3325
+ "name": "api-version",
3275
3326
  "hasDynamicHelp": false,
3276
3327
  "multiple": false,
3277
3328
  "type": "option"
3278
- },
3279
- "no-prompt": {
3280
- "name": "no-prompt",
3281
- "summary": "Skip the confirmation prompt and delete immediately.",
3282
- "allowNo": false,
3283
- "type": "boolean"
3284
3329
  }
3285
3330
  },
3286
- "hasDynamicHelp": false,
3331
+ "hasDynamicHelp": true,
3287
3332
  "hiddenAliases": [],
3288
- "id": "agent:trace:delete",
3333
+ "id": "agent:test:list",
3289
3334
  "pluginAlias": "@salesforce/plugin-agent",
3290
3335
  "pluginName": "@salesforce/plugin-agent",
3291
3336
  "pluginType": "core",
3292
3337
  "strict": true,
3293
- "summary": "Delete trace files from an agent preview session.",
3338
+ "summary": "List the available agent tests in your org.",
3294
3339
  "enableJsonFlag": true,
3295
- "requiresProject": true,
3340
+ "envVariablesSection": {
3341
+ "header": "ENVIRONMENT VARIABLES",
3342
+ "body": [
3343
+ {
3344
+ "name": "SF_TARGET_ORG",
3345
+ "description": "Username or alias of your default org. Overrides the target-org configuration variable."
3346
+ }
3347
+ ]
3348
+ },
3296
3349
  "errorCodes": {
3297
3350
  "header": "ERROR CODES",
3298
3351
  "body": [
3299
3352
  {
3300
3353
  "name": "Succeeded (0)",
3301
- "description": "Traces deleted successfully (or no traces matched)."
3354
+ "description": "Agent tests listed successfully."
3355
+ },
3356
+ {
3357
+ "name": "Failed (4)",
3358
+ "description": "Failed to retrieve agent tests due to API or network errors."
3302
3359
  }
3303
3360
  ]
3304
3361
  },
@@ -3307,222 +3364,27 @@
3307
3364
  "lib",
3308
3365
  "commands",
3309
3366
  "agent",
3310
- "trace",
3311
- "delete.js"
3367
+ "test",
3368
+ "list.js"
3312
3369
  ],
3313
3370
  "aliasPermutations": [],
3314
3371
  "permutations": [
3315
- "agent:trace:delete",
3316
- "trace:agent:delete",
3317
- "trace:delete:agent",
3318
- "agent:delete:trace",
3319
- "delete:agent:trace",
3320
- "delete:trace:agent"
3372
+ "agent:test:list",
3373
+ "test:agent:list",
3374
+ "test:list:agent",
3375
+ "agent:list:test",
3376
+ "list:agent:test",
3377
+ "list:test:agent"
3321
3378
  ]
3322
3379
  },
3323
- "agent:trace:list": {
3380
+ "agent:test:results": {
3324
3381
  "aliases": [],
3325
3382
  "args": {},
3326
- "description": "When you run an agent preview conversation (either interactive or programmatic), trace files are automatically recorded and saved in your local DX project. By default, this command lists all trace files for all agents and all of their sessions. Use flags to narrow results: filter by agent name (--agent), by session (--session-id), or by date (--since).\n\nEach row in the output corresponds to one trace file, which in turn corresponds to one agent session. The Agent column shows the authoring bundle or API name used when starting the session.",
3327
- "examples": [
3328
- "List all trace files for all agents and sessions:\n<%= config.bin %> <%= command.id %>",
3329
- "List all trace files for a specific agent:\n<%= config.bin %> <%= command.id %> --agent My_Agent",
3330
- "List trace files for a specific session:\n<%= config.bin %> <%= command.id %> --session-id <SESSION_ID>",
3331
- "List trace files recorded on or after April 20, 2026 (date-only, interpreted as UTC midnight):\n<%= config.bin %> <%= command.id %> --since 2026-04-20",
3332
- "List trace files recorded on or after a specific UTC time:\n<%= config.bin %> <%= command.id %> --since 2026-04-20T14:00:00Z",
3333
- "Filter by agent and date together:\n<%= config.bin %> <%= command.id %> --agent My_Agent --since 2026-04-20",
3334
- "Return results as JSON:\n<%= config.bin %> <%= command.id %> --json"
3335
- ],
3336
- "flags": {
3337
- "json": {
3338
- "description": "Format output as json.",
3339
- "helpGroup": "GLOBAL",
3340
- "name": "json",
3341
- "allowNo": false,
3342
- "type": "boolean"
3343
- },
3344
- "flags-dir": {
3345
- "helpGroup": "GLOBAL",
3346
- "name": "flags-dir",
3347
- "summary": "Import flag values from a directory.",
3348
- "hasDynamicHelp": false,
3349
- "multiple": false,
3350
- "type": "option"
3351
- },
3352
- "session-id": {
3353
- "name": "session-id",
3354
- "summary": "Session ID used to filter the list of trace files. Use the \"agent preview sessions\" CLI command to list all known agent preview sessions along with their session IDs.",
3355
- "hasDynamicHelp": false,
3356
- "multiple": false,
3357
- "type": "option"
3358
- },
3359
- "agent": {
3360
- "char": "a",
3361
- "name": "agent",
3362
- "summary": "API name of the agent used to filter the list of available trace files. Matches against the API name used when starting the session, either an authoring bundle or a published agent API name.",
3363
- "hasDynamicHelp": false,
3364
- "multiple": false,
3365
- "type": "option"
3366
- },
3367
- "since": {
3368
- "description": "Accepts ISO 8601 format: date-only (2026-04-20), date-time (2026-04-20T14:00:00Z), or date-time with milliseconds (2026-04-20T14:00:00.000Z). The \"Recorded At\" values shown in the table output are valid inputs.",
3369
- "name": "since",
3370
- "summary": "Date used to filter the list of trace files; only those recorded on or after the date are listed.",
3371
- "hasDynamicHelp": false,
3372
- "multiple": false,
3373
- "type": "option"
3374
- }
3375
- },
3376
- "hasDynamicHelp": false,
3377
- "hiddenAliases": [],
3378
- "id": "agent:trace:list",
3379
- "pluginAlias": "@salesforce/plugin-agent",
3380
- "pluginName": "@salesforce/plugin-agent",
3381
- "pluginType": "core",
3382
- "strict": true,
3383
- "summary": "List the available trace files that were recorded during all agent preview sessions.",
3384
- "enableJsonFlag": true,
3385
- "requiresProject": true,
3386
- "errorCodes": {
3387
- "header": "ERROR CODES",
3388
- "body": [
3389
- {
3390
- "name": "Succeeded (0)",
3391
- "description": "Trace files listed successfully (or empty list if none found)."
3392
- }
3393
- ]
3394
- },
3395
- "isESM": true,
3396
- "relativePath": [
3397
- "lib",
3398
- "commands",
3399
- "agent",
3400
- "trace",
3401
- "list.js"
3402
- ],
3403
- "aliasPermutations": [],
3404
- "permutations": [
3405
- "agent:trace:list",
3406
- "trace:agent:list",
3407
- "trace:list:agent",
3408
- "agent:list:trace",
3409
- "list:agent:trace",
3410
- "list:trace:agent"
3411
- ]
3412
- },
3413
- "agent:trace:read": {
3414
- "aliases": [],
3415
- "args": {},
3416
- "description": "When you run an agent preview conversation (either interactive or programmatic), trace files are automatically recorded and saved in your local DX project. Each turn (utterance or response) of a conversation creates trace data. Use this command to view trace data for a specific preview session, so you can then analyze the trace data to observe, monitor, investigate, and troubleshoot agent events and behavior.\n\nUse the --format flag to specify one of these formats of the outputted trace data:\n\n- summary (Default): A per-turn narrative showing topic routing, actions executed, and the agent's response. Use this to quickly understand what happened in a preview session.\n- detail: Diagnostic drill-down into a specific dimension. Filters output to only the trace steps relevant to that dimension, minimizing noise.\n- raw: Unprocessed trace JSON. Use this as a fallback when the trace schema has changed or you need to perform custom analysis.\n\nIf you specify \"--format detail\", you must also specify a dimension with the --dimension flag. Dimensions are a way to slice and analyze the agent execution trace from a specific angle or concern. Instead of looking at the raw sequence of everything that happened, each dimension filters and organizes the trace data to answer a specific type of question. These are the available dimensions and the information they provide:\n\n- actions: The actions the agent executed. Includes action name, input parameters, output, and latency. Use this dimension to understand what the agent actually did when answering an utterance in the preview session.\n- grounding: The reasoning steps used by the LLM. Use this dimension to see how the agent \"thought\" about the problem - the AI reasoning that determined which actions to take.\n- routing: How the agent navigated between subagents. Use this dimension to understand conversation flow - when and why the agent switched between different subagents or contexts during the conversation.\n- errors: Aggregates all errors during the session. Use this dimension to quickly identify and debug issues across all steps.",
3417
- "examples": [
3418
- "Show a session trace summary for all turns in the session with the specified ID:\n<%= config.bin %> <%= command.id %> --session-id <SESSION_ID>",
3419
- "Show a trace summary for the second turn (utterance or response) of the conversation:\n<%= config.bin %> <%= command.id %> --session-id <SESSION_ID> --turn 2",
3420
- "Drill into action execution across all turns:\n<%= config.bin %> <%= command.id %> --session-id <SESSION_ID> --format detail --dimension actions",
3421
- "Drill into routing decisions for the first turn of the conversation:\n<%= config.bin %> <%= command.id %> --session-id <SESSION_ID> --format detail --dimension routing --turn 1",
3422
- "Show all errors across the session:\n<%= config.bin %> <%= command.id %> --session-id <SESSION_ID> --format detail --dimension errors",
3423
- "Output raw trace JSON for custom parsing:\n<%= config.bin %> <%= command.id %> --session-id <SESSION_ID> --format raw",
3424
- "Return results as JSON:\n<%= config.bin %> <%= command.id %> --session-id <SESSION_ID> --json"
3425
- ],
3426
- "flags": {
3427
- "json": {
3428
- "description": "Format output as json.",
3429
- "helpGroup": "GLOBAL",
3430
- "name": "json",
3431
- "allowNo": false,
3432
- "type": "boolean"
3433
- },
3434
- "flags-dir": {
3435
- "helpGroup": "GLOBAL",
3436
- "name": "flags-dir",
3437
- "summary": "Import flag values from a directory.",
3438
- "hasDynamicHelp": false,
3439
- "multiple": false,
3440
- "type": "option"
3441
- },
3442
- "session-id": {
3443
- "char": "s",
3444
- "name": "session-id",
3445
- "required": true,
3446
- "summary": "Session ID to read traces for. Use the \"agent preview sessions\" CLI command to list all known agent preview sessions along with their session IDs",
3447
- "hasDynamicHelp": false,
3448
- "multiple": false,
3449
- "type": "option"
3450
- },
3451
- "format": {
3452
- "char": "f",
3453
- "name": "format",
3454
- "summary": "Output format of the trace data; specifies the level of detail you want in the trace files.",
3455
- "default": "summary",
3456
- "hasDynamicHelp": false,
3457
- "multiple": false,
3458
- "options": [
3459
- "summary",
3460
- "detail",
3461
- "raw"
3462
- ],
3463
- "type": "option"
3464
- },
3465
- "dimension": {
3466
- "char": "d",
3467
- "name": "dimension",
3468
- "summary": "Dimension to drill into when using \"--format detail\"; used to filter and organize the trace data to answer a specific type of question.",
3469
- "hasDynamicHelp": false,
3470
- "multiple": false,
3471
- "options": [
3472
- "actions",
3473
- "grounding",
3474
- "routing",
3475
- "errors"
3476
- ],
3477
- "type": "option"
3478
- },
3479
- "turn": {
3480
- "char": "t",
3481
- "name": "turn",
3482
- "summary": "Turn number for which you want trace data. A turn is a single utterance or response in a conversation, starting with 1.",
3483
- "hasDynamicHelp": false,
3484
- "multiple": false,
3485
- "type": "option"
3486
- }
3487
- },
3488
- "hasDynamicHelp": false,
3489
- "hiddenAliases": [],
3490
- "id": "agent:trace:read",
3491
- "pluginAlias": "@salesforce/plugin-agent",
3492
- "pluginName": "@salesforce/plugin-agent",
3493
- "pluginType": "core",
3494
- "strict": true,
3495
- "summary": "Read trace files from an agent preview session.",
3496
- "enableJsonFlag": true,
3497
- "requiresProject": true,
3498
- "isESM": true,
3499
- "relativePath": [
3500
- "lib",
3501
- "commands",
3502
- "agent",
3503
- "trace",
3504
- "read.js"
3505
- ],
3506
- "aliasPermutations": [],
3507
- "permutations": [
3508
- "agent:trace:read",
3509
- "trace:agent:read",
3510
- "trace:read:agent",
3511
- "agent:read:trace",
3512
- "read:agent:trace",
3513
- "read:trace:agent"
3514
- ]
3515
- },
3516
- "agent:generate:agent-spec": {
3517
- "aliases": [],
3518
- "args": {},
3519
- "description": "An agent spec is a YAML-formatted file that contains basic information about the agent, such as its role, company description, and an AI-generated list of topics based on this information. Topics define the range of jobs your agent can handle.\n\nUse flags, such as --role and --company-description, to provide details about your company and the role that the agent plays in your company. If you prefer, you can also be prompted for the basic information; use --full-interview to be prompted for all required and optional properties. Upon command execution, the large language model (LLM) associated with your org uses the provided information to generate a list of topics for the agent. Because the LLM uses the company and role information to generate the topics, we recommend that you provide accurate, complete, and specific details so the LLM generates the best and most relevant topics. Once generated, you can edit the spec file; for example, you can remove topics that don't apply or change a topic's description.\n\nYou can also iterate the spec generation process by using the --spec flag to pass an existing agent spec file to this command, and then using the --role, --company-description, etc, flags to refine your agent properties. Iteratively improving the description of your agent allows the LLM to generate progressively better topics.\n\nYou can also specify other agent properties, such as a custom prompt template, how to ground the prompt template to add context to the agent's prompts, the tone of the prompts, and the username of a user in the org to assign to the agent.\n\nWhen your agent spec is ready, generate an authoring bundle from it by passing the spec file to the --spec flag of the \"agent generate authoring-bundle\" CLI command. An authoring bundle is a metadata type that contains an Agent Script file, which is the blueprint for an agent. (While not recommended, you can also use the agent spec file to immediately create an agent with the \"agent create\" command. We don't recommend this workflow because these types of agents don't use Agent Script, and are thus less flexible and more difficult to maintain.)",
3383
+ "description": "This command requires a job ID, which the original \"agent test run\" command displays when it completes. You can also use the --use-most-recent flag to see results for the most recently run agent test.\n\nBy default, this command outputs test results in human-readable tables for each test case. The tables show whether the test case passed, the expected and actual values, the test score, how long the test took, and more. Use the --result-format to display the test results in JSON or Junit format. Use the --output-dir flag to write the results to a file rather than to the terminal.",
3520
3384
  "examples": [
3521
- "Generate an agent spec in the default location and use flags to specify the agent properties, such as its role and your company details; use your default org:\n<%= config.bin %> <%= command.id %> --type customer --role \"Field customer complaints and manage employee schedules.\" --company-name \"Coral Cloud Resorts\" --company-description \"Provide customers with exceptional destination activities, unforgettable experiences, and reservation services.\"",
3522
- "Generate an agent spec by being prompted for the required agent properties and generate a maxiumum of 5 topics; write the generated file to the \"specs/resortManagerSpec.yaml\" file and use the org with alias \"my-org\":\n<%= config.bin %> <%= command.id %> --max-topics 5 --output-file specs/resortManagerAgent.yaml --target-org my-org",
3523
- "Be prompted for all required and optional agent properties; use your default org:\n<%= config.bin %> <%= command.id %> --full-interview",
3524
- "Specify an existing agent spec file called \"specs/resortManagerAgent.yaml\", and then overwrite it with a new version that contains newly AI-generated topics based on the updated role information passed in with the --role flag:\n<%= config.bin %> <%= command.id %> --spec specs/resortManagerAgent.yaml --output-file specs/resortManagerAgent.yaml --role \"Field customer complaints, manage employee schedules, and ensure all resort operations are running smoothly\"",
3525
- "Specify that the conversational tone of the agent is formal and to attach the \"resortmanager@myorg.com\" username to it; be prompted for the required properties and use your default org:\n<%= config.bin %> <%= command.id %> --tone formal --agent-user resortmanager@myorg.com"
3385
+ "Get the results of an agent test run in your default org using its job ID:\n<%= config.bin %> <%= command.id %> --job-id 4KBfake0000003F4AQ",
3386
+ "Get the results of the most recently run agent test in an org with alias \"my-org\":\n<%= config.bin %> <%= command.id %> --use-most-recent --target-org my-org",
3387
+ "Get the results of the most recently run agent test in your default org, and write the JSON-formatted results into a directory called \"test-results\":\n<%= config.bin %> <%= command.id %> --use-most-recent --output-dir ./test-results --result-format json"
3526
3388
  ],
3527
3389
  "flags": {
3528
3390
  "json": {
@@ -3557,164 +3419,119 @@
3557
3419
  "multiple": false,
3558
3420
  "type": "option"
3559
3421
  },
3560
- "type": {
3561
- "name": "type",
3562
- "summary": "Type of agent to create. Internal types are copilots used internally by your company and customer types are the agents you create for your customers.",
3563
- "hasDynamicHelp": false,
3564
- "multiple": false,
3565
- "options": [
3566
- "customer",
3567
- "internal"
3568
- ],
3569
- "type": "option"
3570
- },
3571
- "role": {
3572
- "name": "role",
3573
- "summary": "Role of the agent.",
3574
- "hasDynamicHelp": false,
3575
- "multiple": false,
3576
- "type": "option"
3577
- },
3578
- "company-name": {
3579
- "name": "company-name",
3580
- "summary": "Name of your company.",
3581
- "hasDynamicHelp": false,
3582
- "multiple": false,
3583
- "type": "option"
3584
- },
3585
- "company-description": {
3586
- "name": "company-description",
3587
- "summary": "Description of your company.",
3588
- "hasDynamicHelp": false,
3589
- "multiple": false,
3590
- "type": "option"
3591
- },
3592
- "company-website": {
3593
- "name": "company-website",
3594
- "summary": "Website URL of your company.",
3595
- "hasDynamicHelp": false,
3596
- "multiple": false,
3597
- "type": "option"
3598
- },
3599
- "max-topics": {
3600
- "name": "max-topics",
3601
- "summary": "Maximum number of topics to generate in the agent spec; default is 5.",
3602
- "hasDynamicHelp": false,
3603
- "multiple": false,
3604
- "type": "option"
3605
- },
3606
- "agent-user": {
3607
- "name": "agent-user",
3608
- "summary": "Username of a user in your org to assign to your agent; determines what your agent can access and do.",
3609
- "hasDynamicHelp": false,
3610
- "multiple": false,
3611
- "type": "option"
3612
- },
3613
- "enrich-logs": {
3614
- "name": "enrich-logs",
3615
- "summary": "Adds agent conversation data to event logs so you can view all agent session activity in one place.",
3422
+ "job-id": {
3423
+ "char": "i",
3424
+ "name": "job-id",
3425
+ "required": true,
3426
+ "summary": "Job ID of the completed agent test run.",
3616
3427
  "hasDynamicHelp": false,
3617
3428
  "multiple": false,
3618
- "options": [
3619
- "true",
3620
- "false"
3621
- ],
3622
3429
  "type": "option"
3623
3430
  },
3624
- "tone": {
3625
- "name": "tone",
3626
- "summary": "Conversational style of the agent, such as how it expresses your brand personality in its messages through word choice, punctuation, and sentence structure.",
3431
+ "result-format": {
3432
+ "name": "result-format",
3433
+ "summary": "Format of the agent test run results.",
3434
+ "default": "human",
3627
3435
  "hasDynamicHelp": false,
3628
3436
  "multiple": false,
3629
3437
  "options": [
3630
- "formal",
3631
- "casual",
3632
- "neutral"
3438
+ "json",
3439
+ "human",
3440
+ "junit",
3441
+ "tap"
3633
3442
  ],
3634
3443
  "type": "option"
3635
3444
  },
3636
- "spec": {
3637
- "name": "spec",
3638
- "summary": "Agent spec file, in YAML format, to use as input to the command.",
3639
- "hasDynamicHelp": false,
3640
- "multiple": false,
3641
- "type": "option"
3642
- },
3643
- "output-file": {
3644
- "name": "output-file",
3645
- "summary": "Path for the generated YAML agent spec file; can be an absolute or relative path.",
3646
- "default": "specs/agentSpec.yaml",
3445
+ "output-dir": {
3446
+ "char": "d",
3447
+ "description": "If the agent test run completes, write the results to the specified directory. If the test is still running, the test results aren't written.",
3448
+ "name": "output-dir",
3449
+ "summary": "Directory to write the agent test results into.",
3647
3450
  "hasDynamicHelp": false,
3648
3451
  "multiple": false,
3649
3452
  "type": "option"
3650
3453
  },
3651
- "full-interview": {
3652
- "name": "full-interview",
3653
- "summary": "Prompt for both required and optional flags.",
3654
- "allowNo": false,
3655
- "type": "boolean"
3656
- },
3657
- "prompt-template": {
3658
- "name": "prompt-template",
3659
- "summary": "API name of a customized prompt template to use instead of the default prompt template.",
3454
+ "test-runner": {
3455
+ "description": "By default, the command automatically detects which test runner to use based on the test definition metadata type in your org. Use this flag to explicitly specify the runner type. 'agentforce-studio' uses AiTestingDefinition metadata. 'testing-center' uses AiEvaluationDefinition metadata.",
3456
+ "name": "test-runner",
3457
+ "summary": "Explicitly specify which test runner to use (agentforce-studio or testing-center).",
3660
3458
  "hasDynamicHelp": false,
3661
3459
  "multiple": false,
3662
- "type": "option"
3663
- },
3664
- "grounding-context": {
3665
- "dependsOn": [
3666
- "prompt-template"
3460
+ "options": [
3461
+ "agentforce-studio",
3462
+ "testing-center"
3667
3463
  ],
3668
- "name": "grounding-context",
3669
- "summary": "Context information and personalization that's added to your prompts when using a custom prompt template.",
3670
- "hasDynamicHelp": false,
3671
- "multiple": false,
3672
3464
  "type": "option"
3673
3465
  },
3674
- "force-overwrite": {
3675
- "name": "force-overwrite",
3676
- "summary": "Don't prompt the user to confirm that an existing spec file will be overwritten.",
3466
+ "verbose": {
3467
+ "description": "When enabled, includes detailed generated data (such as invoked actions) in the human-readable test results output. This is useful for debugging test failures and understanding what actions were actually invoked during the test run.\n\nThe generated data is in JSON format and includes the Apex classes or Flows that were invoked, the Salesforce objects that were touched, and so on. Use the JSON structure of this information to build the test case JSONPath expression when using custom evaluations.",
3468
+ "name": "verbose",
3469
+ "summary": "Show generated data in the test results output.",
3677
3470
  "allowNo": false,
3678
3471
  "type": "boolean"
3679
3472
  }
3680
3473
  },
3681
3474
  "hasDynamicHelp": true,
3682
3475
  "hiddenAliases": [],
3683
- "id": "agent:generate:agent-spec",
3476
+ "id": "agent:test:results",
3684
3477
  "pluginAlias": "@salesforce/plugin-agent",
3685
3478
  "pluginName": "@salesforce/plugin-agent",
3686
3479
  "pluginType": "core",
3687
3480
  "strict": true,
3688
- "summary": "Generate an agent spec, which is a YAML file that captures what an agent can do.",
3481
+ "summary": "Get the results of a completed agent test run.",
3689
3482
  "enableJsonFlag": true,
3690
- "requiresProject": true,
3483
+ "envVariablesSection": {
3484
+ "header": "ENVIRONMENT VARIABLES",
3485
+ "body": [
3486
+ {
3487
+ "name": "SF_TARGET_ORG",
3488
+ "description": "Username or alias of your default org. Overrides the target-org configuration variable."
3489
+ }
3490
+ ]
3491
+ },
3492
+ "errorCodes": {
3493
+ "header": "ERROR CODES",
3494
+ "body": [
3495
+ {
3496
+ "name": "Succeeded (0)",
3497
+ "description": "Results retrieved successfully. Test results (passed/failed) are in the output."
3498
+ },
3499
+ {
3500
+ "name": "NotFound (2)",
3501
+ "description": "Job ID not found or invalid."
3502
+ },
3503
+ {
3504
+ "name": "Failed (4)",
3505
+ "description": "Failed to retrieve results due to API or network errors."
3506
+ }
3507
+ ]
3508
+ },
3691
3509
  "isESM": true,
3692
3510
  "relativePath": [
3693
3511
  "lib",
3694
3512
  "commands",
3695
3513
  "agent",
3696
- "generate",
3697
- "agent-spec.js"
3514
+ "test",
3515
+ "results.js"
3698
3516
  ],
3699
3517
  "aliasPermutations": [],
3700
3518
  "permutations": [
3701
- "agent:generate:agent-spec",
3702
- "generate:agent:agent-spec",
3703
- "generate:agent-spec:agent",
3704
- "agent:agent-spec:generate",
3705
- "agent-spec:agent:generate",
3706
- "agent-spec:generate:agent"
3519
+ "agent:test:results",
3520
+ "test:agent:results",
3521
+ "test:results:agent",
3522
+ "agent:results:test",
3523
+ "results:agent:test",
3524
+ "results:test:agent"
3707
3525
  ]
3708
3526
  },
3709
- "agent:generate:authoring-bundle": {
3527
+ "agent:test:resume": {
3710
3528
  "aliases": [],
3711
3529
  "args": {},
3712
- "description": "Authoring bundles are metadata components that contain an agent's Agent Script file. The Agent Script file is the agent's blueprint; it fully describes what the agent can do using the Agent Script language.\n\nUse this command to generate a new authoring bundle based on an agent spec YAML file, which you create with the \"agent generate agent-spec\" command. The agent spec YAML file is a high-level description of the agent; it describes its essence rather than exactly what it can do. The resulting Agent Script file is customized to reflect what's in the agent spec file. You can also create an authoring bundle without an agent spec file by specifying the \"--no-spec\" flag; in this case, the resulting Agent Script file is just the default boilerplate.\n\nThe metadata type for authoring bundles is aiAuthoringBundle, which consist of a standard \"<bundle-api-name>.bundle-meta.xml\" metadata file and the Agent Script file (with extension \".agent\"). When you run this command, the new authoring bundle is generated in the force-app/main/default/aiAuthoringBundles/<bundle-api-name> directory. Use the --output-dir flag to generate them elsewhere.\n\nAfter you generate the initial authoring bundle, code the Agent Script file so your agent behaves exactly as you want. The Agent Script file generated by this command is just a first draft of your agent! Interactively test the agent by conversing with it using the \"agent preview\" command. Then publish the agent to your org with the \"agent publish authoring-bundle\" command.\n\nThis command requires an org because it uses it to access an LLM for generating the Agent Script file.",
3530
+ "description": "This command requires a job ID, which the original \"agent test run\" command displays when it completes. You can also use the --use-most-recent flag to see results for the most recently run agent test.\n\nUse the --wait flag to specify the number of minutes for this command to wait for the agent test to complete; if the test completes by the end of the wait time, the command displays the test results. If not, the CLI returns control of the terminal to you, and you must run \"agent test resume\" again.\n\nBy default, this command outputs test results in human-readable tables for each test case. The tables show whether the test case passed, the expected and actual values, the test score, how long the test took, and more. Use the --result-format to display the test results in JSON or Junit format. Use the --output-dir flag to write the results to a file rather than to the terminal.",
3713
3531
  "examples": [
3714
- "Generate an authoring bundle by being prompted for all required values, such as the agent spec YAML file, the bundle name, and the API name; use your default org:\n<%= config.bin %> <%= command.id %>",
3715
- "Generate an authoring bundle without using an agent spec file; give the bundle the label \"My Authoring Bundle\" and use your default org:\n<%= config.bin %> <%= command.id %> --no-spec --name \"My Authoring Bundle\"",
3716
- "Generate an authoring bundle from the \"specs/agentSpec.yaml\" agent spec YAML file and give it the label \"My Authoring Bundle\"; use your default org:\n<%= config.bin %> <%= command.id %> --spec specs/agentSpec.yaml --name \"My Authoring Bundle\"",
3717
- "Similar to previous example, but generate the authoring bundle files in the \"other-package-dir/main/default\" package directory; use the org with alias \"my-dev-org\":\n<%= config.bin %> <%= command.id %> --spec specs/agentSpec.yaml --name \"My Authoring Bundle\" --output-dir other-package-dir/main/default --target-org my-dev-org"
3532
+ "Resume an agent test in your default org using a job ID:\n<%= config.bin %> <%= command.id %> --job-id 4KBfake0000003F4AQ",
3533
+ "Resume the most recently-run agent test in an org with alias \"my-org\" org; wait 10 minutes for the tests to finish:\n<%= config.bin %> <%= command.id %> --use-most-recent --wait 10 --target-org my-org",
3534
+ "Resume the most recent agent test in your default org, and write the JSON-formatted results into a directory called \"test-results\":\n<%= config.bin %> <%= command.id %> --use-most-recent --output-dir ./test-results --result-format json"
3718
3535
  ],
3719
3536
  "flags": {
3720
3537
  "json": {
@@ -3742,13 +3559,6 @@
3742
3559
  "multiple": false,
3743
3560
  "type": "option"
3744
3561
  },
3745
- "api-name": {
3746
- "name": "api-name",
3747
- "summary": "API name of the new authoring bundle; if not specified, the API name is derived from the authoring bundle name (label); the API name can't exist in the org.",
3748
- "hasDynamicHelp": false,
3749
- "multiple": false,
3750
- "type": "option"
3751
- },
3752
3562
  "api-version": {
3753
3563
  "description": "Override the api version used for api requests made by this command",
3754
3564
  "name": "api-version",
@@ -3756,77 +3566,141 @@
3756
3566
  "multiple": false,
3757
3567
  "type": "option"
3758
3568
  },
3759
- "spec": {
3760
- "char": "f",
3761
- "name": "spec",
3762
- "summary": "Path to the agent spec YAML file. If you don't specify the flag, the command provides a list that you can choose from. Use the --no-spec flag to skip using an agent spec entirely.",
3569
+ "job-id": {
3570
+ "char": "i",
3571
+ "name": "job-id",
3572
+ "summary": "Job ID of the original agent test run.",
3763
3573
  "hasDynamicHelp": false,
3764
3574
  "multiple": false,
3765
3575
  "type": "option"
3766
3576
  },
3767
- "no-spec": {
3768
- "name": "no-spec",
3769
- "summary": "Skip prompting for an agent spec and use the default Agent Script boilerplate in the generated authoring bundle.",
3577
+ "use-most-recent": {
3578
+ "char": "r",
3579
+ "name": "use-most-recent",
3580
+ "summary": "Use the job ID of the most recent agent test run.",
3770
3581
  "allowNo": false,
3771
3582
  "type": "boolean"
3772
3583
  },
3584
+ "wait": {
3585
+ "char": "w",
3586
+ "name": "wait",
3587
+ "summary": "Number of minutes to wait for the command to complete and display results to the terminal window.",
3588
+ "default": "5 minutes",
3589
+ "hasDynamicHelp": true,
3590
+ "multiple": false,
3591
+ "type": "option"
3592
+ },
3593
+ "result-format": {
3594
+ "name": "result-format",
3595
+ "summary": "Format of the agent test run results.",
3596
+ "default": "human",
3597
+ "hasDynamicHelp": false,
3598
+ "multiple": false,
3599
+ "options": [
3600
+ "json",
3601
+ "human",
3602
+ "junit",
3603
+ "tap"
3604
+ ],
3605
+ "type": "option"
3606
+ },
3773
3607
  "output-dir": {
3774
3608
  "char": "d",
3609
+ "description": "If the agent test run completes, write the results to the specified directory. If the test is still running, the test results aren't written.",
3775
3610
  "name": "output-dir",
3776
- "summary": "Directory where the authoring bundle files are generated.",
3611
+ "summary": "Directory to write the agent test results into.",
3777
3612
  "hasDynamicHelp": false,
3778
3613
  "multiple": false,
3779
3614
  "type": "option"
3780
3615
  },
3781
- "name": {
3782
- "char": "n",
3783
- "name": "name",
3784
- "summary": "Name (label) of the authoring bundle; if not specified, you're prompted for the name.",
3616
+ "test-runner": {
3617
+ "description": "By default, the command automatically detects which test runner to use based on the test definition metadata type in your org. Use this flag to explicitly specify the runner type. 'agentforce-studio' uses AiTestingDefinition metadata. 'testing-center' uses AiEvaluationDefinition metadata.",
3618
+ "name": "test-runner",
3619
+ "summary": "Explicitly specify which test runner to use (agentforce-studio or testing-center).",
3785
3620
  "hasDynamicHelp": false,
3786
3621
  "multiple": false,
3622
+ "options": [
3623
+ "agentforce-studio",
3624
+ "testing-center"
3625
+ ],
3787
3626
  "type": "option"
3788
3627
  },
3789
- "force-overwrite": {
3790
- "name": "force-overwrite",
3791
- "summary": "Overwrite the existing authoring bundle if one with the same API name already exists locally.",
3628
+ "verbose": {
3629
+ "description": "When enabled, includes detailed generated data (such as invoked actions) in the human-readable test results output. This is useful for debugging test failures and understanding what actions were actually invoked during the test run.\n\nThe generated data is in JSON format and includes the Apex classes or Flows that were invoked, the Salesforce objects that were touched, and so on. Use the JSON structure of this information to build the test case JSONPath expression when using custom evaluations.",
3630
+ "name": "verbose",
3631
+ "summary": "Show generated data in the test results output.",
3792
3632
  "allowNo": false,
3793
3633
  "type": "boolean"
3794
3634
  }
3795
3635
  },
3796
3636
  "hasDynamicHelp": true,
3797
3637
  "hiddenAliases": [],
3798
- "id": "agent:generate:authoring-bundle",
3638
+ "id": "agent:test:resume",
3799
3639
  "pluginAlias": "@salesforce/plugin-agent",
3800
3640
  "pluginName": "@salesforce/plugin-agent",
3801
3641
  "pluginType": "core",
3802
3642
  "strict": true,
3803
- "summary": "Generate an authoring bundle from an existing agent spec YAML file.",
3643
+ "summary": "Resume an agent test that you previously started in your org so you can view the test results.",
3804
3644
  "enableJsonFlag": true,
3805
- "requiresProject": true,
3645
+ "envVariablesSection": {
3646
+ "header": "ENVIRONMENT VARIABLES",
3647
+ "body": [
3648
+ {
3649
+ "name": "SF_TARGET_ORG",
3650
+ "description": "Username or alias of your default org. Overrides the target-org configuration variable."
3651
+ }
3652
+ ]
3653
+ },
3654
+ "errorCodes": {
3655
+ "header": "ERROR CODES",
3656
+ "body": [
3657
+ {
3658
+ "name": "Succeeded (0)",
3659
+ "description": "Test completed successfully (with test results in the output)."
3660
+ },
3661
+ {
3662
+ "name": "Failed (1)",
3663
+ "description": "Tests encountered execution errors (test cases with ERROR status)."
3664
+ },
3665
+ {
3666
+ "name": "NotFound (2)",
3667
+ "description": "Job ID not found or invalid."
3668
+ },
3669
+ {
3670
+ "name": "OperationFailed (4)",
3671
+ "description": "Failed to poll test due to API or network errors."
3672
+ }
3673
+ ]
3674
+ },
3806
3675
  "isESM": true,
3807
3676
  "relativePath": [
3808
3677
  "lib",
3809
3678
  "commands",
3810
3679
  "agent",
3811
- "generate",
3812
- "authoring-bundle.js"
3680
+ "test",
3681
+ "resume.js"
3813
3682
  ],
3814
3683
  "aliasPermutations": [],
3815
3684
  "permutations": [
3816
- "agent:generate:authoring-bundle",
3817
- "generate:agent:authoring-bundle",
3818
- "generate:authoring-bundle:agent",
3819
- "agent:authoring-bundle:generate",
3820
- "authoring-bundle:agent:generate",
3821
- "authoring-bundle:generate:agent"
3685
+ "agent:test:resume",
3686
+ "test:agent:resume",
3687
+ "test:resume:agent",
3688
+ "agent:resume:test",
3689
+ "resume:agent:test",
3690
+ "resume:test:agent"
3822
3691
  ]
3823
3692
  },
3824
- "agent:generate:template": {
3693
+ "agent:test:run-eval": {
3825
3694
  "aliases": [],
3826
3695
  "args": {},
3827
- "description": "WARNING: This command doesn't work for agents that were created from an Agent Script file. In other words, you can't currently package an agent template for agents that use Agent Script.\n\nAt a high-level, agents are defined by the Bot, BotVersion, and GenAiPlannerBundle metadata types. The GenAiPlannerBundle type in turn defines the agent's topics and actions. This command uses the metadata files for these three types, located in your local DX project, to generate a BotTemplate metadata file for a specific agent (Bot). You then use the BotTemplate metadata file, along with the GenAiPlannerBundle metadata file that references the BotTemplate, to package the template in a managed package that you can share between orgs or on AppExchange.\n\nUse the --agent-file flag to specify the relative or full pathname of the Bot metadata file, such as force-app/main/default/bots/My_Awesome_Agent/My_Awesome_Agent.bot-meta.xml. A single Bot can have multiple BotVersions, so use the --agent-version flag to specify the version. The corresponding BotVersion metadata file must exist locally. For example, if you specify \"--agent-version 4\", then the file force-app/main/default/bots/My_Awesome_Agent/v4.botVersion-meta.xml must exist.\n\nThe new BotTemplate metadata file is generated in the \"botTemplates\" directory in the output directory specified with the --output-dir flag, and has the name <Agent_API_name>\\_v<Version>\\_Template.botTemplate-meta.xml, such as my-package/botTemplates/My_Awesome_Agent_v4_Template.botTemplate-meta.xml. The command displays the full pathname of the generated files when it completes.\n\nSee \"Develop and Package Agent Templates Using Scratch Orgs\" (https://developer.salesforce.com/docs/atlas.en-us.pkg2_dev.meta/pkg2_dev/dev2gp_package_agent_templates.htm) for details about the complete process, which includes using a scratch org to create and test the agent, retrieving the agent metadata to your DX project, running this command to create the agent template, and then packaging the template.",
3696
+ "description": "Specify the tests you want to run with one of these inputs to the --spec flag:\n\n- YAML test spec generated by the `agent generate test-spec` CLI command\n- JSON payload\n\nWhen you provide a YAML test spec, this command automatically translates test cases into internal state-based evaluation framework calls and infers the agent name from the test spec's `subjectName` field. As a result, you can use the same test spec with both the `agent test run` and `agent test run-eval` commands. YAML test specs also support context variables, which allow you to inject contextual data (such as CaseId or RoutableId) into agent sessions for testing with different contexts.\n\nWhen you provide a JSON payload, it's sent directly to the evaluation framework with optional normalization. The normalizer auto-corrects common field name mistakes, converts shorthand references to JSONPath, and injects defaults. Use `--no-normalize` to disable this auto-normalization. JSON payloads can also include context_variables on agent.create_session steps for the same contextual testing capabilities as when you use a YAML test spec.\n\nThis command supports more than 8 evaluator types, including subagent routing assertions, action invocation checks, string/numeric assertions, semantic similarity scoring, and LLM-based quality ratings.",
3828
3697
  "examples": [
3829
- "Generate an agent template from the My_Awesome_Agent Bot metadata file in your DX project and save the BotTemplate and GenAiPlannerBundle to the specified directory; use version 1 of the agent. The agent that the template is based on is in the org with alias \"my-scratch-org\":\n<%= config.bin %> <%= command.id %> --agent-file force-app/main/default/bots/My_Awesome_Agent/My_Awesome_Agent.bot-meta.xml --agent-version 1 --output-dir my-package --source-org my-scratch-org"
3698
+ "Run tests using a YAML test spec on the org with alias \"my-org\":\n<%= config.bin %> <%= command.id %> --spec specs/my-agent-testSpec.yaml --target-org my-org",
3699
+ "Run tests using a YAML spec with explicit agent name override; use your default org:\n<%= config.bin %> <%= command.id %> --spec specs/my-agent-testSpec.yaml --api-name My_Agent",
3700
+ "Run tests using a JSON payload:\n<%= config.bin %> <%= command.id %> --spec specs/eval-payload.json --target-org my-org",
3701
+ "Run tests and output results in JUnit format; useful for continuous integration and deployment (CI/CD):\n<%= config.bin %> <%= command.id %> --spec specs/my-agent-testSpec.yaml --target-org my-org --result-format junit",
3702
+ "Run tests with contextVariables to inject contextual data into agent sessions (add contextVariables to test cases in your YAML spec):\n<%= config.bin %> <%= command.id %> --spec specs/agent-with-context.yaml --target-org my-org",
3703
+ "Pipe JSON payload from stdin (--spec flag is automatically populated from stdin):\n$ echo '{\"tests\":[...]}' | <%= config.bin %> <%= command.id %> --spec --target-org my-org"
3830
3704
  ],
3831
3705
  "flags": {
3832
3706
  "json": {
@@ -3844,6 +3718,16 @@
3844
3718
  "multiple": false,
3845
3719
  "type": "option"
3846
3720
  },
3721
+ "target-org": {
3722
+ "char": "o",
3723
+ "name": "target-org",
3724
+ "noCacheDefault": true,
3725
+ "required": true,
3726
+ "summary": "Username or alias of the target org. Not required if the `target-org` configuration variable is already set.",
3727
+ "hasDynamicHelp": true,
3728
+ "multiple": false,
3729
+ "type": "option"
3730
+ },
3847
3731
  "api-version": {
3848
3732
  "description": "Override the api version used for api requests made by this command",
3849
3733
  "name": "api-version",
@@ -3851,82 +3735,127 @@
3851
3735
  "multiple": false,
3852
3736
  "type": "option"
3853
3737
  },
3854
- "source-org": {
3738
+ "spec": {
3855
3739
  "char": "s",
3856
- "name": "source-org",
3857
- "noCacheDefault": true,
3740
+ "name": "spec",
3858
3741
  "required": true,
3859
- "summary": "Username or alias of the namespaced scratch org that contains the agent which this template is based on.",
3860
- "hasDynamicHelp": true,
3742
+ "summary": "Path to test spec file (YAML or JSON). Supports reading from stdin when piping content.",
3743
+ "hasDynamicHelp": false,
3861
3744
  "multiple": false,
3862
3745
  "type": "option"
3863
3746
  },
3864
- "agent-version": {
3865
- "name": "agent-version",
3866
- "required": true,
3867
- "summary": "Version of the agent (BotVersion).",
3747
+ "api-name": {
3748
+ "char": "n",
3749
+ "name": "api-name",
3750
+ "summary": "Agent API name (also called DeveloperName) used to resolve agent_id and agent_version_id. Auto-inferred from the YAML spec's subjectName.",
3868
3751
  "hasDynamicHelp": false,
3869
3752
  "multiple": false,
3870
3753
  "type": "option"
3871
3754
  },
3872
- "agent-file": {
3873
- "char": "f",
3874
- "name": "agent-file",
3875
- "required": true,
3876
- "summary": "Path to an agent (Bot) metadata file.",
3755
+ "result-format": {
3756
+ "name": "result-format",
3757
+ "summary": "Format of the agent test run results.",
3758
+ "default": "human",
3877
3759
  "hasDynamicHelp": false,
3878
3760
  "multiple": false,
3761
+ "options": [
3762
+ "json",
3763
+ "human",
3764
+ "junit",
3765
+ "tap"
3766
+ ],
3879
3767
  "type": "option"
3880
3768
  },
3881
- "output-dir": {
3882
- "char": "r",
3883
- "name": "output-dir",
3884
- "summary": "Directory where the generated BotTemplate and GenAiPlannerBundle files are saved.",
3769
+ "batch-size": {
3770
+ "name": "batch-size",
3771
+ "summary": "Number of tests per API request (max 5).",
3772
+ "default": 5,
3885
3773
  "hasDynamicHelp": false,
3886
3774
  "multiple": false,
3887
3775
  "type": "option"
3776
+ },
3777
+ "no-normalize": {
3778
+ "name": "no-normalize",
3779
+ "summary": "Disable auto-normalization of field names and shorthand references.",
3780
+ "allowNo": false,
3781
+ "type": "boolean"
3888
3782
  }
3889
3783
  },
3890
3784
  "hasDynamicHelp": true,
3891
3785
  "hiddenAliases": [],
3892
- "id": "agent:generate:template",
3786
+ "id": "agent:test:run-eval",
3893
3787
  "pluginAlias": "@salesforce/plugin-agent",
3894
3788
  "pluginName": "@salesforce/plugin-agent",
3895
3789
  "pluginType": "core",
3790
+ "state": "beta",
3896
3791
  "strict": true,
3897
- "summary": "Generate an agent template from an existing agent in your DX project so you can then package the template in a second-generation managed package.",
3792
+ "summary": "Run rich evaluation tests against an Agentforce agent.",
3898
3793
  "enableJsonFlag": true,
3899
- "requiresProject": true,
3794
+ "envVariablesSection": {
3795
+ "header": "ENVIRONMENT VARIABLES",
3796
+ "body": [
3797
+ {
3798
+ "name": "SF_TARGET_ORG",
3799
+ "description": "Username or alias of your default org. Overrides the target-org configuration variable."
3800
+ }
3801
+ ]
3802
+ },
3803
+ "errorCodes": {
3804
+ "header": "ERROR CODES",
3805
+ "body": [
3806
+ {
3807
+ "name": "Succeeded (0)",
3808
+ "description": "Tests completed successfully. Test results (passed/failed) are in the JSON output."
3809
+ },
3810
+ {
3811
+ "name": "Failed (1)",
3812
+ "description": "Tests encountered execution errors (tests couldn't run properly)."
3813
+ },
3814
+ {
3815
+ "name": "NotFound (2)",
3816
+ "description": "Agent not found, spec file not found, or invalid agent name."
3817
+ },
3818
+ {
3819
+ "name": "OperationFailed (4)",
3820
+ "description": "Failed to execute tests due to API or network errors."
3821
+ }
3822
+ ]
3823
+ },
3900
3824
  "isESM": true,
3901
3825
  "relativePath": [
3902
3826
  "lib",
3903
3827
  "commands",
3904
3828
  "agent",
3905
- "generate",
3906
- "template.js"
3829
+ "test",
3830
+ "run-eval.js"
3907
3831
  ],
3908
3832
  "aliasPermutations": [],
3909
3833
  "permutations": [
3910
- "agent:generate:template",
3911
- "generate:agent:template",
3912
- "generate:template:agent",
3913
- "agent:template:generate",
3914
- "template:agent:generate",
3915
- "template:generate:agent"
3834
+ "agent:test:run-eval",
3835
+ "test:agent:run-eval",
3836
+ "test:run-eval:agent",
3837
+ "agent:run-eval:test",
3838
+ "run-eval:agent:test",
3839
+ "run-eval:test:agent"
3916
3840
  ]
3917
3841
  },
3918
- "agent:generate:test-spec": {
3842
+ "agent:test:run": {
3919
3843
  "aliases": [],
3920
3844
  "args": {},
3921
- "description": "The first step when using Salesforce CLI to create an agent test in your org is to use this interactive command to generate a local YAML-formatted test spec file. The test spec YAML file contains information about the agent being tested, such as its API name, and then one or more test cases. This command uses the metadata components in your DX project when prompting for information, such as the agent API name; it doesn't look in your org.\n\nTo generate a specific agent test case, this command prompts you for this information; when possible, the command provides a list of options for you to choose from:\n\n- Utterance: Natural language statement, question, or command used to test the agent.\n- Expected topic: API name of the topic you expect the agent to use when responding to the utterance.\n- Expected actions: One or more API names of the expection actions the agent takes.\n- Expected outcome: Natural language description of the outcome you expect.\n- (Optional) Custom evaluation: Test an agent's response for specific strings or numbers.\n- (Optional) Conversation history: Boilerplate for additional context you can add to the test in the form of a conversation history.\n\nYou can manually add contextVariables to test cases in the generated YAML file to inject contextual data (such as CaseId or RoutableId) into agent sessions. This is useful for testing agent behavior with different contextual information.\n\nWhen your test spec is ready, you then run the \"agent test create\" command to actually create the test in your org and synchronize the metadata with your DX project. The metadata type for an agent test is `AiEvaluationDefinition` (legacy testing-center) or `AiTestingDefinition` (Agentforce Studio / NGT), selected via --test-runner.\n\nIf you have an existing AiEvaluationDefinition or AiTestingDefinition metadata XML file in your DX project, you can generate its equivalent YAML test spec file with the --from-definition flag. The runner is inferred from the file extension; pass --test-runner to override.",
3845
+ "description": "Use the --api-name flag to specify the name of the agent test you want to run. Use the output of the \"agent test list\" command to get the names of all the available agent tests in your org.\n\nBy default, this command starts the agent test in your org, but it doesn't wait for the test to finish. Instead, it displays the \"agent test resume\" command, with a job ID, that you execute to see the results of the test run, and then returns control of the terminal window to you. Use the --wait flag to specify the number of minutes for the command to wait for the agent test to complete; if the test completes by the end of the wait time, the command displays the test results. If not, run \"agent test resume\".\n\nBy default, this command outputs test results in human-readable tables for each test case, if the test completes in time. The tables show whether the test case passed, the expected and actual values, the test score, how long the test took, and more. Use the --result-format to display the test results in JSON or Junit format. Use the --output-dir flag to write the results to a file rather than to the terminal.",
3922
3846
  "examples": [
3923
- "Generate an agent test spec YAML file interactively:\n<%= config.bin %> <%= command.id %>",
3924
- "Generate an Agentforce Studio (NGT) test spec YAML file interactively:\n<%= config.bin %> <%= command.id %> --test-runner agentforce-studio",
3925
- "Generate an agent test spec YAML file and specify a name for the new file; if the file exists, overwrite it without confirmation:\n<%= config.bin %> <%= command.id %> --output-file specs/Resort_Manager-new-version-testSpec.yaml --force-overwrite",
3926
- "Generate an agent test spec YAML file from an existing AiEvaluationDefinition metadata XML file in your DX project:\n<%= config.bin %> <%= command.id %> --from-definition force-app/main/default/aiEvaluationDefinitions/Resort_Manager_Tests.aiEvaluationDefinition-meta.xml",
3927
- "Generate an Agentforce Studio (NGT) test spec YAML file from an existing AiTestingDefinition metadata XML file:\n<%= config.bin %> <%= command.id %> --from-definition force-app/main/default/aiTestingDefinitions/Returns_Checkout_Tests.aiTestingDefinition-meta.xml"
3847
+ "Start an agent test called Resort_Manager_Test for an agent in your default org, don't wait for the test to finish:\n<%= config.bin %> <%= command.id %> --api-name Resort_Manager_Test",
3848
+ "Start an agent test for an agent in an org with alias \"my-org\" and wait for 10 minutes for the test to finish:\n<%= config.bin %> <%= command.id %> --api-name Resort_Manager_Test --wait 10 --target-org my-org",
3849
+ "Start an agent test and write the JSON-formatted results into a directory called \"test-results\":\n<%= config.bin %> <%= command.id %> --api-name Resort_Manager_Test --wait 10 --output-dir ./test-results --result-format json"
3928
3850
  ],
3929
3851
  "flags": {
3852
+ "json": {
3853
+ "description": "Format output as json.",
3854
+ "helpGroup": "GLOBAL",
3855
+ "name": "json",
3856
+ "allowNo": false,
3857
+ "type": "boolean"
3858
+ },
3930
3859
  "flags-dir": {
3931
3860
  "helpGroup": "GLOBAL",
3932
3861
  "name": "flags-dir",
@@ -3935,24 +3864,58 @@
3935
3864
  "multiple": false,
3936
3865
  "type": "option"
3937
3866
  },
3938
- "from-definition": {
3939
- "char": "d",
3940
- "name": "from-definition",
3941
- "summary": "Filepath to an AiEvaluationDefinition or AiTestingDefinition metadata XML file in your DX project that you want to convert to a test spec YAML file.",
3867
+ "target-org": {
3868
+ "char": "o",
3869
+ "name": "target-org",
3870
+ "noCacheDefault": true,
3871
+ "required": true,
3872
+ "summary": "Username or alias of the target org. Not required if the `target-org` configuration variable is already set.",
3873
+ "hasDynamicHelp": true,
3874
+ "multiple": false,
3875
+ "type": "option"
3876
+ },
3877
+ "api-version": {
3878
+ "description": "Override the api version used for api requests made by this command",
3879
+ "name": "api-version",
3942
3880
  "hasDynamicHelp": false,
3943
3881
  "multiple": false,
3944
3882
  "type": "option"
3945
3883
  },
3946
- "force-overwrite": {
3947
- "name": "force-overwrite",
3948
- "summary": "Don't prompt for confirmation when overwriting an existing test spec YAML file.",
3949
- "allowNo": false,
3950
- "type": "boolean"
3884
+ "api-name": {
3885
+ "char": "n",
3886
+ "name": "api-name",
3887
+ "summary": "API name of the agent test to run; corresponds to the name of the AiEvaluationDefinition metadata component that implements the agent test.",
3888
+ "hasDynamicHelp": false,
3889
+ "multiple": false,
3890
+ "type": "option"
3951
3891
  },
3952
- "output-file": {
3953
- "char": "f",
3954
- "name": "output-file",
3955
- "summary": "Name of the generated test spec YAML file. Default value is \"specs/<AGENT_API_NAME>-testSpec.yaml\" (legacy) or \"specs/<AGENT_API_NAME>-ngtTestSpec.yaml\" (Agentforce Studio).",
3892
+ "wait": {
3893
+ "char": "w",
3894
+ "name": "wait",
3895
+ "summary": "Number of minutes to wait for the command to complete and display results to the terminal window.",
3896
+ "hasDynamicHelp": true,
3897
+ "multiple": false,
3898
+ "type": "option"
3899
+ },
3900
+ "result-format": {
3901
+ "name": "result-format",
3902
+ "summary": "Format of the agent test run results.",
3903
+ "default": "human",
3904
+ "hasDynamicHelp": false,
3905
+ "multiple": false,
3906
+ "options": [
3907
+ "json",
3908
+ "human",
3909
+ "junit",
3910
+ "tap"
3911
+ ],
3912
+ "type": "option"
3913
+ },
3914
+ "output-dir": {
3915
+ "char": "d",
3916
+ "description": "If the agent test run completes, write the results to the specified directory. If the test is still running, the test results aren't written.",
3917
+ "name": "output-dir",
3918
+ "summary": "Directory to write the agent test results into.",
3956
3919
  "hasDynamicHelp": false,
3957
3920
  "multiple": false,
3958
3921
  "type": "option"
@@ -3968,33 +3931,70 @@
3968
3931
  "testing-center"
3969
3932
  ],
3970
3933
  "type": "option"
3934
+ },
3935
+ "verbose": {
3936
+ "description": "When enabled, includes detailed generated data (such as invoked actions) in the human-readable test results output. This is useful for debugging test failures and understanding what actions were actually invoked during the test run.\n\nThe generated data is in JSON format and includes the Apex classes or Flows that were invoked, the Salesforce objects that were touched, and so on. Use the JSON structure of this information to build the test case JSONPath expression when using custom evaluations.",
3937
+ "name": "verbose",
3938
+ "summary": "Show generated data in the test results output.",
3939
+ "allowNo": false,
3940
+ "type": "boolean"
3971
3941
  }
3972
3942
  },
3973
- "hasDynamicHelp": false,
3943
+ "hasDynamicHelp": true,
3974
3944
  "hiddenAliases": [],
3975
- "id": "agent:generate:test-spec",
3945
+ "id": "agent:test:run",
3976
3946
  "pluginAlias": "@salesforce/plugin-agent",
3977
3947
  "pluginName": "@salesforce/plugin-agent",
3978
3948
  "pluginType": "core",
3979
3949
  "strict": true,
3980
- "summary": "Generate an agent test spec, which is a YAML file that lists the test cases for testing a specific agent.",
3981
- "enableJsonFlag": false,
3950
+ "summary": "Start an agent test in your org.",
3951
+ "enableJsonFlag": true,
3952
+ "envVariablesSection": {
3953
+ "header": "ENVIRONMENT VARIABLES",
3954
+ "body": [
3955
+ {
3956
+ "name": "SF_TARGET_ORG",
3957
+ "description": "Username or alias of your default org. Overrides the target-org configuration variable."
3958
+ }
3959
+ ]
3960
+ },
3961
+ "errorCodes": {
3962
+ "header": "ERROR CODES",
3963
+ "body": [
3964
+ {
3965
+ "name": "Succeeded (0)",
3966
+ "description": "Test started successfully (without --wait), or test completed successfully (with --wait)."
3967
+ },
3968
+ {
3969
+ "name": "Failed (1)",
3970
+ "description": "Tests encountered execution errors (test cases with ERROR status when using --wait)."
3971
+ },
3972
+ {
3973
+ "name": "NotFound (2)",
3974
+ "description": "Test definition not found or invalid test name."
3975
+ },
3976
+ {
3977
+ "name": "OperationFailed (4)",
3978
+ "description": "Failed to start or poll test due to API or network errors."
3979
+ }
3980
+ ]
3981
+ },
3982
3982
  "isESM": true,
3983
3983
  "relativePath": [
3984
3984
  "lib",
3985
3985
  "commands",
3986
3986
  "agent",
3987
- "generate",
3988
- "test-spec.js"
3987
+ "test",
3988
+ "run.js"
3989
3989
  ],
3990
3990
  "aliasPermutations": [],
3991
3991
  "permutations": [
3992
- "agent:generate:test-spec",
3993
- "generate:agent:test-spec",
3994
- "generate:test-spec:agent",
3995
- "agent:test-spec:generate",
3996
- "test-spec:agent:generate",
3997
- "test-spec:generate:agent"
3992
+ "agent:test:run",
3993
+ "test:agent:run",
3994
+ "test:run:agent",
3995
+ "agent:run:test",
3996
+ "run:agent:test",
3997
+ "run:test:agent"
3998
3998
  ]
3999
3999
  },
4000
4000
  "agent:validate:authoring-bundle": {
@@ -4667,5 +4667,5 @@
4667
4667
  ]
4668
4668
  }
4669
4669
  },
4670
- "version": "1.45.0"
4670
+ "version": "2.0.0"
4671
4671
  }