宣告式代理程式提供由 Microsoft 365 Copilot 所提供的目標導向交談體驗。 您定義其目的、指示、知識和行動。 本指南說明如何使用 TypeSpec 和 Microsoft 365 Agents Toolkit 建置宣告式代理程式。
注意
您在本教學課程中建置的代理程式以授權的 Microsoft 365 Copilot 使用者為目標。 您也可以為功能有限的 Microsoft 365 Copilot Chat 使用者建置代理程式。 如需詳細資料,請參閱 Microsoft 365 Copilot 開發人員授權。
秘訣
推薦項目: 從 Work IQ 開發工具 開始,支援專業程式碼宣告式代理程式和外掛程式案例。 請參閱 WIQD 快速入門。 工具組式指示仍然適用於需要工具組的指示的現有專案和工作流程。 在選擇工具之前,請先檢查 功能和目標體驗支援 : WIQD 不會以自訂引擎代理程式為目標。
注意
Word 和 PowerPoint 現在支援以 Microsoft 365 Copilot 為基礎的宣告式代理程式。
先決條件
- Microsoft 365 租用戶,您可以在其中上傳自訂應用程式。 如果未啟用自訂應用程式上傳,則佈建失敗。 若要啟用自訂應用程式上傳,請參閱 Microsoft 365 代理程式工具組需求。 如需開發環境和授權選項,請參閱 Copilot 開發環境。
若要完成本文所述的步驟,您需要下列資源:
注意
本文中的螢幕擷取畫面和使用者介面參考使用 Microsoft 365 Agents Toolkit 的發行版本。 發行前版本可能與顯示的使用者介面不同。
請熟悉下列適用於 Microsoft 365 Copilot 的宣告式代理程式標準與指導方針:
- Teams 市集驗證指導方針中所述的合規性、效能、安全性和使用者體驗標準。
建立宣告式代理程式
首先建立基本的宣告式代理程式。
開啟 Visual Studio Code。
選取 [Microsoft 365 代理程式工具組 > ]、[建立新的代理程式/應用程式]。
選取 宣告式代理程式。
選取 [從 Microsoft 365 Copilot 的 TypeSpec 開始] 以建立基本的宣告式代理程式。
選取 [預設資料夾] ,將專案根資料夾儲存在預設位置。
輸入
My Agent應用程式名稱,然後按 Enter。在開啟的新 Visual Studio Code 視窗中,選取 [Microsoft 365 代理程式工具組]。 在 [ 生命週期 ] 窗格中,選取 [佈建]。
測試代理程式
移至 Copilot 應用程式。https://m365.cloud.microsoft/chat
在 [新增 Chat] 按鈕旁邊,選取 [交談選單] 圖示。
選取宣告式代理程式 [我的代理程式]。
輸入一個問題,讓宣告式代理程式查看它的實際運作方式。
新增指示
指令會變更客服專員的行為方式。
開啟
main.tsp檔案,並使用下列程式碼取代@instructions裝飾器。@instructions(""" You are an expert at creating poems. Every time a user asks a question, you **must** turn the answer into a poem. The poem **must** not use the quote markdown and use regular text. """)佈建程式會將此裝飾器
instructions的內容插入代理程式資訊清單中的屬性。 如需詳細資訊,請參閱 宣告式代理程式資訊清單物件。在 [Agents Toolkit] 的 [生命週期] 窗格中選取 [佈建]。
宣告式代理程式會在您重新載入頁面後使用您更新的指示。
新增交談入門
交談入門是 Copilot 向使用者顯示的提示,說明他們如何開始使用宣告式代理程式。
開啟檔案,
main.tsp並以下列內容取代已註解的@conversationStarter裝飾器:@conversationStarter(#{ title: "Getting started", text: "How can I get started with Agents Toolkit?" }) @conversationStarter(#{ title: "Getting Help", text: "How can I get help with Agents Toolkit?" })如需詳細資訊,請參閱 交談入門物件。
在 [Agents Toolkit] 的 [生命週期] 窗格中選取 [佈建]。
重新整理頁面之後,更新的交談入門程式將可在宣告式代理程式中使用。
新增網頁內容
Web 搜尋功能可讓代理程式使用 Bing 中的搜尋索引來回應使用者提示。
開啟
main.tsp檔案,並在命名空間中MyAgent新增WebSearch具有下列內容的功能。namespace MyAgent { op webSearch is AgentCapabilities.WebSearch<Sites = [ { url: "https://learn.microsoft.com", }, ]>; }如需詳細資訊,請參閱 Web 搜尋物件。
注意
如果您未指定
Sites陣列,代理程式可以存取所有網頁內容。在 [Agents Toolkit] 的 [生命週期] 窗格中選取 [佈建]。
宣告式代理程式可以存取 Web 內容,以在您重新載入頁面後產生其答案。
新增 OneDrive 和 SharePoint 內容
SharePoint 功能可讓代理程式將 OneDrive 和 SharePoint 內容當做知識使用。
開啟
main.tsp檔案,並在OneDriveAndSharePoint命名空間中使用MyAgent下列值新增此功能,並以https://contoso.sharepoint.com/sites/ProductSupportMicrosoft 365 組織中的 SharePoint 網站 URL 取代。namespace MyAgent { // Omitted for brevity op od_sp is AgentCapabilities.OneDriveAndSharePoint<ItemsByUrl = [ { url: "https://contoso.sharepoint.com/sites/ProductSupport" } ]>; // Omitted for brevity }如需詳細資訊,請參閱 OneDrive 和 SharePoint 物件。
注意
- URL 應為網站、文件庫、資料夾或檔案) (SharePoint 項目的完整路徑。 您可以在 SharePoint 中使用 [複製直接連結] 選項來取得完整路徑或檔案和資料夾。 以滑鼠右鍵按一下檔案或資料夾,然後選取 [詳細資料]。 瀏覽至 [路徑] ,然後選取複製圖示。
- 如果您未指定
ItemsByUrl陣列 (或替代ItemsBySharePointIds陣列) ,代理程式可以存取登入使用者可以存取之 Microsoft 365 組織中的所有 OneDrive 和 SharePoint 內容。
在 [Agents Toolkit] 的 [生命週期] 窗格中選取 [佈建]。
宣告式代理程式可以存取 OneDrive 和 SharePoint 內容,以便在您重新載入頁面之後產生其解答。
新增 Teams 訊息
Teams 訊息功能可讓專員將 Teams 頻道、團隊和會議聊天當做知識來使用。
開啟
main.tsp檔案,並在TeamsMessages命名空間中使用MyAgent下列值新增功能,並以https://teams.microsoft.com/l/team/...貴組織的 Teams 頻道或小組 URL 取代。namespace MyAgent { // Omitted for brevity op teamsMessages is AgentCapabilities.TeamsMessages<TeamsMessagesByUrl = [ { url: "https://teams.microsoft.com/l/team/...", } ]>; // Omitted for brevity }如需詳細資訊,請參閱 Microsoft Teams 訊息物件。
注意
- 屬性中的
urlURL 必須是指向 Teams 聊天、小組或會議聊天的正確格式連結。 - 如果您未指定
TeamsMessagesByUrl陣列,代理程式可以存取已驗證使用者可以存取的所有 Microsoft 365 組織中的 Teams 頻道、團隊、會議、一對一聊天和群組聊天。
- 屬性中的
在 [Agents Toolkit] 的 [生命週期] 窗格中選取 [佈建]。
宣告式代理程式可以存取 Teams 資料,以在您重新載入頁面後產生其解答。
新增人員知識
人員功能可讓您將代理程式限定為回答有關組織中個人的問題。
開啟
main.tsp檔案,並在命名空間中MyAgent新增People具有下列內容的功能。namespace MyAgent { // Omitted for brevity op people is AgentCapabilities.People; // Omitted for brevity }如需詳細資訊,請參閱 People 物件。
在 [Agents Toolkit] 的 [生命週期] 窗格中選取 [佈建]。
在您重新載入頁面之後,宣告式代理程式可以存取人員知識。
新增電子郵件知識
電子郵件功能可讓您將代理程式範圍限定為使用來自使用者信箱或共用信箱的電子郵件作為知識來源。
開啟
main.tsp檔案,並在命名空間中MyAgent新增Email具有下列內容的功能。namespace MyAgent { // Omitted for brevity op email is AgentCapabilities.Email<Folders = [ { folder_id: "Inbox", } ]>; // Omitted for brevity }如需詳細資訊,請參閱 Email 物件。
注意
- 此範例會存取代理程式信箱的使用者。 若要改為存取共用信箱,請將選擇性
shared_mailbox屬性集新增至共用信箱的電子郵件地址。 - 陣列會
Folders將信箱存取限制為特定資料夾。 若要存取整個信箱,請省略陣folders列。
- 此範例會存取代理程式信箱的使用者。 若要改為存取共用信箱,請將選擇性
在 [Agents Toolkit] 的 [生命週期] 窗格中選取 [佈建]。
在您重新載入頁面之後,宣告式代理程式可以存取電子郵件知識。
新增影像產生器
圖像生成器功能使代理能夠根據用戶提示生成圖像。
開啟
main.tsp檔案,並在命名空間中MyAgent新增GraphicArt具有下列內容的功能。namespace MyAgent { // Omitted for brevity op graphicArt is AgentCapabilities.GraphicArt; // Omitted for brevity }如需詳細資訊,請參閱 圖形藝術物件。
在 [Agents Toolkit] 的 [生命週期] 窗格中選取 [佈建]。
宣告式代理程式可以在您重新載入頁面後產生影像。
新增程式碼解譯器
程式碼解釋器功能是一種高級工具,旨在透過 Python 程式碼解決複雜的任務。
開啟
main.tsp檔案,並在命名空間中MyAgent新增CodeInterpreter具有下列內容的功能。namespace MyAgent { // Omitted for brevity op codeInterpreter is AgentCapabilities.CodeInterpreter; // Omitted for brevity }如需詳細資訊,請參閱 程式碼解譯器物件。
在 [Agents Toolkit] 的 [生命週期] 窗格中選取 [佈建]。
在您重新載入頁面之後,宣告式代理程式具有程式碼解譯器功能。
新增 Copilot 連接器內容
將 Copilot 連接器擷取的項目新增至代理程式可用的知識。
開啟
main.tsp檔案,並在GraphConnectors命名空間中使用MyAgent下列值新增此功能,並以policieslocalMicrosoft 365 組織中的有效 Copilot 連接器識別碼取代。 如需尋找 Copilot 連接器識別碼的詳細資訊,請參閱 擷取宣告式代理程式資訊清單的功能識別碼。namespace MyAgent { // Omitted for brevity op copilotConnectors is AgentCapabilities.GraphConnectors<Connections = [ { connectionId: "policieslocal", } ]>; // Omitted for brevity }如需詳細資訊,請參閱 Copilot 連接器物件。
注意
如果您未指定陣列,
Connections代理程式會從登入使用者可以存取的 Microsoft 365 組織中的所有 Copilot 連接器取得內容。在 [Agents Toolkit] 的 [生命週期] 窗格中選取 [佈建]。
宣告式代理程式可以存取 Copilot 連接器內容,以在您重新載入頁面之後產生其答案。
已完成
您已完成 Microsoft 365 Copilot 的宣告式代理程式指南。 現在您已熟悉使用 TypeSpec 建置宣告式代理程式,您可以在下列文章中深入瞭解。
- 了解如何為您的客服專員 撰寫有效的說明 。
- 使用開發人員模式測試您的代理程式,以驗證 Copilot 協調器是否及如何選取您的知識來源以用於回應指定的提示。 如需詳細資訊,請參閱 使用 開發人員模式測試和偵錯 Microsoft 365 Agents Toolkit 中的代理程式。
- 取得 常見問題的解答。
- 瞭解建置宣告式代理程式的其他方法: Agent Builder 中的無程式碼,或 Copilot Studio 中的低程式碼。