Egain (Pré-visualização)

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

Serviço	Class	Regiões
Estúdio Copiloto	Premium	Todas as regiões do Power Automatic , exceto as seguintes:      - Governo dos EUA (CCG)      - Governo dos EUA (GCC High)      - China Cloud operado pela 21Vianet      - Departamento de Defesa dos EUA (DoD)
Aplicações Lógicas	Standard	Todas as regiões do Logic Apps , exceto as seguintes:      - Regiões do Azure Government      - Regiões do Azure China      - Departamento de Defesa dos EUA (DoD)
Aplicações Power	Premium	Todas as regiões do Power Apps , exceto as seguintes:      - Governo dos EUA (CCG)      - 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 Automatic , exceto as seguintes:      - Governo dos EUA (CCG)      - Governo dos EUA (GCC High)      - China Cloud operado pela 21Vianet      - Departamento de Defesa dos EUA (DoD)

Contato
Nome	Suporte eGain
Email	support@egain.com

Metadados do conector
Editora	eGain Corporation
Sítio Web	http://egain.com/
Política de privacidade	https://www.egain.com/privacy-policies
Categorias	IA; Finanças
Fonte	marketplace
Cor da Marca	#FEF0FD

Egain - Guia de Utilização de Agentes do Copilot

Visão geral

O conector Egain foi concebido para integrar-se perfeitamente com agentes Microsoft Copilot Studio, proporcionando poderosas capacidades de gestão de conhecimento através de duas instâncias eGain distintas. Este conector permite aos agentes pesquisar bases de conhecimento, gerar respostas alimentadas por IA e fornecer citações precisas com geração automática de URLs.

Pré-requisitos

Antes de usar o conector Egain, certifique-se de que tem os seguintes pré-requisitos:

1. Requisitos da Instância eGain: Precisa de ter uma instância eGain a correr na versão Rigel ou R21.x.x ou superior.

2. Configuração da Aplicação Cliente: Uma aplicação cliente deve ser criada na sua instância eGain com as permissões apropriadas para as ações que planeia usar. A aplicação cliente deve ter:

   • Permissões de portais para operações de pesquisa em base de conhecimento
   • Permissões de IA para operações de IA generativa

   Para informações detalhadas sobre a criação e configuração de aplicações cliente, consulte a documentação da eGain Client Application.

3. Configuração do Portal de Conhecimento: Um portal de conhecimento deve estar pré-configurado na sua instância eGain para permitir a pesquisa e recuperação de conteúdos. O portal serve de base para as operações da base de conhecimento e para a gestão de conteúdos.

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

Configurações de Agentes

1. Agente de Demonstração eGain

• Anfitrião API: api.egain.cloud
• URL da instância: https://egainr21demo.egain.cloud
• Autenticação: Segurança ativada com autenticação por token portador
• Tópicos Personalizados:
  • Pesquisa eGain: Utiliza Kb-search a operação
  • Gerativo: Utiliza Generative-V3 a operação

2. Assistente de Conector eGain

• Anfitrião API: api.ai.egain.cloud
• URL da instância: https://ai.egain.cloud/s5fa
• Autenticação: Segurança ativada com autenticação por token portador
• Tópicos Personalizados:
  • Gerativo: Utiliza Generative-V3 a operação
  • eGainSearch: Utiliza Search-V3 a operação

Segurança e Autenticação

Importante: O próprio conector Egain não requer qualquer configuração de autenticação. No entanto, as APIs do eGain são seguras e suportam autenticação OAuth 2.0 genérica, que é configurada no separador Segurança dos seus agentes do Copilot Studio.

Ambas as instâncias eGain têm segurança ativada, garantindo que todas as chamadas de API são devidamente autenticadas. O conector trata automaticamente:

• Suporte OAuth 2.0: Autenticação OAuth genérica 2.0 configurada no separador de Segurança do Copilot Studio
• Autenticação de Token de Portador: Adiciona Bearer automaticamente o prefixo se não estiver presente
• Gestão de Cabeçalhos: Gerir corretamente os cabeçalhos de autorização
• Sanitização de parâmetros: Remove parâmetros de autenticação antes de encaminhar para APIs eGain
• Gestão de erros: Tratamento gracioso de falhas de autenticação

Operações e Utilização

Operação 1: Search-V3

Usado por: eGain Connector Assistant (tema eGainSearch)

Objetivo: Pesquisa avançada usando a API de pesquisa V3 do eGain com processamento de resultados melhorado e geração automática de URLs de citação.

Configuração:

• Anfitrião API: api.ai.egain.cloud
• Ponto final:/search/v3
• Método: POST

Pedido 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

Exemplo de Resposta:

