🤖 Документация по виджету Luka Embed

Инструкции по встраиванию для: https://chat-vpotoke-audit.apps.vpotoke.app

🎨 Заголовок виджета

Настройте параметры виджета. Код ниже будет обновляться автоматически.

Режим отображения

Язык виджета

Цветовая тема

Позиция

AI агент

Заголовок виджета

Приветственное сообщение

📋 Ваш код виджета

Скопируйте этот код и вставьте его в ваш HTML, прямо перед закрывающим тегом </body>.

<script
    src="https://chat-vpotoke-audit.apps.vpotoke.app/luka_embed.js"
    data-luka-id="default"
    data-mode="bubble"
    data-position="bottom-right"
    data-theme="auto"
    data-sub-agent="crypto_analyst"
    data-api-url="https://chat-vpotoke-audit.apps.vpotoke.app"
></script>

💡 Быстрый старт

Код автоматически обновляется при изменении настроек выше. Просто скопируйте и вставьте!

🎮 Управление виджетом

Используйте эти кнопки для программного взаимодействия с виджетом:

🎨 Выбрать тему

Светлая

Тёмная

Океан

Закат

Авто (Системная)

🤖 Выбрать под-агента:

📐 Ширина панели:

400px

📝 Заголовок виджета:

💬 Приветственное сообщение (необязательно):

📚 Справочник расширенной конфигурации

Подробная документация по расширенным функциям и параметрам конфигурации.

Все доступные опции

Attribute	Values	Default	Description
data-mode	bubble, copilot, inline	bubble	Display mode
data-locale	en, ru, auto	auto (browser)	UI and LLM language
data-theme	auto, light, dark, ocean, sunset	auto	Color theme
data-position	bottom-right, bottom-left	bottom-right	Widget position (bubble mode)
data-sub-agent	crypto_analyst, etc.	(default)	AI agent persona
data-title	any string	Luka Assistant	Widget header title
data-greeting	any string	(none)	Initial greeting message
data-api-url	URL	(auto)	Backend API URL

🤖 Конфигурация под-агента

Под-агенты позволяют настраивать персону AI-ассистента, предложения на экране приветствия и поведение для различных случаев использования.

Как работают под-агенты

Когда вы указываете атрибут <code>data-sub-agent</code>, виджет встраивания:

Загружает конфигурацию под-агента с бэкенда
Отображает настроенные предложения на экране приветствия на основе персоны агента
Передаёт ID под-агента в CopilotKit, который перенаправляет его на бэкенд
Использует поведение и контекст, специфичные для агента, на протяжении всего разговора

Доступные под-агенты

Под-агенты настраиваются на бэкенде. Распространённые примеры:

<code>crypto_analyst</code> - Специализируется на анализе криптовалют и блокчейна
<code>defi_alert_bot</code> - Ассистент для оповещений и мониторинга DeFi
<code>prompt_engineer</code> - Специалист по инженерии и оптимизации промптов
<code>general_luka</code> - Универсальный ассистент по умолчанию (Luka)

Чтобы увидеть все доступные под-агенты, проверьте API endpoint бэкенда: <code>https://chat-vpotoke-audit.apps.vpotoke.app/api/copilotkit/sub-agents</code>

Пример использования

// Встраивание с под-агентом crypto_analyst<script src="https://chat-vpotoke-audit.apps.vpotoke.app/luka_embed.js"data-sub-agent="crypto_analyst"data-api-url="https://chat-vpotoke-audit.apps.vpotoke.app" ></script>

💡 Примечание:

Если <code>data-sub-agent</code> не указан, виджет использует под-агента по умолчанию, настроенного на бэкенде (обычно <code>general_luka</code>).

Под-агент влияет на предложения на экране приветствия и начальный контекст разговора, аналогично использованию <code>?subAgent=crypto_analyst</code> в основном интерфейсе чата.

🔐 Аутентификация и контекст пользователя

Этот раздел объясняет, как будет работать аутентификация с виджетом встраивания и как контекст пользователя передаётся на бэкенд.

Поток аутентификации

Виджет встраивания поддерживает передачу токенов аутентификации, которые будут перенаправлены на бэкенд <code>ag_ui_gateway</code> для идентификации и авторизации пользователя.

// Настройте виджет с токеном аутентификации (перед загрузкой скрипта)
window.LukaWidgetConfig = {
  authToken: "your-jwt-token-here"
};

