Agent 365 开发入门

代理 365 可用于多种代理实现。 代理可以按需帮助用户，在后台自主运行，或在Microsoft 365中使用自己的用户标识进行操作。 了解哪个模式最能描述代理很重要，因为它确定代理的标识模型、对Microsoft 365资源的访问权限以及哪些生命周期步骤适用。

代理类型

在开始之前，请问自己： 我正在构建什么样的代理？

有两种类型的代理，具体取决于它们拥有的访问类型：

代理类型 Overview
代理 代表具有委派访问权限的用户工作，或作为具有作用域权限的应用程序运行。 注册为 Microsoft Entra 应用程序或代理身份模板。
AI 团队成员 在Microsoft 365中使用自己的用户标识进行操作，包括邮箱、Teams 状态和目录条目。 这种类型的代理仅适用于参与 边境预览计划的租户。

代理

代理代表用户工作。 它响应请求、在后台运行任务、连接到 API、处理数据和驱动操作。

代理形式多样。 有些是对话 - 用户询问某些内容，代理会做出响应。 有些在后台悄悄地运行 -- 由计划、事件或传入消息触发 - 没有任何人积极参与。 有些两者都做。

示例方案：

  • 用户要求代理汇总其未读电子邮件和草稿回复。 代理执行工作，仅访问用户可以访问的资源，并将结果交回。
  • 客户服务代理可帮助支持工程师查询内部知识库，并在实时支持会话期间撰写响应。
  • 合规性监控代理每晚都会运行，扫描被授予访问权限的 SharePoint 站点以检测策略违规，并生成审核报告——没有任何人直接监督。
  • 订单处理代理从队列中选取新的销售订单，更新 CRM，并发送确认电子邮件——这一切都自动完成，无需人工干预。

标识基础：

通常，您将代理程序注册为Microsoft Entra应用程序。 这种方法继续工作。 今后，还可以通过 代理身份蓝图 在 Microsoft Entra 智能体 ID 上构建代理 - IT 批准的、通过治理强制实施的关于代理功能、允许的工具访问和合规性约束的定义。 基于蓝图构建是新代理人的推荐路径。 它解锁了受治理的 Work IQ 工具访问权限、Microsoft Purview 数据保护、Microsoft Defender 威胁监控和 Entra ID 治理功能，使您的代理从第一天起就成为一个完全受治理的企业标识。

AI 团队成员

重要

若要 提前访问 此类代理，需要成为 “边境预览”计划的一部分。 边界将你直接与Microsoft最新的 AI 创新联系起来。 Frontier 预览版受客户协议中现有预览条款的约束。 由于这些功能仍在开发中，其可用性和功能可能会随时间而变化。

AI 团队成员使用自己的代理标识在Microsoft 365中操作。 您可以为其配置功能，例如通过其自己的邮箱发送和接收电子邮件、参与 Teams 1：1 和组对话，并且在具有分配的经理关系的情况下出现在目录和组织元数据中。 用户可以通过熟悉的Microsoft 365入口点（如 @mentions、电子邮件、日历邀请和 Teams 聊天）与之交互。

从代理蓝图创建这些代理，该蓝图是 IT 批准的、受治理强制执行的代理功能定义、允许的工具访问和合规性约束。 每个代理实例从其父代理标识蓝图继承标识模型、权限和策略。

代理的作用（无论是对话、背景还是两者）都取决于设计方式。 某些代理具有高度交互性，可实时响应消息和支持工作。 其他人在后台处理任务，对电子邮件或事件执行操作，而无需直接用户参与。 代理使用自己的用户标识进行操作，并且其操作通过该标识进行管理和审核。

如果已有代理，则无需再开始。 可以通过添加本指南后面介绍的标识和蓝图配置，扩展现有代理以使用自己的标识进行操作。

示例方案：

  • 将 HR 入职 AI 助手添加到新员工的 Teams 入职频道。 它从自己的邮箱发送欢迎电子邮件，在其自己的日历上安排定向会议，并使用为代理实例配置的功能来回答问题。
  • 将目录元数据中的经理关系分配给采购 AI 团队成员。 员工将购买请求发送到公司的专用邮箱。 代理通过其受控的Work IQ工具访问权限处理请求，查询ERP和财务系统，并根据自身身份进行审批或升级响应。
  • 将研究 AI 团队成员添加到项目团队的SharePoint网站和 Teams 频道。 它可以使用为该代理配置的权限和工具，在会议期间显示相关文档、在对话线程中响应和草稿每周状态报告。

标识基础：

基于代理身份蓝图构建，该蓝图创建 Microsoft Entra 智能体 ID 和关联的用户帐户：始终是必需的。

以增量方式添加代理 365 功能

