Agente QBR Deck do Jitterbit

Visão geral

O Jitterbit fornece o Agente QBR Deck aos clientes através do Jitterbit Marketplace. Este agente automatiza a criação de decks de apresentação de revisão trimestral (QBR) no Google Slides, coletando dados de clientes do Salesforce, NetSuite e APIs de uso do produto, e processando esses dados com IA para produzir resumos e insights estruturados. Este agente usa a técnica de Geração Aumentada por Recuperação (RAG), que combina raciocínio de LLM com acesso a ferramentas externas e fontes de dados.

O agente recebe solicitações através de comandos slash do Slack, consulta o Salesforce para detalhes da conta, contatos e casos de suporte, recupera dados de projetos do NetSuite e extrai métricas de uso do produto das APIs regionais. Um LLM processa os dados combinados e gera resumos narrativos e insights. O agente então duplica um modelo do Google Slides no Google Drive, preenche os slides com o conteúdo gerado e envia o link do deck concluído (ou uma notificação de erro) de volta ao usuário no Slack.

O agente executa as seguintes tarefas:

• Recebe solicitações de geração de QBR de usuários via comandos slash do Slack.
• Consulta o Salesforce para informações de conta, detalhes de região, contatos e casos de suporte.
• Recupera dados de projetos do NetSuite.
• Extrai métricas de uso do produto das APIs de uso do produto regional.
• Normaliza todos os dados coletados em um formato canônico para processamento.
• Envia os dados combinados para um LLM a fim de gerar resumos e insights.
• Duplica um modelo de slide QBR no Google Drive para o cliente de destino.
• Preenche os slides com conteúdo gerado por IA.
• Envia o link do deck concluído ou uma notificação de erro de volta ao usuário no Slack.

Este documento explica como configurar e operar este agente de IA. Ele cobre arquitetura, pré-requisitos, orientação sobre como usar o agente e etapas para instalar, configurar e operar o agente de IA.

Arquitetura do agente de IA

Este agente de IA gera decks de QBR orquestrando a recuperação de dados no Salesforce, NetSuite e APIs de uso do produto, depois usando um LLM para sintetizar os dados em uma apresentação do Google Slides preenchida. Uma interação típica segue estas etapas:

1. Um usuário envia um comando slash /completeqbr para o bot do Slack, especificando um nome de cliente ou ID de conta do Salesforce.
2. O Slack chama o endpoint da API Jitterbit, acionando o manipulador de solicitação principal.
3. O agente consulta o Salesforce para informações de conta, detalhes de região, contatos e casos de suporte.
4. O agente recupera dados de projetos do NetSuite.
5. O agente recupera métricas de uso do produto da API de uso do produto regional apropriada.
6. O agente normaliza todos os dados coletados em um formato canônico.
7. O agente envia os dados normalizados para o LLM, que gera resumos e insights para cada seção de slide.
8. O agente duplica o modelo QBR do Google Slides no Google Drive e preenche cada slide com o conteúdo gerado.
9. O agente envia o link do deck concluído para o usuário no Slack. Se ocorrer um erro (por exemplo, o cliente não for encontrado ou vários correspondentes forem retornados), o agente envia uma notificação de erro.

Diagrama de fluxo de trabalho

O diagrama a seguir mostra o fluxo de trabalho principal de tratamento de solicitações para o Agente QBR Deck do Jitterbit.

Pré-requisitos

Você precisa dos seguintes componentes para usar este agente de IA.

Componentes Harmony

Você deve ter uma licença Jitterbit Harmony com acesso aos seguintes componentes:

• Jitterbit Studio
• Jitterbit API Manager
• Agente QBR Deck adquirido como um complemento de licença.

Endpoints suportados

O agente de IA se conecta aos seguintes endpoints. Você pode acomodar outros sistemas modificando as configurações de endpoint e fluxos de trabalho do projeto.

Modelo de linguagem grande (LLM)

O agente de IA usa o Azure OpenAI como provedor de LLM. Para usar o Azure OpenAI, você deve ter uma assinatura do Microsoft Azure com permissões para criar um recurso do Azure OpenAI com um modelo implementado.

Salesforce

