Manage AI Agents - Cognigy Documentation

Documentation Index

Fetch the complete documentation index at: /llms.txt

Use this file to discover all available pages before exploring further.

Skip to main content

Updated in 2026.6 To manage a new generation of AI Agents, Cognigy.AI introduces the AI Agent Management interface, where you can create, edit, and delete AI Agents.

​ Create AI Agents

You can create an AI Agent from scratch or hire an AI Agent from the Job Market, designed for your industry, such as airlines, food services, or sales, and customize it to fit your business needs.To create an AI Agent, select one of the following options:

• Create from scratch
• Hire from the Job Market

​ Create from Scratch

• GUI

• API

1. In the left-side menu of the Project page, select Build > AI Agents.
2. Click Create AI Agent if you are creating an AI Agent for the first time, or click + New AI Agent on the AI Agents page if you have created at least one AI Agent before. Configure the following settings:

1. General Settings

1. In the General Settings step, fill in the following fields:

• Name — enter a name for your AI Agent. This name will be visible to end users when the AI Agent greets them in the chat or when one AI Agent transfers the conversation to another AI Agent. For example, Hello, my name is Sara. How can I help you? or Our support specialist Alex will help with this question, transferring the conversation now.
  • Description — enter a description of the AI Agent that shapes its behavior and enhances its ability to understand the desired communication style. For example, describe the AI Agent as follows: Anna works at ACME and is highly skilled at making customers feel comfortable.

2. In the Avatar section, select avatar of your choice or upload your custom one by clicking + next to avatars. You can use any image as an avatar for your AI Agent, or create a Cognigy-style avatar using the Cognigy.AI PSD template. To open and customize the template, you will need Adobe Photoshop or Paint.net with the PSD plugin installed. The requirements for the avatar are as follows:

• Use an alpha channel for a transparent background.
  • Set the recommended width to 136px.
  • Set the recommended height to 184px.
  • Save the file as .png.
  • Include _optimized in the file name.

2. Speaking Style

1. In the Speaking Style step, configure the following settings:

• Set up Style— configure how the AI Agent’s choice of wording is influenced by the selected speaking style, which can affect the tone and clarity of its responses:

• Concise/Comprehensive — adjust the slider to the left for brief responses and to the right for detailed responses.

  • Formal/Informal — adjust the slider to the left for more casual and conversational responses, and to the right for professional and structured responses.
  • Voice Configuration — assign a specific voice to your AI Agent if you want to use your AI Agent as a voice-based assistant. To configure this setting, ensure you have installed Voice Gateway and set up the Voice Preview provider. Then, fill in the fields following the same process you used for Set Session Config Node:

• TTS Vendor — select the text-to-speech provider for your AI Agent. This setting determines which service will convert the AI Agent’s text responses into speech.

  • TTS Language — select the language that your AI Agent will use for speech output. Ensure this language aligns with the preferred language of the end user.
  • TTS Voice — select the voice from the selected TTS vendor. This setting allows you to customize the tone, gender, and style of your AI Agent’s voice.
  • TTS Label — select the alternative name of the TTS vendor, as specified in the Voice Gateway Self-Service Portal. If you have multiple speech services from the same vendor, use the label to specify which service to use.
  • Disable TTS Audio Caching — by default, this setting is deactivated. With caching enabled, previously requested TTS audio is stored in the AI Agent cache, and repeated requests for the same audio text will use the cached result instead of sending another request. With caching disabled, the AI Agent stores the TTS audio but doesn’t use it; each request is sent directly to the speech provider. Note that disabling caching can increase TTS costs. For detailed information, contact your speech provider.
  • Language Configuration — by default, this setting is activated. Deactivate automatic language detection to ensure the AI Agent always responds in the language defined by your instructions. This setting provides predictable and consistent responses, preventing unintended language switching when users say or type words from more than one language. When active, this setting also simplifies the system prompt, giving you clearer control over language behavior.

3. Instructions

1. In the Instructions step, configure the following setting:

• Instructions — provide special instructions to your AI Agent in bullet-point form. For example:

 - Greet users warmly and professionally.
 - Keep responses concise; expand only if requested.
 - Start with a formal tone; adjust as needed.
 - Share troubleshooting links for technical issues.
 - Apologize if errors occur, then correct promptly.

4. Knowledge Store

1. In the Knowledge Store step, configure the following settings:

• Knowledge Store Type — select or upload a knowledge source that the AI Agent will use to access information from the documents you provide. By accessing and understanding these knowledge bases, the AI Agent can deliver more accurate, context-aware, and helpful responses to user queries. You need to configure an embedding model to use Knowledge AI. Select one of the following options:

• Choose existing Knowledge Store — select the Knowledge Store that the AI Agent will use to access information from the documents you provide.

  • Upload Knowledge Source — upload documents with supported formats, such as PDF, text, DOCX, PPTX, or CTXT file formats. The CTXT file format has restrictions. For more information, refer to the CTXT article.
  • Upload URL Knowledge Source — enter the URL of the web page to be used as a Knowledge Source. This type of Knowledge Source has restrictions. For more information, refer to the Web Page article.

