宣告式代理程式會量身打造 Microsoft 365 Copilot,以滿足組織的特定需求。 您可以透過 API 外掛程式新增自訂動作。 針對支援的專業程式碼案例,建議使用 Work IQ 開發工具 。 這些整合可讓您的代理程式透過 API 查詢組織的資料並與之互動;它們不是技能中描述 為外掛程式功能的可重複使用的指令檔案。
本文說明代理程式架構,並提供撰寫包含 API 外掛程式之宣告式代理程式指示的最佳實務。
具有 API 外掛程式的宣告式代理程式的主要元件
呼叫 API 外掛程式的聲明式代理程式包含多個確保有效整合和功能的元件。 了解此架構將幫助您有效地設計代理。 架構包含下列元件:
- 應用程式資訊清單 - 描述應用程式的設定方式,並參照宣告式代理程式資訊清單。
- 宣告式代理程式資訊清單 - 定義代理程式的設定,包括指示、功能、交談入門和動作。 參照外掛程式資訊清單。
- 外掛程式資訊清單 - 描述外掛程式設定,包括可用的函式和 OpenAPI 規格的參考。
- OpenAPI 規格 - 提供 API 端點的詳細定義,包括路徑、參數、要求和回應格式,以及驗證。
這些檔案共同定義代理程式的行為及其與基礎 API 互動的方式。
如需有關 API 外掛程式的詳細資訊,請參閱:
外掛程式資訊清單中的函數對應
在外掛程式資訊清單中,每個函式都必須對應至 OpenAPI 規格中對應的 operationId 。 這可確保當代理程式叫用函數 (例如 createTask) 時,代理程式知道要呼叫哪個 API 端點。
下列範例顯示外掛程式資訊清單中的對應和 OpenAPI 規格中的對應函式。
"functions": [
{
"name": "createTask",
"description": "Creates a new task in the specified task list."
}
]
paths:
/me/todo/lists/{listId}/tasks:
post:
operationId: createTask
summary: Create a new task
description: Creates a new task in the specified task list.
parameters:
代理程式指示的最佳做法
編寫有效的指令對於確保具有 API 外掛程式的聲明式代理成功至關重要。 若要最佳化您的客服專員,請套用正確的功能對應,使用鏈結來啟用更豐富的互動,並反覆測試和完善客服專員的行為。
使用 API 外掛程式撰寫宣告式代理程式的指令時,請套用下列最佳實務:
- 避免模棱兩可或負面的指示。 對比或負面指令可能會帶來歧義並混淆模型。 重點是透過正面範例定義有效的用例。 如果區分有效和無效查詢很重要,請提供明確的準則和範例來定義每個查詢的預期客服專員回應。
- 使用範例 提供明確的範例來指導客服專員行為。 例如:
使用者輸入:布拉格的天氣如何? 客服專員通話: getWeather (location=“Prague”) 使用者輸入:「我明天需要雨傘嗎?」 客服專員通話:getWeather (location=user_location, forecast=“tomorrow”)
檢閱並測試指示。 在各種案例中測試指示,以驗證代理程式是否進行了正確的函數呼叫。 如果在測試中發現代理程式意外叫用函式,請修訂 OpenAPI 規格中的函式描述,並釐清代理程式指示,以改善意圖對應。
多輪交談的設計指示。 當您整合 API 外掛程式時,請設計您的指示,讓客服專員處理多輪交談。
例如,如果函數需要多個參數,除了在 OpenAPI 規格中定義所需參數之外,還要指示代理程式在進行 API 呼叫之前收集所有參數。 這可確保代理程式以邏輯順序收集所有必要的資訊。
下列範例顯示如何指示天氣代理程式進行多輪交談,以及產生的代理程式流程。
| 代理程式指示 | 代理程式流程 |
|---|---|
| 如果用戶詢問天氣: - 向用戶詢問位置。 - 向使用者詢問預測日。 - 向使用者詢問單位制。 - 僅在收集所有值時呼叫 getWeather 。 |
使用者: 「天氣怎麼樣?」 代理程式: 「你的位置在哪裡?」 使用者:「倫敦」 客服專員:「您偏好公制還是英制單位的天氣資訊?」 使用者:「公制」 客服專員:「您需要今天的天氣還是明天的天氣預報?」 使用者:「今天」 客服專員:「我今天要查看倫敦的天氣」 客服專員通話: getWeather (location=“London”, forecast=“today”, system=“Metric”) |
如需代理程式指示的一般最佳實務,請參閱 撰寫有效的指示。
在 API 外掛程式中鏈結函數呼叫
鏈結函數呼叫可讓宣告式代理程式在一個無縫流程中結合多個 API 動作。 下列各節說明常見模式,以及如何撰寫每個模式的指示。
使用輸出做為輸入參數的函數呼叫連結
使用一個 API 呼叫的結果做為另一個 API 呼叫的輸入。 當需要第一個函數的結果來執行第二個函數時,這非常有用。 這可以在各個外掛程式之間運作。
在下列範例中,具有天氣 API 和待辦事項 API 的宣告式代理程式會使用天氣預報中的資料建立待辦事項任務。
| 代理程式指示 | 代理程式流程 |
|---|---|
| 若要取得天氣,請一律使用 getWeather 動作,然後建立標題為「溫度在」的工作,並將天氣中提及的位置和溫度新增至工作標題。 |
使用者: “獲取布拉格的天氣信息” 代理程式: 呼叫 getWeather (location=“Prague”, forecast=“today”) 代理程式: 使用第一次通話中的資料建立待辦事項工作 createTask (title =“{weather output}”) |
根據一個代理程式內的交談記錄進行連結
當您使用基於對話記錄的連結時,代理程式會使用先前的回應來處理後續動作。 此方法會使用交談記錄來維護內容。
在下列範例中,代理程式會依名稱刪除待辦事項。
| 代理程式指示 | 代理程式流程 |
|---|---|
| 1. 當使用者要求列出所有待辦事項時,呼叫 getTasks 以擷取包含標題和 ID 的待辦事項清單。 2. 列出待辦事項之後,如果使用者要求刪除待辦事項,請使用回應中的識別碼來呼叫 deleteTask。 |
使用者: 「在 [工作] 資料夾中顯示所有待辦事項?」 代理程式: alls getTasks (folderId=“Tasks”) 並顯示所有具有識別碼的待辦事項。 使用者: “Delete TaskMaster Pro to-do” 代理: 使用對話記錄中的信息查找待辦事項的 ID,並通過調用 deleteTask 刪除待辦事項。 |
與 SharePoint 知識連結
鏈結 API 呼叫可讓代理程式結合知識來源和動作來設計更複雜的工作流程。
在下列範例中,代理程式從 SharePoint 擷取專案狀態資料,並在Microsoft To-Do 中建立對應的工作以進行追蹤。
| 代理程式指示 | 代理程式流程 |
|---|---|
| - 若要取得專案狀態,請使用 SharePoint 知識 ProjectDeadlines。 - 一律使用遊戲的狀態更新為每個專案建立待辦事項。 |
使用者:「可以提供所有專案狀態的最新資訊嗎?」 代理程式: 從 SharePoint 提取專案狀態資料,然後使用 createTask 為每個專案產生待辦事項工作。 |
使用程式碼解譯器進行連結
還可以鏈結 API 呼叫並整合其他功能,例如代碼解釋器。 這可讓代理程式動態處理 API 輸出,以啟用更進階的工作流程。
在下列範例中,客服專員會根據待辦事項工作中的資料建立圖表。
| 代理程式指示 | 代理程式流程 |
|---|---|
| 當使用者要求列出所有待辦事項時,請呼叫 getTasks 以擷取具有標題和 ID 的待辦事項清單,同時繪製輸出的圖表。 |
使用者: 「擷取工作中的所有工作」 代理程式: 呼叫 getTasks (folderId=“Tasks”) 並顯示所有具有識別碼的待辦事項。 代理程式: 呼叫代碼 Interpreter 根據第一個呼叫的輸出啟動圖表產生。 |
此範例也會同時執行多個動作。 這在啟動不需要多個使用者輸入的一系列相關動作時很有用。
當程式碼解譯器產生檔案 (,例如圖表影像或試算表) 時,Copilot 會自動在回應中顯示下載連結,讓使用者可以將檔案儲存在本機。 如需詳細資訊,請參閱 產生可下載的檔案。