代理 365 不是全部或全无。 如果你的场景不需要，则无需在第一天构建 AI 伙伴，或者根本不需要构建。 以增量方式采用功能，从代理现在需要的内容开始，随着需求的发展而扩展。

为什么要基于代理身份蓝图进行构建？

创建代理身份蓝图时，Agent 365 CLI 会为您的代理预配Microsoft Entra 智能体 ID，这是您租户中的一级身份，享有与人类用户相同的企业治理政策的约束。 单一身份是所有基于蓝图的代理自动获得安全优势的基础。

Benefit 对您的代理的影响
Microsoft Entra ID 管理与治理 代理的标识和访问生命周期通过适用于人类用户的相同条件访问、标识保护和访问评审进行管理。
Microsoft Purview 代理执行的每个数据交互都受租户的敏感度标签、DLP 策略和保留策略的约束 - 无需额外的代码。
Microsoft Defender 持续监视代理行为是否存在异常和威胁。 可疑活动触发与租户中的任何用户相同的警报和响应工作流。

这些优势适用于所有基于蓝图的代理，包括具有用户委托访问权限的代理，以及在创建蓝图后立即使用自己的标识运行的代理。 无需单独配置它们。

下面的四个能力层级表示可以分阶段采用的级别。 下表显示了根据您的基础，Agent 365 可用的项目：

Capability Microsoft 365自定义引擎代理 所有其他代理 1
注册 √ 2 ✓
可观察性 ✓ ✓
工作智商 ✓ ✓
AI 团队成员 ✔ 3 ✔ 3

1 当前注册为Microsoft Entra应用程序的代理必须首先创建代理标识蓝图，才能开始使用此列中的任何功能。

2 Microsoft 365自定义引擎代理已使用其现有的Microsoft Entra应用程序注册-无需其他设置。

Microsoft 365自定义引擎代理的 3 AI 团队成员需要代理标识蓝图。 仅适用于 边境计划 参与者。

Register

注册代理可使其在Microsoft 365 管理中心中可见和管理。 管理员可以在组织的代理清单中发现并查看它。

获取的内容：

  • 您的代理出现在Microsoft 365管理中心；管理员可以找到它，并在组织的代理库存中查看它。
  • 基于蓝图的代理还将获得完整的 Entra ID 治理、Purview 和 Defender 权益，如为什么要基于代理标识蓝图构建？中所述。

您所构建的内容：

使用现有的Microsoft Entra应用程序注册或蓝图注册代理。

注释

如果代理是基于 Google Vertex AI 或 Amazon Bedrock 构建的，则注册无需开发工作 - 代理将通过 Google 和 Amazon API 自动拉取。 无需 SDK 集成、蓝图和代码更改。 注册后，可以使用代理 365 SDK 以增量方式添加可观测性、工作 IQ 工具访问权限和其他功能。 请参阅 注册 Google Vertex AI 和 Amazon Bedrock 代理 以开始使用。

如何构建它：

使用 AI 引导式设置 并相应地回答代理类型问题。 AI 引导式设置执行此层所需的步骤。 Microsoft 365自定义引擎代理，现已通过其现有的Microsoft Entra应用程序注册被发现。

可观察性

注册你的代理后，接下来的投资是可观察性，使 IT、安全团队和你自己的工程团队能够看清你的代理实际在做什么。 每个推理调用、工具调用和交互都会捕获、跟踪和进行审核。

可观测性是信任的基础。 如果没有它，管理员无法大规模验证行为、审核合规性或诊断问题。 有了它，你的代理就成了企业资产，而不是黑匣子。

获取的内容：

  • 基于 [OpenTelemetry (OTel)]（https://opentelemetry.io/docs/specs/otel/protocol/）的每次代理交互的完整跟踪：输入、输出、工具调用和模型调用。
  • Microsoft 365 管理中心和相关监控界面中显示的活动。
  • 纳入Microsoft Entra、Microsoft Purview和Microsoft Defender的审计记录，支持合规性、数据保护和威胁响应的需要。

您所构建的内容：

使用 代理 365 SDK 可观测性 API 进行检测：自动检测（如果使用 OpenAI、LangChain 或 Agent Framework）或手动检测任何其他堆栈。

如何构建它：

使用 AI 引导式设置 并相应地回答可观测性问题。 AI 指导设置执行此功能所需的步骤。

工作 IQ

注册代理并使其可观察后，可通过 Work IQ 访问Microsoft 365数据和操作。 Work IQ 是一组受治理的工具，可让你的代理使用邮件、日历、OneDrive、SharePoint、Teams 等。

工作 IQ 工具需要获得管理员的同意，经过审计，并且可以撤销。 代理使用蓝图中定义的权限来调用它们 - 无需额外的 OAuth 流或自定义连接器。