5. Data Privacy & Security

1. In the Data Privacy & Security step, configure the following fields:

• Contact Profile Information — select which information the AI Agent should use from the Cognigy Contact Profile:

• None — no data will be used from the Contact Profile. This option is selected by default.

  • Selected Profile Fields — enter specific fields from the Contact Profile for targeted data use. Specify the field using the Profile keys format and press Enter to apply it.
  • Complete Profile — use all fields from the Contact Profile to provide comprehensive user details.
  • Profile Memories — use the Memories field from the Contact Profile.
  • Safety Instructions— adjust the AI Agent’s safety settings to guide content generation, interactions, and responses, ensuring compliance with ethical, legal, and operational standards. Although these settings reduce risks, occasional unexpected outputs may still occur. The selected safety instructions are included in the prompt to enhance safety, which may increase token usage. Select the safety instructions you want to apply:

• Avoid harmful content — prevent generating content that could be harmful, offensive, or abusive to end users.

  • Avoid ungrounded content — prevent generating content that is based on speculation or unsupported claims, ensuring it is reliable and verifiable.
  • Avoid copyright infringements — prevent generating content that violates intellectual property rights or uses copyrighted material without authorization.
  • Prevent jailbreak and manipulations — prevent attempts to bypass security measures or manipulate the AI Agent into producing unauthorized or unsafe content.

6. Job Selection

1. In the Job Selection step, select one of the following options:

• Default — create an AI Agent with a predefined Flow, then click Create & Configure LLM to save changes and open the Flow with the created AI Agent. If you haven’t added an LLM before, the system will prompt you to configure a model to ensure your AI-driven Flow works.
  • Personality Only — create an AI Agent without a predefined Flow, then click Create to save changes.
  • Job — select one of the available jobs you want to assign to the AI Agent, then click Create to save changes.

You can create an Agent from scratch using the Cognigy.AI API POST beta/aiagents request.

​ Hire from the Job Market

• GUI

• API

1. In the left-side menu on the Project page, select Build > AI Agents.
2. On the AI Agents page, click Hire AI Agent. The Job Market page displays a list of available AI Agents to hire.
3. Hover your cursor over the desired AI Agent template and click Hire. This action will trigger the Hire AI Agent task in the Task Manager.
4. Check the status of the Hire AI Agent task by clicking in the upper-right corner.
5. Once the task is complete, go to Build > Flows and find the Flow with the AI Agent name from the template you installed.

You can hire an Agent from the Job Market using the Cognigy.AI API POST beta/aiagents/hire request.

​ Combine Custom and Hired AI Agents

You can reassign your custom AI Agent to take on the responsibilities of the hired AI Agent. To do this, hire an AI Agent from the Job Market and configure their interaction by defining which functions and personality traits should be combined. This approach lets you combine the strengths of both AI Agents: ready-made job functions from the hired AI Agent and your brand’s AI Agent persona from your custom AI Agent.To combine custom and hired AI Agents, follow these steps:

1. On the AI Agents page, select + Hire AI Agent. The Job Market page displays a list of available AI Agents to hire.
2. Hover your cursor over the desired AI Agent template and click > Hire & Configure.
3. In the Select an AI Agent to Combine window, use the search field to find an AI Agent by name, then select the AI Agent from the list.
4. Click Combine. This action will trigger the Hire AI Agent and Merge Package tasks in the Task Manager.
5. In the left-side menu of the Project page, select Build > Flows.
6. Select the Flow that belongs to the hired AI Agent. In the Flow, you will see an AI Agent Node with your custom AI Agent persona.

​ Configure Jobs and Tools for AI Agents

When you create an AI Agent from scratch or add one from the Job Market, you can add or change jobs and tools in the AI Agent configuration.

1. Open the created AI Agent and go to the Jobs tab.
2. Fill in the following fields:
   • Job Name — enter a title for the job you want to assign to the AI Agent. For example, Customer Support Specialist.
   • Job Description — enter a description of the job that outlines the responsibilities and tasks associated with the role. For example, Handle customer inquiries, provide product information, and resolve issues efficiently.
   • Instructions and Context — provide specific instructions or guidelines that the AI Agent should follow while performing its job. For example, Always respond politely, escalate complex issues to a human agent, and ensure customer satisfaction.

​ Configure Tools for AI Agents

In the Tools section, click Add Tool to add tools that the AI Agent can use to perform its job. Select one of the following options:

• Regular Tool

• MCP

• Knowledge

• Send Email

• Handover to AI Agent

• Handover to Human Agent

• Execute Workflow Tool

A tool is a specific task that an AI Agent can perform. The AI Agent can call tools to perform different tasks, such as retrieving information from a database or interacting with an external API. Fill in the following fields:

