Here’s a guide to create agent sessions with programmatically provisioned Knowledge Contexts.
And then embed a programmatic agent in your web application using those agent sessions.
Default agent system
With the default agents system, your Mindset App admin dashboard manages access permissions for knowledge contexts assigned on an agent basis.
Knowledge Context Provisioning System
You may need to provision agents and knowledge contexts access based on the permission system set up in your platform.
We’ve introduced the concept of an agent session: Agent sessions are programmatically provisioned on-demand for specified agents and knowledge contexts.
Once an agent session is created, providing the agentSessionUid
to the <mindset-agent>
HTML tag will allow you to embed the agent with the specified access permissions.
Tutorial : Create agent sessions and embed an agent with provisioned knowledge contexts
Required parameters
You will need to get a few parameters before starting.
YOUR-APP-UID is provided by the Mindset support team. All others parameters can be found in the Mindset Management Portal.
Parameter | Description |
---|
YOUR-APP-UID | Your appUid is provided by mindset. |
YOUR-MINDSET-API-KEY | Your Mindset API key. It is used to authenticate your API calls. |
AGENT-UID | The agent Uid you want the user chat with. You can find that Agent Uid in the setting of the agent in the Agent Management Portal. |
KNOWLEDGECONTEXT-1-UID | One Knowledge context Uid you want to provision the agent with |
KNOWLEDGECONTEXT-2-UID | Another one Knowledge context Uid you want to provision the agent with |
MINDSET-API-HOST | The Mindset API host. Used to call the Mindset API. |
Step 1: Create an agent session
To create an Agent Session (and hence generate an agentSessionUid
required by the SDK), you will need to call the Mindset agentSessions API
. (See the Agent Sessions API documentation for more details).
You would need to manage multiple agents, knowledge contexts and users on your platform.
According to your permissions and roles system, users
would have specific rights to access specific agents and specific Knowledge contexts
For example:
- A
User1
has the permission to use the agent1
provisioned with the Knowledge Context 1
and knowledge context 2
.
- But a
User2
has the permission to use the agent1
provisioned with the Knowledge Context 1
Based on your permissions rules you will then create agent sessions
.
What we would like to achieve is :
- to provision the agent (
agentUid v8srU0hv88BeWBDcirSm
)
- with the 2 knowledge contexts (
contextUids [qZJGsjytbM5fL15sfBui
, 3am8rolEPXx3j0n132Bf
])
- and for a user with an
externalUserId
(user-x123456
).
We would need to provide the following parameters in the request body:
const requestBody = {
{
agentUid: "v8srU0hv88BeWBDcirSm",
externalUserId: "user-x123456",
contextUids: ["qZJGsjytbM5fL15sfBui", "3am8rolEPXx3j0n132Bf"]
}
};
Below is an example of an HTTP POST request to create that agent session.
// Example Node.js code to make a server-side HTTP POST request for creating an agent session
// Adapt this example based on your server-side programming environment
const fetch = require('node-fetch');
const YOUR-MINDSET-API-KEY = 'YOUR-MINDSET-API-KEY'
const MINDSET-API-HOST = 'MINDSET-API-HOST'
const YOUR-APP-UID = 'YOUR-APP-UID'
const requestBody = {
{
agentUid: "v8srU0hv88BeWBDcirSm",
externalUserId: "user-x123456",
contextUids: ["qZJGsjytbM5fL15sfBui", "3am8rolEPXx3j0n132Bf"]
}
};
fetch('https://${MINDSET-API-HOST}/api/v1/appuid/${YOUR-APP-UID}/agentsessions', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-api-key': YOUR-MINDSET-API-KEY
},
body: JSON.stringify(requestBody)
})
.then(response => response.json())
.catch((error) => {
console.error('Error:', error);
});
The API response object will be:
{
"uid": "uFKbuW0ipk2Za4QuQ6rx",
"createdAt": "2025-06-10T16:26:21.635Z",
"agentSessionUid": "v8srU0hv88BeWBDcirSm::uFKbuW0ipk2Za4QuQ6rx",
"humanUid": "j8no2tZ26IcWQgJ9oNJbHjOf7hE3",
"agentUid": "v8srU0hv88BeWBDcirSm",
"externalUserId": "user-x123456",
"lastUsedAt": "2025-06-10T16:26:21.634Z",
"tags": [],
"contextUids": [
"qZJGsjytbM5fL15sfBui",
"3am8rolEPXx3j0n132Bf"
],
"userEmail": ""
}
The most important information that will be reused in the next step is the :
agentSessionUid
(v8srU0hv88BeWBDcirSm::uFKbuW0ipk2Za4QuQ6rx
).
Step 2: Embed the agent in your web application
You embed this agent using the same method that you used to embed the default agent.
You will use the <mindset-agent>
HTML tag in your Front-end page:
<mindset-agent
agentUid='AGENT-SESSION-UID'
style='width: 100%; height: 600px; display: block; background-color: rgb(255, 255, 255);'>
</mindset-agent>
But instead of providing the agentUid
you will provide the agentSessionUid
you just created in the previous step.
The final HTML tag will look like this:
<mindset-agent
agentUid='v8srU0hv88BeWBDcirSm::uFKbuW0ipk2Za4QuQ6rx'
style='width: 100%; height: 600px; display: block; background-color: rgb(255, 255, 255);'>
</mindset-agent>
Agent Session Access Duration
Agent Sessions are intended to be generated on demand each time you create a web page that contains an embedded agent.
They become inactive after 31 days of non-use. They can also be deactivated immediately using the API.
We expect that you will create multiple agent sessions for the same user with identical agent and context details.
Please refer to the Agent Sessions API documentation for more details on how to manage agent sessions.
Reporting
Here’s how to set up reporting for agents.
When creating an agent session through the API, you can provide tags to the parmaters:
{
agentUid: "v8srU0hv88BeWBDcirSm",
externalUserId: "user-x123456",
contextUids: ["qZJGsjytbM5fL15sfBui", "3am8rolEPXx3j0n132Bf"],
tags: ["tag1", "tag2"],
}
When initiating an agent session, the tags you specify are essential for understanding the interaction between agents, contexts, and users.
Adding tags enables you to view reports based on groups or filter activity according to the tags you’ve applied.
Please refer to the Agent Sessions API documentation for more information on adding tags.
Back-end and Front-end scripts full example
Back-end script
Sample back-end script (using express).
It shows 2 end-points you can implement:
/api/getusertoken
which authenticate the user with Mindset system and returns an authToken
/api/getagentsessionuid
which create an agent session and returns the agentSessionUid
import express from "express";
import axios from "axios";
const YOUR-MINDSET-API-KEY = 'YOUR-MINDSET-API-KEY' ;
const MINDSET-API-HOST = 'MINDSET-API-HOST';
const YOUR-APP-UID = 'YOUR-APP-UID';
const app = express();
app.get("/api/getusertoken/:currentUserId", async (req, res) => {
const currentUserId = req.params.currentUserId;
const EXTERNAL-USER-ID = "userx123456" // You can use the currentUserId to get the externalId from your database or session store
try {
const embedUserToken: any = await axios.post(
`https://${MINDSET-API-HOST}/api/v1/appuid/${YOUR_APP_UID}/sdkusers/auth`,
{
externalId: EXTERNAL-USER-ID,
},
{
headers: {
'Content-Type': 'application/json',
'x-api-key': YOUR-MINDSET-API-KEY
},
}
)
res.send(embedUserToken.data);
} catch (error: any) {
console.error(error);
console.error("Error", error, error.response.status, error.response, error);
res.status(500).send("Error getting token");
};
});
app.get("/api/getagentsessionuid/:currentUserId", async (req, res) => {
const currentUserId = req.params.currentUserId;
const EXTERNAL-USER-ID = "userx123456" // You can use the currentUserId to get the externalId from your database or session store
const AGENT-UID = "AGENT-UID"; // The Agent Uid you want to provision
const KNOWLEDGE-CONTEXT-UID = "KNOWLEDGE-CONTEXT-UID"; // The Knowledge Context Uid you want to provision
try {
const agentSessionCreationResponse: any = await axios.post(
`https://${MINDSET-API-HOST}/api/v1/appuid/${YOUR-APP-UID}/agentsessions`,
{
agentUid: AGENT-UID,
externalUserId: EXTERNAL-USER-ID,
contextUids: [KNOWLEDGE-CONTEXT-UID]
},
{
headers: {
'Content-Type': 'application/json',
'x-api-key': YOUR-MINDSET-API-KEY
},
}
)
res.send(agentSessionCreationResponse.data);
} catch (error: any) {
console.error(error);
console.error("Error", error, error.response.status, error.response, error);
res.status(500).send("Error getting token");
};
});
export default app;
Front-end script
A sample front-end script which:
- Provide a
getAuthToken()
method using your /api/getusertoken
end-point.
- Provide a
getAgentSessionUid()
method using your /api/getagentsessionuid
end-point.
- Build the
<mindset-agent>
html tag by passing the agentSessionUid
returned.
- call
mindset.init()
<!DOCTYPE html>
<html>
<head>
<meta name="viewport" content="width=device-width, initial-scale=1">
<script src="MINDSET-SERVER-URL/mindset-sdk2.js"></script>
<body>
<script>
const userAgentSessionServerUrl = `https://YOUR-BACK-END-HOST/api/getagentsessionuid/${currentUserId}`
async function createAgentSession() {
try {
const response = await fetch(userAgentSessionServerUrl);
const textData = await response.json();
return textData.agentSessionUid;
} catch (error) {
console.log('Error fetching auth token:', error);
throw error;
}
}
const userAuthTokenServerUrl = `https://YOUR-BACK-END-HOST/api/getusertoken/${currentUserId}`
async function getAuthToken() {
try {
const response = await fetch(userAuthTokenServerUrl);
const textData = await response.json();
return textData.authToken;
} catch (error) {
console.log('Error fetching auth token:', error);
throw error;
}
}
(async function addMindsetAgent(){
const agentSessionUid = await createAgentSession()
const embededAgentPlaceholder = document.getElementById("embeded-agent-placeholder");
const agenttag = '<mindset-agent id="agent" agentUid="' + agentSessionUid + '" style="width: 100%; height: 600px; display: block;"></mindset-agent>'
embededAgentPlaceholder.innerHTML = agenttag;
mindset.init({
fetchAuthentication: getAuthToken,
appUid: "YOUR-APP-UID"
});
})();
</script>
<div id="embeded-agent-placeholder" style="width: 800px; height: 800px;"></div>
</body>
</html>
Responses are generated using AI and may contain mistakes.