Como personalizar o chat embarcado do Amazon Quick na sua aplicação

Por que o chat padrão cria uma experiência fragmentada

O Amazon Quick oferece uma interface de chat com IA conversacional que pode ser embarcada diretamente em aplicações web. Com ela, os usuários conseguem explorar dados, fazer perguntas e obter respostas sem precisar sair da plataforma onde estão trabalhando.

O problema é que, na configuração padrão, esse chat chega com visual genérico — paleta de cores diferente, branding próprio do Quick e uma aparência que destoa do restante da aplicação. O resultado é uma experiência fragmentada: o usuário percebe que aquele componente foi “colado” ali, e não que faz parte do produto. Para resolver isso, o Amazon Quick disponibiliza recursos de personalização em duas frentes: identidade visual e tom de comunicação.

As duas dimensões da personalização

Antes de entrar nas configurações, vale entender o que pode ser ajustado:

• Identidade visual: o chat deve respeitar a paleta de cores, tipografia e layout da organização.
• Tom de comunicação: além do visual, as respostas do assistente precisam refletir a personalidade e o contexto da empresa — não basta parecer bonito se o chat responde de forma genérica.

Para ilustrar as configurações, a AWS usa como exemplo um assistente de análise financeira embarcado em um painel de performance financeira.

Personalizando a identidade visual

Como o chat é renderizado dentro de um iframe, não é possível estilizar seus elementos internos diretamente com CSS. A abordagem é trabalhar em dois níveis: estilizar o contêiner que envolve o iframe e usar as opções do SDK para remover elementos de branding padrão que conflitem com o design da aplicação.

Configuração do frameOptions

O parâmetro frameOptions controla como o iframe se comporta dentro do contêiner. Veja o exemplo de configuração:

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 do contêiner e layout

No exemplo do painel financeiro, o chat aparece como um painel lateral que desliza pela direita da tela. O CSS abaixo mostra como estilizar esse contêiner e aplicar a identidade visual da marca:

/* 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%;
  }
}

Removendo o branding padrão

Por padrão, o chat embarcado exibe a atribuição de marca do Amazon Quick e um link de política de uso no rodapé. Para uma experiência totalmente integrada à identidade da aplicação, esses elementos podem ser removidos via contentOptions:

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

Com o CSS do contêiner aplicado, a classe personalizada no iframe e o branding padrão removido, o chat passa a se comportar como uma extensão natural do painel — mesma paleta, rodapé limpo e aparência consistente com o restante da aplicação.

A tabela abaixo resume as principais opções de personalização visual disponíveis:

• className: classe CSS aplicada ao iframe (border-radius, sombras, z-index)
• width / height: dimensões do iframe (use "100%" para layouts responsivos)
• withIframePlaceholder: exibe um spinner de carregamento enquanto o conteúdo é inicializado
• footerOptions.showBrandAttribution: exibe ou oculta o texto “Powered by”
• footerOptions.showUsagePolicy: exibe ou oculta o link de política de uso
• CSS do contêiner: posicionamento do painel, bordas, sombras e estilo do cabeçalho

Configurando a persona e o tom do assistente

Visual alinhado é metade do caminho. A outra metade é garantir que as respostas do chat reflitam o contexto e a linguagem da organização. Sem configuração de persona, o assistente tende a responder de forma genérica e descontextualizada.

Por exemplo, no painel financeiro, a pergunta “Qual foi nossa receita no último trimestre?” produziria uma resposta assim sem personalização:

“Receita é uma medida de renda gerada pelas operações do negócio. Para encontrar a receita da sua empresa no último trimestre, você normalmente consultaria seus demonstrativos financeiros ou sistema contábil. A receita pode ser detalhada por linha de produto, região ou período de tempo.”

Essa resposta não tem contexto específico sobre a organização e usa um tom que não corresponde à forma como uma equipe de finanças se comunica. Com o agente de chat personalizado do Quick, é possível definir uma persona que controla o tom, o estilo de linguagem e o comportamento das respostas. A configuração acontece em dois lugares: nas opções de conteúdo do SDK e nas instruções de persona definidas no console do Quick.

Opções de conteúdo do SDK

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,
  },
};

Instruções de persona do agente (console do Quick)

Ao configurar o agente de chat personalizado no console do Amazon Quick, são definidas as instruções de persona que moldam como o agente responde. O bloco abaixo exemplifica como essas instruções podem ser estruturadas:

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

Com o agente financeiro personalizado configurado, a mesma pergunta sobre receita passa a produzir uma resposta direta, orientada a dados e contextualizada:

“A receita do Q2 2025 foi de US$ 8,89M, alta de 12,5% em relação ao Q2 2024 (US$ 7,05M). O crescimento foi impulsionado por momentum consistente mês a mês em todas as regiões: Abril: US$ 2,89M / Maio: US$ 2,95M / Junho: US$ 3,05M. A América do Norte liderou com crescimento de 15%, seguida pela EMEA com 9%.”

As principais opções de personalização de persona disponíveis via SDK são:

• fixedAgentId: bloqueia o agente personalizado, removendo o seletor genérico de agentes
• initialPrompt: define a abertura conversacional — proativa ou reativa
• showInitialPromptMessage: false: faz o assistente parecer o iniciador da conversa, criando uma experiência de “consultor”
• showAgentKnowledgeBoundary: indica ao usuário quais fontes de dados o assistente consegue acessar
• Instruções de persona do agente: definem tom, vocabulário, estrutura de resposta e limites de atuação

Interação programática com sendPrompt()

Além da personalização visual e de persona, o SDK disponibiliza o método sendPrompt(), que permite à aplicação disparar perguntas contextuais a partir de interações na interface. Por exemplo: quando o usuário seleciona uma métrica em um gráfico, a aplicação pode enviar automaticamente uma pergunta relacionada ao assistente, conectando os visuais do painel com a interface conversacional.

// 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.'
);

No exemplo do painel financeiro, botões de ação rápida no cabeçalho do painel de chat implementam esse padrão:

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);
});

Por onde começar

Para colocar essas personalizações em prática, o ponto de partida é embutir o chat do Quick na sua aplicação. Em seguida, aplique a paleta de cores, tipografia e layout da marca por meio do CSS do contêiner e das opções de frame do SDK, para que o chat se comporte como um componente nativo. Por fim, crie um agente de chat personalizado no console do Quick com instruções de persona que definam o domínio de conhecimento e o estilo de comunicação desejado. A documentação oficial de personalizações do Amazon Quick traz todos os detalhes necessários para cada etapa.

Fonte

Customize Amazon Quick embedded chat into your application (https://aws.amazon.com/blogs/machine-learning/customize-amazon-quick-embedded-chat-into-your-application/)