使用 Microsoft 365 Agents Toolkit 和 TypeSpec 建立宣告式代理程式

宣告式代理程式提供由 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 Agents Toolkit 的發行版本。 發行前版本可能與顯示的使用者介面不同。

請熟悉下列適用於 Microsoft 365 Copilot 的宣告式代理程式標準與指導方針:

建立宣告式代理程式

首先建立基本的宣告式代理程式。

  1. 開啟 Visual Studio Code。

  2. 選取 [Microsoft 365 代理程式工具組 > ]、[建立新的代理程式/應用程式]。

    Microsoft 365 代理程式工具組提要欄位中 [建立新應用程式] 按鈕的螢幕擷取畫面

  3. 選取 宣告式代理程式。

    已選取代理程式的 [新增專案] 選項螢幕擷取畫面

  4. 選取 [從 Microsoft 365 Copilot 的 TypeSpec 開始] 以建立基本的宣告式代理程式。

  5. 選取 [預設資料夾] ,將專案根資料夾儲存在預設位置。

  6. 輸入My Agent應用程式名稱,然後按 Enter。

  7. 在開啟的新 Visual Studio Code 視窗中,選取 [Microsoft 365 代理程式工具組]。 在 [ 生命週期 ] 窗格中,選取 [佈建]。

    Microsoft 365 Agents Toolkit 的 [生命週期] 窗格中 [佈建] 選項的螢幕擷取畫面

測試代理程式

  1. 移至 Copilot 應用程式。https://m365.cloud.microsoft/chat

  2. 在 [新增 Chat] 按鈕旁邊,選取 [交談選單] 圖示。

  3. 選取宣告式代理程式 [我的代理程式]。

    Copilot 中宣告式代理程式的螢幕擷取畫面

  4. 輸入一個問題,讓宣告式代理程式查看它的實際運作方式。

新增指示

指令會變更客服專員的行為方式。

  1. 開啟 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 的內容插入代理程式資訊清單中的屬性。 如需詳細資訊,請參閱 宣告式代理程式資訊清單物件。

  2. 在 [Agents Toolkit] 的 [生命週期] 窗格中選取 [佈建]。

宣告式代理程式會在您重新載入頁面後使用您更新的指示。

宣告式代理程式根據更新的指示所提供的答案螢幕擷取畫面

新增交談入門

交談入門是 Copilot 向使用者顯示的提示,說明他們如何開始使用宣告式代理程式。

  1. 開啟檔案, 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?"
    })
    

    如需詳細資訊,請參閱 交談入門物件。

  2. 在 [Agents Toolkit] 的 [生命週期] 窗格中選取 [佈建]。

重新整理頁面之後,更新的交談入門程式將可在宣告式代理程式中使用。

螢幕擷取畫面,顯示來自 Microsoft 365 Copilot 中宣告式代理程式的交談開場白

新增網頁內容

Web 搜尋功能可讓代理程式使用 Bing 中的搜尋索引來回應使用者提示。

  1. 開啟main.tsp檔案,並在命名空間中MyAgent新增WebSearch具有下列內容的功能。

    namespace MyAgent {
      op webSearch is AgentCapabilities.WebSearch<Sites = [
        {
          url: "https://learn.microsoft.com",
        },
      ]>;
    }
    

    如需詳細資訊,請參閱 Web 搜尋物件。

    注意

    如果您未指定 Sites 陣列,代理程式可以存取所有網頁內容。

  2. 在 [Agents Toolkit] 的 [生命週期] 窗格中選取 [佈建]。

宣告式代理程式可以存取 Web 內容,以在您重新載入頁面後產生其答案。

顯示來自包含 Web 內容之宣告式代理程式回應的螢幕擷取畫面

新增 OneDrive 和 SharePoint 內容

SharePoint 功能可讓代理程式將 OneDrive 和 SharePoint 內容當做知識使用。

  1. 開啟 main.tsp 檔案,並在 OneDriveAndSharePoint 命名空間中使用 MyAgent 下列值新增此功能,並以 https://contoso.sharepoint.com/sites/ProductSupport Microsoft 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 內容。
  2. 在 [Agents Toolkit] 的 [生命週期] 窗格中選取 [佈建]。

宣告式代理程式可以存取 OneDrive 和 SharePoint 內容,以便在您重新載入頁面之後產生其解答。

螢幕擷取畫面,顯示來自包含 SharePoint 和 OneDrive 內容之宣告式代理程式的回應

新增 Teams 訊息

