自定义 Amazon Quick 嵌入式聊天，融入您的应用

Amazon Quick嵌入式聊天提供了一个对话式AI界面，您可以直接将其集成到您的Web应用程序中。您的用户无需离开应用程序即可提问、探索数据并获得洞察。然而，通用的聊天界面会造成割裂的体验。聊天界面必须看起来和感觉起来像是您应用程序的自然组成部分，而不是外部附加物。借助Quick自定义功能，您可以扩展组织的视觉主题和品牌语调，使其与应用程序的外观和风格相匹配，从而提供一致且品牌化的体验。

在本文中，我们将逐步介绍自定义Amazon Quick嵌入式聊天的配置选项，以便在您的应用程序中提供一致且品牌化的体验。

概述

自定义需求通常分为两个关键领域。第一个是视觉主题，以匹配公司的品牌。您的组织已建立了品牌指南，嵌入式聊天必须体现这些指南。第二个是语调，以匹配公司的声音，因为仅靠视觉一致性是不够的。聊天的沟通方式也必须体现您组织的个性。

以下示例使用嵌入在财务绩效仪表板中的财务分析助手，演示如何配置视觉主题和语调自定义。

配置视觉主题

当您首次将Quick聊天嵌入到应用程序中时，聊天界面使用其默认样式。这会造成视觉上的不匹配。聊天看起来像是外部工具被硬塞进您的应用程序，而不是原生组件。请注意不匹配的配色方案、通用品牌标识，以及与周围财务仪表板缺乏视觉整合的问题。

应用视觉主题，使嵌入式聊天感觉像是财务仪表板的自然组成部分。嵌入式聊天的视觉主题在两个层面运作。第一个是容器和布局样式，即您围绕聊天iframe控制的CSS。第二个是SDK框架选项，即传递给嵌入SDK的配置，用于控制iframe行为和品牌元素。

由于聊天在iframe内渲染，您无法直接设置其内部元素的样式。相反，您需要为包裹iframe的容器设置样式，并使用SDK选项移除与您的设计冲突的默认品牌元素。

框架选项配置

import { createEmbeddingContext } from 'amazon-quicksight-embedding-sdk';
const embeddingContext = await createEmbeddingContext();

const frameOptions = {
    url: chatEmbedUrl,
    container: document.getElementById('chat-container'),
    height: '100%',
    width: '100%',
    // 直接将自定义CSS类应用于iframe元素。
    // 用于调整边框半径、定位或z-index，
    // 以匹配您应用程序的组件设计。
    className: 'anycompany-chat-iframe',
    // 在聊天内容加载时显示加载占位符，
    // 防止初始化期间出现空白白色矩形。
    withIframePlaceholder: true,
    // 启用剪贴板访问，以便用户可以复制回复
    // 或将内容粘贴到聊天输入框中。
    framePermissions: {
        clipboardRead: true,
        clipboardWrite: true,
    },
};

容器和布局CSS

为包裹聊天的容器设置样式，以匹配您应用程序的设计系统。在我们的财务仪表板示例中，聊天以从右侧滑入的侧边面板形式出现。

/* 将聊天定位为固定侧边面板 */
.chat-side-panel {
    position: fixed;
    top: 0;
    right: 0;
    bottom: 0;
    width: 400px;
    z-index: 997;
    box-shadow: -4px 0 20px rgba(0, 0, 0, 0.15);
    animation: slideInRight 0.3s ease-out;
}

/* 与仪表板渐变匹配的品牌色页眉 */
.chat-panel-header {
    background: linear-gradient(135deg, #667eea, #764ba2);
    color: white;
    padding: 12px 16px;
}

/* 通过frameOptions中的自定义className定位iframe */
.anycompany-chat-iframe {
    border-radius: 0 0 12px 12px;
}

/* 响应式：移动端全宽显示 */
@media (max-width: 900px) {
    .chat-side-panel {
        width: 100%;
    }
}

移除默认品牌标识

默认情况下，嵌入式聊天在页脚显示Amazon Quick品牌归属和使用政策链接。为了获得品牌主题体验，使聊天看起来像是您应用程序的原生部分，请移除这些元素：

const contentOptions = {
    footerOptions: {
        showBrandAttribution: false,
        showUsagePolicy: false,
    },
};

应用容器样式、自定义CSS类并移除品牌标识后，嵌入式聊天现在看起来像是财务仪表板的自然扩展。面板使用相同的颜色渐变，页脚干净整洁，整体外观与应用程序的设计系统保持一致。

下表提供了视觉主题选项及其各自控制内容的参考。

配置聊天角色与语气

除了视觉主题之外，聊天的沟通风格也必须体现您组织的个性。如果没有配置角色，嵌入式聊天会以通用、宽泛的答案回应，无法匹配您公司的沟通风格或领域专业知识。

没有自定义聊天代理，回复就缺乏组织上下文。例如，在财务仪表板中，问题“我们上个季度的收入是多少？”会产生如下回复：

“收入是衡量业务运营所产生收益的指标。要查找贵公司上个季度的收入，通常需要查看财务报表或会计系统。收入可以按产品线、地区或时间段进行细分。”

这种回复缺乏关于您组织的具体上下文，且语气与您财务团队的沟通方式不符。通过 Quick 自定义聊天代理，您可以定义控制语气、语言风格和回复行为的角色。您可以通过 SDK 内容选项和代理角色指令进行配置。SDK 内容选项控制显示哪些 UI 元素并将用户引导至您的自定义代理。代理角色指令定义个性、回复风格和知识边界（在 Quick 控制台创建聊天代理时配置）。

SDK 内容选项

const contentOptions = {
    // 锁定到您的自定义财务代理——移除通用代理选择器
    // 使用户只能与您的专用助手交互
    agentOptions: {
        fixedAgentId: 'your-finance-agent-id',
    },
    promptOptions: {
        // 首次加载时自动发送上下文问候语。
        // 助手主动分享相关洞察，
        // 而不是被动等待提问。
        initialPrompt: '本季度有哪些关键财务亮点？',
        // 隐藏初始提示的用户消息气泡。
        // 这使对话看起来像是助手主动发起的，
        // 营造更自然的“顾问”体验。
        showInitialPromptMessage: false,
        // 启用文件附件——用户可以上传电子表格
        // 或报告供助手分析
        allowFileAttachments: true,
        // 显示网络搜索以补充市场研究
        showWebSearch: true,
        // 显示聊天历史，使用户可以继续之前的对话
        showChatHistory: true,
        // 显示知识边界指示器——通过向用户展示
        // 助手可以访问哪些数据源来建立信任
        showAgentKnowledgeBoundary: true,
    },
};

代理角色指令（Quick 控制台）

在 Amazon Quick 控制台的 Chat Agents 页面配置自定义聊天代理时，您可以定义角色指令来塑造代理的回复方式。以下示例展示了可在代理配置中使用的角色指令块：