Egain (versão prévia)

Esse conector está disponível nos seguintes produtos e regiões:

Service	Class	Regions
Copilot Studio	Premium	Todas as regiões do Power Automate , exceto as seguintes:      – Governo dos EUA (GCC)      – Governo dos EUA (GCC High)      - China Cloud operado pela 21Vianet      - Departamento de Defesa dos EUA (DoD)
Aplicativos Lógicos	Standard	Todas as regiões dos Aplicativos Lógicos , exceto as seguintes:      – Regiões do Azure Governamental      - Regiões do Azure China      - Departamento de Defesa dos EUA (DoD)
Power Apps	Premium	Todas as regiões do Power Apps , exceto as seguintes:      – Governo dos EUA (GCC)      – Governo dos EUA (GCC High)      - China Cloud operado pela 21Vianet      - Departamento de Defesa dos EUA (DoD)
Power Automate	Premium	Todas as regiões do Power Automate , exceto as seguintes:      – Governo dos EUA (GCC)      – Governo dos EUA (GCC High)      - China Cloud operado pela 21Vianet      - Departamento de Defesa dos EUA (DoD)

Contato
Nome	Suporte ao eGain
Email	support@egain.com

Metadados do conector
Publicador	EGain Corporation
Site	http://egain.com/
Política de privacidade	https://www.egain.com/privacy-policies
Categorias	IA; Financiar
Source	marketplace
BrandColor	#FEF0FD

Egain – Guia de uso do agente copilot

Visão geral

O conector do Egain foi projetado para se integrar perfeitamente aos agentes do Microsoft Copilot Studio, fornecendo recursos avançados de gerenciamento de conhecimento por meio de duas instâncias de eGain distintas. Esse conector permite que os agentes pesquisem bases de dados de conhecimento, gerem respostas alimentadas por IA e forneçam citações precisas com geração automática de URL.

Pré-requisitos

Antes de usar o conector do Egain, verifique se você tem os seguintes pré-requisitos em vigor:

1. Requisitos de instância do eGain: você precisa ter uma instância do eGain em execução na versão Rigel ou R21.x.x ou superior.

2. Configuração do aplicativo cliente: um aplicativo cliente deve ser criado na instância do eGain com permissões apropriadas para as ações que você planeja usar. O aplicativo cliente deve ter:

   • Permissões do portal para operações de pesquisa de base de dados de conhecimento
   • Permissões de IA para operações de IA gerativas

   Para obter informações detalhadas sobre como criar e configurar aplicativos cliente, consulte a documentação do aplicativo cliente eGain.

3. Configuração do Portal de Conhecimento: um portal de conhecimento deve ser pré-configurado na instância do eGain para habilitar a pesquisa e a recuperação de conteúdo. O portal serve como base para operações de base de dados de conhecimento e gerenciamento de conteúdo.

   Para obter informações sobre como configurar portais de conhecimento, consulte a documentação do eGain Portals.

Configurações do agente

1. Agente de Demonstração do eGain

• Host de API: api.egain.cloud
• URL da instância: https://egainr21demo.egain.cloud
• Autenticação: segurança habilitada com autenticação de token de portador
• Tópicos personalizados:
  • Pesquisa de eGain: usa Kb-search a operação
  • Generativo: usa Generative-V3 a operação

2. Assistente de Conector do eGain

• Host de API: api.ai.egain.cloud
• URL da instância: https://ai.egain.cloud/s5fa
• Autenticação: segurança habilitada com autenticação de token de portador
• Tópicos personalizados:
  • Generativo: usa Generative-V3 a operação
  • eGainSearch: usa Search-V3 a operação

Segurança e autenticação

Importante: o conector Egain em si não requer nenhuma configuração de autenticação. No entanto, as APIs eGain são protegidas e dão suporte à autenticação genérica do OAuth 2.0, que é configurada na guia Segurança dos agentes do Copilot Studio.

Ambas as instâncias de eGain têm a segurança habilitada, garantindo que todas as chamadas à API sejam autenticadas corretamente. O conector manipula automaticamente:

• Suporte ao OAuth 2.0: autenticação genérica do OAuth 2.0 configurada na guia Segurança do Copilot Studio
• Autenticação de token de portador: adiciona Bearer automaticamente o prefixo se não estiver presente
• Gerenciamento de cabeçalho: gerencia corretamente cabeçalhos de autorização
• Sanitização de parâmetro: remove parâmetros de autenticação antes de encaminhar para APIs eGain
• Tratamento de erros: tratamento normal de falhas de autenticação

Operações e uso

Operação 1: Search-V3

Usado por: eGain Connector Assistant (tópico eGainSearch)