Teams 訊息功能可讓專員將 Teams 頻道、團隊和會議聊天當做知識來使用。

  1. 開啟 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 訊息物件。

    注意

    • 屬性中的 url URL 必須是指向 Teams 聊天、小組或會議聊天的正確格式連結。
    • 如果您未指定 TeamsMessagesByUrl 陣列,代理程式可以存取已驗證使用者可以存取的所有 Microsoft 365 組織中的 Teams 頻道、團隊、會議、一對一聊天和群組聊天。
  2. 在 [Agents Toolkit] 的 [生命週期] 窗格中選取 [佈建]。

宣告式代理程式可以存取 Teams 資料,以在您重新載入頁面後產生其解答。

顯示包含 Teams 內容之宣告式代理程式回應的螢幕擷取畫面

新增人員知識

人員功能可讓您將代理程式限定為回答有關組織中個人的問題。

  1. 開啟main.tsp檔案,並在命名空間中MyAgent新增People具有下列內容的功能。

    namespace MyAgent {
      // Omitted for brevity
      op people is AgentCapabilities.People;
      // Omitted for brevity
    }
    

    如需詳細資訊,請參閱 People 物件。

  2. 在 [Agents Toolkit] 的 [生命週期] 窗格中選取 [佈建]。

在您重新載入頁面之後,宣告式代理程式可以存取人員知識。

顯示來自包含人員知識的宣告式代理程式回應的螢幕擷取畫面

新增電子郵件知識

電子郵件功能可讓您將代理程式範圍限定為使用來自使用者信箱或共用信箱的電子郵件作為知識來源。

  1. 開啟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 列。
  2. 在 [Agents Toolkit] 的 [生命週期] 窗格中選取 [佈建]。

在您重新載入頁面之後,宣告式代理程式可以存取電子郵件知識。

螢幕擷取畫面,顯示來自包含電子郵件知識的宣告式代理程式回應

新增影像產生器

圖像生成器功能使代理能夠根據用戶提示生成圖像。

  1. 開啟main.tsp檔案,並在命名空間中MyAgent新增GraphicArt具有下列內容的功能。

    namespace MyAgent {
      // Omitted for brevity
      op graphicArt is AgentCapabilities.GraphicArt;
      // Omitted for brevity
    }
    

    如需詳細資訊,請參閱 圖形藝術物件。

  2. 在 [Agents Toolkit] 的 [生命週期] 窗格中選取 [佈建]。

宣告式代理程式可以在您重新載入頁面後產生影像。

顯示來自包含產生之圖形藝術之宣告式代理程式回應的螢幕擷取畫面

新增程式碼解譯器

程式碼解釋器功能是一種高級工具,旨在透過 Python 程式碼解決複雜的任務。

  1. 開啟main.tsp檔案,並在命名空間中MyAgent新增CodeInterpreter具有下列內容的功能。

    namespace MyAgent {
      // Omitted for brevity
      op codeInterpreter is AgentCapabilities.CodeInterpreter;
      // Omitted for brevity
    }
    

    如需詳細資訊,請參閱 程式碼解譯器物件。

  2. 在 [Agents Toolkit] 的 [生命週期] 窗格中選取 [佈建]。

在您重新載入頁面之後,宣告式代理程式具有程式碼解譯器功能。

顯示來自包含產生圖形之宣告式代理程式回應的螢幕擷取畫面

螢幕擷取畫面,顯示用來產生所要求圖形的 Python 程式碼

新增 Copilot 連接器內容

將 Copilot 連接器擷取的項目新增至代理程式可用的知識。

  1. 開啟 main.tsp 檔案,並在 GraphConnectors 命名空間中使用 MyAgent 下列值新增此功能,並以 policieslocal Microsoft 365 組織中的有效 Copilot 連接器識別碼取代。 如需尋找 Copilot 連接器識別碼的詳細資訊,請參閱 擷取宣告式代理程式資訊清單的功能識別碼。

    namespace MyAgent {
      // Omitted for brevity
      op copilotConnectors is AgentCapabilities.GraphConnectors<Connections = [
        {
          connectionId: "policieslocal",
        }
      ]>;
      // Omitted for brevity
    }
    

    如需詳細資訊,請參閱 Copilot 連接器物件。

    注意

    如果您未指定陣列, Connections 代理程式會從登入使用者可以存取的 Microsoft 365 組織中的所有 Copilot 連接器取得內容。

  2. 在 [Agents Toolkit] 的 [生命週期] 窗格中選取 [佈建]。

宣告式代理程式可以存取 Copilot 連接器內容,以在您重新載入頁面之後產生其答案。

顯示來自包含 Copilot 連接器內容之宣告式代理程式回應的螢幕擷取畫面

已完成

您已完成 Microsoft 365 Copilot 的宣告式代理程式指南。 現在您已熟悉使用 TypeSpec 建置宣告式代理程式,您可以在下列文章中深入瞭解。

後續步驟