int-patterns

Copilot Studio 模式库

只阅读与当前任务相关的模式文件 — 不要阅读所有文件。

如何使用模式

模式是建议，而非要求。如何介绍模式取决于你的角色：

如果你是 Advisor Agent：

• 将每种模式作为建议介绍 — 说明它解决的挑战以及它为何相关
• 使用与状态相符的措辞：
  • proven：「这是一个已在生产环境中使用的成熟模式 — 可以考虑将其用于……」
  • recommended：「这是一种效果良好的推荐方法 — 可以考虑将其用于……」
  • experimental：「这是一种尚未经过充分验证的实验性方法 — 采用前可以考虑进行全面测试」
• 始终使用「你可以考虑……」或「一种常见的方法是……」，切勿说「你必须……」
• 让用户自行决定 — 未经确认，不要自动应用模式

如果你是 Author Agent：

• 在实现用户或 Advisor 已选择的模式时，阅读相关模式文件，了解正确的 YAML 结构
• 不要自行建议模式 — 这是 Advisor 的职责
• 将 YAML 示例作为参考，了解正确的类型、字段和结构

模式索引

JIT 术语表 → jit-glossary.md

在收到首条消息时，将客户专属缩略语加载到全局变量中，以便编排器在搜索知识源之前展开这些缩略语。

在以下情况下阅读此模式：

• 用户想要添加术语表、缩略语列表或术语表格
• 由于 Agent 不理解内部缩写，导致知识搜索效果不佳
• 用户询问如何在对话开始时将 CSV/文本数据加载到变量中

JIT 用户上下文 → jit-user-context.md

将当前用户的 M365 配置文件（国家/地区、部门）加载到全局变量中，以提供个性化回答。

在以下情况下阅读此模式：

• 用户想要获得基于国家/地区、部门或角色的回答
• Agent 需要调用 M365 Users 连接器
• 用户询问如何根据聊天对象个性化回复

动态主题重定向 → dynamic-topic-redirect.md

在 BeginDialog 节点中使用 Switch 表达式，根据变量将流程路由到不同主题。

在以下情况下阅读此模式：

• 用户需要根据变量路由到多个主题之一
• 用户想要用更简洁的方法替代嵌套的 ConditionGroup 节点
• 用户询问动态主题重定向或 Switch 表达式

阻止子 Agent 回复 → prevent-child-agent-responses.md

指示子 Agent 使用输出变量，从而阻止它们直接向用户发送消息。

在以下情况下阅读此模式：

• 用户希望子 Agent 返回数据，而不是向用户发送消息
• 用户不清楚子 Agent 上的完成设置
• 父 Agent 需要控制所有面向用户的回复

日期上下文 → date-context.md

使用 Power Fx 将当前日期注入 Agent 指令，以便准确回答与日期相关的问题。

在以下情况下阅读此模式：

• 用户询问与日期相关的问题（「下周有什么安排？」「即将举行的活动」）
• Agent 处理日程、日历、截止日期或时效性内容
• 日期解读导致混淆或幻觉

Orchestrator 生成的变量 → orchestrator-variables.md

在编排时使用 AutomaticTaskInput 对用户消息进行分类或提取结构化数据——无需额外成本或延迟。

在以下情况下阅读此模式：

• 用户需要按类别路由知识搜索
• 用户希望提取分类结果，而无需询问用户或使用 AI Prompt
• 由于不加区分地搜索所有来源，导致知识搜索质量下降

防止工具调用泄漏 → prevent-tool-call-leaks.md

防止编排器向最终用户泄漏内部推理和工具调用元数据。

在以下情况下阅读此模式：

• 用户报告在 Agent 响应中看到了原始 JSON
• Agent 具有由编排器间接调用的连接器操作
• 响应包含 explanation_of_tool_call 或类似的内部元数据

感知渠道的行为 → channel-aware-behavior.md

从 System.Activity.ChannelId 检测宿主渠道，并针对不同界面（Teams、M365 Copilot、网页聊天、Direct Line、语音）控制行为。

在以下情况下阅读此模式：

• 某项功能在一个渠道上正常工作，但在另一个渠道上出错（文件上传、Adaptive Card 变体、超链接）
• 用户询问如何检测 Teams、M365 Copilot、网页或语音渠道
• 简单的 =Lower(ChannelId) = "msteams" 检查未能检测出 msteams:Copilot 或其他复合渠道 ID，且没有任何提示

RAI 错误处理 → rai-error-handling.md