Tool

Parameters

Configure the parameters that will be collected by the AI Agent before the tool is called. You can switch between the Graphical and JSON editors. When editing the JSON, follow the JSON Schema specification.

Debug Settings

Advanced

An MCP tool connects to a remote MCP server to load tools that the AI Agent can execute. Fill in the following fields:

MCP Tool

Authentication

Debug Settings

Advanced

You can add multiple tools to the AI Agent. The recommended maximum number of tools is 20. The following video shows an MCP Tool example:

Upskill AI Agents with the Model Context Protocol (MCP) - YouTube

Tap to unmute

Upskill AI Agents with the Model Context Protocol (MCP) NiCE Cognigy

NiCE Cognigy2.97K subscribers

A Knowledge tool is a tool that allows the AI Agent to directly access Knowledge Stores to provide context-aware responses. Fill in the following fields:

Tool

Debug Settings

Advanced

The Send Email tool lets your AI Agent send emails directly to users. The Send Email tool has the capabilities and restrictions as the Email Notification Node but is more flexible. While the Email Notification Node sends emails at a fixed step in a Flow, the Send Email tool allows the AI Agent to send emails dynamically, based on user input, conversation context, or instructions. This tool makes automation more flexible and minimizes extra Flow steps.

Tool

Debug Settings

Advanced

The Handover to AI Agent tool lets you transfer a conversation to another AI Agent in the same or a different Flow. This approach ensures that different AI Agents share the same conversation context and can handle specific tasks, and that multi-step conversations run smoothly across Flows.

Tool

Debug Settings

Advanced

The Handover to Human Agent tool lets you transfer a conversation to a human agent through handover providers. This tool allows your AI Agents to refer complex tasks to a human agent if they can’t address the user’s request.

Tool

Live Agent Settings

For more information, read the Live Agent Handover Setup and Real-Time Queue Notifications documentation.

Chatwoot Settings

Salesforce Chat Settings

NiCE CXone Settings

Genesys Settings

Example for the Custom Attributes parameter:

{
"section": "section A",
"region": "Europe"
}

For more information, read the Genesys Cloud Guest Chat and Genesys Cloud Open Messaging documentation.

8x8 Settings

For more information, read the 8x8 Handover Setup documentation.

RingCentral Engage Settings

For more information, read the RingCentral Engage Integration documentation.

Cancel Handover Options

On Resolve Options

Event Settings

Debug Settings

Advanced

The Execute Workflow tool lets the AI Agent execute another Flow. After the target Flow executes, the conversation returns to the AI Agent.The target Flow inherits the Context object from the AI Agent. If the Context object is changed during the target Flow execution, these changes are also available to the AI Agent.

Debug Settings

Advanced

​ Configure AI Agent Settings for Each Job

Configure more settings for managing AI Agents:

Memory Handling

Grounding Knowledge

Storage and Streaming Options

Voice

Tool Settings

Image Handling

Advanced

Error Handling

Debug Settings

To test and refine the job settings, use the Interaction Panel on the right side of the screen.To view the AI Agent’s Flow in detail, click Advanced Editor in the upper-right corner.One AI Agent can have multiple jobs. To add another job, click Add Job in the bottom-left corner. Note that each job corresponds to one Flow.

​ Other Operations

• GUI

• API

• CLI

You can view and delete AI Agents, and copy their Reference ID in Build > AI Agents.

You can create, edit, and delete AI Agents using Cognigy.AI API.

You can clone and edit AI Agents using Cognigy.AI CLI.

​ More Information

• Overview
• Getting Started

Last modified onJune 23, 2026

Previous Projects\ \ Next

Ctrl+I

ChatVoice

Click the call button to start talking.

Cognigy AssistantReady to talk

Connecting…

Powered by Cognigy.AI

Cookie Consent

We use cookies to recognize your repeated visits and preferences, as well as to measure the effectiveness of our documentation and whether users find what they're searching for.

With your consent, you're helping us make our documentation better. To find out more about the cookies we use, see our Privacy Policy.

Accept

'; cachedClickBlockingCode = css + js; return cachedClickBlockingCode; }

// Helper: Inject click-blocking code into iframe function injectClickBlocking(iframeDoc) { if (!iframeDoc || !iframeDoc.head) return false;

