编写声明性代理的有效说明

声明式代理是智能 智能 Microsoft 365 Copilot 副驾驶® 副驾驶®的自定义版本,通过声明特定的说明、操作和知识来帮助创建个性化体验。 要为您的声明式代理编写有效的说明,请考虑以下问题:

  • 您的代理必须完成什么目标?
  • 您设想您的最终用户会经历哪些工作流程?
    • 是否有要合并的业务逻辑?
    • 是否有想要融入的最终用户体验?
  • 对于每个工作流,能否为代理提供分步说明?

如果您的声明性代理也将 API 插件作为操作,则插件的 OpenAPI 文档可帮助代理理解引用 API 的任何说明。 有关详细信息,请参阅如何 使 OpenAPI 文档有效地扩展 Copilot。

本指南适用于开发人员和制造商,他们使用智能 智能 Microsoft 365 Copilot 副驾驶® 副驾驶®、Work IQ 开发工具或保留的基于工具包的工作流中的代理生成器创建声明式代理。 建议将 WIQD 用于受支持的专业代码方案。 有关如何为 Copilot Studio 代理编写说明的详细信息,请参阅为生成式业务流程配置高质量说明。

重要

智能 智能 Microsoft 365 Copilot 副驾驶® 副驾驶® 定期转换到较新的模型。 由于这些更新是自动的,因此预计随着时间的推移会有一些行为变化,并准备好在精度很重要的地方调整提示和指令。 模型更改可能会影响声明式代理如何理解和响应您的指令,尤其是在结构化或分步场景中。

指令组件

一组结构良好的指令可确保代理了解其角色、应执行的任务以及如何与用户交互。 声明性代理指令的主要组成部分是:

  • 用途
  • 一般指南,包括一般说明、语气和限制
  • 技能

相关时,还请在说明中包括以下组件:

  • 分步说明
  • 错误处理和限制
  • 反馈和迭代
  • 交互示例
  • 非标准术语
  • 跟进和结案

下图显示了声明性代理指令的主要组件。

智能体指令的组成部分图,包括目的、指南和技能

重要

