如何在应用中使用 Amazon Q 嵌入式聊天定制品牌化界面

Amazon QuickSight 嵌入式聊天提供了一个会话式 AI 界面，可以直接集成到你的 Web 应用中。用户可以在不离开应用的情况下提问、探索数据并获取洞察。然而，通用聊天界面会造成体验上的割裂感。聊天界面必须看起来和感觉上是应用原生的组成部分，而不是外部附加物。通过 Quick 的定制能力，你可以将组织的视觉主题和品牌调性延伸到聊天界面，使其外观和感受与你的应用保持一致，提供统一且有品牌特色的体验。

在这篇文章中，我们将详细介绍定制 Quick 嵌入式聊天的配置选项，以在你的应用中提供一致且有品牌特色的体验。

定制需求通常分为两个关键领域。第一个是视觉主题，以匹配公司的品牌。你的组织已经建立了品牌准则，嵌入式聊天必须体现这些准则。第二个是语调，以匹配公司的声音，因为仅有视觉一致性是不够的。聊天传达的方式也必须反映组织的个性。

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

配置视觉主题

当你首次将 Quick 聊天嵌入应用时，聊天界面使用其默认样式。这会造成视觉上的不匹配。聊天看起来像是附加在应用上的外部工具，而不是原生组件。注意不匹配的颜色调色板、通用品牌标识，以及与周围财务仪表板缺乏视觉整合。

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

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

Frame 选项配置

frameOptions 参数控制 iframe 在容器内的行为：

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

const frameOptions = {
    url: chatEmbedUrl,
    container: document.getElementById('chat-container'),
    height: '100%',
    width: '100%',
    // Apply a custom CSS class directly to the iframe element.
    // Use this for border-radius, positioning, or z-index adjustments
    // to match your application's component design.
    className: 'anycompany-chat-iframe',
    // Display a loading placeholder while the chat content loads,
    // preventing a blank white rectangle during initialization.
    withIframePlaceholder: true,
    // Enable clipboard access so users can copy responses
    // or paste content into the chat input.
    framePermissions: {
        clipboardRead: true,
        clipboardWrite: true,
    },
};

容器和布局 CSS

样式化包裹聊天的容器，以匹配你的应用设计系统。在我们的财务仪表板示例中，聊天显示为一个从右侧滑入的侧边面板。

/* Position the chat as a fixed side panel */
.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;
}

