Last updated: 22/08/2025

Best practices

Embedding an agent

1. Ensure responsiveness for mobile devices

To guarantee optimal responsiveness and prevent the agent UI text from appearing too small on mobile devices, include the following HTML tag within the <head> section of your webpage:

<head>
     <meta name="viewport" content="width=device-width, initial-scale=1">
</head>

This meta tag ensures proper scaling and a good user experience across various devices.

2. Control embedded agent UI dimensions

You can manage the size and position of the agent UI by passing parameters to its style attribute. If necessary, you can also wrap the <mindset-agent> tag within a parent <div> container. For example:

<mindset-agent
    agentUid="1rLosTJfVV0Ew9FPDfB7"
    style="width: 80%; height: 100%; display: block;">
</mindset-agent>

3. Customize embedded agent UI appearance

The <mindset-agent> tag allows for customization of the following:

Agent UI Width
Agent UI Height
Agent UI Background Color: This is only visible for a few milliseconds while the UI loads completely.

Example with background color:

<mindset-agent
    agentUid="1rLosTJfVV0Ew9FPDfB7"
    style="width: 100%; height: 100%; display: block; background-color: tomato;">
</mindset-agent>

You can also apply additional standard CSS parameters as needed:

<mindset-agent
    agentUid="v8srU0hv88BeWBDcirSm"
    style="transition: 0.3s; position: fixed; bottom: 0px; right: 0px; width: 100%; height: calc(100%); margin: 0px; border-radius: 0px; box-shadow: rgba(0, 0, 0, 0.2) 0px 4px 12px; background-color: rgb(255, 255, 255); overflow: hidden; transform-origin: right bottom; transform: scale(1); z-index: 9999; opacity: 1; pointer-events: auto; display: block;">
</mindset-agent>

4. Agent UI responsiveness for Videos and Segments

The agent UI is designed to be responsive and will adjust content based on the viewer’s screen size. When video content is played, a “Segment” area allows users to navigate between video segments. The display of the segment area depends on the screen width:

Right of the video: If the screen width is greater than 1056px.

Below the video: If the screen width is less than 1056px.

5. Sample code for embedding an agent in a Single Page Application

Below, a sample React component that embeds a Mindset agent:

import React, { useEffect } from "react";

export default function Mindset({ config }) {
    
    async function getAuthToken() {
        const currentUserId = 'session123'
        const userAuthTokenServerUrl = `YOUR-BACKEND-API-RETURNING-AUTHTOKEN`
        // e.g. https://mycompany-backend/api/getusertoken/${currentUserId}

        try {
            const headers = {
                "accept": "application/json",
                "Content-Type": "application/json"
            };
            const response = await fetch(userAuthTokenServerUrl, {
                method: 'POST',
                headers: headers,
                body: JSON.stringify({"currentUserId": `${currentUserId}`})
            });
            if (!response.ok) {
                throw new Error(`HTTP error! status: ${response.status}`);
            }
            const responseData = await response.json();
            return responseData.authToken;
        } catch (error) {
            console.log('Error fetching auth token:', error);
            throw error;
        }
    }

    function mindsetAgentInit() {
        if (window.mindset && typeof window.mindset.init === 'function' && !window.__mindsetInitCalled) {
            window.mindset.init({
                fetchAuthentication: getAuthToken,
                appUid: config.YOUR-APP-UID
            });
            window.__mindsetInitCalled = true;
        }
    }

    function mindsetSDKscriptLoad(scriptId) {
        const script = document.createElement('script');
        script.src = config.mindsetSdkUrl;
        script.id = scriptId;
        script.async = true;
        script.onload = () => {
            mindsetAgentInit()
        };
        document.body.appendChild(script);
    }

    useEffect(() => {
        const scriptId = 'mindset-sdk2-script';
        if (!document.getElementById(scriptId)) {
            mindsetSDKscriptLoad(scriptId)
        } else {
            mindsetAgentInit()
        }
    }, [config]);

    return (
        <mindset-agent 
            agentUid={config.YOUR-AGENT-UID}
            style={{
                width: '100%',
                height: '600px', 
                display: 'block',
                backgroundColor: rgb(255, 255, 255)
            }}
        ></mindset-agent>
    );
}