获取的内容：

  • 访问完整的 Work IQ 工具目录 - 邮件、日历、OneDrive、SharePoint、Teams 等。
  • 管理员控制的权限，并限定为代理所需的权限。
  • 通过可观察性管道，每个工具调用都可以追踪和审核。

您所构建的内容：

使用 代理 365 SDK 工具 API 调用 Work IQ 工具的代理代码。

如何构建它：

使用 代理 365 SDK 工具 API 手动将 Work IQ 工具调用添加到代理代码。 AI 引导式设置目前不支持此功能。

AI 团队成员

AI 团队成员可供 边境计划 参与者使用。

最后阶段使代理可以使用自己的标识在Microsoft 365中运行。 根据配置，它可以具有邮箱、Teams 状态、目录条目和管理器关系。 用户可以通过熟悉的Microsoft 365体验（如电子邮件、聊天、会议和应用图面）与之交互。

注释

标识和权限模型转变

迁移到 AI 团队成员表示代理访问资源的方式发生了根本变化。 您的现有代理可能会使用委托用户访问权限，即代理在已登录用户的名义下执行操作，并且只能访问该用户可以访问的资源，或者使用应用程序权限，这些权限是根据服务主体范围限定的。 具有用户标识的代理不会在运行时继承调用用户的访问权限。 相反，它在其自己的用户标识下运行，具有自己的访问权限授予、治理策略和审核日志。

这意味着：

  • 在委派用户访问中，代理程序代表已登录用户执行操作，仅限于该用户的访问权限。 使用代理自己的标识，可以直接向代理标识授予对Microsoft 365资源（例如邮箱、日历、Teams 和SharePoint）的访问权限。
  • 您管理并审核授予代理身份的权限，将其作为代理自身访问的一部分。 它们与从呼叫用户传递的用户委派权限不同。
  • 如果当前实现依赖于委派用户访问或应用程序权限，请在启用此功能之前查看并重新限定代理标识的权限。

获取的内容：

  • 从可发现性、可观测性和工作智慧到所有内容。
  • 具有单独邮箱的代理用户身份 - 人们可以直接向该邮箱发送电子邮件，该身份也可以从其专属地址发送邮件。
  • 在整个 Microsoft 365 应用中的集成 - 用户可以与它聊天、@mention、将其添加到频道中，并邀请它参加 Teams 会议；还可以在 Word、Excel、PowerPoint 和其他 M365 平台中直接与它交互。
  • 指定经理下的组织结构图条目 - 代理将显示在组织的目录中。
  • 管理控制的生命周期 - 代理通过Microsoft 365 管理中心创建、管理和停用，并且对每个实例进行完全治理。

您所构建的内容：

所有功能，包括实例创建以及（可选）市场发布。

如何构建它：

使用 AI 引导式设置 并相应地回答 AI 团队成员问题。 AI 引导式设置执行此层所需的步骤。

AI导向设置

使用 AI 编码代理自动为 Agent 365 设置和配置代理。 AI 引导式设置将引导你完成启用注册、可观测性、工作 IQ 工具访问和 AI 团队成员功能所需的先决条件检查、配置步骤和代码集成。

AI 引导式设置先决条件

在开始之前，请确保具有以下项：

要求 详细信息
AI 编码代理 Visual Studio Code 配合 GitHub Copilot 和 GitHub Copilot Chat 扩展，或其他具备终端访问权限的 AI 编码代理
代理代码 Python、Node.js或.NET中的工作代理项目。 如果没有，请从 快速入门示例开始。
Entra 角色 全局管理员 - 完成所有步骤，包括 OAuth2 权限授予。 代理 ID 开发者 — 完成除 OAuth2 权限授予之外的所有步骤；此设置为全局管理员生成接管流程。

AI 引导式设置步骤

这些步骤适用于是启用 单个代理 还是 代理工厂。 AI 代理会检查所需的工具，并自动处理安装、身份验证和验证。

打开代理项目，并将此提示复制到所选的 AI 代理中。 如果使用 GitHub Copilot，请首先切换到 Agent 模式 - 请求和编辑模式没有终端访问权限。

Follow the steps at aka.ms/agent365enable to enable my agent for Agent 365.

AI 代理首先询问三个问题，以确定哪些功能适用于代理：

问题 1: 您的代理是否已在 Teams 或 Copilot 中可用？

  • Yes
  • No

问题 2：调用下游 API 时代理如何进行身份验证？

  • 代理 （OBO） - 代理充当登录用户（委派权限）
  • 服务对服务（S2S）——代理充当其自身的身份（应用权限）
  • （OBO 和 S2S）

问题 3：要启用哪些代理 365 功能？

安装设置会自动包括您选择的所有必要功能。

然后，AI 代理会在适用的层次中自动执行任务，只在请求您的输入时暂停：