Finalidade: pesquisa avançada usando a API de pesquisa V3 do eGain com processamento de resultados aprimorado e geração de URL de citação automática.

Configuração:

• Host de API: api.ai.egain.cloud
• Ponto de extremidade:/search/v3
• Método: POST

Solicitação de exemplo:

{
  "q": "How to reset password for user accounts?",
  "baseUrl": "https://ai.egain.cloud/s5fa/kb/ebank,
  "shortName": "content",
  "authToken": "your-bearer-token-here",
  "$attribute": "snippet",
  "$lang": "en-us",
  "$pagenum": 1,
  "$pagesize": 10,
  "Accept": "application/json",
  "Accept-language": "en-us",
  "portalId": "202400000001000"
}

Configuração do Copilot Studio:

$attribute: snippet
$lang: en-us
$pagenum: 1
$pagesize: 10
Accept: application/json
Accept-language: en-us
authToken: =System.User.AccessToken
baseUrl: https://ai.egain.cloud/s5fa/kb/ebank
portalId: "202400000001000"
query: =Topic.Var1_SearchQuestion
shortName: content

Resposta de exemplo:

{
  "results": [
    {
      "alternateId": "KB-12345",
      "title": "Password Reset Procedures",
      "url": "https://ai.egain.cloud/s5fa/kb/ebank/content/KB-12345/Password-Reset-Procedures",
      "snippet": "To reset a user password, follow these steps...",
      "relevanceScore": 0.95,
      "lastModifiedDate": "2024-01-15T10:30:00Z"
    },
    {
      "alternateId": "KB-12346",
      "title": "Account Security Guidelines",
      "url": "https://ai.egain.cloud/s5fa/kb/ebank/content/KB-12346/Account-Security-Guidelines",
      "snippet": "Best practices for maintaining account security...",
      "relevanceScore": 0.87,
      "lastModifiedDate": "2024-01-10T14:20:00Z"
    }
  ],
  "totalCount": 2,
  "query": "How to reset password for user accounts?"
}

Operação 2: Kb-search

Usado por: Agente de Demonstração do eGain (tópico da Pesquisa do eGain)

Finalidade: pesquisa de artigo da base de dados de conhecimento com processamento de metadados aprimorado e geração automática de URL.

Configuração:

• Host de API: api.egain.cloud
• Ponto de extremidade:/search/kb
• Método: POST

Solicitação de exemplo:

{
  "q": "troubleshooting network connectivity issues",
  "baseUrl": "https://egainr21demo.egain.cloud/kb",
  "shortName": "ebank",
  "authToken": "your-bearer-token-here",
  "$attribute": "snippet",
  "$lang": "en-us",
  "$pagenum": 1,
  "$pagesize": 10,
  "Accept": "application/json",
  "Accept-language": "en-us",
  "portalId": "202200000001170"
}

Configuração do Copilot Studio:

$attribute: snippet
$lang: en-us
$pagenum: 1
$pagesize: 10
Accept: application/json
Accept-language: en-us
authToken: =System.User.AccessToken
baseUrl: https://egainr21demo.egain.cloud/kb
portalId: "202200000001170"
q: =Topic.Var1_SearchQuestion
shortName: ebank

Resposta de exemplo:

{
  "article": [
    {
      "id": "202200000021450",
      "name": "Network Troubleshooting Guide",
      "url": "https://egainr21demo.egain.cloud/kb/content/202200000021450/Network-Troubleshooting-Guide",
      "snippet": "Common network connectivity issues and their solutions...",
      "createdDate": "2022-11-11T14:21:48Z",
      "lastModifiedDate": "2023-10-02T16:46:58Z",
      "hasAttachments": false
    },
    {
      "id": "202200000019399",
      "name": "WiFi Connection Problems",
      "url": "https://egainr21demo.egain.cloud/kb/content/202200000019399/WiFi-Connection-Problems",
      "snippet": "Step-by-step guide to resolve WiFi connectivity issues...",
      "createdDate": "2022-09-28T22:24:43Z",
      "lastModifiedDate": "2025-08-07T15:22:02Z",
      "hasAttachments": true
    }
  ],
  "isSpellingCorrected": false,
  "paginationInfo": {
    "count": 15,
    "pagenum": 1,
    "pagesize": 10
  },
  "query": "troubleshooting network connectivity issues"
}

Operação 3: Generative-V3

Usado por: Ambos os agentes (tópico Generativo)

Finalidade: geração de resposta alimentada por IA com gerenciamento de citação inteligente, detecção duplicada e filtragem configurável.

Configuração:

• Agente de Demonstração do eGain: api.egain.cloud
• Assistente do Conector do eGain: api.ai.egain.cloud
• Ponto de extremidade:/generative/v3
• Método: POST