请勿在 SharePoint 文档 (或任何其他知识源中存储或卸载声明性智能体指令,) 解决 8,000 个字符的指令限制。 知识源内容不是受信任的制造商创作的指令内容,并且会受到 XPIA) 分类器 (交叉提示注入攻击 — 类似指令的语言可以在运行时被阻止、截断或清理,从而导致不可预测的代理行为。 这种模式还扩大了攻击面:任何对引用文档具有编辑权限的人都可以在运行时更改代理行为,绕过清单的创作、版本控制和管理控制。 知识源旨在为事实响应奠定基础,而不是作为系统级指令,平台不保证它们将作为代理指令得到尊重。

高级别参考技能

技能是声明性代理的一个独特组成部分,而不是内联编写的指令。 技能打包自己的指令、资源和脚本,代理仅在任务需要时才加载技能的内容。 在代理的说明中,参考高级技能并指出代理中配置的实际技能,而不是在说明中复制技能的详细步骤。 要了解什么是技能、其限制以及如何添加技能,请参阅 声明式智能体中的技能。

代理说明的最佳实践

使用清晰可操作的语言

  • 关注 Copilot 应该做什么,而不是要避免什么。
  • 使用精确的特定动词,如“ask”、“search”、“send”、“检查”或“use”。
  • 补充示例以尽量减少歧义。
  • 在说明中定义任何非标准或组织独有的术语。

使用过渡构建分步工作流

将工作流分解为模块化、明确且无冲突的步骤。 每个步骤应包括:

  • 目标:步骤的目的。
  • 操作:代理应执行哪些操作以及使用哪些工具。
  • 过渡:明确进入下一步或结束工作流的标准。

使用严格结构

结构是用于解释意图的最强信号之一:

  • 使用 节 将相关任务分组为逻辑类别,而不暗示顺序。
  • 将 项目符号 用于可独立完成的并行任务。 避免可能引入意外顺序的编号。
  • 对必须按所需顺序发生的操作使用步骤,并仅为真正的工作流保留这些 步骤 。

使任务原子

将多操作指令拆分为清晰分隔的单元。 这种方法减少了歧义并防止模型合并或重新解释任务。

  • 而不是: 提取指标并汇总结果。
  • 使用单独的步骤:
    1. 提取指标。
    2. 汇总发现。

始终指定语气、详细程度和输出格式

如果未指定语气和详细级别,语言模型可能会推断出这些属性,这可能导致模型之间的行为不一致。 例如,指定:

  • 语气:专业、简洁。
  • 输出:每个部分三个项目符号。
  • 仅返回请求的格式;无解释。

Markdown 中的结构说明

为了强调和澄清步骤顺序,请使用 Markdown。

  • 对节标题使用 #、 和 ##### 。
  • 用于 - 未排序列表和 1. 编号列表。 除非步骤顺序很重要,否则使用无序列表,在这种情况下,请使用编号表。
  • 使用反引号 (''''') 突出显示工具或系统名称 (Jira例如 、 TeamsServiceNow、) 。
  • 使用 **将关键指令加粗。

清晰的标题和一致的列表结构有助于模型了解预期的层次结构。 避免以可能导致意外解释的方式混合列表类型。

提供域词汇

定义专用术语、公式、首字母缩略词和数据集特定语言。 此定义可防止错误推理并确保一致的解释。

显式引用功能、知识和操作

清楚地指出每个步骤中涉及的操作、能力或知识来源的名称。

  • 操作:例如,“用于 Jira 获取票证”。
  • Copilot 连接器知识:例如,“用于 ServiceNow KB 帮助文章”。
  • SharePoint 知识:例如,“参考 SharePoint 或 OneDrive 内部文档”。
  • Email Messages:例如,“查看用户电子邮件以获取相关信息”。
  • Teams 消息:例如,“搜索 Teams 聊天历史记录”。
  • 代码解释器:例如,“使用代码解释器生成条形图或饼图”。
  • People knowledge:例如,“使用人员知识获取用户电子邮件”。

对配置的知识源的基础响应

语言模型具有来自训练数据的内置知识。 在许多代理场景中,您希望代理仅依赖于您配置的知识源,而不是模型的内部知识。 此方法可确保响应准确、一致且可追溯到组织数据。

防止模型利用其内置知识的推荐方法是将属性true设置为discourage_model_knowledge代理清单的对象中special_instructions。 启用后,代理会尽最大努力避免从模型知识生成响应,而是依赖于您配置的知识源。 有关详细信息,请参阅 特殊指令对象。

提供示例

示例可帮助代理理解说明。

  • 对于简单场景,无需举例。
  • 对于复杂场景,声明式智能体最适合使用少量提示。 也就是说,举多个例子来说明不同的方面或边缘情况。

通过措辞控制推理

您的措辞表明您希望模型应用多少推理。

深度推理

增加深度:

  • 使用显式推理动词 (分析、推导、评估、证明) 。
  • 添加元推理线索 (一步一步思考、反思、验证逻辑) 。
  • 将任务结构化为多个依赖步骤。
Use deep reasoning. Break the problem into steps, analyze each step, evaluate alternatives, and justify the final decision. Reflect before answering.
Task: Determine the optimal 3-year migration strategy given constraints A, B, and C.

检测何时选择了深度推理:

Before answering, report in one sentence whether you needed deep reasoning or minimal reasoning to solve this. Then provide the final answer only.

适度推理 (平衡)

平衡推理:

  • 要求简洁但结构化的解释。
  • 提供明确的约束,但不提供元推理线索。
Provide a concise but structured explanation. Include a short summary, 3 key drivers, and a final recommendation. No step-by-step reasoning required.
Task: Explain the tradeoffs between solution X and Y.

快速、最小的推理

若要减少深度,请执行以下操作:

  • 信号简洁。 指定短而快速的响应;没有理由/解释。
  • 避免使用分析性动词和多步骤结构。
  • 使用单意图、单阶段命令式表达。
Short answer only. No reasoning or explanation. Provide the final result only.
Task: Extract the product name and renewal date from this paragraph.

避免常见提示失败

请注意以下陷阱及其解决方案,以避免常见故障。

  • 过预切工具使用
    • 问题:模型在没有必要输入的情况下调用工具。
    • 解决方案:添加指令“仅在必要的输入可用时调用工具;否则,请询问用户。”
  • 重复表达
    • 问题:模型逐字重用示例表达。
    • 解决方案:鼓励多样化的回复和自然语言。 请考虑添加多个示例,而不仅仅是一个 (几个镜头的提示) 。 尝试删除示例以节省令牌。
  • 详细说明
    • 问题:模型过度解释或提供过多的格式。
    • 解决方案:若要限制详细程度或格式,请添加约束和简洁示例。

添加最终的自我评估步骤

自我检查步骤可增强完整性,并确保代理在回复之前验证是否符合您的指示。 例如:最终定稿前,请确认 A 部分中的所有项目均显示在摘要中。

在需要时应用稳定标头

当代理出现推理漂移或步骤重新排序的迹象时,添加一个简短的标头,指示模型从字面上解释指令并避免推理。 有关详细信息,请参阅 模式 8:应用文本执行标头以立即保持稳定性。

按照说明迭代

为声明性代理开发指令通常是一个迭代过程。 它通常包含以下步骤:

  1. 按照本文中所述的结构和格式,为您的座席创建说明和对话入场白。
  2. 发布 代理。 负责任的 AI (RAI) 实践已融入验证流程,以确保代理遵守道德标准。 有关详细信息,请参阅:
  3. 测试 代理。
    1. 若要确认代理在接答时带来附加值,请将结果与智能 智能 Microsoft 365 Copilot 副驾驶® 副驾驶®进行比较。
    2. 通过分步指南验证对话发起人是否按预期工作。
    3. 验证代理是否按照提供的说明操作。
    4. 确认妥善处理对话启动器之外的用户提示。
  4. 迭代说明以探索是否可以进一步改进输出。
    • 修改说明以更改代理的行为。
    • 尝试使用 Work IQ Dev Tools 或 Copilot Studio 中支持的配置添加 Web 搜索、OneDrive/SharePoint 或 智能 智能 Microsoft 365 Copilot 副驾驶® 副驾驶® 连接器等知识。

下图说明了用于创建和优化声明性代理指令的迭代过程。

显示创建和优化代理说明的迭代步骤的图表

提示

Work IQ Dev Tools — Work IQ Dev Tools 支持为声明式智能体创建评估,以便您可以衡量指令更改如何影响智能体行为。 为要测试的行为创建评估,然后在优化其指令时针对预置的代理运行它们。 有关详细信息,请参阅 Work IQ 开发工具文档。

示例说明

以下示例说明适用于可帮助解决常见 IT 问题的代理。

# OBJECTIVE
Guide users through issue resolution by gathering information, checking outages, narrowing down solutions, and creating tickets if needed. Ensure the interaction is focused, friendly, and efficient.

# RESPONSE RULES
- Ask one clarifying question at a time, only when needed.
- Present information as concise bullet points or tables.
- Avoid overwhelming users with details or options.
- Always confirm before moving to the next step or ending.
- Use tools only if data is sufficient; otherwise, ask for missing info.

# WORKFLOW

## Step 1: Gather Basic Details
- **Goal:** Identify the user's issue.
- **Action:**
  - Proceed if the description is clear.
  - If unclear, ask a single, focused clarifying question.
    - Example:
      User: "Issue accessing a portal."
      Assistant: "Which portal?"
- **Transition:** Once clear, proceed to Step 2.

## Step 2: Check for Ongoing Outages
- **Goal:** Rule out known outages.
- **Action:**
  - Query `ServiceNow` for current outages.
  - If an outage is found:
    - Share details and ETA.
    - Ask: "Is your issue unrelated? If yes, I can help further."
    - If yes, go to Step 3. If no/no response, end politely.
  - If none, inform the user and go to Step 3.

## Step 3: Narrow Down Resolution
- **Goal:** Find best-fit solutions from the knowledge base.
- **Action:**
  - Search `ServiceNow KB` for related articles.
  - **Iterative narrowing:** Don't list all results. Instead:
    - Ask clarifying questions based on article differences.
    - Eliminate irrelevant options with user responses.
    - Repeat until the best solution is found.
  - Provide step-by-step fix instructions.
  - Confirm: "Did this help? If not, I can go deeper or create a ticket."
    - If more info is provided, repeat this step.
    - If ticket needed, go to Step 4.
    - If resolved/no response, end politely.

## Step 4: Create Support Ticket
- **Goal:** Log unresolved issues.
- **Action:**
  1. Map **category** and **subcategory** from the `sys_choice` SharePoint file.
     - Use only valid pairs. Leave blank if not clear.
  2. Fetch user's UPN (email) with the people capability.
  3. Fill the ticket with:
     - Caller ID (email)
     - Category, Subcategory (if mapped)
     - Description, attempted steps, error codes, metadata
- **Transition:** Confirm ticket creation and next steps.

# OUTPUT FORMATTING RULES
- Use bullets for actions, lists, next steps.
- Use tables for structured data where UI allows.
- Avoid long paragraphs; keep responses skimmable.
- Always confirm before ending or submitting tickets.

# EXAMPLES

## Valid Example
**User:** "I can't connect to VPN."
**Assistant:**
- "Are you seeing a specific error?"
  (User: "DNS server not responding.")
- "Let me check for outages."
  (No outage.)
- "No outages. Searching knowledge base…"
  (Finds articles. Asks: "Are you on office Wi-Fi or home?")
  (User: "Home.")
- "Try resetting your DNS settings. Here's how…"
- "Did this help? If not, I can create a support ticket."

## Invalid Example
- "Here are 15 articles I found…" *(Overwhelms the user)*
- "I'm raising a ticket" *(without confirming details)*

指令模板和设计模式

本节提供可添加到声明性代理指令中的模式和模板。 显示的示例不是规范性的。 将它们用作起点,并使它们适应您的用例要求。

模式 1:将不明确的多任务请求转换为确定性工作流

使用此模式,可以通过定义原子步骤、显式公式和所需验证来消除歧义。 此方法可确保跨模型版本的稳定、可重复的行为。

## Task: Metrics and ROI (Deterministic)

### Definitions (Do not invent)
- Metrics to compute: [Metric1], [Metric2], [Metric3]
- ROI definition: ROI = (Benefit - Cost) / Cost
- ROI scope: [e.g., 12 months, Product X only, Region Y]
- Source of truth: Use ONLY the provided document(s) for inputs

### Steps (Sequential — do not reorder)
Step 1: Locate inputs for [Metric1-3] in the document. Quote the section/table name where each input came from.
Step 2: Compute [Metric1-3] exactly as defined above. If any input is missing, stop and ask ONE question listing what's missing.
Step 3: Compute ROI using the ROI definition above. Do not substitute other ROI formulas.
Step 4: Output ONLY the table in the format below.

### Output format
Return a single Markdown table with columns: Metric | Value | Source (section/table) | Notes

### Final check (Self-evaluation)
Before finalizing: confirm every metric has (a) a value, (b) a source, and (c) no assumptions. If assumptions exist, stop and ask the user.

模式 2:正确的并行结构与顺序结构

通过使用此模式,可确保模型将并行逻辑和顺序逻辑分开。 该模型正确运行工作流,无需添加或重新排序步骤。

Section A — Extract Data
- Extract pricing changes.
- Extract margin changes.
- Extract sentiment themes.

Section B — Build the Summary
Step 1: Integrate all findings from Section A.
Step 2: Produce the 2 page call prep summary.

模式 3:显式决策规则

通过使用此模式,您可以添加显式 if/then 规则,以防止意外的模型解释并强制实施确定性结果。 这种方法阻止了语言模型尝试自行解析模棱两可的条件逻辑,这可能导致混合分支 (“两者都做”) 或选择错误的条件路径。

Read the product report.
Check category performance.
If performance is stable or improving, write the summary section.
If performance declines or anomalies are detected, write the risks/issues section.

模式 4: 输出协定

输出合同提供形状、结构、语气和允许的内容,确保一致性。 如果没有明确的输出约束,您的代理可能会生成过长的解释、过于简洁的响应或不可预知地在版本之间切换。

精度好:

Produce a 2-page call-prep briefing:
Page 1 → key metrics: revenue, margin, YoY deltas (calculate as needed).
Page 2 → top themes, risks, opportunities, customer signals.
Tone: Professional. Reasoning: none unless calculation required.

输出协定:

## Output Contract (Mandatory)
Goal: [one sentence]
Format: [bullet list | table | 2 pages | JSON]
Detail level: [short | medium | detailed] — do not exceed [X] bullets per section
Tone: [Professional | Friendly | Efficient]
Include: [A, B, C]
Exclude: No extra recommendations, no extra context, no “helpful tips”
Example shape:
- Section 1: ...
- Section 2: ...

当输出必须遵循以下内容时,请使用此模式:

  • 精确 (项目符号、表格、JSON、多页摘要) 格式。
  • 指定的详细信息级别 (短、中、详细) 。
  • 合规性、审核或面向客户的模板。
  • 需要跨团队使用一致格式的业务流程。

模式 5:干净的 Markdown 结构

干净、有意的 Markdown 可确保模型能够可靠地解析你的指令。 嵌套不当的列表、不清晰的标题或不一致的格式导致合并步骤、意外的层次结构或折叠的部分。

## Section A — Extract Data
- Extract pricing changes.
- Extract margin changes.
- Extract sentiment themes.

## Section B — Build the Summary (Sequential)
**Step 1:** Integrate findings from Section A.
**Step 2:** Produce the 2 page call prep summary.

模式 6:自评门

通过添加显式自我检查步骤,您可以鼓励模型在响应之前验证完整性、验证与指令的一致性并纠正遗漏。 此步骤提高了一致性和可靠性。

## Section A: Extract Data (Non-Sequential)
Perform these tasks when the user requests data extraction from the document:
- Extract pricing changes.
- Extract margin changes.
- Extract sentiment themes.
Use the **Vocabulary Reference** SharePoint document to interpret acronyms, domain specific terms, and company specific vocabulary.

## Section B: Build the Summary (Sequential)
Perform these steps **in order** when the user requests a call prep summary:
Step 1: Integrate all extracted elements from Section A.
Step 2: Produce a clear, well structured 2 page call prep summary.

## Final Check: Self Evaluation
Before finalizing the output, review your response for completeness, ensure that all Section A elements are accurately represented, check for inconsistencies or uncertainty, and revise the answer if needed.

模式 7:转向自动模式推理

显式推理线索使您可以控制模型应用的思维程度。 如果没有这种指导,您的代理可能会过度解释简单的答案或解释不足复杂的决策。

触发深度推理:

Use deep reasoning. Break the problem into steps, analyze each step, evaluate alternatives, and justify the final decision. Reflect before answering.
Task: Determine the optimal 3-year migration strategy given constraints A, B, and C.

强制快速和最小的推理:

Short answer only. No reasoning or explanation. Provide the final result only.
Task: Extract the product name and renewal date from this paragraph.

当工作流需要时,请使用此模式:

  • 更深入的推理 (规划、评估替代方案、多步骤逻辑) 。
  • 快速检索或提取,只需最少的解释。
  • 在高级摘要和更深入的分析之间切换。
  • 跨多个代理或用例的一致深度。

模式 8:应用文本执行标头以立即保持稳定性

字面执行标头有助于暂时稳定现有代理。 在更新完整指令集时,此模式作为临时修复特别有用。

Always interpret instructions literally.
Never infer intent or fill in missing steps.
Never add context, recommendations, or assumptions.
Follow step order exactly with no optimization.
Respond concisely and only in the requested format.
Do not call tools unless a step explicitly instructs you to do so.

在以下情况下使用此模式:

  • 您观察到代理的响应中有重新排序、添加步骤或过度推理。
  • 在应用更深层次的结构改进之前,你需要快速的短期缓解措施。
  • 你想要诊断是推理还是指令模糊性导致了问题。

模式 9:评估现有声明性代理指令

使用结构化评估提示快速审核现有代理,识别具体弱点,并生成精确的修复。

You are reviewing Data Access (DA) agent instructions for stability.

INPUT
<instructions>
[PASTE CURRENT INSTRUCTIONS]
</instructions>

TASK
Concise audit. Identify ONLY issues and exact fixes.

CHECKS
- Step order: identify ambiguity, missing steps, or merged steps → propose atomic, numbered steps.
- Tool use: identify auto-calls, retries, or tool switching → add "use only in step X; no auto-retry".
- Grounding: detect inference, blending, or citation gaps → add "cite only retrieved; no inference; no cross-document stitching".
- Missing-data handling: if retrieval is empty or conflicting → add "stop and ask the user".
- Verbosity: identify chatty or explanatory output → replace with "return only the requested data/format".
- Contradictions or duplicates: resolve discrepancies; prefer explicit over implied.
- Vague verbs ("verify", "process", "handle", "clean"): replace with precise, observable actions.
- Safety: prohibit step reordering, optimization, or reinterpretation.

OUTPUT (concise)
- Header patch (3–6 lines)
- Top 5 changes (bullet list: "Issue → Fix")
- Example rewrite (≤10 lines) for the riskiest step

在以下情况下使用此模式:

  • 你正在审核行为不一致的现有代理。
  • 你不确定指令集的哪些部分易碎或不明确。
  • 您希望对整个组织中的多个声明式代理有一个可重复的评估过程。
  • 您需要一种快速的方法来确定哪些问题与结构、风格或安全相关。