O agente consulta o Salesforce para dados de conta, detalhes de região, contatos e casos de suporte. Você deve ter uma conta Salesforce com acesso à API e credenciais com permissões para ler registros de conta, contato e caso.

NetSuite

O agente consulta o NetSuite usando integração baseada em SOAP para recuperar dados de projeto. Você deve ter uma conta NetSuite com credenciais de autenticação baseada em token que tenham permissões para ler registros de projeto.

APIs de uso de produto

O agente recupera métricas de uso de produto de endpoints de API regionais que cobrem América do Norte (NOAM), Europa/Oriente Médio/África (EMEA) e Ásia-Pacífico (APAC). Você deve ter chaves de API válidas para as regiões aplicáveis.

Slack

O agente usa o Slack como interface de conversação e canal de notificação. Você deve ter um workspace Slack onde possa instalar um app personalizado e a capacidade de criar e configurar um manifest de app.

Google Cloud

O agente usa a Google Drive API e a Google Slides API para duplicar um template e preencher a apresentação gerada. Você deve ter um projeto Google Cloud com ambas as APIs habilitadas e uma conta de serviço com acesso de Editor ao Shared Drive que contém o template QBR e as pastas de saída.

Prompts do agente

O QBR Deck Agent recebe todas as solicitações como comandos de barra enviados para o bot do Slack. Esta seção descreve os comandos suportados e fornece exemplos de entrada.

Diretrizes de prompt

Siga estas diretrizes ao enviar comandos ao agente:

• Especifique um cliente usando o parâmetro customer= seguido pelo nome do cliente ou ID da conta Salesforce.
• Se o nome corresponder a mais de uma conta Salesforce, o agente retorna um erro. Use o ID da conta Salesforce para direcionar um registro específico.
• Use /completeqbr para gerar um deck de apresentação QBR completo.
• Use /singleslideqbr para gerar um slide único. Use os parâmetros customer= e slide= para especificar o cliente e qual slide gerar.

Exemplos de prompts

Os exemplos a seguir mostram os comandos que o agente suporta. Substitua <customer name> pelo nome do cliente ou ID da conta Salesforce.

Deck QBR completo

Envie o comando a seguir para gerar um deck de apresentação QBR completo para um cliente.

QBR de slide único

Envie o comando a seguir para gerar um slide único para um cliente. O parâmetro slide= aceita os seguintes valores: title_1, Summary_1, Usage_1, Cases_1, Entitlements_1, Projects_1 ou team_1.

Instalação, configuração e operação

Siga estas etapas para instalar, configurar e operar este agente de IA:

1. Baixe e instale o projeto
2. Configure o Azure OpenAI
3. Configure o Google Cloud
4. Prepare o Google Drive
5. Configure as variáveis do projeto
6. Teste as conexões
7. Implante o projeto
8. Crie uma API personalizada
9. Crie e configure o app do Slack
10. Revise os workflows do projeto
11. Dispare os workflows do projeto

Para orientação sobre resolução de problemas, consulte Resolução de problemas.

Baixar e instalar o projeto

Siga estas etapas para instalar o projeto do Studio para o agente de IA:

1. Faça login no portal Harmony em https://login.jitterbit.com e abra o Marketplace.

2. Localize o agente de IA chamado QBR Deck Agent. Para localizá-lo, use a barra de pesquisa ou, no painel Filters, em Type, selecione AI Agent para limitar a exibição apenas aos agentes de IA.

3. Clique no link Documentation do agente para abrir sua documentação em uma nova aba. Mantenha a aba aberta para consultá-la depois de iniciar o projeto.

4. Clique em Start Project para abrir um diálogo de configuração de duas etapas.

   Nota

   Se ainda não adquiriu o agente de IA, Get agent será exibido. Clique nele para abrir um diálogo informativo e, em seguida, clique em Submit para que um representante entre em contato com você sobre a compra do agente de IA.

   Dica

   O diálogo de configuração inclui um aviso para não importar o modelo antes de aplicar personalizações de endpoint. Este aviso não se aplica a este agente de IA e pode ser ignorado. Siga a ordem recomendada de etapas nesta documentação.

5. Na etapa 1 de configuração, Download Customizations, baixe o arquivo ZIP fornecido que contém a estrutura de pastas do Google Drive e o modelo de slide QBR.