Solicitação de exemplo:

{
  "q": "What are the steps to configure a new user account with proper security settings?",
  "baseUrl": "https://egainr21demo.egain.cloud/kb",
  "shortName": "ebank",
  "minScore": 0.3,
  "maxReferences": 5,
  "authToken": "your-bearer-token-here",
  "Accept": "application/json",
  "languageCode": "en-us",
  "portalId": "202200000001170"
}

Configuração do Copilot Studio:

Accept: application/json
authToken: =System.User.AccessToken
baseUrl: https://egainr21demo.egain.cloud/kb
languageCode: en-us
portalId: 202200000001170
q: =Topic.Var1_UserQuestion
shortName: ebank
minScore: 0.3
maxReferences: 5

Resposta de exemplo:

{
  "Content": "To configure a new user account with proper security settings, follow these comprehensive steps:\n\n**1. Account Creation**\n- Create the user account in the system [1]\n- Set up initial login credentials [2]\n- Configure basic profile information [3]\n\n**2. Security Configuration**\n- Enable two-factor authentication [4]\n- Set password complexity requirements [5]\n- Configure access permissions based on role [6]\n\n**3. Verification and Testing**\n- Test login functionality [7]\n- Verify security settings are active [8]\n- Conduct security audit [9]\n\n**References:**\n1. [User Account Setup Guide](https://egainr21demo.egain.cloud/kb/ebank/content/USR-001/User-Account-Setup-Guide)\n2. [Login Credentials Management](https://egainr21demo.egain.cloud/kb/ebank/content/USR-002/Login-Credentials-Management)\n3. [Profile Configuration](https://egainr21demo.egain.cloud/kb/ebank/content/USR-003/Profile-Configuration)\n4. [Two-Factor Authentication Setup](https://egainr21demo.egain.cloud/kb/ebank/content/SEC-001/Two-Factor-Authentication-Setup)\n5. [Password Policy Configuration](https://egainr21demo.egain.cloud/kb/ebank/content/SEC-002/Password-Policy-Configuration)",
  "Sources": [
    {
      "Id": "1",
      "Name": "User Account Setup Guide",
      "Url": "https://egainr21demo.egain.cloud/kb/ebank/content/USR-001/User-Account-Setup-Guide",
      "Score": 0.95
    },
    {
      "Id": "2",
      "Name": "Login Credentials Management",
      "Url": "https://egainr21demo.egain.cloud/kb/ebank/content/USR-002/Login-Credentials-Management",
      "Score": 0.92
    },
    {
      "Id": "3",
      "Name": "Profile Configuration",
      "Url": "https://egainr21demo.egain.cloud/kb/ebank/content/USR-003/Profile-Configuration",
      "Score": 0.88
    }
  ],
  "Score": 0.92,
  "ReferenceCount": 9
}

Configuração e configuração do agente

Instalação do agente de demonstração do eGain

1. Criar conector personalizado:

   • Importar a definição OpenAPI
   • Definir host de API como api.egain.cloud
   • Configurar a autenticação com o token de portador

2. Configurar tópicos personalizados:

   • Tópico de Pesquisa do eGain: Mapear para a Kb-search operação
   • Tópico Generativo: Mapear para a Generative-V3 operação

3. Configuração de autenticação:

   • Obter o token de portador da instância de Demonstração do eGain
   • Definir nas configurações de autenticação do conector
   • Testar a conexão antes de implantar

Instalação do Assistente do Conector do eGain

1. Criar conector personalizado:

   • Importar a definição OpenAPI
   • Definir host de API como api.ai.egain.cloud
   • Configurar a autenticação com o token de portador

2. Configurar tópicos personalizados:

   • Tópico eGainSearch: Mapear para a Search-V3 operação
   • Tópico Generativo: Mapear para a Generative-V3 operação

3. Configuração de autenticação:

   • Obter o token de portador da instância do Assistente do Conector do eGain
   • Definir nas configurações de autenticação do conector
   • Testar a conexão antes de implantar

Práticas recomendadas para agentes copilot

1. Design do tópico

• Reconhecimento de Intenção Claro: Tópicos de design para identificar claramente quando usar cada operação
• Reconhecimento de Contexto: usar o contexto de conversa para determinar os parâmetros de pesquisa apropriados
• Tratamento de fallback: implementar respostas de fallback quando nenhum resultado for encontrado

2. Processamento de resposta

• Integração de citação: aproveite a geração automática de URL para respostas avançadas
• Formatação de conteúdo: use o formato de resposta estruturado para apresentação consistente
• Tratamento de erros: implementar o tratamento de erros normal para falhas de API

3. Considerações de segurança