6. Embedding an agent in an IFRAME and voice to text feature

In case you embed the agent in an IFRAME, you will have to ensure that the IFRAME has the allow="microphone www.yourweburl.com" attribute set, so the voice to text feature works properly under SAFARI browser.

<iframe width="100%" height="100%" 
        allow="microphone https://mywebsite.com"
        src="https://mywebsite.com/embedagent.html"></iframe>

Agent access control

1. Agent access granted by Agent Sessions

If you embed your agents and provision the knowledge context through the agent Sessions mechanism and APIs, you have the full control over agents’ access. For example, as seen in the tutorial, when you create an AgentSession:

POST https://${MINDSET-API-HOST}/api/v1/appuid/${YOUR-APP-UID}/agentsessions
body : {
    agentUid: "v8srU0hv88BeWBDcirSm",
    externalUserId: "user-x123456",
    contextUids: ["qZJGsjytbM5fL15sfBui", "3am8rolEPXx3j0n132Bf"]
}
headers: {
    'Content-Type': 'application/json',
    'x-api-key': YOUR-MINDSET-API-KEY
}

You then give access to the agentUid v8srU0hv88BeWBDcirSm for the user user-x123456 (remember that the externalUserId is also passed to the embed agent SDK via the SDK Users auth API, so the Mindset system recognizes the user accordingly) In the Agent settings (Mindset app admin), there is an Access tab where two types of access can be set:

Open access - all app users
Restricted Access - only users with specified account membership

We recommend selecting the restricted access (without assigning any accounts) type because if the agent is restricted, then only users who have been granted access through an agent session will be able to communicate with it.

2. Agent access granted by Account membership

Without the agent sessions mechanism, agents access is managed via the SDK users API. When creating the user session (see authentication), you can specify the accountUids to which the user should be added. This is done by passing the accountUids array in the request body:

POST https://MINDSET-API-HOST/api/v1/appuid/YOUR-APP-UID/sdkusers/auth
body: {
  name: "My User Name", // optional 
  userEmail: "myuser@email.com", // Pass the userEmail if you want to authenticate a user by email as you did previously
  // OR
  externalId: "user-x123456", // Pass the externalId if you want to authenticate a user by externalId
  accountUids: ["accountUid1", "accountUid2"]
},
headers: {
    'Content-Type': 'application/json',
    'x-api-key': YOUR-MINDSET-API-KEY
}

if accountUids are provided, the user will be granted to use the agent only if the agent settings are :

Open access - all app users

Restricted Access with one of the account selected (accountUid1, accountUid2).

In most cases we recommend using agent sessions so you control the users permissions without managing accounts in your Mindset app admin area.

Agent creation

1. Provide clear purpose

✅ Good - specific and actionable purpose: “Answer questions about our e-commerce platform, help with order tracking, and provide product recommendations”❌ Avoid - a vague purpose: “Help customers”

When defining the agent’s purpose, be as specific as possible. A clear purpose helps guide the agent’s behavior and ensures it meets user expectations. Avoid vague descriptions that could lead to confusion or misalignment with user needs.

Why Agent Purpose Matters

The purpose field is critical because it defines the agent’s intended role and objectives. A well-defined purpose not only guides the agent’s behavior but also enables future analysis of its conversations to determine if it is achieving its intended outcomes. When the purpose is specific and measurable, you can assess the agent’s effectiveness and make improvements based on real-world interactions.

Characteristics of a Good Agent Purpose

Specific: Clearly states what the agent should do.
Measurable: Enables evaluation of whether the agent is fulfilling its role.
Actionable: Describes tasks or goals the agent can realistically achieve.

Examples of Good Agent Purposes

Example Purpose	Why It’s Good
`Answer questions about our e-commerce platform, help with order tracking, and provide product recommendations`	Specific tasks and measurable outcomes for the agent
`Assist users with technical troubleshooting and software issues for our SaaS platform`	Clearly defines the scope (technical support) and the target audience (SaaS users)
`Guide new employees through onboarding, explain company policies, and answer HR-related questions`	Actionable, focused on onboarding and HR, with clear objectives
`Help customers find the right insurance products, explain coverage options, and provide policy information`	Outlines the agent’s role in product guidance and customer education
`Support students with homework questions in math and science, and provide step-by-step explanations`	Specifies subject areas and the type of help (step-by-step explanations) the agent should provide

