Node client for the Salesforce Agent API

See the API documentation and the Postman collection for more information on the Salesforce Agent API.

• Quick Start Example
• Configuration
• Logging
• Reference

Quick Start Example

Here's an example that will get you started quickly with streaming events.

1. Install the client library and dotenv:

   npm install salesforce-agent-api-client dotenv

2. Create a .env file at the root of your project and configure it with the the following template:

   instanceUrl=
   clientId=
   clientSecret=
   agentId=

3. Create an index.js file with the following code:

   import * as dotenv from 'dotenv';
   import AgentApiClient from 'salesforce-agent-api-client';
   
   // Hard-coded prompt used for a single demo run
   const SAMPLE_PROMPT = 'What does "AI" stand for?';
   
   // Load config from .env file
   dotenv.config();
   const config = {
       instanceUrl: process.env.instanceUrl,
       clientId: process.env.clientId,
       clientSecret: process.env.clientSecret,
       agentId: process.env.agentId
   };
   
   // Configure Agent API client
   const client = new AgentApiClient(config);
   
   // Authenticate
   await client.authenticate();
   
   // Prepare SSE stream event handler
   function streamEventHandler({ data, event }) {
       const eventData = JSON.parse(data);
       console.log('Event: %s', event);
       console.log(JSON.stringify(eventData, null, 2));
       // TODO: add custom logic to process events
   }
   
   // Prepare SSE stream disconnect handler
   async function streamDisconnectHandler() {
       // On disconnect, close the session
       await client.closeSession(sessionId);
   }
   
   // Create a new session
   const sessionId = await client.createSession();
   const variables = [];
   try {
       // Sends an streaming message
       const eventSource = client.sendStreamingMessage(
           sessionId,
           SAMPLE_PROMPT,
           variables,
           streamEventHandler,
           streamDisconnectHandler
       );
   } catch (error) {
       console.log(error);
       await client.closeSession(sessionId);
   }

4. Run the code with node index.js.

   If everything goes well, the output should look like this:

   Agent API: authenticated on https://coralcloudresorts19-dev-ed.develop.my.salesforce.com (API endpoint: https://api.salesforce.com)
   Agent API: created session a4923398-0d60-4529-9f7a-91f021409875
   Agent API: sending async message 1740068546539 with text: What does AI stand for?
   Event: INFORM
   {
       "timestamp": 1740068551742,
       "originEventId": "1740068546968-REQ",
       "traceId": "66b8d7d8f3aac7bb404730970c88659d",
       "offset": 0,
       "message": {
           "type": "Inform",
           "id": "f5d3d83f-3bc7-4d81-9f8f-4b7e75522aa3",
           "feedbackId": "12636229-b716-4fcd-ba0b-6a498e27caab",
           "planId": "12636229-b716-4fcd-ba0b-6a498e27caab",
           "isContentSafe": true,
           "message": "How can I assist you with any customer support issues today?",
           "result": [],
           "citedReferences": []
       }
   }
   Event: END_OF_TURN
   {
       "timestamp": 1740068551746,
       "originEventId": "1740068546968-REQ",
       "traceId": "66b8d7d8f3aac7bb404730970c88659d",
       "offset": 0,
       "message": {
           "type": "EndOfTurn",
           "id": "696fd6f5-53bc-4366-b37c-fbf0a74ce992"
       }
   }
   SSE disconnected. Preventing auto reconnect.
   Agent API: closed session a4923398-0d60-4529-9f7a-91f021409875
   

Configuration

Object that describes the client configuration:

Name	Type	Description
instanceUrl	string	Your Salesforce Org domain.
clientId	string	Connected app client ID.
clientSecret	string	Connected app client secret.
agentId	string	Agent ID.

Logging

The client uses debug level messages so you can lower the default logging level if you need more information.

The documentation examples use the default client logger (the console). The console is fine for a test environment but you'll want to switch to a custom logger with asynchronous logging for increased performance.

You can pass a logger like pino in the client constructor:

import pino from 'pino';

const config = {
    /* your config goes here */
};
const logger = pino();
const client = new AgentApiClient(config, logger);

Reference

AgentApiClient

Client for the Salesforce Agent API

AgentApiClient(configuration, [logger])

Builds a new Agent API client.

Name	Type	Description
configuration	Configuration	The client configuration (authentication...).
logger	Logger	An optional custom logger. The client uses the console if no value is supplied.

async authenticate() → {Promise.<void>}

Authenticates with Salesforce.

Returns: Promise that resolves once the client is authenticated.

async createSession() → {Promise.<string>}

Creates an agent session.

Returns: Promise that holds the session ID.

async sendSyncMessage(sessionId, text, variables = []) → {Promise.<any>}

Sends a synchronous prompt to the agent.

Name	Type	Description
sessionId	string	An agent session ID.
text	string	The prompt sent to the agent.
variables	Object[]	Optional context variables.

Returns: Promise that holds the agent's response.

async sendStreamingMessage(sessionId, text, variables = [], onMessage, onDisconnect) → EventSource

Sends an asynchronous prompt to the agent.

Name	Type	Description
sessionId	string	An agent session ID.
text	string	The prompt sent to the agent.
variables	Object[]	Context variables.
onMessage	MessageCallback	Message callback function.
onDisconnect	function()	Optional disconnect callback function.

Returns: a SSE event source. See EventSource for implementation details.

MessageCallback(Object: message) is a callback function from EventSource. Notable message properties are as follow:

Name	Type	Description
event	string	Event type. One of INFORM, ERROR or END_OF_TURN.
data	string	The event data. Can be empty.

async closeSession(sessionId) → {Promise.<void>}

Closes the agent session.

Name	Type	Description
sessionId	string	An agent session ID.

Returns: Promise that resolves once the session is closed.

async submitFeedback(sessionId, feedbackId, feedback, feedbackText) → {Promise.<void>}

Submits feedback to the agent.

Name	Type	Description
sessionId	string	An agent session ID.
feedbackId	string	Feedback ID.
feedback	string	feedback type (GOOD or BAD)
feedbackText	string	Optional feedback text

Returns: Promise that resolves once the feedback is saved.