6. Clique em Next.

7. Na etapa 2 de configuração, Create a New Project, selecione um ambiente onde o projeto do Studio será criado e, em seguida, clique em Create Project.

8. Após o diálogo de progresso indicar que o projeto foi criado, use o link do diálogo Go to Studio ou abra o projeto diretamente na página Projects do Studio.

Configurar Azure OpenAI

Crie um recurso Azure OpenAI e implante um modelo para usar como LLM do agente:

1. Entre no portal do Azure e crie um recurso Azure OpenAI em sua assinatura.
2. No Azure AI Foundry, crie uma implantação e anote o nome da implantação e o ID do modelo.
3. Copie a chave de API e a URL do endpoint da seção Keys and Endpoint do recurso.
4. Armazene a chave, o endpoint e os detalhes da implantação nas variáveis de projeto correspondentes listadas em Azure OpenAI.

Configurar Google Cloud

Crie uma conta de serviço do Google Cloud para permitir que o agente acesse o Google Drive e o Google Slides:

1. Acesse console.cloud.google.com, selecione ou crie um projeto e ative a Google Drive API e a Google Slides API em APIs & Services > Library.
2. Acesse IAM & Admin > Service Accounts e crie uma nova conta de serviço.
3. Na aba Keys, clique em Add Key > Create new key, selecione JSON e baixe o arquivo de chave gerado.
4. A partir do arquivo JSON baixado, extraia os valores client_email, private_key e project_id e armazene-os nas variáveis de projeto correspondentes listadas em Google Cloud.
5. Defina a variável Google_OAuth_Scopes como https://www.googleapis.com/auth/drive.

Preparar Google Drive

Carregue o modelo QBR em um Shared Drive e conceda acesso à conta de serviço:

1. No Google Drive, verifique se o destino é um Shared Drive (não uma pasta pessoal My Drive).
2. Conceda à conta de serviço (o valor de Google_Client_Email) acesso de Editor ao Shared Drive.
3. Carregue o arquivo ZIP baixado em Baixar e instalar o projeto para o Shared Drive e extraia seu conteúdo. Verifique se duas pastas foram criadas: New Documents e QBR Template.
4. Abra a pasta QBR Template, localize o arquivo de modelo do Google Slides e copie o ID do arquivo de modelo da URL (a sequência longa entre /d/ e /edit).
5. Abra a pasta New Documents e copie o ID da pasta da URL (a sequência após /folders/).
6. Armazene ambos os IDs nas variáveis de projeto Google_Drive_Template_File_Id e Google_Drive_Destination_Folder.

Configurar variáveis do projeto

No projeto do Studio instalado do Marketplace, defina valores para as seguintes variáveis do projeto.

Para configurar variáveis do projeto, use o menu de ações do projeto e selecione Project Variables para abrir a gaveta de configuração.

Salesforce

NetSuite

Google Cloud

APIs de uso do produto

Azure OpenAI

Testar conexões

Teste as configurações de endpoint para verificar a conectividade usando os valores de variáveis do projeto definidos.

Para testar conexões, vá para a aba Project endpoints and connectors na paleta de componentes de design, passe o mouse sobre cada endpoint e clique em Test.

Implantar o projeto

Implante o projeto do Studio.

Para implantar o projeto, use o menu de ações do projeto e selecione Deploy.

Criar uma API personalizada

Crie uma API personalizada no Jitterbit API Manager para expor o ponto de entrada do agente:

1. No API Manager, crie uma nova API personalizada com um método POST no caminho /newqbr.
2. Defina o gatilho da operação como a operação API Request Handler no workflow 1.0 Main Entry – Slack API Request Handler.
3. Publique a API e copie a URL do endpoint gerada.
4. Use esta URL para ambos os placeholders {{Jitterbit API for complete QBR Report}} e {{Jitterbit API for Partial QBR Report}} ao configurar o manifesto da aplicação Slack. Apenas uma API é necessária; ambos os comandos de barra usam o mesmo endpoint.

Criar e configurar a aplicação Slack

Criar um aplicativo Slack e configurá-lo para chamar o endpoint da API Jitterbit:

