@salesforce/agents
Version:
Client side APIs for working with Salesforce agents
290 lines • 12.2 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."]]));
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;
id;
/**
* Create an instance of an agent in an org. Must provide a connection to an org
* and the agent (Bot) API name as part of `AgentOptions`.
*
* @param {options} AgentOptions
*/
constructor(options) {
this.options = options;
}
/**
* 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;
}
/**
* 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, exports.generateAgentApiName)(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: 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) {
const query = `SELECT Id FROM BotDefinition WHERE DeveloperName = '${this.options.name}'`;
this.id = (await this.options.connection.singleRecordQuery(query)).Id;
}
return this.id;
}
}
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');
}
};
/**
* 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 genLogger = core_1.Logger.childFromRoot('Agent-GenApiName');
genLogger.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