声明式代理提供由智能 智能 Microsoft 365 Copilot 副驾驶® 副驾驶® 支持的目标导向对话体验。 定义其目的、说明、知识和操作。 本指南演示如何使用 TypeSpec 和 Microsoft 365 Agents Toolkit 生成声明性代理。
注意
本教程中生成的代理面向获得许可的智能 智能 Microsoft 365 Copilot 副驾驶® 副驾驶®用户。 还可以使用有限的功能为 智能 Microsoft 365 Copilot 副驾驶® 对话助手用户生成代理。 有关详细信息,请参阅 智能 智能 Microsoft 365 Copilot 副驾驶® 副驾驶®开发人员许可证。
提示
受到推崇的: 从 Work IQ 开发工具 开始,用于受支持的专业代码声明代理和插件方案。 请参阅 WIQD 快速入门。 基于工具包的说明仍然可用于需要它们的现有项目和工作流。 在选择工具之前,请检查 功能和目标体验支持 : WIQD 不面向自定义引擎代理。
注意
Word 和 PowerPoint 现在支持基于智能 智能 Microsoft 365 Copilot 副驾驶® 副驾驶®的声明性代理。
先决条件
- 可在其中上传自定义应用的 Microsoft 365 租户。 如果未启用自定义应用上传,则预配失败。 若要启用自定义应用上传,请参阅 Microsoft 365 Agents Toolkit 要求。 有关开发环境和许可选项,请参阅 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
在“新建对话助手”按钮旁边,选择对话抽屉图标。
选择声明性代理 My Agent。
输入一个问题,供声明式代理查看其操作效果。
添加说明
指令可更改代理的行为方式。
打开该
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 内容
Web 搜索功能使代理能够使用必应中的搜索索引来响应用户提示。
打开该
main.tsp文件,并在命名空间中MyAgent添加WebSearch包含以下内容的功能。namespace MyAgent { op webSearch is AgentCapabilities.WebSearch<Sites = [ { url: "https://learn.microsoft.com", }, ]>; }有关详细信息,请参阅 Web 搜索对象。
注意
如果未指定
Sites数组,代理可以访问所有 Web 内容。在 Agents Toolkit 的生命周期窗格中选择预配。
声明性代理可以访问 Web 内容,以便在您重新加载页面后生成其答案。
添加 OneDrive 和 SharePoint 内容
SharePoint 功能使代理能够将 OneDrive 和 SharePoint 内容用作知识。
打开
main.tsp文件,并在命名空间中使用MyAgent以下值添加OneDriveAndSharePoint功能,替换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 内容。
在 Agents Toolkit 的生命周期窗格中选择预配。
声明性代理有权访问 OneDrive 和 SharePoint 内容,以便在你重新加载页面后生成其答案。
添加 Teams 消息
Teams 消息功能 使代理能够将 Teams 频道、团队和会议聊天用作知识。
打开该
main.tsp文件,并在命名空间中使用MyAgent以下值添加TeamsMessages功能,替换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该文件,并在命名空间中使用MyAgent以下值添加GraphConnectors功能,替换policieslocal为 Microsoft 365 组织中的有效 Copilot 连接器 ID。 有关查找 Copilot 连接器 ID 的详细信息,请参阅 检索声明性代理清单的功能 ID。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 中测试和调试代理。
- 获取 常见问题的解答。
- 了解构建声明式代理的其他方法:代理生成器中的无代码或 Copilot Studio 中的低代码。