Egain（預覽）

此連接器適用於以下產品和區域：

服務	Class	Regions
副駕駛工作室	進階	除下列區域外的所有 Power Automate 區域 ：      - 美國政府 （GCC）      - 美國政府（海灣合作委員會高中）      - 由 21Vianet 營運的中國雲      - 美國國防部 （DoD）
邏輯應用程式	標準	所有 Logic Apps 區域， 但下列區域除外：      - Azure Government 區域      - Azure 中國區域      - 美國國防部 （DoD）
Power Apps	進階	除下列區域外的所有 Power Apps 區域 ：      - 美國政府 （GCC）      - 美國政府（海灣合作委員會高中）      - 由 21Vianet 營運的中國雲      - 美國國防部 （DoD）
Power Automate（自動化服務）	進階	除下列區域外的所有 Power Automate 區域 ：      - 美國政府 （GCC）      - 美國政府（海灣合作委員會高中）      - 由 21Vianet 營運的中國雲      - 美國國防部 （DoD）

連絡人​​
名稱	eGain 支援
Email	support@egain.com

連接器中繼資料
Publisher	eGain 公司
網站	http://egain.com/
隱私策略	https://www.egain.com/privacy-policies
類別	人工智慧;財政
來源	市集
品牌顏色	#FEF0FD

Egain - 副駕駛代理使用指南

概觀

Egain 連接器設計為能無縫整合 Microsoft Copilot Studio 代理，透過兩個獨立的 eGain 實例提供強大的知識管理能力。 此連接器使客服人員能搜尋知識庫、生成 AI 驅動的回應，並透過自動 URL 生成提供準確的引用。

先決條件

在使用Egain接頭前，請確保您已具備以下先決條件：

1. eGain 實例需求：你需要有一個運行於 Rigel 或 R21.x.x 版本或更高版本的 eGain 實例。

2. 用戶端應用程式設定：必須在您的 eGain 實例中建立用戶端應用程式，並賦予您計畫使用的動作適當的權限。 客戶端應用程式應具備：

   • 知識庫搜尋作業的入口網站權限
   • 生成式 AI 操作的 AI 權限

   關於建立與配置用戶端應用程式的詳細資訊，請參閱 eGain 用戶端應用程式文件。

3. 知識入口網站設置：必須在你的 eGain 實例中預先設定知識入口網站，以啟用內容搜尋與檢索。 該入口網站是知識庫運作與內容管理的基礎。

   關於如何設置知識入口網站的資訊，請參閱 eGain 入口網站的文件。

代理配置

1. eGain 示範代理

• API 主機： api.egain.cloud
• 實例網址： https://egainr21demo.egain.cloud
• 認證：透過持有憑證認證啟用安全性
• 自訂主題：
  • eGain 搜尋：使用 Kb-search 運算
  • 生成式：使用 Generative-V3 運算

2. eGain 連接器助理

• API 主機： api.ai.egain.cloud
• 實例網址： https://ai.egain.cloud/s5fa
• 認證：透過持有憑證認證啟用安全性
• 自訂主題：
  • 生成式：使用 Generative-V3 運算
  • eGainSearch：使用運算Search-V3

安全性與認證

重要提示：Egain 連接器本身不需要任何認證設定。 不過，eGain API 是安全的，並支援通用的 OAuth 2.0 認證，該認證可在 Copilot Studio 代理的安全性標籤中設定。

兩個 eGain 實例皆啟用安全機制，確保所有 API 呼叫皆經過正確認證。 連接器自動處理：

• OAuth 2.0 支援：在 Copilot Studio Security 標籤中設定通用 OAuth 2.0 認證
• 持有人令牌認證：若不存在，自動新增 Bearer 前綴
• 標頭管理：正確管理授權標頭
• 參數淨化：在轉發至 eGain API 前移除認證參數
• 錯誤處理：優雅處理認證失敗

運作與使用

行動一：Search-V3

使用者：eGain 連接器助理（eGainSearch 主題）

目的：利用 eGain 的 V3 搜尋 API 進行進階搜尋，並加強結果處理及自動生成引用網址。

配置：

• API 主機： api.ai.egain.cloud
• 端點：/search/v3
• 方法：POST

範例請求：

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

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

範例回應：

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

操作 2：Kb-搜尋

使用者：eGain 示範代理（eGain 搜尋主題）

目的：具備強化元資料處理與自動 URL 生成的知識庫文章搜尋。

配置：

• API 主機： api.egain.cloud
• 端點：/search/kb
• 方法：POST

範例請求：

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

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

範例回應：

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

行動三：Generative-V3

使用者：兩個代理（生成主題）

目的：具備人工智慧驅動的回應生成，具備智慧引用管理、重複偵測及可配置過濾功能。

配置：

• eGain 示範代理： api.egain.cloud
• eGain 連接器助理： api.ai.egain.cloud
• 端點：/generative/v3
• 方法：POST

範例請求：

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

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

範例回應：

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

代理程式設定與設定

eGain 示範代理設定

1. 建立自訂連接器：

   • 匯入 OpenAPI 定義
   • 設定 API host 為 api.egain.cloud
   • 設定持有憑證認證

