Agente de Conhecimento Jitterbit

Visão Geral

A Jitterbit oferece o Agente de Conhecimento aos clientes através do Jitterbit Marketplace. Este agente foi projetado para permitir que o time interno da sua organização obtenha respostas inteligentes a partir dos dados internos da sua organização. O agente utiliza a técnica de Retrieval-Augmented Generation (RAG), que combina raciocínio de LLM com acesso a ferramentas e fontes de dados externas. Ele realiza o seguinte:

• Conecta-se e busca informações das seguintes fontes usando o Jitterbit Studio:

  • Páginas do Atlassian Confluence
  • Problemas do Atlassian Jira
  • Documentos do Google Drive
  • Casos de suporte do Salesforce (do objeto Case)

• Integra-se com um LLM para potencializar um chatbot AI inteligente usando dados das fontes acima acessados por meio de uma API customizada criada com o Jitterbit API Manager.

Este documento explica como configurar e operar este agente de IA. Aborda arquitetura e pré-requisitos, exemplos de prompts que mostram o que o agente é capaz de fazer, e etapas para instalar, configurar e operar o agente de IA.

Arquitetura do agente de IA

O diagrama a seguir representa a arquitetura implementada no Agente de Conhecimento:

Fluxo de dados do agente

Workflows de carga inicial de dados e manutenção de dados

Pré-requisitos

Para usar o Agente de Conhecimento, os seguintes componentes são necessários ou presumidos no design do agente.

Componentes Harmony

É necessário ter uma licença Jitterbit Harmony com acesso aos seguintes componentes:

• Jitterbit Studio
• Jitterbit API Manager
• Jitterbit Knowledge Agent adquirido como um add-on de licença

Endpoints suportados

Os seguintes endpoints estão incorporados ao design do agente.

Modelo de linguagem grande (LLM)

O agente de IA usa Azure OpenAI como provedor de LLM. Para usar o Azure OpenAI, é necessário ter uma assinatura do Microsoft Azure com permissões para criar e gerenciar os seguintes recursos:

• Recurso Azure OpenAI com um modelo gpt-4o ou gpt-4.1 implementado.
• Azure Storage com um container de Blob para armazenar dados buscados.
• Azure AI Search com um serviço de busca que pode ser configurado com um índice e indexador.

Base de conhecimento

É possível usar qualquer uma ou todas estas endpoints como base de conhecimento para este agente de IA:

• Atlassian Confluence: A fonte de páginas do Confluence.
• Atlassian Jira: A fonte de problemas do Jira.
• Google Drive: A fonte de arquivos armazenados em um Google Drive compartilhado.
• Salesforce: A fonte de seus casos de suporte ao cliente do objeto Case.

Interface de chat

O design do agente incorpora o Slack como a interface de chat para interagir com o agente de IA. Se desejar usar um aplicativo diferente como interface de chat, um workflow separado e instruções para uma configuração de API genérica estão inclusos neste agente de IA.

Exemplos de prompts

Aqui estão exemplos de prompts que o Agente de Conhecimento consegue processar com acesso aos dados apropriados. O agente pode encontrar informações em qualquer uma ou em todas as endpoints conectadas.

• "Estou tendo um problema com o componente 'ABC'. Pode me ajudar com isso?"
• "Como posso conectar a um banco de dados MySQL usando JDBC?"
• "Pode me dar detalhes sobre o ticket do Jira número 123?"
• "Existem tickets do Jira relacionados ao conector SQL?"
• "Qual é a política de segurança para instalar software no meu computador de trabalho?" (Pode haver um documento no Google Drive ou uma página do Confluence sobre este tópico.)

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

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

1. Baixar personalizações e instalar o projeto Studio.
2. Revisar fluxos de trabalho do projeto.
3. Criar recursos do Microsoft Azure.
4. Criar o aplicativo Slack.
5. Configurar uma conta de serviço do Google e unidade compartilhada.
6. Configurar variáveis do projeto.
7. Testar conexões.
8. Implantar o projeto.
9. Criar a API personalizada do Jitterbit.
10. Revisar fluxos de trabalho do projeto.
11. Disparar os fluxos de trabalho do projeto.
12. Solução de problemas.

Baixar personalizações e instalar o projeto

Siga estas etapas para baixar arquivos de personalização e instalar o projeto Studio:

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

2. Localize o agente de IA chamado Jitterbit Knowledge Agent. Para localizar o agente, você pode usar a barra de pesquisa ou, no painel Filtros em Tipo, selecione Agente de IA para limitar a exibição aos agentes de IA disponíveis.

