在 Microsoft Teams 中部署代理

Microsoft Teams 的持久聊天环境为 Copilot Studio 代理带来了独特的部署挑战。 与自动重置会话的基于 Web 的部署不同，Teams 无限期地维护会话线程，这可能导致过时的上下文、令牌过期和过时的缓存内容。

本文提供了在 Teams 中有效地部署 Copilot Studio 代理的指导。 了解如何管理持久会话、实施调试策略，并确保跨扩展会话生命周期的可靠性能。

所涉及的主要考虑因素：

• 会话生命周期管理和非活动处理
• 持久对话的调试技术
• 版本控制和更新部署策略
• Teams 特定实现模式

遵循这些做法，创建在 Teams 环境中一致执行的可靠代理，同时向用户提供有关状态更改和系统行为的明确反馈。

Teams 部署为何不同

Teams 对话可以持续多日，不会自动重置。 与Web 聊天会话不同，ConversationStart事件仅在首次添加代理时触发。 重新安装应用不会重新触发此事件。

Teams 数据持久性会产生多种风险：

• 过期上下文：对话历史记录将持续保留直至手动清除。
• 令牌过期：连接器可以在长时间会话期间过期。
• 上下文限制：累积的消息可能超过模型限制。
• 更新缓存：用户可能会继续与过时的逻辑交互。

主动状态管理和明确的用户指南至关重要。

管理会话生命周期

通过闲置处理机制管理会话生命周期。

实现不活动状态重置

创建一个新主题，并选择用户处于非活动状态触发器，以便在用户不活动一段时间后启动重置流程。 在非活动触发器中详细了解特定于 Teams 的模式，包括防护变量和永久对话模型。

1. 添加非活动触发器并设置超时（例如 15 分钟）。
2. 添加一个或多个 Clear 变量值 节点以删除会话变量和会话历史记录，以防止上下文溢出。
3. 结束会话并将会话标记为 已解决。

此方法可防止上下文溢出，并在用户返回时确保可预测行为。

在重置后提供指导

清除状态后，发送说明所发生情况的消息。 示例：“本次对话已进入闲置状态，为确保安全我将清除先前上下文。 说“hello”后重启。

由于 ConversationStart 仅触发一次，因此首次添加代理时， Greeting 主题将成为有效的初始化点。 提示用户说出“hello”可确保启动逻辑正常运行。

提供自助重置命令

添加消息，告知用户可以键入特定命令：“如果出现错误，请尝试键入 /debug clearstate 以刷新状态。

此命令强制完成对话重置：

• 清除聊天状态
• 删除缓存的连接器信息
• 重新验证连接器
• 加载最新版本的代理

在以下情况下使用此命令：

• 机器人似乎“卡住”了过时的信息
• 连接器身份验证已过期
• 机器人逻辑更新后
• 行为似乎不一致时

提高透明度并改进调试

若要提高透明度并改进 Teams 中部署的代理的调试，请使用 OnKnowledgeRequested 触发器。

使用 OnKnowledgeRequested 显示重写的查询

Copilot Studio 在执行检索之前重写用户问题。 如果启用 OnKnowledgeRequested 触发器，可以：

• 诊断意图不匹配
• 了解如何重写查询
• 在调试期间增加用户信任

添加一条消息，其中显示了生成的关键字和语义查询。 例如：

kind: AdaptiveDialog
beginDialog:
  kind: OnKnowledgeRequested
  id: main
  actions:
    - kind: SendActivity
      id: sendActivity_debug
      activity: |-    
        **Debug**: sending this lexical query "{System.KnowledgeSearchQuery}"
        **Debug**: sending this semantic query "{System.SearchQuery}"
inputType: {}
outputType: {}

此查询提供对业务流程协调程序根据用户问题生成的优化搜索查询（查询重写）的只读访问权限。

优点：

• 帮助调试意图不匹配问题。
• 向用户显示代理查找的内容。
• 增强用户对智能体操作的信任感。
• 在测试期间协助制造商。

版本控制和更新可靠性

管理代理版本并确保用户与最新逻辑交互在持久环境中尤其重要，例如 Teams。

在问候语或专用主题中显示机器人版本号

使用 Greeting 主题或专门的版本主题来包含版本标识符：

Contoso Helpdesk Bot – Version 1.3 (Nov 2025)

每次版本发布时更新此值，以帮助用户和支持团队验证哪个构建处于活动状态。 更新版本元数据还会刷新缓存的内容。 更改代理的名称或说明会导致 Teams 将其加载为新的更新。

发布时启用“强制最新版本”

Force 最新版本设置可确保 Teams 下次用户发送消息时加载最新的代理逻辑。 此设置还有助于使缓存的版本失效。 但是，强制更新会中断任何正在进行的对话。

Teams 特定实现注意事项

Teams 具有独特行为模式，需特别关注。

将问候主题视为启动逻辑

由于 ConversationStart 仅触发一次，因此首次添加代理时：

• 将初始化逻辑置于 Greeting 中。
• 在 Teams 应用说明中添加明确的说明。
• 提醒用户：“超时后，键入”hello“以启动新对话。

优化触发器和回退

Teams 用户自然而不可预测地进行交互。 请确保您的机器人：

• 处理多个问候语变体。
• 包括告别处理。
• 提供多个示例话语。
• 提供友好且有用的回退响应。
• 使用关键字指导用户了解相关主题。
• 使用 OnKnowledgeRequested 来帮助诊断未识别的意图。
• 基于关键字重定向到相关主题。
• 如果机器人真正停滞，提示用户重新回复。

验证连接器身份验证行为

使用连接器（ServiceNow、Outlook 和其他连接器）时，请测试：

• 初始登录卡的行为方式。
• 令牌过期时会发生什么，以及如何自动续订。
• 强制无效化与重新授权流的工作原理。

在实际条件下进行测试

由于 Teams 会跨会话保留状态，因此测试应反映实际用户体验：

1. 通过使用 仅对我可见 进行部署。
2. 测试长时间运行的场景（运行数小时后返回）。
3. 发布更新并确认代理程序切换到新的版本。
4. 验证在桌面和移动设备上自适应卡片的呈现效果。
5. 在各种对话上下文中测试行为。

部署检查表

关键结论

• 适当时，通过配置非活动触发器并使用状态清除选项来管理会话生命周期。
• 通过查询重写和状态相关消息展示系统活动以提升透明度。
• 考虑特定于 Teams 的行为，例如处理手动问候语和管理永久性内存。
• 通过实施版本控制做法并在必要时强制执行更新来维护代理可靠性。
• 通过提供自助服务故障排除命令和引导式恢复选项来支持用户自治。

相关信息

• 连接并配置用于 Teams 和 Microsoft 365 的代理
• 关键概念 - 发布和部署代理