@salesforce/agents
Version:
Client side APIs for working with Salesforce agents
359 lines • 15.1 kB
JavaScript
;
/*
* Copyright (c) 2024, salesforce.com, inc.
* All rights reserved.
* Licensed under the BSD 3-Clause license.
* For full license text, see LICENSE.txt file in the repo root or https://opensource.org/licenses/BSD-3-Clause
*/
var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
if (k2 === undefined) k2 = k;
var desc = Object.getOwnPropertyDescriptor(m, k);
if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
desc = { enumerable: true, get: function() { return m[k]; } };
}
Object.defineProperty(o, k2, desc);
}) : (function(o, m, k, k2) {
if (k2 === undefined) k2 = k;
o[k2] = m[k];
}));
var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
Object.defineProperty(o, "default", { enumerable: true, value: v });
}) : function(o, v) {
o["default"] = v;
});
var __importStar = (this && this.__importStar) || (function () {
var ownKeys = function(o) {
ownKeys = Object.getOwnPropertyNames || function (o) {
var ar = [];
for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
return ar;
};
return ownKeys(o);
};
return function (mod) {
if (mod && mod.__esModule) return mod;
var result = {};
if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
__setModuleDefault(result, mod);
return result;
};
})();
Object.defineProperty(exports, "__esModule", { value: true });
exports.Agent = exports.AgentCreateLifecycleStages = void 0;
const node_util_1 = require("node:util");
const path = __importStar(require("node:path"));
const promises_1 = require("node:fs/promises");
const core_1 = require("@salesforce/core");
const source_deploy_retrieve_1 = require("@salesforce/source-deploy-retrieve");
const kit_1 = require("@salesforce/kit");
const maybe_mock_1 = require("./maybe-mock");
const utils_1 = require("./utils");
;
const messages = new core_1.Messages('@salesforce/agents', 'agents', new Map([["invalidAgentSpecConfig", "Missing one or more of the required agent spec arguments: type, role, companyName, companyDescription"], ["missingAgentName", "The \"agentName\" configuration property is required when saving an agent."], ["agentRetrievalError", "Unable to retrieve newly created Agent metadata. Due to: %s"], ["agentRetrievalErrorActions", "Retrieve the agent metadata using the \"project retrieve start\" command."], ["missingAgentNameOrId", "The \"nameOrId\" agent option is required when creating an Agent instance."], ["agentIsDeleted", "The %s agent has been deleted and its activation state can't be changed."], ["agentActivationError", "Changing the agent's activation status was unsuccessful due to %s."]]));
let logger;
const getLogger = () => {
if (!logger) {
logger = core_1.Logger.childFromRoot('Agent');
}
return logger;
};
/**
* Events emitted during Agent.create() for consumers to listen to and keep track of progress
*
* @type {{Creating: string, Previewing: string, Retrieving: string}}
*/
exports.AgentCreateLifecycleStages = {
Creating: 'creatingAgent',
Previewing: 'previewingAgent',
Retrieving: 'retrievingAgent',
};
/**
* A client side representation of an agent within an org. Also provides utilities
* such as creating agents, listing agents, and creating agent specs.
*
* **Examples**
*
* Create a new instance and get the ID (uses the `Bot` ID):
*
* `const id = new Agent({connection, name}).getId();`
*
* Create a new agent in the org:
*
* `const myAgent = await Agent.create(connection, project, options);`
*
* List all agents in the local project:
*
* `const agentList = await Agent.list(project);`
*/
class Agent {
options;
// The ID of the agent (Bot)
id;
// The name of the agent (Bot)
name;
// The metadata fields for the agent (Bot and BotVersion)
botMetadata;
/**
* Create an instance of an agent in an org. Must provide a connection to an org
* and the agent (Bot) API name or ID as part of `AgentOptions`.
*
* @param {options} AgentOptions
*/
constructor(options) {
this.options = options;
if (!options.nameOrId) {
throw messages.createError('missingAgentNameOrId');
}
if (options.nameOrId.startsWith('0Xx') && [15, 18].includes(options.nameOrId.length)) {
this.id = options.nameOrId;
}
else {
this.name = options.nameOrId;
}
}
/**
* List all agents in the current project.
*
* @param project a `SfProject` for a local DX project.
*/
static async list(project) {
const projectDirs = project.getPackageDirectories();
const bots = [];
const collectBots = async (botPath) => {
try {
const dirStat = await (0, promises_1.stat)(botPath);
if (!dirStat.isDirectory()) {
return;
}
bots.push(...(await (0, promises_1.readdir)(botPath)));
}
catch (_err) {
// eslint-disable-next-line no-unused-vars
}
};
for (const pkgDir of projectDirs) {
// eslint-disable-next-line no-await-in-loop
await collectBots(path.join(pkgDir.fullPath, 'bots'));
// eslint-disable-next-line no-await-in-loop
await collectBots(path.join(pkgDir.fullPath, 'main', 'default', 'bots'));
}
return bots;
}
/**
* Lists all agents in the org.
*
* @param connection a `Connection` to an org.
* @returns the list of agents
*/
static async listRemote(connection) {
const agentsQuery = await connection.query('SELECT FIELDS(ALL), (SELECT FIELDS(ALL) FROM BotVersions LIMIT 10) FROM BotDefinition LIMIT 100');
return agentsQuery.records;
}
/**
* Creates an agent from a configuration, optionally saving the agent in an org.
*
* @param connection a `Connection` to an org.
* @param project a `SfProject` for a local DX project.
* @param config a configuration for creating or previewing an agent.
* @returns the agent definition
*/
static async create(connection, project, config) {
const url = '/connect/ai-assist/create-agent';
const maybeMock = new maybe_mock_1.MaybeMock(connection);
// When previewing agent creation just return the response.
if (!config.saveAgent) {
getLogger().debug(`Previewing agent creation using config: ${(0, node_util_1.inspect)(config)} in project: ${project.getPath()}`);
await core_1.Lifecycle.getInstance().emit(exports.AgentCreateLifecycleStages.Previewing, {});
const response = await maybeMock.request('POST', url, config);
return decodeResponse(response);
}
if (!config.agentSettings?.agentName) {
throw messages.createError('missingAgentName');
}
getLogger().debug(`Creating agent using config: ${(0, node_util_1.inspect)(config)} in project: ${project.getPath()}`);
await core_1.Lifecycle.getInstance().emit(exports.AgentCreateLifecycleStages.Creating, {});
if (!config.agentSettings.agentApiName) {
config.agentSettings.agentApiName = (0, core_1.generateApiName)(config.agentSettings?.agentName);
}
const response = await maybeMock.request('POST', url, config);
// When saving agent creation we need to retrieve the created metadata.
if (response.isSuccess) {
await core_1.Lifecycle.getInstance().emit(exports.AgentCreateLifecycleStages.Retrieving, {});
const defaultPackagePath = project.getDefaultPackage().path ?? 'force-app';
try {
const cs = await source_deploy_retrieve_1.ComponentSetBuilder.build({
metadata: {
metadataEntries: [`Agent:${config.agentSettings.agentApiName}`],
directoryPaths: [defaultPackagePath],
},
org: {
username: connection.getUsername(),
exclude: [],
},
});
const retrieve = await cs.retrieve({
usernameOrConnection: connection,
merge: true,
format: 'source',
output: path.resolve(project.getPath(), defaultPackagePath),
});
const retrieveResult = await retrieve.pollStatus({
frequency: kit_1.Duration.milliseconds(200),
timeout: kit_1.Duration.minutes(5),
});
if (!retrieveResult.response.success) {
const errMessages = retrieveResult.response.messages?.toString() ?? 'unknown';
const error = messages.createError('agentRetrievalError', [errMessages]);
error.actions = [messages.getMessage('agentRetrievalErrorActions')];
throw error;
}
}
catch (err) {
const error = core_1.SfError.wrap(err);
if (error.name === 'AgentRetrievalError') {
throw error;
}
throw core_1.SfError.create({
name: 'AgentRetrievalError',
message: messages.getMessage('agentRetrievalError', [error.message]),
cause: error,
actions: [messages.getMessage('agentRetrievalErrorActions')],
});
}
}
return decodeResponse(response);
}
/**
* Create an agent spec from provided data.
*
* @param connection a `Connection` to an org.
* @param config The configuration used to generate an agent spec.
* @returns the agent job spec
*/
static async createSpec(connection, config) {
const maybeMock = new maybe_mock_1.MaybeMock(connection);
verifyAgentSpecConfig(config);
const url = '/connect/ai-assist/draft-agent-topics';
const body = {
agentType: config.agentType,
generationInfo: {
defaultInfo: {
role: config.role,
companyName: config.companyName,
companyDescription: config.companyDescription,
},
},
generationSettings: {
maxNumOfTopics: config.maxNumOfTopics ?? 10,
},
};
if (config.companyWebsite) {
body.generationInfo.defaultInfo.companyWebsite = config.companyWebsite;
}
if (config.promptTemplateName) {
body.generationInfo.customizedInfo = { promptTemplateName: config.promptTemplateName };
if (config.groundingContext) {
body.generationInfo.customizedInfo.groundingContext = config.groundingContext;
}
}
const response = await maybeMock.request('POST', url, body);
const htmlDecodedResponse = decodeResponse(response);
if (htmlDecodedResponse.isSuccess) {
return { ...config, topics: htmlDecodedResponse.topicDrafts };
}
else {
throw core_1.SfError.create({
name: 'AgentJobSpecCreateError',
message: htmlDecodedResponse.errorMessage ?? 'unknown',
data: htmlDecodedResponse,
});
}
}
/**
* Returns the ID for this agent.
*
* @returns The ID of the agent (The `Bot` ID).
*/
async getId() {
if (!this.id) {
await this.getBotMetadata();
}
return this.id; // getBotMetadata() ensures this.id is not undefined
}
/**
* Queries BotDefinition and BotVersions (limited to 10) for the bot metadata and assigns:
* 1. this.id
* 2. this.name
* 3. this.botMetadata
* 4. this.botVersionMetadata
*/
async getBotMetadata() {
if (!this.botMetadata) {
const whereClause = this.id ? `Id = '${this.id}'` : `DeveloperName = '${this.name}'`;
const query = `SELECT FIELDS(ALL), (SELECT FIELDS(ALL) FROM BotVersions LIMIT 10) FROM BotDefinition WHERE ${whereClause} LIMIT 1`;
this.botMetadata = await this.options.connection.singleRecordQuery(query);
this.id = this.botMetadata.Id;
this.name = this.botMetadata.DeveloperName;
}
return this.botMetadata;
}
/**
* Returns the latest bot version metadata.
*
* @returns the latest bot version metadata
*/
async getLatestBotVersionMetadata() {
if (!this.botMetadata) {
this.botMetadata = await this.getBotMetadata();
}
const botVersions = this.botMetadata.BotVersions.records;
return botVersions[botVersions.length - 1];
}
/**
* Activates the agent.
*
* @returns void
*/
async activate() {
return this.setAgentStatus('Active');
}
/**
* Deactivates the agent.
*
* @returns void
*/
async deactivate() {
return this.setAgentStatus('Inactive');
}
async setAgentStatus(desiredState) {
const botMetadata = await this.getBotMetadata();
const botVersionMetadata = await this.getLatestBotVersionMetadata();
if (botMetadata.IsDeleted) {
throw messages.createError('agentIsDeleted', [botMetadata.DeveloperName]);
}
if (botVersionMetadata.Status === desiredState) {
getLogger().debug(`Agent ${botMetadata.DeveloperName} is already ${desiredState}. Nothing to do.`);
return;
}
const url = `/connect/bot-versions/${botVersionMetadata.Id}/activation`;
const maybeMock = new maybe_mock_1.MaybeMock(this.options.connection);
const response = await maybeMock.request('POST', url, { status: desiredState });
if (response.success) {
this.botMetadata.BotVersions.records[0].Status = response.isActivated ? 'Active' : 'Inactive';
}
else {
throw messages.createError('agentActivationError', [response.messages?.toString() ?? 'unknown']);
}
}
}
exports.Agent = Agent;
// private function used by Agent.createSpec()
const verifyAgentSpecConfig = (config) => {
const { agentType, role, companyName, companyDescription } = config;
if (!agentType || !role || !companyName || !companyDescription) {
throw messages.createError('invalidAgentSpecConfig');
}
};
// Decodes all HTML entities in ai-assist API responses.
const decodeResponse = (response) => JSON.parse((0, utils_1.decodeHtmlEntities)(JSON.stringify(response)));
//# sourceMappingURL=agent.js.map