@salesforce/agents
Version:
Client side APIs for working with Salesforce agents
253 lines • 10.9 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.generateAgentApiName = 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."]]));
/**
* 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',
};
/**
* Class for creating Agents and agent specs.
*/
class Agent {
project;
logger;
maybeMock;
connection;
/**
* Create an Agent instance
*
* @param {Connection} connection
* @param {SfProject} project
*/
constructor(connection, project) {
this.project = project;
this.logger = core_1.Logger.childFromRoot(this.constructor.name);
this.maybeMock = new maybe_mock_1.MaybeMock(connection);
this.connection = connection;
}
/**
* List all agents in the current 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;
}
/**
* Creates an agent from a configuration, optionally saving the agent in an org.
*
* @param config a configuration for creating or previewing an agent
* @returns the agent definition
*/
async create(config) {
const url = '/connect/ai-assist/create-agent';
// When previewing agent creation just return the response.
if (!config.saveAgent) {
this.logger.debug(`Previewing agent creation using config: ${(0, node_util_1.inspect)(config)} in project: ${this.project.getPath()}`);
await core_1.Lifecycle.getInstance().emit(exports.AgentCreateLifecycleStages.Previewing, {});
const response = await this.maybeMock.request('POST', url, config);
return decodeResponse(response);
}
if (!config.agentSettings?.agentName) {
throw messages.createError('missingAgentName');
}
this.logger.debug(`Creating agent using config: ${(0, node_util_1.inspect)(config)} in project: ${this.project.getPath()}`);
await core_1.Lifecycle.getInstance().emit(exports.AgentCreateLifecycleStages.Creating, {});
if (!config.agentSettings.agentApiName) {
config.agentSettings.agentApiName = (0, exports.generateAgentApiName)(config.agentSettings?.agentName);
}
const response = await this.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 = this.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: this.connection.getUsername(),
exclude: [],
},
});
const retrieve = await cs.retrieve({
usernameOrConnection: this.connection,
merge: true,
format: 'source',
output: 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 config The configuration used to generate an agent spec.
*/
async createSpec(config) {
this.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 this.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,
});
}
}
// eslint-disable-next-line class-methods-use-this
verifyAgentSpecConfig(config) {
const { agentType, role, companyName, companyDescription } = config;
if (!agentType || !role || !companyName || !companyDescription) {
throw messages.createError('invalidAgentSpecConfig');
}
}
}
exports.Agent = Agent;
/**
* Generate an API name from an agent name. Matches what the UI does.
*/
const generateAgentApiName = (agentName) => {
const maxLength = 255;
let apiName = agentName;
apiName = apiName.replace(/[\W_]+/g, '_');
if (apiName.charAt(0).match(/_/i)) {
apiName = apiName.slice(1);
}
apiName = apiName
.replace(/(^\d+)/, 'X$1')
.slice(0, maxLength)
.replace(/_$/, '');
const logger = core_1.Logger.childFromRoot('Agent-GenApiName');
logger.debug(`Generated Agent API name: [${apiName}] from Agent name: [${agentName}]`);
return apiName;
};
exports.generateAgentApiName = generateAgentApiName;
// 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