重要
MCP 和 API 插件在 声明性代理中提供操作。 它们不是独立的可安装插件包:只有包含的代理才能访问它们的功能和工具。 有关包和操作清单关系的信息,请参阅 插件和声明性代理操作。
提示
受到推崇的: 从 Work IQ 开发工具 开始,用于受支持的专业代码声明代理和插件方案。 请参阅 WIQD 快速入门。 基于工具包的说明仍然可用于需要它们的现有项目和工作流。 在选择工具之前,请检查 功能和目标体验支持 : WIQD 不面向自定义引擎代理。
API 插件是声明性代理的自定义操作,用于将具有 OpenAPI 规范的 REST API 连接到智能 智能 Microsoft 365 Copilot 副驾驶® 副驾驶®。 本指南演示如何使用 TypeSpec 和 Microsoft 365 代理工具包将 API 插件添加到声明性代理。
先决条件
- Copilot 可扩展性选项的要求中指定的要求
- 本演练 (现有 REST API 使用 JSON 占位符 API)
- Visual Studio Code
- Microsoft 365 代理工具包
- 使用 Microsoft 365 智能体工具包和智能 智能 智能 Microsoft 365 Copilot 副驾驶® 副驾驶® TypeSpec 创建的代理
提示
为获得最佳结果,请确保生成的 API 遵循以下文章中详述的准则: 如何使 OpenAPI 文档有效地扩展 Copilot。
在 VS Code 中设置 API 插件项目
本文假定你已有使用 Microsoft 365 Agents Toolkit 和 TypeSpec 创建的声明性代理项目。 可通过在 TypeSpec 中定义其 REST API 操作,然后预配代理来向该项目添加 API 插件。 以下部分将介绍每个操作。
- 如果还没有代理项目,请按照创建 声明式代理创建一个。 出现提示时,选择“开始使用适用于智能 智能 Microsoft 365 Copilot 副驾驶® 副驾驶®的 TypeSpec)。
- 在 Visual Studio Code 中打开代理项目,然后在项目根目录中打开
main.tsp文件。 - 通过向以下部分
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 副驾驶® 副驾驶®中测试自定义操作。
- 选择左侧“活动栏”中的“ Microsoft 365 代理工具包 ”图标。
- 在 “生命周期 ”窗格中,选择 “预配”。
- 等待预配完成,然后在浏览器中打开 https://m365.cloud.microsoft/ 。
- 从代理列表中选择代理。
- 使用以下提示测试代理,或尝试自己的提示。
测试 GET 操作
提示: “列出所有博客文章并将它们呈现为表格。”
提示: “列出 ID 为 1 的用户的所有博客文章,并将其呈现为表格。”
测试 POST 操作
提示: “创建一篇用户 ID 为 1、标题为'新帖子'、正文为'这是一篇新文章'的新博客文章。”
测试 PATCH 操作
提示: “使用 ID 30 更新博客文章,并将标题更新为'更新后的标题',将正文更新为'更新的正文'。”
测试 DELETE 操作
提示: “删除 ID 为 50 的博客文章。”
完整 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;
}
}
}