在 OnError 主题中按子代码对 Azure OpenAI 内容筛选器错误进行分类，并返回带有遥测数据的类别专属用户消息。仅适用于 Azure OpenAI 模型——不适用于 Anthropic 或 xAI 模型。

在以下情况下阅读此模式：

• 用户需要针对 RAI 内容筛选违规情况提供行业专属或富有同理心的错误消息
• 用户希望按类别进行处理（例如，为自我伤害情况提供危机资源，为越狱尝试提供安全提示）
• 用户询问 OnError、ContentFiltered、Azure OpenAI 内容筛选器或 RAI 子代码

消息中的换行 → line-breaks-in-messages.md

在消息和问题节点中使用 <br /><br />，以便在各渠道中可靠地呈现段落间距。

在以下情况下阅读此模式：

• 用户反映机器人消息读起来像一大堵文字
• 多部分问题或欢迎消息需要在视觉上分隔
• 用户询问消息或问题中的换行、<br /> 或格式

知识搜索等待消息 → knowledge-hold-message.md

在知识搜索期间发送随机等待消息，让用户知道 Agent 正在处理。

在以下情况下阅读此模式：

• Agent 的知识搜索延迟明显
• 用户在等待期间放弃对话或重新发送问题
• 用户询问 OnKnowledgeRequested、输入指示器或等待消息

确定性 MCP 调用 → deterministic-mcp-calls.md

通过基于指令的提示或专用子 Agent 包装器，提高 MCP 工具调用可靠性的变通方法。

在以下情况下阅读此模式：

• 对于特定意图，每次都必须调用某个 MCP 工具，但编排器会跳过它
• 用户询问如何强制调用 MCP 工具，或如何在 MCP 工具中使用 / 语法
• 用户需要为业务关键型工作流进行确定性的工具调用

思维链日志记录 → chain-of-thought-logging.md

在多步骤编排期间发送高层级的“思考”消息，以提升可观察性和用户感知到的响应速度。

请在以下情况下阅读此模式：

• Agent 会使用多个工具、MCP 服务或串联协作的子 Agent
• 用户在多步骤推理期间会遇到长时间无响应
• 用户想要调试或观察编排器行为的跟踪记录
• 用户询问复杂流程的流式传输、输入指示器或进度消息

对话历史变量 → conversation-history-variable.md

尽可能将对话记录捕获到变量中，以便用于升级处理、日志记录和下游自动化。

请在以下情况下阅读此模式：

• 用户需要捕获对话上下文，以便升级至人工客服处理
• 下游工具或连接器需要将对话历史作为输入
• 用户想要将对话记录到 Dataverse、票务系统或电子邮件中

Teams 生产环境强化 → teams-production-hardening.md

针对 Teams 和 M365 Copilot Agent 的 8 种协同生产环境模式，涵盖重新安装、过期上下文、重置、诊断和建议提示词。

请在以下情况下阅读此模式：

• 用户正在 Microsoft Teams 上部署或强化 Copilot Studio Agent
• 用户报告在返回长期运行的 Teams 对话后遇到过期上下文
• 上下文变量在 Web 聊天中有效，但在 Microsoft 365 Copilot 中无效
• 用户想要包含诊断信息、体验更丰富的 OnError 或 Start Over
• 用户询问 OnInstallationUpdate、OnInactivity、OnSystemRedirect、建议提示词或 Teams 特定行为

组合模式

一个 Agent 中可以组合使用多种模式。常见组合包括：

• JIT 术语表 + JIT 用户上下文 → 合并到单个 conversation-init OnActivity 主题中（模板位于 templates/topics/conversation-init.topic.mcs.yml）
• 日期上下文 + JIT 用户上下文 → 两者都放在 Agent 指令中；日期使用 Power Fx 表达式，用户上下文使用全局变量引用
• 编排器变量 + JIT 用户上下文 → 按类别分类并按国家/地区个性化，实现精准的知识路由
• RAI 错误处理 + Teams 生产环境强化 → 先在 OnError 中处理 RAI 子代码，再回退到模式 7 中的通用诊断卡片
• 知识保留消息 + 思维链日志记录 → 知识密集型 Agent 使用保留消息，多工具 Agent 使用思维链日志记录；两者都能降低用户感知到的延迟，但解决的是不同问题
• Teams 生产环境强化 + JIT 用户上下文 → 模式 4 会跨渠道设置 Global.UserContext；要获取真实个人资料数据，请将硬编码值替换为 JIT 用户上下文连接器调用