3. Clique no link Documentação do agente de IA para abrir sua documentação em uma aba separada. Mantenha a aba aberta para consultar depois de iniciar o projeto.

4. Clique em Iniciar Projeto para abrir um diálogo de configuração em duas etapas para baixar personalizações e importar o agente de IA como um projeto Studio.

   Nota

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

5. Na etapa de configuração 1, Baixar Personalizações, os seguintes arquivos são fornecidos para facilitar a configuração do índice e indexador no Azure AI Search e para criar o aplicativo Slack. Selecione os arquivos e clique em Baixar Arquivos:

   • Arquivos de definição JSON do índice e indexador do Azure AI Search

     • Azure_AI_Search_Datasource_Definition.json
     • Azure_AI_Search_Index_Definition.json
     • Azure_AI_Search_Indexer_Definition.json

   • Arquivo de manifesto do aplicativo Slack

     • slack_app_manifest.json

   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.

   Clique em Próximo.

6. Na etapa de configuração 2, Criar um Novo Projeto, selecione um ambiente onde deseja criar o projeto Studio e clique em Criar Projeto.

7. Um diálogo de progresso é exibido. Após indicar que o projeto foi criado, use o link do diálogo Ir para Studio ou abra o projeto diretamente na página Projetos do Studio.

Criar recursos do Microsoft Azure

Crie os seguintes recursos do Microsoft Azure e retenha as informações a seguir para configurar o agente de IA. Para criar e gerenciar esses recursos, é necessário ter uma assinatura do Microsoft Azure com as permissões apropriadas.

Contêiner de Blob do Azure

É necessário criar um contêiner de Blob do Azure para armazenar detalhes do cliente. Os dados do contêiner de Blob serão indexados no Azure AI Search usando um índice e indexador.

Você precisará da URL SAS do contêiner para determinar os valores das variáveis do projeto Armazenamento de Blobs do Azure. Para gerar a URL SAS:

1. No portal do Azure, navegue para Contas de armazenamento e abra a conta de armazenamento específica.
2. No menu de recursos em Armazenamento de dados, selecione Contêineres e abra o contêiner específico.
3. No menu de recursos em Configurações, selecione Tokens de acesso compartilhado.
4. Use o menu Permissões para verificar que a URL da assinatura de acesso compartilhado (SAS) para este contêiner tem no mínimo permissões de Leitura e Escrita:

1. Clique em Generate SAS token and URL.
2. Copie a Blob SAS URL exibida na parte inferior.
3. Determine os valores das variáveis de projeto do Azure Blob Storage a partir da URL do SAS. A URL do SAS está no formato {{ azure_blob_base_url }}/{{ Azure_Blob_Container_Name }}?{{ azure_blob_sas_token }}.

Se usar os arquivos de definição JSON incluídos nos arquivos de personalização do agente de IA para gerar o índice e o indexador, você também precisará da chave da conta do Azure Blob Storage. Para visualizar chaves de acesso da conta:

1. No portal do Azure, acesse Contas de armazenamento e abra a conta de armazenamento específica.
2. No menu de recursos em Segurança + redes, selecione Chaves de acesso.

3. Clique em Mostrar chaves para revelar a chave de acesso a usar durante a configuração do Azure AI Search.

   

Serviço Azure AI Search

É necessário criar um serviço Azure AI Search e configurar seu índice e indexador para processar os dados do contêiner Blob.

Você precisará da URL e da chave de API do serviço Azure AI Search para determinar os valores das variáveis de projeto do Azure AI Search:

• URL: Para obter o valor a usar para azure_ai_search_url, consulte a documentação do Azure Obter informações do serviço.
• Chave de API: Para obter o valor a usar para azure_ai_search_api_key, consulte a documentação do Azure Configurar acesso baseado em função.

Você pode usar os arquivos de definição JSON incluídos nos arquivos de personalização do agente de IA para gerar o índice e o indexador, ou criá-los você mesmo.

Se usar os arquivos de definição fornecidos, substitua os seguintes espaços reservados pelos seus próprios valores de configuração:

Azure_AI_Search_Indexer_Definition.json

Azure_AI_Search_Datasource_Definition.json

Recurso Azure OpenAI

É necessário criar um recurso Azure OpenAI e implantar um modelo gpt-4o ou gpt-4.1 por meio do portal Azure AI Foundry.

