使用 Microsoft 365 代理工具包和 TypeSpec 创建声明性代理

声明性代理是智能 Microsoft 365 Copilot 副驾驶®的自定义版本，允许用户通过声明特定的说明、作和知识来创建个性化体验。 本指南演示如何使用 TypeSpec 和 Microsoft 365 代理工具包生成声明性代理。

先决条件

在开始之前，请确保智能 Microsoft 365 Copilot 副驾驶®可供组织使用。

以下选项可用于开发环境：

• 具有 Copilot (的沙盒Microsoft 365 组织通过 TAP 成员资格) 以有限预览版提供。
• 具有智能 Microsoft 365 Copilot 副驾驶®许可证的合格Microsoft 365 或Office 365生产环境。

需要以下资源才能完成本文中所述的步骤：

• Visual Studio Code
• Microsoft 365 代理工具包Visual Studio Code扩展

应熟悉智能 Microsoft 365 Copilot 副驾驶®声明性代理的以下标准和准则：

• Teams 应用商店验证指南中所述的合规性、性能、安全性和用户体验标准。

创建声明性代理

首先创建基本声明性代理。

1. 打开 Visual Studio Code。

2. 选择 “Microsoft 365 代理工具包 > 创建新代理/应用”。

   

3. 选择“ 声明性代理”。

   

4. 为智能 Microsoft 365 Copilot 副驾驶®选择“使用 TypeSpec 开始”以创建基本声明性代理。

5. 选择“ 默认文件夹 ”，将项目根文件夹存储在默认位置。

6. 输入 My Agent 作为 应用程序名称 ，然后按 Enter。

7. 在打开的新Visual Studio Code窗口中，选择“Microsoft 365 代理工具包”。 在“ 生命周期 ”窗格中，选择“ 预配”。

   

测试代理

1. 使用 URL https://m365.cloud.microsoft/chat导航到 Copilot 应用程序。

2. 在“ 新建聊天 ”按钮旁边，选择对话抽屉图标。

3. 选择声明性代理 “我的代理”。

   

4. 输入声明性代理的问题，以查看其作情况。

添加说明

说明更改代理的行为方式。

1. 打开 文件， main.tsp 并将 @instructions 修饰器替换为以下内容。

   @instructions("""
     You are a declarative agent and were created with Team Toolkit. 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 代理清单中的 属性中。 有关详细信息，请参阅 声明性代理清单对象。

1. 在 Microsoft 365 代理工具包的“生命周期”窗格中选择“预配”。

重新加载页面后，声明性代理将使用更新的说明。

添加对话初学者

对话启动器是向用户显示的提示，用于演示如何开始使用声明性代理。

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?"
   })
   

有关详细信息，请参阅 Conversation starters 对象。

1. 在 Microsoft 365 代理工具包的“生命周期”窗格中选择“预配”。

刷新页面后，更新的聊天启动器将在声明性代理中提供。

添加 Web 内容

Web 搜索功能使代理能够使用必应中的搜索索引来响应用户提示。

1. 打开 文件，main.tspWebSearch并在命名空间中添加MyAgent包含以下内容的 功能。

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

   有关详细信息，请参阅 Web 搜索对象。

   注意

   不指定 Sites 数组会导致代理可以使用所有 Web 内容。

2. 在 Microsoft 365 代理工具包的“生命周期”窗格中选择“预配”。

声明性代理有权访问 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. 在 Microsoft 365 代理工具包的“生命周期”窗格中选择“预配”。

声明性代理有权访问 OneDrive 和 SharePoint 内容，以在重新加载页面后生成其答案。

添加 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<Urls = [
       {
         url: "https://teams.microsoft.com/l/team/...",
       }
     ]>;
     // Omitted for brevity
   }
   

   有关详细信息，请参阅 Microsoft Teams 消息对象。

   注意

   • 属性中的 url URL 必须是指向 Teams 聊天、团队或会议聊天的格式正确的链接。
   • 如果不指定 Urls 数组，则会导致 Microsoft 365 组织中可供登录用户使用的所有 Teams 频道、团队、会议、1：1 聊天和群组聊天可供代理使用。

2. 在 Microsoft 365 代理工具包的“生命周期”窗格中选择“预配”。

声明性代理有权访问 Teams 数据，以在重新加载页面后生成其答案。

添加人员知识

借助) 人员功能 ，你可以将代理的范围限定为回答有关组织中个人的问题。

1. 打开 文件，main.tspPeople并在命名空间中添加MyAgent包含以下内容的 功能。

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

有关详细信息，请参阅 人员 对象。

1. 在 Microsoft 365 代理工具包的“生命周期”窗格中选择“预配”。

重新加载页面后，声明性代理可以访问人员知识。

添加电子邮件知识

使用电子邮件功能，可将代理的范围限定为使用来自用户邮箱或共享邮箱的电子邮件作为知识源。

1. 打开 文件，main.tspEmail并在命名空间中添加MyAgent包含以下内容的 功能。

   namespace MyAgent {
     // Omitted for brevity
     op email is AgentCapabilities.Email<Folders = [
       {
         folder_id: "Inbox",
       }
     ]>;
     // Omitted for brevity
   }
   

   有关详细信息，请参阅 Email 对象。

   注意

   • 此示例访问代理邮箱的用户。 若要改为访问共享邮箱，请将可选 shared_mailbox 属性设置为共享邮箱的电子邮件地址。
   • 数组 Folders 限制邮箱对特定文件夹的访问。 若要访问整个邮箱，请省略 folders 数组。

2. 在 Microsoft 365 代理工具包的“生命周期”窗格中选择“预配”。

重新加载页面后，声明性代理有权访问电子邮件知识。

添加映像生成器

映像生成器功能使代理能够根据用户提示生成图像。

1. 打开 文件，main.tspGraphicArt并在命名空间中添加MyAgent包含以下内容的 功能。

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

有关详细信息，请参阅 图形艺术对象。

1. 在 Microsoft 365 代理工具包的“生命周期”窗格中选择“预配”。

声明性代理能够在重新加载页面后生成图像。

添加代码解释器

代码解释器功能是一种高级工具，旨在通过 Python 代码解决复杂任务。

1. 打开 文件，main.tspCodeInterpreter并在命名空间中添加MyAgent包含以下内容的 功能。

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

有关详细信息，请参阅 代码解释器对象。

1. 在 Microsoft 365 代理工具包的“生命周期”窗格中选择“预配”。

重新加载页面后，声明性代理具有代码解释器功能。

添加 Copilot 连接器内容

可以将 Copilot 连接器引入的项添加到代理的可用知识中。

1. main.tsp打开 文件并在 GraphConnectors 命名空间中添加MyAgent功能，并使用以下值，将 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 连接器中的内容可供代理使用。

2. 在 Microsoft 365 代理工具包的“生命周期”窗格中选择“预配”。

声明性代理有权访问 Copilot 连接器内容，以在重新加载页面后生成其答案。

已完成

已完成 智能 Microsoft 365 Copilot 副驾驶® 的声明性代理指南。 熟悉使用 TypeSpec 生成声明性代理后，可以在以下文章中了解详细信息。

• 了解如何为代理 编写有效的说明 。
• 使用 Copilot 开发人员模式 测试代理，以验证 copilot 业务流程协调程序是否以及如何选择要用于响应给定提示的知识源。
• 获取 常见问题解答。
• 了解使用 Copilot Studio 生成声明性代理的替代方法。

后续步骤