{
  "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: Busca em Kb

Usado por: eGain Demo Agent (tópico de pesquisa eGain)

Objetivo: Pesquisa de artigos na base de conhecimento com processamento de metadados melhorado e geração automática de URLs.

Configuração:

• Anfitrião API: api.egain.cloud
• Ponto final:/search/kb
• Método: POST

Pedido 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

Exemplo de Resposta:

{
  "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 (Tema generativo)

Objetivo: Geração de respostas alimentada por IA com gestão inteligente de citações, deteção de duplicados e filtragem configurável.

Configuração:

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

Pedido 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

Exemplo de Resposta:

{
  "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

Configuração do Agente de Demonstração eGain

1. Criar Conector Personalizado:

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

2. Configurar Tópicos Personalizados:

   • Tópico de Pesquisa eGain: Mapeamento para Kb-search operação
   • Tema Generativo: Mapa para Generative-V3 operação

3. Configuração da Autenticação:

   • Obter token portador a partir da instância eGain Demo
   • Configurar nas definições de autenticação do conector
   • Testar a ligação antes de ser implementada

Configuração do Assistente do Conector eGain

1. Criar Conector Personalizado:

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

2. Configurar Tópicos Personalizados:

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

3. Configuração da Autenticação:

   • Obter token portador a partir da instância eGain Connector Assistant
   • Configurar nas definições de autenticação do conector
   • Testar a ligação antes de ser implementada

Melhores Práticas para Agentes Copilot

1. Design do Tópico

• Reconhecimento Claro de Intenções: Desenhar tópicos para identificar claramente quando usar cada operação
• Consciência do Contexto: Use o contexto da conversa para determinar parâmetros de pesquisa apropriados
• Gestão de Reserva: Implementar respostas de replio quando não forem encontrados resultados

2. Processamento de Respostas

• Integração de Citações: Aproveite a geração automática de URLs para respostas ricas
• Formatação do Conteúdo: Use o formato de resposta estruturada para uma apresentação consistente
• Gestão de Erros: Implementar um tratamento gracioso de erros para falhas na API

3. Considerações de Segurança

• Gestão de Tokens: Implementar armazenamento e rotação seguros de tokens
• Controlo de Acessos: Garantir controlos de acesso adequados para diferentes papéis de utilizador
• Registo de Auditoria: Chamadas de API de registo para monitorização de segurança

4. Otimização de Desempenho

• Cache: Implementar uma cache adequada para conteúdos frequentemente acedidos
• Limitação de Taxa: Respeitar os limites de taxa da API eGain
• Filtragem de Respostas: Utilize eficazmente os parâmetros minScore e maxReferences

Solução de problemas

Problemas comuns

Erros de Autenticação:

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

Resultados vazios:

• As consultas de pesquisa de verificação são suficientemente específicas
• Verifica se existe conteúdo na base de conhecimento
• Revise as definições minScore para respostas generativas

Problemas de Geração de URLs:

• Garantir que os parâmetros baseUrl e shortName estão corretamente configurados
• Verifique se os URLs das instâncias do eGain estão acessíveis
• Verifique caracteres especiais nos nomes dos artigos

Passos de Depuração

1. Teste Operações Individuais: Use o Power Automate para testar cada operação separadamente
2. Verificar o Formato da Resposta: Verificar se a estrutura da resposta corresponde ao esquema esperado
3. Validar Autenticação: Garantir que os tokens estão devidamente configurados
4. Consulte os registos: Verifique os registos de execução dos conectores para informações detalhadas sobre erros

Funcionalidades avançadas

Deteção de Duplicados

O conector remove automaticamente citações duplicadas com base nas combinações de ID de referência e nome, garantindo listas de referências limpas nas respostas generativas.

Score-Based Filtragem

Configure limiares mínimos de pontuação e contagens máximas de referências 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 personalizada de URLs usando parâmetros baseUrl e shortName:

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

Suporte e Manutenção

Manutenção Regular

• Rotação de Tokens: Atualiza regularmente os tokens de autenticação
• Monitorização de APIs: Monitorizar a utilização e o desempenho da API
• Atualizações de Conteúdo: Mantenha o conteúdo da base de conhecimento atualizado

Recursos de suporte

• Documentação do eGain: Consulte a documentação oficial da API do eGain
• Microsoft Copilot Studio: Use os guias de resolução de problemas do conector da Microsoft
• Apoio Comunitário: Aproveite os recursos comunitários da Microsoft Power Platform

Histórico de versões

• v1.0.0: Lançamento inicial com operações Search-V3, Kb-search e Generative-V3
• Adicionada ligação automática de citações e deteção de duplicados
• Implementou filtragem de pontuação configurável e limites de referência
• Segurança reforçada com o tratamento adequado da autenticação

---

Esta documentação foi concebida para ajudar programadores e administradores a implementar e manter eficazmente o conector Egain nos agentes Microsoft Copilot Studio.

A criar uma ligação

O conector suporta os seguintes tipos de autenticação:

Predefinição	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.

Esta conexão não é compartilhável. Se o aplicativo avançado for compartilhado com outro usuário, outro usuário será solicitado a criar uma nova conexão explicitamente.

Nome	Tipo	Description	Obrigatório
eGain API Host	cadeia (de caracteres)	Domínio da API eGain baseado no tipo de instância	Verdade

Limites de Limitação

Name	Chamadas	Período de Renovação
Chamadas de API por conexão	100	60 segundos

Ações

Devolve o resultado da pesquisa na base de bases para eGain R21	Só está disponível para instalação do eGain na versão 21.x.x.x
Obtenha os melhores resultados de pesquisa para uma consulta de utilizador	Obtenha os melhores resultados de pesquisa para uma consulta de utilizador. Não é aplicável à versão 21.x.x.x
Recupera respostas para um determinado âmbito com fontes de dados e Portal KB	O serviço irá recolher um conjunto de respostas para um determinado âmbito. Um scope é uma coleção de fontes de dados ou um portal eGain KB com uma linguagem específica e um ID de perfil de personalização.

Devolve o resultado da pesquisa na base de bases para eGain R21

Obtenha os melhores resultados de pesquisa para uma consulta de utilizador

Recupera respostas para um determinado âmbito com fontes de dados e Portal KB