try { const style = iframeDoc.createElement('style'); style.textContent = 'a,button,input,select,textarea,[onclick],[role="button"],input[type="button"],input[type="submit"],[href],[tabindex]:not([tabindex="-1"]){pointer-events:none!important;cursor:default!important}a:hover,button:hover{cursor:default!important;opacity:0.7!important}'; iframeDoc.head.appendChild(style);

const script = iframeDoc.createElement('script'); script.textContent = '(function(){var preventClick=function(e){e.preventDefault();e.stopPropagation();e.stopImmediatePropagation();return false;};document.addEventListener("click",preventClick,true);document.addEventListener("mousedown",preventClick,true);document.addEventListener("mouseup",preventClick,true);document.addEventListener("touchstart",preventClick,true);document.addEventListener("touchend",preventClick,true);document.addEventListener("contextmenu",preventClick,true);window.addEventListener("beforeunload",function(e){e.preventDefault();e.returnValue="";return "";},true);try{Object.defineProperty(window,"location",{value:{href:"#",replace:function(){},assign:function(){}},writable:false,configurable:false});}catch(e){}var originalPushState=history.pushState;history.pushState=function(){return false;};var originalReplaceState=history.replaceState;history.replaceState=function(){return false;};var originalOpen=window.open;window.open=function(){return null;};var allElements=document.querySelectorAll("*");for(var i=0;i 0 || replacedViewers.length > 0) { const currentUrl = window.location.href; if (!processedUrls.has(currentUrl)) { processedUrls.add(currentUrl); lastUrl = currentUrl; } return; }

const currentUrl = window.location.href; if (currentUrl === lastUrl && lastUrl !== null && processedUrls.has(currentUrl)) { return; }

// Optimized: Use cached viewer query const viewers = getUninitializedViewers();

if (viewers.length === 0) { if (periodicCheckInterval) { clearInterval(periodicCheckInterval); periodicCheckInterval = null; } return; }

// Final safety check if (viewers.length > 0) { if (currentUrl === lastUrl && lastUrl !== null && processedUrls.has(currentUrl)) { viewers.forEach(function(viewer) { viewer.setAttribute('data-initialized', 'true'); }); return; }

if (currentUrl === lastUrl && lastUrl !== null) { if (existingContainers.length > 0) { processedUrls.add(currentUrl); viewers.forEach(function(viewer) { viewer.setAttribute('data-initialized', 'true'); }); return; } } }

isInitializing = true; let processedAny = false;

// Optimized: Process viewers in batch viewers.forEach(function(viewer) { if (processedElements.has(viewer) || viewer.hasAttribute('data-initialized')) { return; }

if (viewer.closest('.single-page-viewer-container')) { return; }

if (!viewer.parentNode) { return; }

const isInContentArea = contentArea === document.body || contentArea.contains(viewer); if (!isInContentArea) { return; }

const src = viewer.getAttribute('data-src'); const hint = viewer.getAttribute('data-hint') || ''; const defaultZoom = parseFloat(viewer.getAttribute('data-zoom')) || DEFAULT_ZOOM; const dataHeight = viewer.getAttribute('data-height'); const height = dataHeight ? parseFloat(dataHeight) : null;