// Виджет отправляет токен в заголовке Authorization
// Authorization: Bearer your-jwt-token-here

// Authorization: Bearer your-jwt-token-here
// Промежуточное ПО ag_ui_gateway извлекает и проверяет токен
// Контекст пользователя внедряется в request.state

Формат токена

Виджет ожидает JWT токен, который будет отправлен в заголовке <code>Authorization</code> с префиксом <code>Bearer</code>:

// Структура токена (JWT){user_id: 123,platform: "web",token_type: "authenticated" | "guest",permissions: ["read:threads", "write:messages"],exp: 1234567890}

Обработка на бэкенде (ag_ui_gateway)

<code>ag_ui_gateway</code> обрабатывает аутентификацию в следующем порядке:

Извлечение токена: Промежуточное ПО извлекает токен из заголовка <code>Authorization: Bearer <token></code>
Проверка токена: Токен проверяется с помощью <code>TokenManager.validate_token()</code>
Внедрение контекста пользователя: Проверенные данные пользователя внедряются в <code>request.state</code>:
Обработка запроса: API endpoints используют <code>request.state.user_id</code> для управления потоками и операций, специфичных для пользователя
- request.state.user_id - Числовой ID пользователя
- request.state.platform - Идентификатор платформы (например, "web", "telegram")
- request.state.token_type - "authenticated" или "guest"
- request.state.is_guest - Булев флаг
- request.state.permissions - Массив строк разрешений
- request.state.authenticated - Статус аутентификации (булево)

💡 Статус реализации:

Передача токена аутентификации запланирована для будущей реализации. В настоящее время виджет работает в гостевом режиме. После реализации токены будут:

Безопасно храниться в конфигурации виджета
Отправляться в заголовке <code>Authorization</code> для всех API запросов
Проверяться промежуточным ПО <code>ag_ui_gateway</code>
Использоваться для связи разговоров с аутентифицированными пользователями

📄 Контекст страницы

Контекст страницы позволяет предоставить LLM информацию о текущей странице для более контекстно-зависимых разговоров.

Структура объекта контекста

{url: string,           // url: string - URL текущей страницыtitle: string,         // title: string - Заголовок страницыdescription: string,  // description: string - Мета-описаниеtopic: string,        // topic: string - Основная тема контентаstage: string,         // stage: string - Этап пути пользователяproduct: {                    // product: object - Информация о продукте/услугеid: string,name: string,category: string,price: number},userSegment: string,   // userSegment: string - Персона/сегмент пользователяcustom: {                    // custom: object - Пользовательские данные для конкретной области[key: string]: any}}

Примеры использования

Страница товара в интернет-магазине

window.LukaWidgetConfig = {pageContext: {url: window.location.href,title: document.title,topic: "Product Information",product: {id: "PROD-12345",name: "Wireless Headphones",category: "Electronics",price: 199.99},stage: "browsing"}};

Страница поддержки

window.LukaWidgetConfig = {pageContext: {url: "/support/faq",topic: "Frequently Asked Questions",stage: "support",userSegment: "premium"}};

Страница оформления заказа

window.LukaWidgetConfig = {pageContext: {url: "/checkout",topic: "Order Completion",stage: "checkout",custom: {cartValue: 299.97,items: 3,shippingMethod: "express"}}};

💡 Статус реализации:

Передача контекста страницы запланирована для будущей реализации. После реализации контекст будет:

Передаваться в LLM при начале разговора
Использоваться для предоставления контекстно-зависимых ответов
Обновляться динамически при навигации пользователей между страницами
Включаться в историю разговора для лучшей преемственности

🔍 Статус виджета

Проверка статуса виджета...

💡 Примечание:

Эта страница документации доступна по адресу <code>https://chat-vpotoke-audit.apps.vpotoke.app/embed</code> в каждом развёртывании.

Виджет поддерживает три режима:

Режим Bubble: Плавающая кнопка с всплывающей панелью (по умолчанию)

Режим Copilot: Боковая панель справа с ручкой для сворачивания

Режим Inline: Переключаемая плавающая панель без заголовка, полный интерфейс чата

Если виджет не появляется, проверьте консоль браузера на наличие ошибок. Убедитесь, что CORS правильно настроен на бэкенде.