使用 TypeSpec for Microsoft 365 Copilot 建置 API 外掛程式

重要

MCP 和 API 外掛程式可在 宣告式代理程式內提供動作。 它們不是獨立的可安裝外掛程式套件:只有包含的代理程式才能存取其功能和工具。 如需套件與動作資訊清單關係的相關資訊,請參閱 外掛程式和宣告式代理程式動作。

秘訣

推薦項目: 從 Work IQ 開發工具 開始,支援專業程式碼宣告式代理程式和外掛程式案例。 請參閱 WIQD 快速入門。 工具組式指示仍然適用於需要工具組的指示的現有專案和工作流程。 在選擇工具之前,請先檢查 功能和目標體驗支援 : WIQD 不會以自訂引擎代理程式為目標。

API 外掛程式是宣告式代理程式的自訂動作,可將具有 OpenAPI 規格的 REST API 連線至 Microsoft 365 Copilot。 本指南示範如何使用 TypeSpec 和 Microsoft 365 代理程式工具組,將 API 外掛程式新增至宣告式代理程式。

先決條件

秘訣

為了獲得最佳結果,請確定您產生的 API 遵循在 如何讓 OpenAPI 文件有效地擴充 Copilot 中詳述的指導方針。

在 VS Code 中設定 API 外掛程式專案

本文假設您已有使用 Microsoft 365 代理程式工具組和 TypeSpec 建立的宣告式代理程式專案。 您可以透過在 TypeSpec 中定義其 REST API 作業,然後佈建代理程式,將 API 外掛程式新增至該專案。 下列各節將逐步解說每個作業。

  1. 如果您還沒有代理程式專案,請按照 下列建立宣告式代理程式建立專案。 當系統提示時,選取 [從 Microsoft 365 Copilot 的 TypeSpec 開始]。
  2. 在 Visual Studio Code 中開啟您的代理程式專案,然後在專案根目錄中開啟main.tsp檔案。
  3. 透過新增作業 main.tsp 來定義您的 API 外掛程式,如下列各節所示。 完成後,請按照佈建中所述佈建代理程式並 測試自訂動作。

新增 GET 作業

若要開始,請新增一個 GET 作業以列出所有張貼項目。 開啟檔案main.tsp,並在命名MyAgent空間中新增具有下列內容的新命名空間PostsAPI。

// Omitted for brevity
namespace MyAgent {
  // Omitted for brevity
  @service
  @server("https://jsonplaceholder.typicode.com")
  @actions(#{
    nameForHuman: "Posts APIs",
    descriptionForHuman: "Manage blog post items with the JSON Placeholder API.",
    descriptionForModel: "Read, create, update and delete blog post items with the JSON Placeholder API."
  })
  namespace PostsAPI {

    /**
     * List all blog post items.
     */
    @route("/posts")
    @get op listPosts(): PostItem[];

    /**
     * Structure of a blog post item.
     */
    model PostItem {
      /**
       * The ID of the user who created the post.
       */
      userId: integer;

      /**
       * The ID of the post.
       */
      @visibility(Lifecycle.Read)
      id: integer;

      /**
       * The title of the post.
       */
      title: string;

      /**
       * The body of the post.
       */
      body: string;
    }
  }
  // Omitted for brevity
}

此程式碼定義模型 PostItem 和 REST API GET /posts。

新增 GET 具有查詢參數的作業

GET上述範例中的作業不需要任何參數。 若要啟用依使用者 ID 篩選,請使用選用的查詢參數更新 GET 作業,以依使用者 ID 篩選結果。

開啟檔案, main.tsp 並以下列內容取代現有 listPosts 作業。

/**
 * List all blog post items.
  * @param userId The ID of the user who created the post. If not provided, all posts will be returned.
  */
@route("/posts")
@get op listPosts(@query userId?: integer): PostItem[];

@query userId?為了將 REST API 更新為 listPostsGET /posts?userId={userId}而新增的參數。

將調適型卡片 GET 新增至作業

將調適型卡片listPosts新增至作業會變更所產生回應中引文的呈現方式。

在 appPackage 目錄中建立名為 post-card.json 的新檔案,並新增下列內容。

{
  "type": "AdaptiveCard",
  "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
  "version": "1.5",
  "body": [
    {
      "type": "Container",
      "$data": "${$root}",
      "items": [
        {
          "type": "TextBlock",
          "text": "**${if(title, title, 'N/A')}**",
          "wrap": true
        },
        {
          "type": "TextBlock",
          "text": "${if(body, body, 'N/A')}",
          "wrap": true
        }
      ]
    }
  ],
  "actions": [
    {
      "type": "Action.OpenUrl",
      "title": "Read More",
      "url": "https://www.bing.com/search?q=https://jsonplaceholder.typicode.com/posts/${id}"
    }
  ]
}

開啟 main.tsp 檔案並將裝飾器新增至 @card 作業, listPosts 如下列程式碼片段所示。

/**
 * List all blog post items.
  * @param userId The ID of the user who created the post. If not provided, all posts will be returned.
  */