Capability AI 代理的作用 1
注册 检查.NET和Agent 365 CLI（如果缺少则安装或更新），安装Azure CLI（如果缺少），如果未进行身份验证则运行az login，验证您的自定义客户端应用注册，收集代理名称和经理电子邮件，在Teams开发人员门户中配置代理，并注册代理蓝图。
可观察性 将代理 365 SDK 可观测性检测添加到代理代码
AI 团队成员 运行 a365 publish 并指导您逐步完成部署后的步骤，包括创建代理实例。

1 执行的步骤取决于在设置开始时选择的代理类型和阶段。

重要

为了 便于观察，AI 代理将代码直接写入项目。 AI 编码代理可能会出错。 在将更改部署到生产环境之前，请务必仔细检查。

完成任务所需的信息

AI 代理在安装过程中暂停以收集配置：

提示 要提供的内容
代理名称、管理器电子邮件 基本代理元数据
派生值确认 检查代理标识、蓝图和用户主体的自动生成名称。
清单评审 确认您的manifest.json已更新为代理的名称、说明和开发人员信息。

部署后步骤

自动化层完成后，AI 代理会暂停，并执行两个需要浏览器交互的步骤：

  1. 创建一个代理实例

    （仅 AI 团队成员） - 在 Microsoft Teams 中，转到 Apps，搜索代理，然后选择 Add。 如果需要管理员批准，Microsoft 365管理员将收到请求。 批准后，代理将显示在组织结构图中。 有关其他实例，请参阅 “创建代理实例”。 新发布的代理可能需要几分钟才能显示在 Teams 搜索中。

  2. 测试您的智能体

    向 Teams 中的代理发送消息，以验证其是否正常工作。

完成 — 代理已部署、发布和实时。 如果需要其他实例 ，请参阅“创建代理 实例”。

如果任何操作都不起作用，AI 代理将提供有针对性的故障排除。 还可以参考 代理 365 故障排除指南。

手动路径参考

仅在对步骤进行故障排除、构建 CI/CD 自动化或在没有使用 AI 编码代理的情况下工作时，才使用此参考。

Step 它的作用是什么 指南
设置配置 创建 a365.config.json 并使用租户、订阅和项目详细信息。 如果有现有部署，请在此处 设置消息传送终结点 。 设置代理365配置
设置蓝图 在 Entra 中注册代理标识，并预配 Azure 资源（资源组、应用服务计划、Web 应用） 设置代理蓝图
部署 将代理代码部署到Azure 应用服务。 可选（如果已在其他位置托管）。 AzureAWS · GCP
Publish 创建 manifest.zip 并上传到Microsoft 365 管理中心 发布代理

有关 CLI 安装、命令和故障排除，请参阅 代理 365 CLI。

将代理发布到Microsoft市场

在一个或多个租户中全面开发并测试您的代理后，使其在 Microsoft 市场上可用。

要执行此操作，您需要在 Partner Center 中拥有一个微软 AI 云合作伙伴计划帐户。 如果没有帐户，请创建一个帐户以获取 PartnerID。 接下来，注册 Microsoft 365 和 Copilot 计划，以便获取发布代理要约所需的资源和支持。 注册后，查看提交清单和验证指南，然后通过合作伙伴中心分步提交指南提交代理。

了解如何使用合作伙伴中心将代理提交到 Microsoft 市场。

完成后，代理将发布到Microsoft市场，可供客户发现和部署。

AI 引导式设置疑难解答

如果在 AI 引导式设置过程中遇到问题，请参阅以下常见问题及其解决方案。

问题 Description
AI 代理不运行终端命令 AI 代理描述命令，但不执行命令
AI 代理跳过步骤 安装程序似乎跳过所需的步骤
CLI 命令失败并出现权限错误 运行 365 CLI 命令时的授权错误
配置值错误 创建 a365.config.json 后需要更改配置

AI 代理不运行终端命令

如果 AI 代理描述命令但未执行命令，请确保在GitHub Copilot聊天中使用 Agent 模式。 询问和编辑模式没有终端访问。

AI 代理跳过步骤

指令文件强制执行严格的步序顺序。 如果 AI 代理似乎跳过了一个步骤，请让其重新开始。

Please start from Step 1 in the setup instructions and work through each step in order.

CLI 命令因权限错误而失败

如果 a365 CLI命令因授权错误失败，最常见的原因是自定义客户端应用注册缺失或不完整。 AI 代理在设置期间验证此问题，但如果跳过了验证，请参阅 自定义客户端应用注册。

有关常规故障排除，请参阅 代理 365 故障排除指南。

配置值错误

如果需要在创建 a365.config.json后更改配置值，请执行以下任一操作：

  • 直接编辑文件并重新运行 a365 config init -c ./a365.config.json
  • 让AI代理更新具体数值
  • Last updated on