Você precisará do nome da implantação, da URL do endpoint do Azure OpenAI e da chave de API para determinar os valores das variáveis de projeto do Azure OpenAI. Para encontrar esses valores:

1. No portal do Azure AI Foundry, abra o recurso específico do OpenAI.

2. Os valores a usar para a URL do endpoint (azure_openai_base_url) e chave de API (azure_openai_api_key) são exibidos na página inicial do recurso:

   

3. No menu de navegação em Recursos compartilhados, selecione Implantações. O nome da implantação (Azure_OpenAI_Deployment_Name) é exibido.

Criar o app Slack

Para criar a interface de chat do Knowledge Agent no Slack, siga estas etapas:

1. Crie um app Slack usando o arquivo manifest do app Slack (slack_app_manifest.json) fornecido com os arquivos de personalização deste agente de IA. Alternativamente, crie o app do zero.

2. Se usar o arquivo manifest fornecido, substitua os seguintes espaços reservados pelos seus valores de configuração:

   Espaço reservado	Descrição
   {{Replace with Slack bot name}}	O nome que você deseja que seu bot Slack tenha, conforme exibido aos usuários. Substitua este valor em dois lugares no manifest.
   {{Replace with Jitterbit API URL}}	A URL de serviço da API personalizada do Jitterbit que você criou em Criar a API personalizada do Jitterbit.

3. Instale o app no seu workspace Slack.

4. Obtenha o token do bot (para o campo Bot User OAuth Token da conexão Slack) e insira seu valor para a variável de projeto slack_bot_oauth_user_token.

5. Configure a variável de projeto slack_channel_name com o canal onde as notificações devem ser enviadas.

6. Insira o valor do token do bot para a variável de projeto slack_bot_oauth_user_token e o nome do canal para a variável de projeto slack_channel_name. Você configurará essas variáveis na próxima etapa.

Configurar uma conta de serviço do Google e uma unidade compartilhada

Esta configuração é necessária apenas se você estiver usando o workflow Data upload Utility - Google Drive to Azure Blob. Você deve ter um projeto Google Cloud ativo para prosseguir. Se não tiver um, você pode criar um seguindo as instruções do Google.

Criar uma conta de serviço do Google

Siga as etapas abaixo para criar uma chave da conta de serviço do Google e permitir que o utilitário acesse com segurança seus arquivos do Google Drive:

1. No console do Google Cloud, use a barra de pesquisa para localizar e navegar até a página Contas de serviço.

2. Se você já tiver uma conta de serviço que deseja usar, prossiga para a etapa 3. Caso contrário, clique em Criar conta de serviço, forneça um nome e clique em Concluído. Nenhuma permissão ou acesso adicional é necessário.

   

3. Selecione a conta de serviço para abrir seus Detalhes da conta de serviço:

   

4. Navegue até a guia Chaves e use o menu Adicionar chave para selecionar Criar nova chave.

   

5. Escolha JSON como o tipo de chave e clique em Criar. Um arquivo JSON contendo as credenciais será baixado no seu computador.

6. Abra o arquivo JSON baixado para encontrar os seguintes valores necessários para configurar as variáveis de projeto do Google Drive:

   • client_email: Este é o valor da variável de projeto Google_Client_Email e é necessário para configurar a unidade compartilhada do Google na próxima seção.
   • private_key: Este é o valor da variável de projeto Google_Private_Key.

7. Ative a Google Drive API na sua conta do Google Cloud:

   1. No console do Google Cloud, use a barra de pesquisa para encontrar e navegar até a página APIs & Services.

   2. Acesse a API Library e selecione a Google Drive API:

      

   3. Clique no botão Enable:

      

Configurar o Google shared drive

O Google shared drive deve ser configurado da seguinte forma para permitir que o utilitário acesse qualquer arquivo que você carregue nele:

1. Crie um Google shared drive se ainda não tiver um.

2. Abra o shared drive e copie seu ID da URL do navegador. O ID é a longa sequência de caracteres no final. Por exemplo, se a URL for https://drive.google.com/drive/folders/dftg-LbGrP7hdfd, o ID será dftg-LbGrP7hdfd. Este ID é o valor para a variável de projeto Google_Drive_ID ao configurar variáveis de projeto do Google Drive.

3. Clique no nome do shared drive no topo da página e selecione Manage members. Uma caixa de diálogo aparece.

4. No campo Add people and groups, cole o valor de client_email do arquivo JSON que você baixou anteriormente.

5. Atribua a função Content manager à conta de serviço e confirme a ação.

Configurar variáveis de projeto