@route("/posts")
@card(#{ dataPath: "$", file: "post-card.json", properties: #{ title: "$.title" } })
@get op listPosts(@query userId?: integer): PostItem[];

新增 POST 作業

開啟 main.tsp 檔案,並在命名空間中 PostsAPI 新增下列內容。

/**
 * Create a new blog post item.
 * @param post The post item to create.
 */
@route("/posts")
@post op createPost(@body post: PostItem): PostItem;

此程式碼定義 REST API POST /posts,以建立新的部落格文章。

新增 PATCH 作業

開啟 main.tsp 檔案,並在命名空間中 PostsAPI 新增下列內容。

/**
 * Updates a blog post item.
 * @param id The ID of the post to update.
 * @param post The updated post item.
 */
@route("/posts/{id}")
@patch op updatePost(@path id: integer, @body post: PostItem): PostItem;

此程式碼定義 REST API PATCH /posts/{id},以更新現有的部落格文章。

新增 DELETE 作業

開啟 main.tsp 檔案,並在命名空間中 PostsAPI 新增下列內容。

/**
 * Deletes a blog post item.
 * @param id The ID of the post to delete.
 */
@route("/posts/{id}")
@delete op deletePost(@path id: integer): void;

此程式碼定義 REST API,此 API DELETE /posts/{id}會刪除現有的部落格文章。

佈建並測試自訂動作

使用 Microsoft 365 代理程式工具組中的 [生命週期] 窗格來佈建您的代理程式及其 API 外掛程式,然後在 Microsoft 365 Copilot 中測試自訂動作。

  1. 選取左側活動列中的 Microsoft 365 代理程式工具組 圖示。
  2. 在 [ 生命週期 ] 窗格中,選取 [佈建]。
  3. 等待佈建完成,然後在瀏覽器中開啟 https://m365.cloud.microsoft/ 。
  4. 從代理程式清單中選取您的代理程式。
  5. 使用下列提示測試代理程式,或自行嘗試。

測試 GET 作業

提示: 「列出所有部落格文章,並將它們轉譯為表格。」

宣告式代理程式根據新 GET 作業的回答螢幕擷取畫面

提示: 「列出識別碼為 1 之使用者的所有部落格文章,並將其轉譯為表格。」

宣告式代理程式的答案螢幕擷取畫面,以使用自適性卡片的 GET 作業為基礎

測試 POST 作業

提示: 「建立使用者識別碼為 1、標題為『新文章』和本文為『這是新文章』的新部落格文章。」

宣告式代理程式根據 POST 作業的回答螢幕擷取畫面

測試 PATCH 作業

提示: 「使用 ID 30 更新部落格文章,並將標題更新為『更新的標題』,並將內文更新為『更新的內文』。」

宣告式代理程式根據 PATCH 作業的答案螢幕擷取畫面

測試 DELETE 作業

提示: 「刪除識別碼為 50 的部落格文章。」

宣告式代理程式根據 DELETE 作業的回答螢幕擷取畫面

完整 main.tsp 檔案的範例

下列範例是main.tsp新增了 、 POSTPATCH、 及DELETE運算的完整檔案GET。

import "@typespec/http";
import "@typespec/openapi3";
import "@microsoft/typespec-m365-copilot";

using TypeSpec.Http;
using TypeSpec.M365.Copilot.Actions;
using TypeSpec.M365.Copilot.Agents;

@agent(
  "My Posts Agent",
  "Declarative agent focusing on blog posts management."
)

@instructions("""
  You should help users with blog posts management.
  You can read, create, update and delete blog post items.
  You can also search for blog posts by user ID.
""")

@conversationStarter(#{
  title: "List Blog Posts",
  text: "List all blog posts and render them as a table."
})

@conversationStarter(#{
  title: "Lists a user's blog posts",
  text: "List all blog posts for the user with ID 1 and render them as a table."
})

@conversationStarter(#{
  title: "Delete a blog post",
  text: "Delete the blog post with ID 50."
})

@conversationStarter(#{
  title: "Update a blog post",
  text: "Update the blog post with ID 30 and update the title to 'Updated Title' and body to 'Updated Body'."
})

@conversationStarter(#{
  title: "Create a blog post",
  text: "Create a new blog post with user ID 1, title 'New Post' and body 'This is a new post'."
})

@conversationStarter(#{
  title: "Get a blog post",
  text: "Get all the details about the blog post with ID 10."
})

namespace MyAgent {
  @service
  @server("https://jsonplaceholder.typicode.com")
  @actions(#{
    nameForHuman: "Posts APIs",
    descriptionForHuman: "Manage blog post items on JSON Placeholder APIs.",
    descriptionForModel: "Read, create, update and delete blog post items on the JSON Placeholder APIs."
  })
  namespace PostsAPI {
    /**
     * List all blog post items.
     * @param userId The ID of the user who created the post. If not provided, all posts will be returned.
     */
    @route("/posts")
    @card(#{ dataPath: "$", file: "post-card.json", properties: #{ title: "$.title" } })
    @get op listPosts(@query userId?: integer): PostItem[];

    /**
     * Get a blog post item by ID.
     */
    @route("/posts/{id}")
    @card(#{ dataPath: "$", file: "post-card.json", properties: #{ title: "$.title" } })
    @get op getPost(@path id: integer): PostItem;

    /**
     * Create a new blog post item.
     * @param post The post item to create.
     */
    @route("/posts")
    @post op createPost(@body post: PostItem): PostItem;

    /**
     * Updates a blog post item.
     * @param id The ID of the post to update.
     * @param post The updated post item.
     */
    @route("/posts/{id}")
    @patch op updatePost(@path id: integer, @body post: PostItem): PostItem;

    /**
     * Deletes a blog post item.
     * @param id The ID of the post to delete.
     */
    @route("/posts/{id}")
    @delete op deletePost(@path id: integer): void;

    model PostItem {
      /**
       * The ID of the user who created the post.
       */
      userId: integer;

      /**
       * The ID of the post.
       */
      @visibility(Lifecycle.Read)
      id: integer;

      /**
       * The title of the post.
       */
      title: string;

      /**
       * The body of the post.
       */
      body: string;
    }
  }
}