2. Define Personality Traits

✅ Good - specific personality traits personality: “Professional yet approachable, uses positive language, shows empathy for customer concerns”❌ Avoid - generic descriptions personality: “Nice and helpful”

Personality examples

Below are the available personality types you can use for your agent’s personality field:

Name	Description	Example Personality Field
Friendly & Empathetic	For learning, coaching, and onboarding use cases. This personality is warm, understanding, and supportive.	`"You are friendly, empathetic, and supportive. Respond in a warm, understanding, and conversational manner, ensuring users feel heard and valued. Use positive language and provide encouragement whenever possible."`
Professional & Knowledgeable	For professional writing or giving important responses. This personality is confident and authoritative.	`"You are professional, knowledgeable, and confident. Respond in a clear, concise, and accurate manner, ensuring information is reliable and authoritative. Maintain a formal tone and provide well-structured responses."`
Insightful & Analytical	For problem solving, ideation, and research use cases. This personality is detail-oriented, analytical, and data-driven.	`"You are insightful, analytical, and thoughtful. Respond in a detailed, evidence-based manner, providing in-depth analysis and data to support your answers. Focus on accuracy and thoroughness in your explanations."`
Strict & Precise	For answering important questions, guidelines, or procedures such as compliance or drafting formal documents. This personality is firm, concise, and meticulous.	`"You are strict, precise, and rule-focused. Respond in a firm, meticulous manner, ensuring all responses adhere to established guidelines and policies. Maintain a formal and authoritative tone, and prioritize accuracy and compliance."`
Custom Personality	Define the personality for this agent.	(Provide your own custom description and prompt.)

3. Specify Clear Formatting Rules

✅ Good - detailed formatting instructions formatting: “Use numbered lists for multi-step processes, bullet points for options, and bold text for important warnings”❌ Avoid - vague formatting: “Be clear”

Formatting examples

Below are the available formatting types you can use for your agent’s formatting field:

Name	Formatting Field
Conversational	`"Use a friendly, conversational tone with short paragraphs. Avoid using numbered lists or bullet points. Instead, write in a way that flows naturally, as if you were speaking with the user. Example: Hi there! 😊 How can I help you today?"`
Structured	`"Keep paragraphs short and use limited emojis and bullet points. Use GitHub markdown. Example: - Item 1 - Item 2 - Item 3"`
Storytelling	"Use vivid descriptions, metaphors, and anecdotes. Write in a way that paints a picture in the reader's mind and draws them into the story. Avoid using bullet points and lists. Example: Imagine you're launching a new product. The excitement in the air is palpable as the team gathers around, each person contributing their unique skills. The campaign's visuals are like vibrant strokes on a canvas, each one telling a part of the brand's story. Suddenly, the data starts pouring in, showing a wave of interest from eager customers, each click a testament to the hard work and creativity invested..."
Technical	`"Use tables, block quotes, and inline code. Use GitHub markdown. Put code in codeblocks."`

4. Set Appropriate Policies

✅ Good - specific boundaries the LLM can implement policy: “Never provide medical advice or health recommendations. Always direct users to consult healthcare professionals.”✅ Good - content restrictions the LLM can follow policy: “Do not mention or compare with products from companies such as Google, Microsoft, or Amazon. Only discuss and provide information about our company’s (ACME Corp) solutions.”❌ Avoid - requires external actions the LLM cannot perform policy: “Escalate complex issues to human agents”

Effective Policy Examples

The policy field should contain rules that the LLM can implement through its responses. Here are examples of effective policies:

Effective Policy Examples

