声明式代理通过说明、知识源和支持的功能针对特定业务方案自定义 智能 智能 Microsoft 365 Copilot 副驾驶® 副驾驶®。 使用这些做法可以让代理保持专注,安全地配置其操作,并在其发展过程中评估其行为。
从定义的受众、用户任务和预期结果开始。 有关托管运行时和您运行的服务之间的边界,请参阅 声明式代理体系结构。
注意
本文介绍使用 Copilot 的托管运行时的声明性代理。 如果要生成检索 Microsoft 365 基础数据的自定义引擎代理,请遵循 检索 API 最佳做法 以及 权限和限制。 该指南与配置声明式代理的知识源是分开的。
声明性代理组件
选择每个组件以支持代理的预期任务。 遵循所选创作工具和清单架构中的限制。
| 组件 | 最佳做法 |
|---|---|
| 名称 | 使用传达代理用途的不同名称。 代理生成器最多允许 30 个字符;声明性代理清单允许最多 100 个。 |
| 说明 | 在 1,000 个字符的限制范围内,用几句精确的句子总结任务和域。 在说明字段中保留详细的行为说明。 |
| 说明 | 在 8,000 个字符的限制范围内定义代理的用途、支持的任务、源和工具使用、输出格式和失败行为。 |
| 知识源 | 为预期问题添加相关源。 确认其支持的范围、新鲜度、权限和许可。 |
| 内置功能 | 仅当 代码解释器 或 图像生成器 等功能支持预期任务时才启用它们。 |
| 自定义技能 (预览) | 将 技能 用于模块化任务指令、资源或脚本。 在高级别上引用配置的技能,而不是复制其详细说明。 |
| 操作 | 使用 MCP 或 API 插件 实现与外部服务的支持交互。 描述每个工具的用途、输入、输出和故障条件。 |
| 对话发起人 | 提供演示支持任务的代表性提示。 没有最低数量要求。 测试每个提示并遵循所选工具的限制。 |
代理说明的最佳实践
使用说明来定义代理应如何处理预期任务:
- 说明结果和界限。 描述代理帮助用户完成的工作、它需要哪些信息以及它应该如何响应不受支持的请求。
- 明确源和工具使用。 确定适用于每项任务的已配置源、功能或操作。 询问缺少的输入,而不是猜测。
- 将步骤与演示分开。 在顺序很重要的地方使用清晰的任务步骤,并指定响应的预期语气、结构和详细程度。
- 为丢失的信息和故障做好计划。 描述如何在不声明成功的情况下处理源不可用、结果不完整、访问被拒绝和不成功的操作。
- 将说明与知识分开。 不要在 SharePoint 文档或其他知识来源中放置行为指令来绕过指令限制。 检索的内容不是受信任的制造商创作的指令内容。
有关模型更改的详细模式、示例和指南,请参阅 编写有效的说明。 有关将知识与 API 调用相结合的任务,请参阅 使用 API 插件为代理编写说明。
选择正确的知识源
根据代理必须回答的问题选择 知识源 :
- 优先考虑相关性而非数量。 将源范围限定到任务所需的文件、网站、聊天或其他内容。 对于 SharePoint 和嵌入文件,请遵循 优化内容检索。
- 将检索与新鲜度要求相匹配。 定期查看源内容和所有权。 范围的 Web 搜索使用必应索引的内容,而不是对基础数据的直接查询。 对于当前结构化数据,请改为评估支持的 API 或 MCP 操作。 请参阅 Web 搜索基础和动态内容。
- 共享前确认访问权限。 使用表示目标受众和权限的用户进行测试。 分开访问原始文件审查嵌入式 文件共享行为 。
- 检查功能和许可支持。 源和范围选项因创作工具和租户配置而异。 遵循 知识源支持矩阵 和 许可指南。
- 评估基础情况,而不仅仅是回答的流利程度。 使用已知答案测试问题,并检查回答和引文是否与预期来源匹配。 包括无法提供答案的问题。
添加源本身并不能阻止代理使用内置模型知识。 当方案需要基于源的响应时,请在说明中设置为behavior_overrides.special_instructions.discourage_model_knowledgetrue并加强预期的源使用。 此控件不保证响应仅使用配置的源。 在缺少证据时继续评估来源归属和行为。 请参阅 对配置的知识源的 Ground 响应 和 特殊说明参考。
设计安全操作
使用操作与外部服务进行受支持的交互,并将其与知识源区分开来。 用于接地的 Copilot 连接器不可与更改外部数据的 API 或 MCP 工具互换。
- 准确描述操作。 说明何时应使用工具、其必需参数及其预期结果和错误。 对于 REST API,请遵循 OpenAPI 文档指南。
- 为集成配置确认。 对于 API 插件,请使用 OpenAPI 扩展
x-openai-isConsequential,而不是isConsequential,并将具有副作用的操作标记为相应操作。 对于 MCP 工具,仅用于readOnlyHint只读工具。 按照 MCP 和 API 插件的确认提示 获取受支持的设置和行为。 - 在服务中强制执行访问。 使用支持的 身份验证方法 ,并在外部服务中验证授权和输入。 说明和确认提示不能取代这些检查。
- 针对失败和重复请求进行设计。 测试拒绝确认、身份验证过期、输入无效和服务错误。 对于更改数据的操作,请确保重试不会无意中重复更改。
使用 计划数据、隐私和安全性 来确定每个操作的数据流、权限和人工监督要求。
测试和循环访问
在更改代理之前定义预期行为,并保留一组可重复的测试用例。 使用创作工具的测试体验获取早期反馈,然后在其预期主机中验证已部署的代理。
| 测试区域 | 要验证的内容 |
|---|---|
| 支持的任务 | 对话开场白、现实的用户措辞和后续问题会产生预期的结果。 |
| 缺少或不受支持的信息 | 代理要求提供必要的输入,解释不可用的证据,并且不会编造事实或声称已完成不成功的操作。 |
| 基础设置和权限 | 答案和引文与预期来源匹配。 测试具有不同访问权限的用户,并确认受限信息不会泄露。 |
| 操作和失败 | 检查实际的外部结果和响应。 测试确认、取消、身份验证失败、服务错误和重复请求。 |
| 主机体验 | 测试要部署到的每个受支持应用。 检查文档上下文、响应呈现方式和可用功能,而不是假设所有应用的行为都相同。 |
| 性能和更改 | 测量响应时间,并在指令、知识、工具、技能或平台行为发生更改后重新运行回归案例。 |
包括未编写说明的用户,以便测试捕获意外的措辞和假设。 将用户报告的可重现问题转化为回归案例。
有关测试用例设计、断言和可重复评估的信息,请参阅 代理评估概述。 有关发布检查,请参阅 负责任的 AI 验证 和 验证和测试插件。