• Gerenciamento de tokens: implementar o armazenamento e a rotação de token seguro
• Controle de Acesso: garantir controles de acesso adequados para diferentes funções de usuário
• Log de auditoria: chamadas à API de log para monitoramento de segurança

4. Otimização de desempenho

• Cache: implementar o cache apropriado para conteúdo acessado com frequência
• Limitação de taxa: respeitar os limites de taxa da API eGain
• Filtragem de resposta: use os parâmetros minScore e maxReferences efetivamente

Resolução de problemas

Problemas comuns

Erros de autenticação:

• Verificar se o token de portador é válido e não expirou
• Verificar se a configuração do host da API corresponde à instância de eGain pretendida
• Garantir o formato de token adequado nas configurações do conector

Resultados vazios:

• Verifique se as consultas de pesquisa são específicas o suficiente
• Verificar se o conteúdo existe na base de dados de conhecimento
• Examinar as configurações de minScore para respostas gerativas

Problemas de geração de URL:

• Verifique se os parâmetros baseUrl e shortName estão configurados corretamente
• Verifique se as URLs de instância do eGain estão acessíveis
• Verificar se há caracteres especiais em nomes de artigo

Etapas de depuração

1. Testar operações individuais: usar o Power Automate para testar cada operação separadamente
2. Verificar formato de resposta: verificar se a estrutura de resposta corresponde ao esquema esperado
3. Validar autenticação: verifique se os tokens estão configurados corretamente
4. Revisar logs: verificar os logs de execução do conector para obter informações detalhadas de erro

Recursos avançados

Detecção duplicada

O conector remove automaticamente citações duplicadas com base na ID de referência e combinações de nomes, garantindo listas de referência limpas em respostas gerativas.

Filtragem de Score-Based

Configure limites mínimos de pontuação e contagens máximas de referência para controlar a qualidade e o comprimento da resposta:

• minScore: filtrar citações de baixa relevância (padrão: 0,01)
• maxReferences: número limite de referências (padrão: 10)

Personalização de URL

Suporte para construção de URL personalizada usando parâmetros baseUrl e shortName:

• baseUrl: URL base da instância do eGain
• shortName: segmento de caminho de URL para acesso ao conteúdo

Suporte e manutenção

Manutenção regular

• Rotação de tokens: atualizar regularmente tokens de autenticação
• Monitoramento de API: Monitorar o uso e o desempenho da API
• Atualizações de conteúdo: manter o conteúdo da base de dados de conhecimento atualizado

Recursos de suporte

• Documentação do eGain: consulte a documentação oficial da API do eGain
• Microsoft Copilot Studio: usar os guias de solução de problemas do conector da Microsoft
• Suporte à comunidade: aproveite os recursos da comunidade do Microsoft Power Platform

Histórico de Versão

• v1.0.0: Versão inicial com operações search-V3, Kb-search e Generative-V3
• Adição de vinculação automática de citação e detecção duplicada
• Filtragem de pontuação configurável implementada e limites de referência
• Segurança aprimorada com tratamento de autenticação adequado

---

Esta documentação foi projetada para ajudar desenvolvedores e administradores a implementar e manter efetivamente o conector Egain nos agentes do Microsoft Copilot Studio.

Criando uma conexão

O conector dá suporte aos seguintes tipos de autenticação:

Default	Parâmetros para criar conexão.	Todas as regiões	Não compartilhável

Padrão

Aplicável: todas as regiões

Parâmetros para criar conexão.

Essa não é uma conexão compartilhável. Se o aplicativo de energia for compartilhado com outro usuário, outro usuário será solicitado a criar uma nova conexão explicitamente.

Nome	Tipo	Description	Obrigatório
Host da API do eGain	cadeia	Domínio da API eGain com base no tipo de instância	Verdade

Limitações

Nome	Chamadas	Período de renovação
Chamadas à API por conexão	100	60 segundos

Ações

Obter os melhores resultados de pesquisa para uma consulta de usuário	Obtenha os melhores resultados de pesquisa para uma consulta de usuário. Não é aplicável para a versão 21.x.x.x.x
Recupera respostas para um determinado escopo com fontes de dados e portal KB	O serviço recuperará um conjunto de respostas para um determinado escopo. Um escopo é uma coleção de fontes de dados ou um portal EGain KB com uma ID de perfil de personalização e linguagem específica.
Retorna o resultado da pesquisa KB para eGain R21	Ele só é válido para a instalação do eGain na versão 21.x.x.x

Obter os melhores resultados de pesquisa para uma consulta de usuário

Recupera respostas para um determinado escopo com fontes de dados e portal KB

Retorna o resultado da pesquisa KB para eGain R21