/* Brand-colored header matching the dashboard's gradient */
.chat-panel-header {
    background: linear-gradient(135deg, #667eea, #764ba2);
    color: white;
    padding: 12px 16px;
}

/* Target the iframe via the custom className from frameOptions */
.anycompany-chat-iframe {
    border-radius: 0 0 12px 12px;
}

/* Responsive: full-width on mobile */
@media (max-width: 900px) {
    .chat-side-panel {
        width: 100%;
    }
}

移除默认品牌

默认情况下，嵌入式聊天在页脚显示 Amazon Quick 品牌标识和用法策略链接。对于希望聊天成为应用原生部分的有品牌主题体验，需要移除这些元素：

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

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

下表提供了视觉主题选项的参考以及每个选项控制的内容。

配置聊天人格和语调

除了视觉主题外，聊天沟通风格必须反映组织的个性。没有人格配置，嵌入式聊天会给出通用的、宽泛的回答，与你公司的沟通风格或领域专业知识不匹配。

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

"收入是衡量从业务运营中产生的收入的指标。要找到你公司上一季度的收入，你通常需要查看财务报表或会计系统。收入可以按产品线、地区或时间段细分。"

这个回答缺乏关于你组织的具体背景，使用的语气也与财务团队的沟通方式不匹配。通过 Quick 自定义聊天代理，你可以定义控制语气、语言风格和回复行为的人格。这是通过 SDK 内容选项和代理人格指令配置的。SDK 内容选项控制出现哪些 UI 元素，并将用户引导到你的自定义代理。代理人格指令定义个性、回复风格和知识边界（在创建聊天代理时在 Quick 控制台中配置）。

const contentOptions = {
    // Lock to your custom finance agent --- removes the generic agent selector
    // so users only interact with your purpose-built assistant
    agentOptions: {
        fixedAgentId: 'your-finance-agent-id',
    },
    promptOptions: {
        // Auto-send a contextual greeting on first load.
        // The assistant proactively shares relevant insights
        // rather than waiting passively for a question.
        initialPrompt: 'What are the key financial highlights this quarter?',
        // Hide the user message bubble for the initial prompt.
        // This makes it appear as if the assistant initiated the conversation,
        // creating a more natural "advisor" experience.
        showInitialPromptMessage: false,
        // Enable file attachments --- users can upload spreadsheets
        // or reports for the assistant to analyze
        allowFileAttachments: true,
        // Show web search for supplementary market research
        showWebSearch: true,
        // Show chat history so users can resume prior conversations
        showChatHistory: true,
        // Display knowledge boundary indicator --- builds trust by showing
        // users what data sources the assistant can access
        showAgentKnowledgeBoundary: true,
    },
};

代理人格指令（Quick 控制台）

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

You are the AnyCompany Finance Assistant, an AI embedded in AnyCompany's
Finance Performance Dashboard.

## Your Role
You help executive leadership, finance teams, and business leads explore
financial data, understand performance trends, and take action on insights
--- all without leaving the dashboard.

## Response Style
- Lead with the direct answer and the key number
- Provide context and comparison to prior period
- Cite the source document when referencing qualitative information
- Use bullet points for multi-part answers
- Keep responses concise --- executives want the insight, not the explanation

## Boundaries
- Only discuss AnyCompany financial data and business context
- Do not speculate about future performance beyond stated targets
- For questions outside your knowledge, direct users to finance@anycompany.com

配置了自定义财务代理后，同样的问题"上一季度我们的收入是多少？"现在产生的回复与组织的沟通风格一致：直接、数据驱动、有上下文。

"2025 年第二季度收入为 889 万美元，较 2024 年第二季度（705 万美元）增长 12.5%。增长是由所有地区持续的环比增长势头发达的：

北美领先，增长 15%，其次是 EMEA，增长 9%。"

下表列出了使用 SDK 时可以配置的人格定制选项。

程序化交互

除了视觉主题和人格，SDK 还提供了 sendPrompt() 方法。通过这个方法，你的应用可以从 UI 交互触发上下文相关的问题。例如，当用户选择图表指标时，应用向助手发送相关问题。这将仪表板可视化与会话界面连接起来。

// Store the experience reference after embedding
const chatExperience = await embeddingContext.embedQuickChat(
    frameOptions,
    contentOptions
);

// When a user selects a revenue metric card in your dashboard:
chatExperience.sendPrompt(
    'Explain the revenue trend this quarter and what is driving it.'
);

在财务仪表板示例中，聊天面板顶部的快捷操作按钮实现了这个模式：

const askAboutMetric = (metricName) => {
    chatExperience.sendPrompt(
        `Explain the trend for ${metricName} and what's driving it.`
    );
};

// Quick-action buttons
const metrics = [
    { metric: 'revenue', label: 'Revenue' },
    { metric: 'profit margin', label: 'Margins' },
    { metric: 'expenses', label: 'Expenses' }
];

const container = document.getElementById('quick-actions');
metrics.forEach(({ metric, label }) => {
    const button = document.createElement('button');
    button.type = 'button';
    button.textContent = label;
    button.setAttribute('aria-label', `Ask about ${metric}`);
    button.addEventListener('click', () => askAboutMetric(metric));
    container.appendChild(button);
});

在这篇文章中，我们展示了如何定制 Quick 嵌入式聊天界面，以在你的应用中提供一致且有品牌特色的体验。通过配置 CSS，你可以将聊天面板在视觉上与你的设计系统对齐，使其看起来像原生组件而不是外部小部件。通过定义代理人格指令和 SDK prompt 选项，你可以塑造聊天的沟通风格以匹配你的品牌调性。sendPrompt() 方法通过从按钮点击和图表选择等用户交互触发上下文问题，将你的应用 UI 与会话界面连接起来。

要将这些定制付诸实践，首先将 Quick 聊天嵌入你的应用。通过容器 CSS 和 SDK frame 选项应用你品牌的颜色调色板、排版和布局，使聊天感觉像是原生组件。接下来，在 Quick 控制台中创建一个自定义聊天代理，并用人格指令定义你的领域专业知识和沟通风格。