No projeto do Studio instalado anteriormente via Marketplace, você deve definir valores para as seguintes variáveis de projeto.

Isso pode ser feito usando o menu de ações do projeto para selecionar Project Variables e abrir um painel na parte inferior da página, onde você pode revisar e definir os valores.

Salesforce

Jira

Confluence

Google Drive

Armazenamento de Blobs do Azure

Pesquisa de IA do Azure

OpenAI do Azure

Slack

Comum

Testar conexões

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

Para testar conexões, acesse a guia Endpoints e conectores do projeto na paleta de componentes de design e, ao passar o mouse sobre cada endpoint, clique em Testar.

Implantar o projeto

Implante o projeto do Studio.

Para implantar o projeto, use o menu de ações do projeto para selecionar Implantar.

Implantar o projeto

Implante o projeto do Studio. Isso pode ser feito usando o menu de ações do projeto para selecionar Implantar.

Criar a API personalizada do Jitterbit

Crie uma API personalizada usando o API Manager para um dos seguintes:

• Manipulador de solicitações da API do bot do Slack: Obrigatório se estiver usando a notificação do Slack incluída no design deste agente de IA.
• Manipulador genérico de solicitações de API: Opcional. Use para lidar com solicitações de API de qualquer aplicação.

Criar o manipulador de solicitações da API do bot do Slack

Esta API Jitterbit personalizada acionará a operação Slack Bot API Request Handler. Configure e publique a API personalizada com as seguintes configurações:

• Serviço de API: Slack Bot API Request Handler
• Caminho: /
• Projeto: Selecione o projeto do Studio criado a partir do Jitterbit Knowledge Agent no Marketplace
• Operação a Disparar: Slack Bot API Request Handler
• Método: POST
• Tipo de Resposta: Variável de Sistema

Retenha a URL do serviço da API publicada para uso na criação do aplicativo do Slack. A URL do serviço pode ser encontrada na gaveta de detalhes da API na aba Serviços, passando o mouse sobre a coluna Ações do serviço e clicando em Copiar URL do serviço de API.

Manipulador genérico de solicitações de API

Esta API Jitterbit personalizada acionará a operação Generic API request Handler. Não é obrigatório. Crie esta API se estiver usando outras aplicações para processar solicitações de API HTTP. Configure e publique a API personalizada com as seguintes configurações:

• Nome do serviço: Generic API request Handler
• Projeto: Selecione o projeto do Studio criado a partir do Jitterbit Knowledge Agent no Marketplace
• Operação: Generic API request Handler
• Método: POST
• Tipo de resposta: Variável de Sistema

{
    "username": "johnr",
    "prompt": "How to connect to mysql using a connector?"
}

{
    "message": "To connect to a MySQL database using the Database connector, follow these steps:   - Use the MySQL JDBC driver that ships with the agent for additional features like manual queries.",
    "references": [],
    "status_code": 200
}

Revisar fluxos de trabalho do projeto

No projeto do Studio aberto, revise os fluxos de trabalho juntamente com as descrições abaixo para entender o que fazem.

1. Data upload Utility - JIRA Ticket to Azure Index

   Este fluxo de trabalho busca problemas do Jira e executa o fluxo de trabalho Utility - Azure Data Upload and Index para carregar problemas no Azure Blob Storage e indexá-los no índice do Azure AI Search.

   A operação inicial é Main - JIRA tickets upload. Os campos a seguir são buscados:

   "fields": [
       "summary",
       "status",
       "assignee",
       "description",
       "reporter",
       "created",
       "updated",
       "priority",
       "issuetype",
       "components",
       "comment"
    ]
   

   Este fluxo de trabalho pode ser configurado para buscar todos os problemas, ou apenas problemas novos e atualizados, usando as variáveis do projeto Jira.

2. Data upload Utility - SF Cases to Azure Index

   Este fluxo de trabalho recupera casos de suporte do Salesforce e executa o fluxo de trabalho Utility - Azure Data Upload and Index para carregar casos no Azure Blob Storage e indexá-los no índice do Azure AI Search.

   A operação inicial é Main - SF Cases Upload.

   Na configuração da atividade Salesforce Query, a consulta a seguir recupera informações de casos de suporte por agente. Se a sua organização Salesforce não usar esses objetos e campos, ou se as informações de casos de suporte estiverem armazenadas em objetos e campos diferentes, este fluxo de trabalho não funcionará corretamente. Personalize a consulta neste fluxo de trabalho para alinhar-se com o modelo de dados da sua organização Salesforce:

