Escribir instrucciones eficaces para agentes declarativos

Los agentes declarativos son versiones personalizadas de Microsoft 365 Copilot que le ayudan a crear experiencias personalizadas mediante la declaración de instrucciones, acciones y conocimientos específicos. Para escribir instrucciones eficaces para el agente declarativo, tenga en cuenta las siguientes preguntas:

• ¿Cuál es el objetivo que debe lograr el agente?
• ¿Por qué flujos de trabajo se imaginan los usuarios finales?
  • ¿Hay lógica de negocios que le gustaría incorporar?
  • ¿Hay alguna experiencia de usuario final deseada que le gustaría incorporar?
• Para cada flujo de trabajo, ¿puede proporcionar instrucciones paso a paso para el agente?

Si el agente declarativo también tiene complementos de API como acciones, el documento de OpenAPI del complemento ayuda al agente a comprender las instrucciones que hacen referencia a la API. Para obtener más información, consulte How to make an OpenAPI document effective in extending Copilot (Cómo hacer que un documento de OpenAPI sea efectivo para ampliar Copilot).

Esta guía se aplica a los desarrolladores y creadores que usan microsoft 365 Agents Toolkit (una evolución del kit de herramientas de Teams) o Copilot Studio para crear agentes declarativos.

Componentes de instrucciones

Un conjunto bien estructurado de instrucciones garantiza que el agente comprenda su rol, las tareas que debe realizar y cómo interactuar con los usuarios. Los siguientes son los componentes principales de las instrucciones del agente declarativo:

• Objetivo
• Directrices generales, incluidas las instrucciones generales, el tono y las restricciones
• Aptitudes

Además, cuando corresponda, las instrucciones incluyen:

• Instrucciones detalladas
• Control de errores y limitaciones
• Comentarios e iteración
• Ejemplos de interacción
• Términos no estándar
• Seguimiento y cierre

En el diagrama siguiente se muestran los componentes principales de las instrucciones del agente declarativo.

Procedimientos recomendados para las instrucciones del agente

Uso de un lenguaje que permite acciones claras

• Céntrese en lo que Copilot debe hacer, no en lo que debe evitar.
• Use verbos precisos y específicos, como "ask", "search", "send", "check" o "use".
• Complementar con ejemplos para minimizar la ambigüedad.
• Defina los términos que no sean estándar o únicos para la organización en las instrucciones.

Creación de flujos de trabajo paso a paso con transiciones

Divida los flujos de trabajo en pasos modulares, no ambiguos y no de confianza. Cada paso debe incluir:

• Objetivo: el propósito del paso.
• Acción: qué debe hacer el agente y qué herramientas usar.
• Transición: borre los criterios para pasar al paso siguiente o finalizar el flujo de trabajo.

Instrucciones de estructura en Markdown

Para proporcionar énfasis y claridad sobre el orden de los pasos, use Markdown.

• Use #, ##y ### para los encabezados de sección.
• Use - para listas no ordenadas y 1. para listas numeradas. Use listas no ordenadas a menos que el orden de los pasos sea importante en cuyo caso use listas numeradas.
• Resalte los nombres de la herramienta o del sistema (por ejemplo, Jira, ServiceNow, Teams) mediante los ticks (''''').
• Haga que las instrucciones críticas se negritan con **.

Hacer referencia explícitamente a funcionalidades, conocimientos y acciones

Llame claramente a los nombres de las acciones, funcionalidades o orígenes de conocimiento implicados en cada paso.

• Acciones: por ejemplo, "Usar Jira para capturar vales".
• Conocimientos del conector de Copilot: por ejemplo, "Usar ServiceNow KB para artículos de ayuda".
• Conocimientos de SharePoint: por ejemplo, "Referencia a documentos internos de SharePoint o OneDrive".
• Email mensajes: por ejemplo, "Comprobar los correos electrónicos del usuario para obtener información relevante".
• Mensajes de Teams: por ejemplo, "Historial de chat de Search Teams".
• Intérprete de código: por ejemplo, "Use code interpreter to generate bar or pie charts".
• Personas conocimiento: por ejemplo, "Use people knowledge to fetch user email".

Proporcionar ejemplos

Los ejemplos ayudan al agente a comprender las instrucciones.

• Para escenarios sencillos, no es necesario dar ejemplos.
• En escenarios complejos, los agentes declarativos funcionan mejor con una solicitud de pocas capturas. Es decir, dé más de un ejemplo para ilustrar diferentes aspectos o casos perimetrales.

Evitar errores de aviso comunes

Tenga en cuenta estos problemas y sus soluciones.

• Uso excesivo de herramientas
  • Problema: el modelo llama a herramientas sin las entradas necesarias.
  • Solución: Agregue la instrucción "Solo llame a la herramienta si hay entradas disponibles; de lo contrario, pregunte al usuario."
• Expresiones repetitivas
  • Problema: el modelo reutiliza expresiones textuales de ejemplo.
  • Solución: Fomente respuestas variadas y lenguaje natural. Considere la posibilidad de agregar más de un ejemplo en lugar de solo uno (petición de pocas tomas). Experimente con la eliminación del ejemplo para guardar en tokens.
• Explicaciones detalladas
  • Problema: el modelo explica o proporciona un formato excesivo.
  • Solución: para limitar la verbosidad o el formato, agregue restricciones y ejemplos concisos.

Iteración en las instrucciones

El desarrollo de instrucciones para agentes declarativos suele ser iterativo y normalmente consta de los pasos siguientes.

1. Cree instrucciones y inicios de conversación para el agente siguiendo la estructura y el formato descritos en este artículo.
2. Publique el agente. Las prácticas de inteligencia artificial responsable (RAI) se integran en el proceso de validación para garantizar que los agentes mantengan estándares éticos. Para más información, vea:
   • Validación de RAI
   • Herramientas y prácticas de RAI
   • Aplicaciones con tecnología de inteligencia artificial
3. Pruebe el agente.
   1. Para confirmar que el agente aporta valor agregado al responder, compare los resultados con Microsoft 365 Copilot.
   2. Compruebe que los inicios de conversación funcionan según lo esperado con la guía paso a paso.
   3. Compruebe que el agente actúa según las instrucciones proporcionadas.
   4. Confirme que las solicitudes del usuario fuera de los inicios de la conversación se controlan correctamente.
4. Recorre en iteración las instrucciones para explorar si puede mejorar aún más la salida.
   • Modifique las instrucciones para cambiar el comportamiento del agente.
   • Pruebe a agregar conocimientos como la búsqueda web, OneDrive/SharePoint o conectores de Microsoft 365 Copilot (anteriormente conectores de Microsoft Graph), si es necesario mediante agents Toolkit o Copilot Studio.

En el diagrama siguiente se muestra el proceso iterativo para crear y refinar instrucciones de agente declarativo.

Instrucciones de ejemplo

Las instrucciones de ejemplo siguientes son para un agente que puede ayudar a resolver problemas comunes de TI.

# 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)*

Contenido relacionado

• Para obtener un archivo de manifiesto de ejemplo para un agente declarativo creado con Agents Toolkit, consulte Ejemplo de manifiesto de agente declarativo.
• Para obtener información sobre cómo usar Copilot Studio para crear agentes declarativos, consulte Extensión con agentes.
• Para obtener información sobre los requisitos de validación de los agentes declarativos, vea Directrices de validación para agentes.