使用适用于智能 智能 Microsoft 365 Copilot 副驾驶® 副驾驶®的 TypeSpec 生成 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 Agents Toolkit 和 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?添加用于listPosts将 REST API GET /posts?userId={userId}更新为 的参数。

将自适应卡GET添加到操作

将自适应卡listPosts添加到操作会更改生成的响应中引文的呈现方式。

在 appPackage 目录中创建一个名为 post-卡.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 DELETE /posts/{id},它将删除现有博客文章。

预配和测试自定义操作

使用 Microsoft 365 代理工具包中的“生命周期”窗格预配代理及其 API 插件,然后在智能 智能 Microsoft 365 Copilot 副驾驶® 副驾驶®中测试自定义操作。

  1. 选择左侧“活动栏”中的“ Microsoft 365 代理工具包 ”图标。
  2. 在 “生命周期 ”窗格中,选择 “预配”。
  3. 等待预配完成,然后在浏览器中打开 https://m365.cloud.microsoft/ 。
  4. 从代理列表中选择代理。
  5. 使用以下提示测试代理,或尝试自己的提示。

测试 GET 操作

提示: “列出所有博客文章并将它们呈现为表格。”

基于新 GET 操作的声明式代理的答案的屏幕截图

提示: “列出 ID 为 1 的用户的所有博客文章,并将其呈现为表格。”

基于自适应卡的 GET 操作的声明式代理的答案的屏幕截图

测试 POST 操作

提示: “创建一篇用户 ID 为 1、标题为'新帖子'、正文为'这是一篇新文章'的新博客文章。”

声明性代理基于 POST 操作的回答的屏幕截图

测试 PATCH 操作

提示: “使用 ID 30 更新博客文章,并将标题更新为'更新后的标题',将正文更新为'更新的正文'。”

基于 PATCH 操作的声明性代理的答案的屏幕截图

测试 DELETE 操作

提示: “删除 ID 为 50 的博客文章。”

声明式代理基于 DELETE 操作的答案的屏幕截图

完整 main.tsp 文件的示例

下面是添加了 、 POST、 PATCH和 operations 的完整DELETE文件GET的main.tsp示例。

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;
    }
  }
}