SELECT Account.Name,
           Owner.Email,
           Owner.Name,
           (SELECT CreatedBy.Email,
                   CreatedBy.Name,
                   Id,
                   CommentBody,
                   CreatedDate,
                   LastModifiedDate,
                   LastModifiedBy.Email,
                   LastModifiedBy.Name
            FROM   CaseComments),
           Id,
           CaseNumber,
           CreatedDate,
           Description,
           LastModifiedDate,
           Origin,
           Priority,
           Reason,
           Status,
           Subject,
           Type,
           CreatedBy.Email,
           CreatedBy.Name,
           LastModifiedBy.Email,
           LastModifiedBy.Name
    FROM Case

Este workflow pode ser configurado para buscar todos os casos ou apenas casos novos e atualizados, usando as variáveis de projeto do Salesforce.

1. Data upload Utility - Confluence Pages to Azure Index

   Este workflow recupera páginas do Confluence e executa o workflow Utility - Azure Data Upload and Index para fazer upload de documentos no Azure Blob Storage e indexá-los no índice do Azure AI Search.

   A operação inicial é Main - Load Confluence Pages.

   Este workflow busca todas as páginas do Confluence em cada execução.

2. Data upload Utility - Google Drive to Azure Blob

   Este workflow recupera arquivos do Google Drive e executa o workflow Utility - Azure Data Upload and Index para indexá-los no índice do Azure AI Search.

   A operação inicial é Main - Google Drive Upload.

   Os tipos de arquivo suportados incluem Google Docs, Google Spreadsheets e aqueles suportados pela indexação de blob do Azure Storage.

   Os tamanhos máximos de arquivo suportados estão listados como o tamanho máximo de blob nos limites do Indexador do Azure AI Search para sua camada de serviço de pesquisa de IA. Por exemplo, para a camada básica, o limite é de 16 MB; para S1, o limite é de 128 MB.

   Este workflow pode ser configurado para buscar todos os arquivos ou apenas arquivos novos e atualizados, usando as variáveis de projeto do Google Drive.

3. Utility - Azure Data Upload and Index

   Este é um workflow de utilitário comum usado pelos workflows Data upload Utility para fazer upload de dados no Azure Blob Storage e indexá-los no Azure AI Search.

4. Main Entry - Slack API Request Handler

   Este workflow gerencia solicitações recebidas de bots do Slack. É acionado por uma API personalizada do Jitterbit sempre que sua equipe interage com a interface de chat do bot do Slack (ou seja, envia uma mensagem do Slack para ele). A configuração da API personalizada do Jitterbit é descrita em Criar a API personalizada do Jitterbit mais adiante nesta página.

   Se você não estiver usando o Slack, este workflow pode ser ignorado e não será acionado. Para usar uma interface de chat diferente para sua equipe interagir, use o workflow Generic API Request Handler, também acionado por uma API personalizada do Jitterbit.

5. Generic API Request Handler

   Este workflow processa solicitações de API HTTP de qualquer aplicativo. Para integrar com seus aplicativos, crie uma API do Jitterbit personalizada que acione a operação Generic API request Handler. A URL dessa API pode ser usada por qualquer aplicativo para enviar e receber solicitações.

   A configuração da API personalizada do Jitterbit é descrita em Criar a API personalizada do Jitterbit mais adiante nesta página.

Acionar os workflows do projeto

Para o carregamento de dados inicial, execute qualquer um ou todos os workflows Data upload Utility dependendo de suas fontes de dados. Isso pode ser feito usando a opção Run da operação inicial exibida ao passar o cursor sobre a operação. Você precisará executar a operação novamente no futuro se seus dados forem atualizados.

Os outros dois workflows principais são acionados pelas APIs personalizadas do Jitterbit:

• Main Entry - Slack API Request Handler: Este workflow é acionado pelo Slack por meio da API personalizada Slack Bot API Request Handler. Enviar uma mensagem direta para o aplicativo Slack iniciará o acionamento da API personalizada.

• Generic API Request Handler: Este workflow é acionado por outro aplicativo por meio da API personalizada Generic API request Handler. Enviar uma solicitação para a API configurada iniciará o acionamento da API personalizada.

Todos os outros workflows são acionados por outras operações e estão a jusante das listadas acima. Não se destina a executá-los por conta própria.

Resolução de problemas

Ao encontrar problemas, consulte os seguintes logs para obter informações detalhadas de resolução de problemas:

• Logs da API
• Logs de operação

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