Best Practices & Known Limitations

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 meta 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.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:

Agent UI Width
Agent UI Height
Agent UI Background Color (only visible for a few milliseconds while the UI loads)

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:

<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 screen width:

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

5. Sample Code for Single Page Applications

Below is a sample React component that embeds a Mindset AI 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 response = await fetch(userAuthTokenServerUrl);
            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-sdk3-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 with Voice

If you embed the agent in an IFRAME, ensure the IFRAME has the allow="microphone" attribute set so the voice-to-text feature works properly in Safari browser.

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

Agent Access Control

Agent Sessions
Account Membership

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 full control over agents’ access.Example: When you create an Agent Session:

{
  "agentUid": "v8srU0hv88BeWBDcirSm",
  "externalUserId": "user-x123456",
  "contextUids": ["qZJGsjytbM5fL15sfBui", "3am8rolEPXx3j0n132Bf"]
}

You grant access to the agent v8srU0hv88BeWBDcirSm for user user-x123456. The externalUserId is also passed to the embed agent SDK via the SDK Users auth API, so the Mindset AI system recognizes the user accordingly.Access Settings:In the Agent settings (Mindset AI admin), the Access tab offers two types:

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

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

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):

{
  "externalId": "user-x123456",
  "accountUids": ["accountUid1", "accountUid2"]
}

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

Open access - all app users, OR
Restricted Access with one of the accounts selected (accountUid1, accountUid2)

In most cases, we recommend using agent sessions so you control the user’s permissions without managing accounts in your Mindset AI app.

Agent Creation Best Practices

1. Provide a Clear Purpose

When defining the agent’s purpose, be as specific as possible. A clear purpose guides the agent’s behavior and ensures it meets user expectations.

Good Purpose

Specific and actionable:“Answer questions about our e-commerce platform, help with order tracking, and provide product recommendations”

Avoid

Vague purpose:“Help customers”

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.

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 Personality

Specific personality traits:“Professional yet approachable, uses positive language, shows empathy for customer concerns”

Avoid

Generic descriptions:“Nice and helpful”

Personality Examples

Friendly & Empathetic

Use for: Learning, coaching, and onboarding use casesDescription: Warm, understanding, and supportiveExample Personality Field:

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

Use for: Professional writing or giving important responsesDescription: Confident and authoritativeExample Personality Field:

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

Use for: Problem solving, ideation, and research use casesDescription: Detail-oriented, analytical, and data-drivenExample Personality Field:

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

Use for: Important questions, guidelines, or procedures such as compliance or drafting formal documentsDescription: Firm, concise, and meticulousExample Personality Field:

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

Use for: Any specific use case requiring unique personality traitsDescription: Define the personality for this agentExample Personality Field:

(Provide your own custom description and prompt.)

3. Specify Clear Formatting Rules

Good Formatting

Detailed formatting instructions:“Use numbered lists for multi-step processes, bullet points for options, and bold text for important warnings”

Avoid

Vague formatting:“Be clear”

Formatting Examples

Conversational
Structured
Storytelling
Technical

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?

Keep paragraphs short and use limited emojis and bullet points. Use GitHub markdown. 

Example:
- Item 1
- Item 2
- Item 3

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...

Use tables, block quotes, and inline code. Use GitHub markdown. Put code in codeblocks.

4. Set Appropriate Policies

Define policies that the LLM can actually implement, not policies that require external actions.

Good Policies

Specific boundaries the LLM can implement:“Never provide medical advice or health recommendations. Always direct users to consult healthcare professionals.”Content restrictions the LLM can follow:“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:“Escalate complex issues to human agents”

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.”

Known Limitations

The following limitations apply to the current SDK 3.0 build. We are actively working to address these.

1. Single Agent Per Page

Our current implementation limits the number of agents per page to one. We are working to remove this limitation and will notify you 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 the official Google Fonts list.We support most of them, but to ensure the font you want to use is supported, please check our Supported Google Fonts list.The font name to use in the fontFamily parameter must be the font name displayed in the Google fonts list.Example:

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

3. 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

Embedding an Agent

Agent Access Control

Agent Access Granted by Agent Sessions

Agent Access Granted by Account Membership

Agent Creation Best Practices

1. Provide a Clear Purpose

Good Purpose

Avoid

Why Agent Purpose Matters

Characteristics of a Good Agent Purpose

Examples of Good Agent Purposes

2. Define Personality Traits

Good Personality

Avoid

Personality Examples

3. Specify Clear Formatting Rules

Good Formatting

Avoid

Formatting Examples

4. Set Appropriate Policies

Good Policies

Avoid

Effective Policy Examples

Known Limitations

​Best Practices

​Embedding an Agent

​Agent Access Control

​Agent Access Granted by Agent Sessions

​Agent Access Granted by Account Membership

​Agent Creation Best Practices

​1. Provide a Clear Purpose

Good Purpose

Avoid

​Why Agent Purpose Matters

​Characteristics of a Good Agent Purpose

​Examples of Good Agent Purposes

​2. Define Personality Traits

Good Personality

Avoid

​Personality Examples

​3. Specify Clear Formatting Rules

Good Formatting

Avoid

​Formatting Examples

​4. Set Appropriate Policies

Good Policies

Avoid

​Effective Policy Examples

​Known Limitations

Best Practices

Embedding an Agent

Agent Access Control

Agent Access Granted by Agent Sessions

Agent Access Granted by Account Membership

Agent Creation Best Practices

1. Provide a 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

Known Limitations