将 agent 连接到 Microsoft Teams
Microsoft Teams 渠道让用户可以在 Teams 私聊、团队频道和群聊中与 n8n agent 对话。
提示
功能可用性
Microsoft Teams 渠道可用于:
- n8n Cloud: n8n 2.46.0 起的所有计划
- 自托管: n8n 2.46.0 起的所有计划
提示
预览状态
面向 agent 的 Microsoft Teams 渠道处于 Preview 阶段,未来版本中可能会变化。请避免在生产环境中依赖它。
连接 Teams 有两种方式:
- Recommended setup 推荐设置: 你使用 Microsoft 登录,n8n 会为你创建应用注册、Azure Bot 和 Teams 应用。
- 手动设置(界面显示为 Use your own Microsoft app 使用你自己的 Microsoft 应用):你自行创建应用注册和 Azure Bot,然后把凭据交给 n8n。
步骤请参阅设置 Teams 渠道。两种设置的最终结果相同。关于 agent 的可用位置、监听方式、主动发送的消息、文件以及 Microsoft Graph 权限的章节,对两者都适用。
Teams 渠道如何工作
Teams agent 有四个组成部分:Microsoft 侧的三项资源,以及 n8n 中的一个凭据。
| 组件 | 作用 |
|---|---|
| Microsoft Entra 应用注册 | 为 bot 提供身份。它是单租户应用,因此只在你的组织中有效。 |
| Azure Bot | 接收来自 Teams 的消息并转发到 n8n。它使用免费的 F0 层级,并已启用 Microsoft Teams 渠道。 |
| Teams 应用包 | 包含应用清单和图标的 zip 文件。用户在 Teams 中添加此应用,即可联系 agent。 |
| Microsoft Entra Service Principal 凭据 | 在 n8n 中存储应用注册的租户 ID、客户端 ID 和客户端密钥。 |
当有人在 Teams 中给 agent 发消息时:
- Teams 把消息发送到 Azure Bot。
- Azure Bot 把它转发到你的 n8n 实例。
- n8n 运行 agent 的已发布版本。
- agent 在同一聊天或线程中回复。agent 处理期间,Teams 会显示正在输入指示。
每个线程都是独立的会话,因此 agent 会记住同一线程中之前的消息。要重新开始,请发送 /new。如果某个工具需要批准,agent 会发出一张批准卡片。在频道和群聊中,只有需要作答的人能看到这张卡片。
提示
先发布 agent
Teams 渠道运行的是 agent 的已发布版本。在你发布 agent 之前,它不会收到来自 Teams 的消息。你可以在发布之前设置渠道,n8n 会在你发布时完成连接。
用户可以在哪里使用 agent
在 Choose where it works 选择可用范围 步骤中,你决定用户可以在哪里联系 agent。私聊始终开启。你还可以开启团队频道、群聊,以及 agent 是否读取其中的每条消息。
| 选项 | 用户在哪里使用 | 对话如何开始 | 它添加的权限 | 谁来批准 |
|---|---|---|---|---|
| Direct chat 私聊 | 与 agent 的一对一聊天 | 打开应用并发送消息 | 无 | 不需要任何人 |
| Team channels 团队频道 | 已添加该应用的团队中的频道 | 将应用添加到团队,然后在频道中 @提及 agent | ChannelMessage.Read.Group |
添加应用时的 team owner |
| Group and meeting chats 群聊和会议聊天 | 已添加该应用的群聊和会议聊天 | 将应用添加到聊天,然后 @提及 agent | ChatMessage.Read.Chat |
将应用添加到聊天的人 |
| Read all channel messages 读取所有频道消息 | 团队频道 | 频道中的任意消息 | 除 Team channels 团队频道 外无其他权限 | 添加应用时的 team owner |
| Read all group-chat messages 读取所有群聊消息 | 群聊和会议聊天 | 聊天中的任意消息 | 除 Group and meeting chats 群聊和会议聊天 外无其他权限 | 将应用添加到聊天的人 |
此表中的权限是资源特定同意(RSC)权限。它们属于应用包,并且只适用于添加该应用的团队或聊天。它们让 agent 可以读取该团队或聊天中的消息和粘贴的图片。它们不会授予对组织中其他内容的访问权限。
这些选项是应用包的一部分。如果以后更改它们,n8n 会构建新的包,你必须重新上传或发布。请参阅管理 Teams 渠道。
agent 如何在频道和群聊中监听
在私聊中,每条消息都会运行 agent,回复会随着 agent 的撰写逐字出现。
在团队频道和群聊中,agent 可以用两种方式监听。agent 完成后,回复会作为一条消息送达。
仅提及
这是默认方式。只有当有人 @提及 agent 时,它才会响应:
- 当有人 @提及 agent 时,它会加入对话。在频道中,它加入那一个线程。在群聊中,它加入整个聊天。
- 加入之后,该线程或聊天中之后的消息都会到达 agent,即使没有 @提及。
- agent 尚未加入的线程或聊天中的消息不会到达它。
读取所有消息
当你开启 Read all channel messages 读取所有频道消息 或 Read all group-chat messages 读取所有群聊消息 时:
- agent 会在频道或聊天中的每条消息上运行,无需 @提及。
- agent 自行决定是否回复。当消息不是发给它时,它可以保持沉默。
- 每条消息都会消耗模型额度,即使 agent 没有回复。
- n8n 会忽略其他 bot 发送的消息。
当用户直接向 agent 求助时,请保持默认设置。当 agent 需要跟随整个对话时,请开启读取全部选项,例如回答那些没有人向它提出的问题。在繁忙的频道中,这会消耗大量模型额度。
agent 主动发送的消息
agent 不只是回复。它也可以主动发起对话,例如来自计划任务「Send [email protected] the Monday summary」:
- 私聊: agent 向某人发送私聊消息。此人必须已经在 Teams 中添加了该应用。
- 频道和群聊帖子: agent 在团队频道或群聊中发起新帖子。该应用必须已经在该团队或聊天中。
要联系某人,agent 需要对方的 Teams ID 或频道 ID。它可以替你查找:
- 按电子邮件:agent 根据电子邮件地址找到此人。这需要
User.ReadBasic.All。 - 按名称:agent 根据团队和频道名称找到频道,例如「Marketing General」。这需要
Team.ReadBasic.All和Channel.ReadBasic.All。
管理员会将这些权限与文件访问一起批准。请参阅 Microsoft Graph 权限。没有这些权限时,只要有人曾在某个频道中 @提及过 agent,或者 agent 已经知道某人的 Teams ID,它仍然可以联系该频道或该用户。
文件和文件权限
用户可以把文件附加到消息中,agent 会连同文本一起收到这些文件。每个文件最大 10 MB,一条消息最多可以有 10 个文件。如果 n8n 无法读取某个文件,agent 仍然会收到该消息。
文件如何到达 agent,取决于用户在哪里发送它们。
私聊中的文件
在私聊中,Teams 会把文件和消息本身一起发送。你不需要任何额外权限。
频道和群聊中的文件
在团队频道和群聊中,Teams 不会在消息里包含文件。n8n 会通过 Microsoft Graph 再次读取消息来找到它们:
- 粘贴的图片使用应用已有的 RSC 权限即可(
ChannelMessage.Read.Group或ChatMessage.Read.Chat,请参阅用户可以在哪里使用 agent)。你不需要其他任何权限。 - 附加的文件存储在 SharePoint 或 OneDrive 中。要下载它们,应用注册需要 Microsoft Graph application 权限
Files.Read.All,并获得管理员同意。请参阅 Microsoft Graph 权限。
即使有 Files.Read.All,也只有在以下任一条件成立时,n8n 才会下载文件:
- 文件位于频道的 Files 文件夹中。
- 文件位于发送消息的人的 OneDrive 中。
这样可以避免 agent 打开不属于该对话的文件。
当 agent 无法读取文件时
如果 n8n 无法下载文件,它会把原因告诉 agent,以便 agent 向发送者解释:
| 原因 | 处理办法 |
|---|---|
| 还没有管理员批准这些权限 | 按照批准访问中的说明批准,然后最多等待一小时。 |
| Teams 中的应用缺少某项权限 | 上传或发布最新的应用包。较旧的包可能没有 RSC 权限。 |
| 文件不在频道的文件中,且发送者不是所有者 | 请对方在频道中共享该文件,或从自己的 OneDrive 共享。 |
限制
- Teams 渠道只在全球 Microsoft 云中有效。不支持主权云。
- bot 凭据必须使用客户端密钥。不支持证书身份验证。
- 每个凭据只能将一个 agent 连接到 Teams,每个 agent 只有一个 Teams 连接。
- 当 agent 按名称查找频道时,最多搜索 50 个团队。
- 推荐设置始终在 West Europe 的
n8n-agents资源组中创建 bot。 - 每个文件最大 10 MB,每条消息最多 10 个文件。
- 情节记忆(Episodic memory)尚不适用于 Teams 对话。agent 会记住同一线程中之前的消息,但不会记住其他线程或聊天中的上下文。
本节内容
- 设置 Teams 渠道:使用推荐设置或手动设置将 agent 连接到 Teams,并批准 Microsoft Graph 权限。
- 管理 Teams 渠道:发布或上传应用、更新应用、续订客户端密钥、断开 Teams 连接,以及修复常见问题。