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

声明式代理提供由智能 智能 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 副驾驶® 副驾驶® 的声明式代理的标准和准则:

创建声明式代理

首先创建一个基本的声明式代理。

  1. 打开 Visual Studio Code。

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

    Microsoft 365 Agents Toolkit 边栏中“创建新应用”按钮的屏幕截图

  3. 选择 声明式代理。

    选中了代理的新项目选项的屏幕截图

  4. 选择“开始使用适用于智能 智能 Microsoft 365 Copilot 副驾驶® 副驾驶®的 TypeSpec 创建基本声明式代理。

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

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

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

    Microsoft 365 Agents Toolkit 的“生命周期”窗格中“预配”选项的屏幕截图

测试代理

  1. 转到 Copilot 应用程序。https://m365.cloud.microsoft/chat

  2. 在“新建对话助手”按钮旁边,选择对话抽屉图标。

  3. 选择声明性代理 My Agent。

    Copilot 中声明式代理的屏幕截图

  4. 输入一个问题,供声明式代理查看其操作效果。

添加说明

指令可更改代理的行为方式。

  1. 打开该 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 。 有关详细信息,请参阅 声明式代理清单对象。

  2. 在 Agents Toolkit 的生命周期窗格中选择预配。

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

声明性代理基于更新说明的答案的屏幕截图

添加对话发起人

对话发起子是 Copilot 向用户显示的提示,用于演示他们如何开始使用声明式代理。

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

    有关详细信息,请参阅 对话发起人对象。

  2. 在 Agents Toolkit 的生命周期窗格中选择预配。

刷新页面后,更新的对话启动器可在声明式代理中使用。

显示智能 智能 Microsoft 365 Copilot 副驾驶® 副驾驶® 中声明式代理的对话发起人的屏幕截图

添加 Web 内容

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

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

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

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

    注意

    如果未指定 Sites 数组,代理可以访问所有 Web 内容。

  2. 在 Agents Toolkit 的生命周期窗格中选择预配。

声明性代理可以访问 Web 内容,以便在您重新加载页面后生成其答案。

显示来自包含 Web 内容的声明性代理的响应的屏幕截图

添加 OneDrive 和 SharePoint 内容

SharePoint 功能使代理能够将 OneDrive 和 SharePoint 内容用作知识。

  1. 打开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 内容。
  2. 在 Agents Toolkit 的生命周期窗格中选择预配。

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

显示包含 SharePoint 和 OneDrive 内容的声明性代理的响应的屏幕截图

添加 Teams 消息

Teams 消息功能 使代理能够将 Teams 频道、团队和会议聊天用作知识。

  1. 打开该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 消息对象。

    注意

    • 属性中的 url URL 必须是指向 Teams 聊天、团队或会议聊天的格式正确的链接。
    • 如果未指定 TeamsMessagesByUrl 数组,代理可以访问经过身份验证的用户可以访问的 Microsoft 365 组织中的所有 Teams 频道、团队、会议、一对一聊天和群组聊天。
  2. 在 Agents Toolkit 的生命周期窗格中选择预配。

声明性代理可以访问 Teams 数据,以便在你重新加载页面后生成其答案。

显示来自包含 Teams 内容的声明式代理的响应的屏幕截图

添加人员知识

人脉功能使您能够将代理范围限定为回答有关组织中个人的问题。

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

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

    有关详细信息,请参阅 People 对象。

  2. 在 Agents Toolkit 的生命周期窗格中选择预配。

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

显示来自包含人员知识的声明性代理的响应的屏幕截图

添加电子邮件知识

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

  1. 打开该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 数组。
  2. 在 Agents Toolkit 的生命周期窗格中选择预配。

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

显示来自包含电子邮件知识的声明性代理的响应的屏幕截图

添加映像生成器

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

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

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

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

  2. 在 Agents Toolkit 的生命周期窗格中选择预配。

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

显示来自包含生成的图形艺术的声明性代理的响应的屏幕截图

添加代码解释器

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

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

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

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

  2. 在 Agents Toolkit 的生命周期窗格中选择预配。

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

显示声明性代理的响应(其中包含生成的图形)的屏幕截图

显示用于生成请求的图形的 Python 代码的屏幕截图

添加 Copilot 连接器内容

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

  1. 打开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 连接器获取内容。

  2. 在 Agents Toolkit 的生命周期窗格中选择预配。

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

屏幕截图显示了包含 Copilot 连接器内容的声明性代理的响应

已完成

你已完成智能 智能 Microsoft 365 Copilot 副驾驶® 副驾驶®的声明式代理指南。 现在,你已经熟悉使用 TypeSpec 构建声明式代理,可以在以下文章中了解详细信息。

后续步骤