Category	Description	Example Policy
Content Restrictions	Restrict certain topics	`"Do not provide investment advice, tax guidance, or legal counsel. Direct users to qualified professionals for these topics."`
Content Restrictions	Limit scope to company products	`"Only discuss our company's products and services. Do not make comparisons with or recommendations about competitor products."`
Response Guidelines	Require disclaimers	`"Always include a disclaimer when providing technical instructions: 'Please backup your data before making any system changes.'"`
Response Guidelines	Set boundaries on advice	`"Provide general guidance only. For account-specific issues, direct users to log into their account or contact support directly."`
Safety and Compliance	Prevent harmful content	`"Never provide instructions that could be used to harm systems, bypass security, or violate terms of service."`
Safety and Compliance	Maintain professional boundaries	`"Keep all conversations professional and on-topic. Do not engage in personal discussions unrelated to business needs."`
Information Handling	Protect sensitive information	`"Never ask for or process personal information like passwords, social security numbers, or payment details in conversations."`
Information Handling	Source attribution	`"When providing information from documentation, always reference the source and suggest users verify details in the latest official documentation."`

Limitations

1. Single agent per page

Our current implementation still limits the number of agents per page to one. We are working to remove this limitation and will let you know as soon as it is lifted.

2. Supported Google fonts

When using a google font for customizing the agent UI, we do not support 100% of the Google fonts available in that offical list: Google Fonts. We support most of them, but to ensure the font you want to use is supported, please check that Font list: Supported Google Fonts. The font name to use in the fontFamily parameter must be the font name displayed in that Google fonts list. For example:

const myCustomFontTheme = {
    fontFamily: 'Google Sans 3'
}

3. Embed agent voice to text with Firefox browser

The voice to text feature in the embedded agent UI is not supported yet in the Firefox browser.

Overview

Integrate Agent Chat SDK 3

Agent Chat SDK 3: Client-side Integration APIs

Data channels

Integrate Agent Chat SDK 2

MCP Server Integration

Agent Builder SDK Integration

API Overview

API playground

Webhooks

Best practices and known limitations

Best practices

Embedding an agent

1. Ensure responsiveness for mobile devices

2. Control embedded agent UI dimensions

3. Customize embedded agent UI appearance

4. Agent UI responsiveness for Videos and Segments

5. Sample code for embedding an agent in a Single Page Application

6. Embedding an agent in an IFRAME and voice to text feature

Agent access control

1. Agent access granted by Agent Sessions

2. Agent access granted by Account membership

Agent creation

1. Provide clear purpose

Why Agent Purpose Matters

Characteristics of a Good Agent Purpose

Examples of Good Agent Purposes

2. Define Personality Traits

Personality examples

3. Specify Clear Formatting Rules

Formatting examples

4. Set Appropriate Policies

Effective Policy Examples

Effective Policy Examples

Limitations

1. Single agent per page

2. Supported Google fonts

3. Embed agent voice to text with Firefox browser

​Best practices

​Embedding an agent

​1. Ensure responsiveness for mobile devices

​2. Control embedded agent UI dimensions

​3. Customize embedded agent UI appearance

​4. Agent UI responsiveness for Videos and Segments

​5. Sample code for embedding an agent in a Single Page Application

​6. Embedding an agent in an IFRAME and voice to text feature

​Agent access control

​1. Agent access granted by Agent Sessions

​2. Agent access granted by Account membership

​Agent creation

​1. Provide clear purpose

​Why Agent Purpose Matters

Characteristics of a Good Agent Purpose

Examples of Good Agent Purposes

​2. Define Personality Traits

​Personality examples

​3. Specify Clear Formatting Rules

​Formatting examples

​4. Set Appropriate Policies

​Effective Policy Examples

Effective Policy Examples

​Limitations

​1. Single agent per page

​2. Supported Google fonts

​3. Embed agent voice to text with Firefox browser

Best practices

Embedding an agent

1. Ensure responsiveness for mobile devices

2. Control embedded agent UI dimensions

3. Customize embedded agent UI appearance

4. Agent UI responsiveness for Videos and Segments

5. Sample code for embedding an agent in a Single Page Application

6. Embedding an agent in an IFRAME and voice to text feature

Agent access control

1. Agent access granted by Agent Sessions

2. Agent access granted by Account membership

Agent creation

1. Provide clear purpose

Why Agent Purpose Matters

2. Define Personality Traits

Personality examples

3. Specify Clear Formatting Rules

Formatting examples

4. Set Appropriate Policies

Effective Policy Examples

Limitations

1. Single agent per page

2. Supported Google fonts

3. Embed agent voice to text with Firefox browser