1. Acesse api.slack.com/apps e selecione ou crie seu aplicativo Slack.
2. Navegue até App Manifest no menu à esquerda e clique em Edit Manifest.
3. Cole o JSON de manifesto fornecido com o projeto no editor.
4. Substitua os placeholders {{Jitterbit API for complete QBR Report}} e {{Jitterbit API for Partial QBR Report}} pela mesma URL de endpoint da API Jitterbit criada em Criar uma API personalizada. Ambos os comandos de barra usam o mesmo endpoint; o agente os roteia internamente com base no nome do comando.
5. Clique em Save Changes para aplicar a configuração.
6. Instale ou reinstale o aplicativo no seu workspace, se solicitado.

Analisar workflows do projeto

O projeto Studio contém nove workflows que implementam a funcionalidade do QBR Deck Agent, organizados em dois grupos funcionais.

Entrada principal e lógica de IA

1.0 Main Entry – Slack API Request Handler

Este workflow funciona como o controlador central do agente. Ele recebe solicitações de comandos de barra Slack recebidas via endpoint da API Jitterbit, valida a entrada e roteia solicitações para os workflows apropriados de coleta de dados. Após a coleta de dados, coordena operações pós-resposta e orquestra o processamento de IA e as etapas de geração de slides.

8.0 Main – AI Agent Tools Logic

Este workflow executa a lógica principal de processamento de IA. Ele constrói o payload de solicitação a partir dos dados normalizados, envia-o ao LLM e processa os resumos e insights retornados. O conteúdo gerado é então passado para os workflows do Google Slides para inserção na apresentação.

Workflows de utilitário e ferramentas

2.0 Utility – Duplicate Google Slides Template

Este workflow gerencia modelos. Ele autentica com Google Cloud usando um token OAuth, recupera o arquivo de template de QBR configurado do Google Drive, cria uma cópia do template, atribui um novo ID de arquivo e o move para a pasta de destino configurada.

3.0 Utility – Google Slides

Este workflow gerencia atualizações de conteúdo de slides. Ele modifica títulos de slides, conteúdo do corpo e resumos, recupera metadados de apresentação, gerencia mapeamento de placeholders e realiza atualizações finais para garantir que todos os slides reflitam os insights gerados por IA.

4.0 Tool – Canonical Input Handler

Este workflow padroniza dados de solicitação recebida. Ele carrega e normaliza dados de múltiplas fontes em um formato canônico unificado, garantindo consistência antes dos dados serem passados para o workflow de processamento de IA.

5.0 Utility – Salesforce

Este workflow integra dados do Salesforce no workflow. Consulta contas por nome ou ID de conta do Salesforce, recupera detalhes de região e busca contatos e casos de suporte relacionados para fornecer contexto de CRM para o QBR.

6.0 Utility – NetSuite

Este workflow recupera dados relacionados a projetos do NetSuite. Pesquisa e retorna registros de projetos para enriquecer o QBR com contexto operacional ou financeiro.

7.0 Utility – AskJBSales

Este workflow gerencia análises de uso de produtos. Recupera dados de uso de produtos dos endpoints de API regional configurados, cria conjuntos de dados de uso estruturados e combina múltiplas respostas de API nos dados utilizados pelo workflow de processamento de IA.

9.0 Utility – Slack

Este workflow gerencia a comunicação de saída do Slack. Envia mensagens formatadas para o Slack, entregando o link do deck concluído, atualizações de status ou notificações de erro ao usuário que acionou a solicitação.

Acionar os workflows do projeto

O QBR Deck Agent é acionado por comandos de barra do Slack enviados para o app Slack configurado. Quando um usuário envia um comando /completeqbr ou /singleslideqbr, o Slack chama o endpoint da API Jitterbit, que aciona a operação API Request Handler no workflow 1.0 Main Entry – Slack API Request Handler.

Antes de o agent receber comandos, o app Slack precisa estar instalado no seu workspace e as URLs dos endpoints da API devem estar configuradas no manifesto do app. Veja Create and configure the Slack app e Create a custom API.

Solução de problemas

Se encontrar problemas, verifique os logs a seguir para obter informações detalhadas de solução de problemas:

• API logs
• Operation logs

Para obter assistência adicional, entre em contato com o suporte do Jitterbit.