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

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

• 代理必须完成的目标是什么？
• 你认为最终用户将经历哪些工作流？
  • 是否有要合并的业务逻辑？
  • 是否有想要整合的所需最终用户体验？
• 对于每个工作流，是否可以提供代理的分步说明？

如果声明性代理还具有 API 插件作为作，则插件的 OpenAPI 文档可帮助代理了解引用 API 的任何说明。 有关详细信息，请参阅 如何使 OpenAPI 文档在扩展 Copilot 时有效。

本指南适用于使用 Microsoft 365 代理工具包 (Teams 工具包) 或Copilot Studio的演变来创建声明性代理的开发人员和制作者。

指令组件

一组结构良好的指令可确保代理了解其角色、应执行的任务以及如何与用户交互。 下面是声明性代理指令的main组件：

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

此外，在相关时，说明包括：

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

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

代理说明的最佳做法

使用清晰的可作语言

• 专注于 Copilot 应该做什么，而不是要避免什么。
• 使用精确的特定谓词，例如“ask”、“search”、“send”、“检查”或“use”。
• 对示例进行补充 ，以最大程度地减少歧义。
• 在说明中定义组织非标准或唯一的任何术语。

使用转换生成分步工作流

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

• 目标：步骤的目的。
• 作：代理应执行哪些作以及要使用的工具。
• 转换：清除用于移动到下一步或结束工作流的条件。

Markdown 中的结构说明

若要强调步骤顺序并明确步骤顺序，请使用 Markdown。

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

显式引用功能、知识和作

明确标注每个步骤中涉及的作、功能或知识源的名称。

• 作：例如“用于 Jira 提取票证”。
• Copilot 连接器知识：例如，“使用 ServiceNow KB 获取帮助文章”。
• SharePoint 知识：例如，“引用 SharePoint 或 OneDrive 内部文档”。
• Email消息：例如，“检查用户电子邮件中的相关信息”。
• Teams 消息：例如“搜索 Teams 聊天历史记录”。
• 代码解释器：例如，“使用代码解释器生成条形图或饼图”。
• 人员知识：例如，“使用人员知识提取用户电子邮件”。

提供示例

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

• 对于简单方案，无需提供示例。
• 对于复杂方案，声明性代理最适合使用少量提示。 也就是说，提供多个示例来说明不同的方面或边缘情况。

避免常见的提示失败

请注意这些陷阱及其解决方案。

• 过度急切的工具使用
  • 问题：模型无需输入即可调用工具。
  • 解决方案：添加指令“仅在必要时输入可用时调用工具;否则，请询问用户。”
• 重复措辞
  • 问题：模型重用逐字措辞的示例。
  • 解决方案：鼓励不同的响应和自然语言。 请考虑添加多个示例，而不是只添加一个 (几步提示) 。 尝试删除示例以保存令牌。
• 详细解释
  • 问题：模型过度解释或提供过多的格式。
  • 解决方案：若要限制详细程度或格式设置，请添加约束和简洁示例。

循环访问说明

开发声明性代理的说明通常是迭代的，通常包括以下步骤。

1. 按照本文所述的结构和格式为代理创建说明和对话启动程序。
2. 发布 代理。 将负责任的 AI (RAI) 实践集成到验证过程中，以确保代理遵循道德标准。 有关更多信息，请参阅：
   • RAI 验证
   • RAI 工具和做法
   • 由人工智能提供支持的应用
3. 测试 代理。
   1. 若要确认代理在回答时是否具有附加价值，请将结果与智能 Microsoft 365 Copilot 副驾驶®进行比较。
   2. 使用分步指南验证对话初学者是否按预期工作。
   3. 验证代理是否按照提供的说明进行作。
   4. 确认对对话启动程序之外的用户提示进行了适当的处理。
4. 循环访问 说明，了解是否可以进一步改进输出。
   • 修改说明以更改代理的行为。
   • 如果需要，请尝试使用 Agents Toolkit 或 Copilot Studio 添加 Web 搜索、OneDrive/SharePoint 或 智能 Microsoft 365 Copilot 副驾驶® 连接器 (以前Microsoft Graph 连接器) 等知识。

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

示例说明

以下示例说明适用于可帮助解决常见 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)*

相关内容

• 有关使用 Agents Toolkit 创建的声明性代理的示例清单文件，请参阅 声明性代理清单示例。
• 有关如何使用 Copilot Studio 创建声明性代理的信息，请参阅使用代理进行扩展。
• 有关声明性代理的验证要求的信息，请参阅 代理的验证准则。