if (!src) { // Don't set isInitializing = false here - it affects all viewers in the loop return; }

processedElements.add(viewer); viewer.setAttribute('data-initialized', 'true');

let zoom = defaultZoom;

// Optimized: Use document fragment for DOM construction const fragment = document.createDocumentFragment(); const container = document.createElement('div'); container.className = 'single-page-viewer-container';

const wrapper = document.createElement('div'); wrapper.className = 'single-page-viewer-wrapper';

const controlsBar = document.createElement('div'); controlsBar.className = 'single-page-viewer-controls';

if (hint) { const hintDiv = document.createElement('div'); hintDiv.className = 'single-page-viewer-hint'; hintDiv.innerHTML = '' + hint + ''; controlsBar.appendChild(hintDiv); }

const iframeWrapper = document.createElement('div'); iframeWrapper.className = 'single-page-viewer-iframe-wrapper'; iframeWrapper._scrollHandlerAdded = false;

// Optimized: Get height without temporary DOM manipulation const baseHeightFromCSS = height || NORMAL_HEIGHT;

const scaleDiv = document.createElement('div'); scaleDiv.className = 'single-page-viewer-scale'; const initialHeight = baseHeightFromCSS; scaleDiv.style.cssText = 'transform: scale(' + zoom + '); transform-origin: top left; width: ' + (100 / zoom) + '%; height: ' + initialHeight + 'px; transition: transform 0.2s ease;';

const iframe = document.createElement('iframe'); let iframeSrc = src; if (iframeSrc && !iframeSrc.startsWith('http') && !iframeSrc.startsWith('//')) { if (!iframeSrc.startsWith('/')) { iframeSrc = '/' + iframeSrc; } }

iframe.title = 'Single Page Viewer'; iframe.className = 'single-page-viewer-iframe'; iframe.style.width = '100%'; iframe.style.height = initialHeight + 'px'; iframe.loading = 'lazy'; iframe.setAttribute('scrolling', 'no'); iframe.setAttribute('sandbox', 'allow-same-origin allow-scripts allow-forms allow-popups allow-modals');

const clickBlocker = document.createElement('div'); clickBlocker.className = 'single-page-viewer-click-blocker';

if (iframeSrc.endsWith('.html') && !iframeSrc.startsWith('http')) { fetch(iframeSrc) .then(function(response) { return response.text().then(function(htmlContent) { if (htmlContent.includes('Page Not Found') || (htmlContent.includes('__next') && htmlContent.includes('mintlify') && !htmlContent.includes('Page saved with SingleFile'))) { throw new Error('Received 404 page instead of HTML file.'); } const blockingCode = getClickBlockingCode(); if (htmlContent.includes('')) { htmlContent = htmlContent.replace('', blockingCode + ''); } else if (htmlContent.includes('')) { htmlContent = htmlContent.replace('', '' + blockingCode); } else { if (htmlContent.includes('')) { htmlContent = htmlContent.replace('', '' + blockingCode + ''); } else { htmlContent = blockingCode + htmlContent; } } iframe.srcdoc = htmlContent; }); }); } else { iframe.src = iframeSrc; }

iframe.addEventListener('load', function() { setTimeout(function() { updateIframeDimensions(iframeWrapper, scaleDiv, iframe, zoom); }, 100);

try { const iframeDoc = iframe.contentDocument || iframe.contentWindow.document; injectClickBlocking(iframeDoc); } catch (e) { // Cross-origin iframe - cannot block clicks } }, { once: true });

iframe.addEventListener('error', function() { // Iframe failed to load - error handling is silent }, { once: true });

scaleDiv.appendChild(iframe); iframeWrapper.appendChild(scaleDiv); if (!iframeSrc.endsWith('.html') || iframeSrc.startsWith('http')) { iframeWrapper.appendChild(clickBlocker); }

if (hint) { wrapper.appendChild(controlsBar); } wrapper.appendChild(iframeWrapper); container.appendChild(wrapper); fragment.appendChild(container);

try { if (viewer.parentNode) { if (viewer === contentArea || viewer.id === 'content-area') { isInitializing = false; return; }

const viewerId = 'viewer-' + Date.now() + '-' + Math.random().toString(36).slice(2, 11); viewer.id = viewerId; viewer.setAttribute('data-viewer-id', viewerId); container.setAttribute('data-viewer-id', viewerId);

// Optimized: Single DOM insertion using fragment if (viewer.nextSibling) { viewer.parentNode.insertBefore(fragment, viewer.nextSibling); } else { viewer.parentNode.appendChild(fragment); }

// Batch style updates Object.assign(viewer.style, { display: 'none', visibility: 'hidden', position: 'absolute', width: '1px', height: '1px', overflow: 'hidden', opacity: '0', pointerEvents: 'none', margin: '0', padding: '0' });

viewer.setAttribute('data-initialized', 'true'); viewer.setAttribute('data-viewer-replaced', 'true');

processedAny = true; invalidateQueryCache();

requestAnimationFrame(function() { updateIframeDimensions(iframeWrapper, scaleDiv, iframe, zoom); }); } } catch (e) { isInitializing = false; return; } });

if (processedAny) { const currentUrl = window.location.href; processedUrls.add(currentUrl); lastUrl = currentUrl; invalidateQueryCache(); }

isInitializing = false; }

// Wait for content area to be available function waitForContentArea(callback, maxAttempts, attempt) { attempt = attempt || 0; maxAttempts = maxAttempts || 20;

const contentArea = document.querySelector('#content-area') || document.querySelector('.mdx-content');

if (contentArea && document.contains(contentArea)) { cachedContentArea = contentArea; callback(); } else if (attempt < maxAttempts) { setTimeout(function() { waitForContentArea(callback, maxAttempts, attempt + 1); }, 500); } else { cachedContentArea = document.body; callback(); } }

// Optimized: Initialize with better state management function initialize() { const currentUrl = window.location.href; if (lastUrl !== currentUrl && lastUrl !== null) { lastUrl = currentUrl; processedUrls.clear(); invalidateQueryCache(); }

if (typeof window !== 'undefined') { window.__lastFullUrl = window.location.href; }

if (lastThemeClass === null && document.documentElement) { lastThemeClass = document.documentElement.className; }

if (!themeObserver && document.documentElement) { themeObserver = new MutationObserver(function(mutations) { for (let i = 0; i < mutations.length; i++) { const mutation = mutations[i]; if (mutation.type === 'attributes' && mutation.attributeName === 'class') { const currentThemeClass = document.documentElement.className; if (lastThemeClass !== null && lastThemeClass !== currentThemeClass) { themeToggleInProgress = true;

// Optimized: Lock containers synchronously const contentArea = getContentArea(); if (contentArea) { const containers = getContainers(true); containers.forEach(function(container) { if (container.getAttribute('data-position-locked') !== 'true') { const rect = container.getBoundingClientRect(); Object.assign(container.style, { position: 'fixed', top: rect.top + 'px', left: rect.left + 'px', width: rect.width + 'px', zIndex: '9999', margin: '0' }); container.setAttribute('data-position-locked', 'true'); containerPositions.set(container, { top: rect.top, left: rect.left, width: rect.width, height: rect.height }); } }); }

let repositionAttempts = 0; const maxRepositionAttempts = 30;

const repositionInterval = setInterval(function() { repositionAttempts++; repositionContainersAfterThemeToggleCore(); // Use core function for immediate repositioning if (repositionAttempts >= maxRepositionAttempts) { clearInterval(repositionInterval); } }, 100);

setTimeout(function() { clearInterval(repositionInterval); themeToggleInProgress = false; repositionContainersAfterThemeToggleCore(); // Use core function for final repositioning unlockContainers(); }, 3000); } lastThemeClass = currentThemeClass; } } });

themeObserver.observe(document.documentElement, { attributes: true, attributeFilter: ['class'] }); }

if (typeof MutationObserver !== 'undefined') { setupObserver(); }

waitForContentArea(function() { setTimeout(function() { initSinglePageViewers(); setTimeout(function() { const remaining = getUninitializedViewers(true); if (remaining.length > 0) { initSinglePageViewers(); } }, INIT_DELAY); }, INIT_DELAY); }); }

// Optimized: Lock/unlock containers function lockContainersInPlace() { const contentArea = getContentArea(); if (!contentArea) return;

const containers = getContainers(true); containerPositions.clear();

requestAnimationFrame(function() { containers.forEach(function(container) { if (container.getAttribute('data-position-locked') !== 'true') { const rect = container.getBoundingClientRect(); Object.assign(container.style, { position: 'fixed', top: rect.top + 'px', left: rect.left + 'px', width: rect.width + 'px', zIndex: '9999', margin: '0' }); container.setAttribute('data-position-locked', 'true'); containerPositions.set(container, { top: rect.top, left: rect.left, width: rect.width, height: rect.height }); } }); }); }

function unlockContainers() { const contentArea = getContentArea(); if (!contentArea) return;

const containers = Array.from( contentArea.querySelectorAll('.single-page-viewer-container[data-position-locked="true"]') );

containers.forEach(function(container) { Object.assign(container.style, { position: '', top: '', left: '', width: '', zIndex: '', margin: '' }); container.removeAttribute('data-position-locked'); // Clean up container position from Map to prevent memory leak containerPositions.delete(container); });

containerPositions.clear(); }

// Optimized: Reposition containers with better DOM operations // Core repositioning function (not debounced for immediate use) function repositionContainersAfterThemeToggleCore() { const contentArea = getContentArea(); if (!contentArea) return;

const containers = getContainers(true);

containers.forEach(function(container) { const viewerId = container.getAttribute('data-viewer-id'); if (!viewerId) return;

let viewer = document.getElementById(viewerId);

if (!viewer) { const iframe = container.querySelector('iframe'); if (iframe && iframe.src) { const allViewers = contentArea.querySelectorAll('[data-single-page-viewer]'); for (let i = 0; i < allViewers.length; i++) { const v = allViewers[i]; if (v.getAttribute('data-src') === iframe.src) { viewer = v; viewer.id = viewerId; viewer.setAttribute('data-viewer-id', viewerId); Object.assign(viewer.style, { display: 'none', visibility: 'hidden', position: 'absolute', width: '1px', height: '1px', overflow: 'hidden', opacity: '0', pointerEvents: 'none', margin: '0', padding: '0' }); viewer.setAttribute('data-initialized', 'true'); viewer.setAttribute('data-viewer-replaced', 'true'); break; } } } }

if (viewer && viewer.parentNode) { if (container.getAttribute('data-position-locked') === 'true') { unlockContainers(); }

const viewerIndex = Array.from(viewer.parentNode.children).indexOf(viewer); const containerIndex = Array.from(viewer.parentNode.children).indexOf(container);

if (containerIndex !== viewerIndex + 1) { // CRITICAL: Check if container is actually a child before removing if (container.parentNode && container.parentNode.contains(container)) { try { container.parentNode.removeChild(container); } catch (e) { return; // Skip repositioning if removal failed } } if (viewer.nextSibling) { viewer.parentNode.insertBefore(container, viewer.nextSibling); } else { viewer.parentNode.appendChild(container); } } else if (container.parentNode !== viewer.parentNode) { // CRITICAL: Check if container is actually a child before removing if (container.parentNode && container.parentNode.contains(container)) { try { container.parentNode.removeChild(container); } catch (e) { return; // Skip repositioning if removal failed } } if (viewer.nextSibling) { viewer.parentNode.insertBefore(container, viewer.nextSibling); } else { viewer.parentNode.appendChild(container); } } } });

invalidateQueryCache(); }

// Debounced version for non-critical repositioning const repositionContainersAfterThemeToggle = debounce(repositionContainersAfterThemeToggleCore, REPOSITION_DEBOUNCE);

// Optimized: Observer setup with better filtering let observer = null; let containerPositionObserver = null; let fallbackObserver = null; // Track fallback observer for cleanup

function setupContainerPositionObserver() { if (typeof MutationObserver === 'undefined') return;

const contentArea = getContentArea(); if (!contentArea || !document.contains(contentArea)) { setTimeout(setupContainerPositionObserver, 500); return; }

if (containerPositionObserver) { containerPositionObserver.disconnect(); }

containerPositionObserver = new MutationObserver(function(mutations) { if (themeToggleInProgress) { // Use core function (not debounced) for immediate repositioning during theme toggle requestAnimationFrame(repositionContainersAfterThemeToggleCore); return; }

let needsReposition = false; for (let i = 0; i < mutations.length && !needsReposition; i++) { if (mutations[i].type === 'childList') { needsReposition = true; } }

if (needsReposition) { clearTimeout(containerPositionObserver._timeout); containerPositionObserver._timeout = setTimeout(repositionContainersAfterThemeToggle, REPOSITION_DEBOUNCE); } });

containerPositionObserver.observe(contentArea, { childList: true, subtree: true, attributes: false, characterData: false });

containerPositionObserver._timeout = null; }

// Optimized: Main observer with better early exits function setupObserver() { if (typeof MutationObserver === 'undefined') return;

const contentArea = getContentArea(); if (!contentArea || !document.contains(contentArea)) { setTimeout(setupObserver, 500); return; }

if (contentArea === document.documentElement || contentArea === document.body) { return; }

if (observer) { const currentObserved = observer._observedElement; if (currentObserved === contentArea && document.contains(contentArea)) { return; } if (currentObserved) { observer.disconnect(); } observer = null; }

observer = new MutationObserver(function(mutations) { if (themeToggleInProgress) return;

let hasNewViewer = false; for (let i = 0; i < mutations.length && !hasNewViewer; i++) { const mutation = mutations[i]; if (mutation.addedNodes && mutation.addedNodes.length > 0) { for (let j = 0; j < mutation.addedNodes.length && !hasNewViewer; j++) { const node = mutation.addedNodes[j]; if (node.nodeType === 1 && node.hasAttribute && node.hasAttribute('data-single-page-viewer') && !node.hasAttribute('data-initialized') && !node.hasAttribute('data-viewer-replaced')) { hasNewViewer = true; } } } }

if (hasNewViewer) { // Use core function for immediate repositioning when new viewer detected repositionContainersAfterThemeToggleCore(); setTimeout(repositionContainersAfterThemeToggleCore, 10); setTimeout(repositionContainersAfterThemeToggleCore, 50); setTimeout(repositionContainersAfterThemeToggleCore, 200); }

clearTimeout(observerTimeout); observerTimeout = setTimeout(function() { if (themeToggleInProgress) return;

let hasNewViewer = false; for (let i = 0; i < mutations.length && !hasNewViewer; i++) { const mutation = mutations[i];

if (mutation.target === document.documentElement || mutation.target === document.body) { continue; }

if (mutation.type === 'attributes' && mutation.attributeName === 'class' && mutation.target === document.documentElement) { continue; }

if (mutation.type === 'attributes' && mutation.attributeName === 'data-initialized') { const target = mutation.target; if (target && target.hasAttribute && target.hasAttribute('data-single-page-viewer') && !target.hasAttribute('data-initialized')) { hasNewViewer = true; } }

if (mutation.addedNodes && mutation.addedNodes.length > 0) { for (let j = 0; j < mutation.addedNodes.length && !hasNewViewer; j++) { const node = mutation.addedNodes[j]; if (node.nodeType === 1 && node.hasAttribute && node.hasAttribute('data-single-page-viewer') && !node.hasAttribute('data-initialized')) { hasNewViewer = true; } } } }

if (hasNewViewer) { invalidateQueryCache(); initSinglePageViewers(); } }, OBSERVER_DEBOUNCE); });

observer.observe(contentArea, { childList: true, subtree: true, attributes: true, attributeFilter: ['data-initialized'], characterData: false });

observer._observedElement = contentArea; setupContainerPositionObserver(); }

function start() { setupObserver(); initialize(); }

function checkAndInitialize() { if (isInitializing) return;

const currentUrl = window.location.href; if (currentUrl === lastUrl && lastUrl !== null) { return; }

const contentArea = document.querySelector('#content-area') || document.querySelector('.mdx-content'); if (contentArea) { const viewers = getUninitializedViewers(true); if (viewers.length > 0) { cachedContentArea = contentArea; setupObserver(); initialize(); } } }

if (document.readyState === 'loading') { document.addEventListener('DOMContentLoaded', start); } else { setTimeout(start, 100); }

if (typeof window !== 'undefined' && window.next) { let initialLoadAttempts = 0; const maxInitialAttempts = 4; const attemptDelays = [200, 500, 1000, 2000]; const initialUrl = window.location.href;

attemptDelays.forEach(function(delay) { setTimeout(function() { if (initialLoadAttempts < maxInitialAttempts) { initialLoadAttempts++; if (window.location.href === initialUrl) { checkAndInitialize(); } } }, delay); }); }

window.addEventListener('popstate', function(e) { const currentUrl = window.location.href; if (currentUrl !== lastUrl) { handleNavigation(); } });

if (typeof window !== 'undefined') { if (window.next && window.next.router && window.next.router.events) { window.next.router.events.on('routeChangeComplete', function(url) { lastUrl = window.location.href; isInitializing = false; pendingInitCall = false; if (navigationTimeout) { clearTimeout(navigationTimeout); navigationTimeout = null; } invalidateContentAreaCache(); invalidateQueryCache(); setTimeout(function() { setupObserver(); initialize(); }, 300); });

window.next.router.events.on('routeChangeStart', function(url) { isInitializing = false; pendingInitCall = false; }); }

if (!window.next || !window.next.router) { const originalPushState = history.pushState; const originalReplaceState = history.replaceState;

history.pushState = function() { originalPushState.apply(history, arguments); setTimeout(function() { if (window.location.href !== lastUrl) { handleNavigation(); } }, 0); };

history.replaceState = function() { originalReplaceState.apply(history, arguments); setTimeout(function() { if (window.location.href !== lastUrl) { handleNavigation(); } }, 0); }; } }

document.addEventListener('visibilitychange', function() { if (!document.hidden) { isInitializing = false; startPeriodicCheck(); if (!pendingInitCall) { pendingInitCall = true; setTimeout(function() { pendingInitCall = false; initSinglePageViewers(); }, INIT_DELAY / 2); } } });

function startPeriodicCheck() { if (periodicCheckInterval) return;

periodicCheckInterval = setInterval(function() { const uninitialized = getUninitializedViewers(true); if (uninitialized.length === 0) { clearInterval(periodicCheckInterval); periodicCheckInterval = null; } else if (!isInitializing) { initSinglePageViewers(); } }, 2000); }

setTimeout(startPeriodicCheck, INIT_DELAY * 2);

window.__singlePageViewerInit = function() { const currentUrl = window.location.href; if (currentUrl === lastUrl) { return; }

isInitializing = false; pendingInitCall = false; lastUrl = currentUrl; invalidateContentAreaCache(); invalidateQueryCache(); setupObserver(); initialize(); };

window.__singlePageViewerCheck = function() { invalidateQueryCache(); initSinglePageViewers(); }; })();

// Optimized: Second IIFE for navigation handling (function() { 'use strict';

let lastPathname = window.location.pathname; let lastInitializedPathname = window.location.pathname;

function checkAndInit() { const currentPathname = window.location.pathname; if (currentPathname === lastInitializedPathname) { return; }

lastInitializedPathname = currentPathname; if (typeof window !== 'undefined') { window.__lastFullUrl = window.location.href; }

if (window.__singlePageViewerInit) { window.__singlePageViewerInit(); } }

function runInit() { if (window.__singlePageViewerInit) { setTimeout(checkAndInit, 100); } else { let attempts = 0; const maxAttempts = 50; const checkInterval = setInterval(function() { attempts++; if (window.__singlePageViewerInit) { clearInterval(checkInterval); setTimeout(checkAndInit, 100); } else if (attempts >= maxAttempts) { clearInterval(checkInterval); } }, 100); } }

if (document.readyState === 'loading') { document.addEventListener('DOMContentLoaded', runInit); } else { setTimeout(runInit, 100); }

if (typeof window !== 'undefined' && window.next && window.next.router && window.next.router.events) { window.next.router.events.on('routeChangeComplete', function(url) { lastPathname = window.location.pathname; setTimeout(checkAndInit, 300); }); }

setInterval(function() { const currentPathname = window.location.pathname; if (currentPathname !== lastPathname) { lastPathname = currentPathname; setTimeout(checkAndInit, 300); } }, 500);

if (typeof MutationObserver !== 'undefined') { let fallbackObserverTimeout = null; // Store in outer scope for cleanup tracking fallbackObserver = new MutationObserver(function(mutations) { if (fallbackObserverTimeout) { clearTimeout(fallbackObserverTimeout); } fallbackObserverTimeout = setTimeout(function() { const contentArea = document.querySelector('#content-area'); if (contentArea) { const uninitialized = contentArea.querySelectorAll( '[data-single-page-viewer]:not([data-initialized]):not(.single-page-viewer-container [data-single-page-viewer])' ); if (uninitialized.length > 0) { const currentPathname = window.location.pathname; if (currentPathname !== lastInitializedPathname) { setTimeout(checkAndInit, 200); } } } }, 500); });

if (document.body) { fallbackObserver.observe(document.body, { childList: true, subtree: true }); } else { document.addEventListener('DOMContentLoaded', function() { if (document.body) { fallbackObserver.observe(document.body, { childList: true, subtree: true }); } }); } } })();