2. 設定自訂主題：

   • eGain 搜尋主題：映射到 Kb-search 操作
   • 生成主題：映射到 Generative-V3 操作

3. 認證設定：

   • 從 eGain 示範實例取得持有人代幣
   • 在連接器認證設定中設定
   • 部署前測試連線

eGain 連接器助理設定

1. 建立自訂連接器：

   • 匯入 OpenAPI 定義
   • 設定 API host 為 api.ai.egain.cloud
   • 設定持有憑證認證

2. 設定自訂主題：

   • eGainSearch 主題：映射到 Search-V3 操作
   • 生成主題：映射到 Generative-V3 操作

3. 認證設定：

   • 從 eGain Connector Assistant 實例取得持有人憑證
   • 在連接器認證設定中設定
   • 部署前測試連線

副駕駛座席的最佳實務

1. 主題設計

• 明確意圖辨識：設計主題以明確識別每項操作的使用時機
• 情境感知：利用對話情境來判斷適當的搜尋參數
• 備用處理：當未找到結果時，實作備援回應

2. 回應處理

• 引用整合：利用自動 URL 生成功能，豐富回應
• 內容格式：使用結構化回應格式以保持一致呈現
• 錯誤處理：對 API 失敗實施優雅的錯誤處理

3. 安全考量

• 代幣管理：實現安全的代幣儲存與輪替
• 存取控制：確保不同使用者角色的存取控制適當
• 審計日誌：用於安全監控的日誌 API 呼叫

4. 效能優化

• 快取：對經常存取的內容實施適當的快取
• 速率限制：尊重 eGain API 速率限制
• 回應過濾：有效使用 minScore 與 maxReferences 參數

故障排除

常見問題

認證錯誤：

• 確認持有人令牌有效且未過期
• 檢查 API 主機設定是否與預期的 eGain 實例相符
• 確保連接器設定中的令牌格式正確

空結果：

• 驗證搜尋查詢是否足夠具體
• 檢查知識庫中是否有內容
• 檢視生成式回應的 minScore 設定

網址產生問題：

• 確保 baseUrl 和 shortName 參數設定正確
• 確認 eGain 實例網址是否可存取
• 檢查條目名稱中的特殊字元

除錯步驟

1. 測試個別操作：使用 Power Automate 分別測試每個操作
2. 檢查回應格式：驗證回應結構是否符合預期架構
3. 驗證認證：確保憑證正確配置
4. 檢視日誌：請查看連接器執行日誌以獲取詳細錯誤資訊

進階功能

重複偵測

連接器會自動根據參考文獻 ID 與名稱組合移除重複引用，確保生成式回應的參考文獻清單乾淨。

Score-Based 過濾

設定最低分數閾值與最大參考數以控制回應品質與長度：

• minScore：過濾掉低相關性引用（預設值：0.01）
• maxReferences：限制參考數量（預設：10）

URL 自訂

支援使用 baseUrl 與 shortName 參數的自訂 URL 建構：

• baseUrl：你的 eGain 實例基礎網址
• shortName：用於內容存取的 URL 路徑區段

支援與維護

定期維護

• 令牌輪替：定期更新認證令牌
• API 監控：監控 API 使用與效能
• 內容更新：保持知識庫內容的更新

支援資源

• eGain 文件：請參閱 eGain 官方 API 文件
• Microsoft Copilot Studio：使用 Microsoft 連接器故障排除指南
• 社群支持：善用 Microsoft Power Platform 社群資源

版本歷程記錄

• v1.0.0：初始版本，包含 Search-V3、Kb-search 及 Generative-V3 操作
• 新增自動引用連結與重複偵測
• 實作可配置分數篩選與參考限制
• 透過適當的認證處理，提升安全性

---

本文件旨在協助開發者與管理員有效實作並維護 Microsoft Copilot Studio 代理程式中的 Egain 連接器。

正在建立連線

連接器支援以下認證類型：

預設值	建立連線的參數。	所有區域	不可共享

預設

適用：所有地區

建立連線的參數。

這不是可共用的連線。 如果 Power App 與其他使用者共用，系統會明確提示其他使用者建立新連線。

名稱	類型	Description	為必填項目
eGain API Host	字串	基於實例類型的 eGain API 網域	對

節流限制

名稱	呼叫	續約期間
每個連線的 API 呼叫	100	60 秒

動作

回傳 eGain R21 的 KB 搜尋結果	它僅在 21.x.x.x 版本中提供 eGain 安裝
為用戶查詢獲得最佳搜尋結果	為使用者查詢獲得最佳搜尋結果。 此規定不適用於 21.x.x.x 版本
透過資料來源和知識庫入口網站，取得特定範圍的答案	服務會為特定範圍擷取一組答案。 範圍是一組資料來源或 eGain 知識庫入口網站，具有特定語言與個人化設定檔 ID。

回傳 eGain R21 的 KB 搜尋結果

為用戶查詢獲得最佳搜尋結果

透過資料來源和知識庫入口網站，取得特定範圍的答案