Directrices para crear o actualizar un complemento de extensión de mensaje para Copilot para Microsoft 365
Importante
- Los complementos para Microsoft Copilot para Microsoft 365 están en versión preliminar y solo funcionan en Microsoft 365 Chat en Microsoft Teams.
- Asegúrese de que Copilot para Microsoft 365 está disponible para su organización. Tiene dos maneras de obtener un entorno de desarrollador para Copilot:
- Un inquilino de Espacio aislado de Microsoft 365 con Copilot (disponible en versión preliminar limitada mediante la pertenencia a TAP).
- Entorno de producción de clientes empresariales con licencias de Microsoft Copilot para Microsoft 365.
Los complementos de Microsoft 365 proporcionan integración con varios productos de Microsoft 365, como Teams y Outlook. La integración ayuda a los usuarios a buscar o crear contenido en sistemas externos. Los complementos de extensión de mensaje permiten que Microsoft Copilot para Microsoft 365 interactúen con las API de otros servicios y software a través de un bot. Con Copilot para Microsoft 365, puede:
- Búsqueda para obtener la información o el registro más recientes. Por ejemplo, el último vale de incidente o los resultados de la encuesta.
- Resumir información basada en varios registros. Por ejemplo, resuma todos los vales de incidentes relacionados con el proyecto Northwind.
Se recomienda compilar o actualizar las extensiones de mensaje existentes para maximizar su utilidad y facilidad de uso en Copilot para Microsoft 365. Las extensiones de mensaje deben admitir uno o varios comandos de búsqueda, ya que Copilot para Microsoft 365 las reconoce como aptitudes que puede ejecutar en nombre del usuario. Además, las extensiones deben cumplir los estándares de cumplimiento, rendimiento, seguridad y experiencia del usuario descritos en este artículo.
Requisitos obligatorios
Los requisitos para compilar complementos de extensión de mensaje para Copilot para Microsoft 365 incluyen:
Definir descripciones
Una buena descripción ofrece un resumen claro y conciso de las características de la aplicación y permite Copilot para Microsoft 365 detectar y ejecutar operaciones de búsqueda de forma eficaz. Cuando un usuario escribe el nombre de la aplicación junto con un verbo, por ejemplo, Buscar vales de Contoso, el complemento de extensión de mensaje debe invocarse desde Copilot para Microsoft 365 (Chat de M365).
Asegúrese de cumplir las instrucciones de descripción que se enumeran en la tabla siguiente:
| Acción | Reason |
|---|---|
|
Anti-Compete: evite usar el nombre de cualquier otro complemento en descripciones cortas y largas. |
|
|
IA responsable: evite el uso de palabras clave inapropiadas o ofensivas. |
|
|
Inyecciones de mensajes: asegúrese de que las descripciones no guían a Copilot para realizar acciones que omitan el funcionamiento normal de la aplicación. Además, la descripción no debe contener símbolos ni texto que indiquen que se puede usar como código para la inyección de mensajes. Evite usar frases, funciones y código que llamen a una aplicación de forma periódica. |
Descripción de la aplicación
Las descripciones de aplicaciones largas y cortas deben ser claras y definir el ámbito de la aplicación. Para representar una aplicación como complemento en Copilot para Microsoft 365, modifique la descripción de la aplicación para que se adapte a los siguientes requisitos de complemento:
- La descripción larga debe explicar claramente la funcionalidad y el uso del complemento de extensión de mensaje en Copilot para Microsoft 365. Por ejemplo, use la nube de Contoso en Copilot para Microsoft 365 para buscar y resumir las tareas.
- La descripción breve debe describir brevemente la funcionalidad de la aplicación en un lenguaje natural y puede incluir el nombre de la aplicación.
En la tabla siguiente se enumeran los ejemplos de descripción breves para cada categoría:
Descripción: crear, buscar, ver incidencias, errores y proyectos.
Ejemplo de descripción de la aplicación:
{
"$schema": "https://developer.microsoft.com/en-us/json-schemas/teams/v1.13/MicrosoftTeams.schema.json",
"version": "1.0.0",
"manifestVersion": "1.13",
"id": "2bxxxxc5-5xxx-4xxx-aXXX-94xxxx8919e5",
"name": {
"short": "Tasks",
"full": "Contoso Tasks"
},
"description": {
"short": "Create, search, view tickets, bugs, and projects",
"full": "Contoso Tasks makes it easy to stay organized. Create, assign, and track tasks individually or collaboratively with your team, and see everything come together in one place."
},
Búsqueda descripción del comando
Descripción del comando asigna la intención y la expresión del usuario al comando de búsqueda dentro de un complemento y debe compilarse en función del análisis de la intención del usuario y las palabras clave. Búsqueda descripciones de comandos deben:
- Céntrese en qué y cómo busca el comando (lista detallada) en lenguaje natural.
- Incluya verbos y sinónimos, si procede.
- Céntrese en las palabras clave que probablemente se usarán en la función de búsqueda de las aplicaciones nativas.
Descripción semántica
La propiedad semanticDescription se usa para proporcionar una descripción detallada de un comando para Copilot para Microsoft 365. La descripción semántica de los comandos admite hasta 5000 caracteres y no se muestra en la interfaz de usuario. Si la semanticDescription propiedad se deja vacía, Copilot para Microsoft 365 usa la información del description campo. Al escribir un semanticDescription, debe incluir información sobre los valores esperados, los límites y los intervalos para el comando.
La semanticDescription propiedad no es un campo obligatorio. Sin embargo, si agrega semanticDescription en el manifiesto de la aplicación, las comprobaciones de validación existentes para obtener descripciones breves, de parámetros y de comandos también se aplican a las descripciones semánticas.
Te recomendamos que revises las siguientes directrices para obtener una descripción semántica para aumentar las posibilidades de que la aplicación pase el proceso de envío de Microsoft Teams Store:
- Evite frases de instrucciones como "si el usuario dice X", "ignore", "delete", "reset", "new instructions", "Answer in Bold" o "Don't print anything". [Corrección obligatoria]
- Evite direcciones URL, emojis o caracteres ocultos, como símbolos hexadecimales, binarios o no convencionales. [Corrección obligatoria]
- Evite errores de gramática y puntuación. [Corrección obligatoria]
- Evite un lenguaje excesivamente detallado, floral o de marketing. [Corrección sugerida]
- Evite notificaciones superlativas como "#1", "increíble" o "mejor". [Corrección sugerida]
En la tabla siguiente se enumeran los ejemplos de comando y descripción semántica para cada categoría:
Descripción: Búsqueda para las tareas de prioridad alta relacionadas con Northwind que vencen mañana.
Ejemplo de descripción de comandos:
"commands": [
{
"id": "Search",
"type": "query",
"title": "Tasks",
"description": "Search for high priority tasks related to Northwind that are due tomorrow.",
"SemanticDescription": "Search for issues, epics, stories, tasks, sub tasks, bugs + additional details."
"initialRun": true,
"fetchTask": false,
"context": [
"commandBox",
"compose",
"message"
],
Descripción del parámetro
Cada comando de extensión de mensaje compatible tiene una propiedad 'parameters' correspondiente que admite hasta cinco parámetros y el primer parámetro debe estar visible en la barra de búsqueda de la extensión de mensaje. Un parámetro debe tener una buena descripción, que debe contener una combinación de parámetros aceptables, enumeraciones, acrónimos y formato de salida.
La propiedad semanticDescription se usa para proporcionar una descripción detallada de un comando para Microsoft Copilot. La descripción semántica de los parámetros admite hasta 2000 caracteres y no se muestra en la interfaz de usuario. Si la semanticDescription propiedad se deja vacía, Copilot usa la información en el description campo . Al escribir un semanticDescription, debe incluir información sobre los valores esperados, los límites y los intervalos para el comando.
Una buena descripción de parámetros explica los requisitos del sistema en un lenguaje natural con formato de salida. A continuación se muestran algunos ejemplos de solicitudes de búsqueda básicas y avanzadas para cada categoría:
Búsqueda básica: Búsqueda para las tareas relacionadas con Northwind.Búsqueda avanzada: Búsqueda para las tareas de prioridad alta relacionadas con Northwind que vencen mañana.
Ejemplo de descripción de parámetros:
"parameters": [
{
"name": "Name",
"title": "Project or Task Name",
"description": "Project name or task name as keyword.",
"inputType": "text"
},
{
"name": "Time",
"title": "Time",
"description": "Date or number of days for which you need tasks for.",
"semanticDescription": "Date or number of days for which you need tasks for. Output: Number",
"inputType": "text"
},
{
"name": "Priority",
"title": "Priority",
"description": "Priority of tasks.",
"semanticDescription": "Priority of tasks. Acceptable values are high, medium, low, NA",
"inputType": "text"
}]
Expresiones compuestas
Nota:
Búsqueda a través del cuadro de diálogo (denominado módulo de tareas en TeamsJS v1.x) no se admite en el chat de M365.
Para M365 Chat, una extensión de mensaje basada en búsqueda debe admitir más de tres expresiones compuestas únicas para realizar una recuperación profunda de información precisa. Para habilitar expresiones compuestas, debe expandir el ámbito de búsqueda para controlar tres o más parámetros de búsqueda actualizando el manifiesto de aplicación (anteriormente denominado manifiesto de aplicación de Teams) y asegúrese de lo siguiente:
Actualice el servicio web para admitir la búsqueda en función de varios parámetros. Para obtener más información sobre cómo responder a las solicitudes de usuario, vea Responder al comando de búsqueda.
Copilot para Microsoft 365 puede pasar una cadena vacía o un valor NULL para los parámetros, que no forman parte de la expresión del usuario, actualice el servicio web para controlar los parámetros.
Una extensión de mensaje admite hasta 10 comandos (9 utilizables) y cada comando tiene una propiedad correspondiente
parametersque admite hasta 5 parámetros.
El código siguiente es un ejemplo de varios parámetros definidos en el manifiesto de la aplicación:
"commands": [
{
"id": "inventorySearch",
"context": [
"compose",
"commandBox"
],
"description": "Search products by name, category, inventory status, supplier location, stock level",
"title": "Product inventory",
"type": "query",
"parameters": [
{
"name": "productName",
"title": "Product name",
"description": "Enter a product name here",
"inputType": "text"
},
{
"name": "categoryName",
"title": "Category name",
"description": "Enter the category of the product",
"inputType": "text"
},
{
"name": "inventoryStatus",
"title": "Inventory status",
"description": "Enter what status of the product inventory. Possible values are 'in stock', 'low stock', 'on order', or 'out of stock'",
"inputType": "text"
},
{
"name": "supplierCity",
"title": "Supplier city",
"description": "Enter the supplier city of product",
"inputType": "text"
},
{
"name": "stockQuery",
"title": "Stock level",
"description": "Enter a range of integers such as 0-42 or 100- (for >100 items). Only use if you need an exact numeric range.",
"inputType": "text"
}
]
},
{
"id": "discountSearch",
"context": [
"compose",
"commandBox"
],
"description": "Search for discounted products by category",
"title": "Discounts",
"type": "query",
"parameters": [
{
"name": "categoryName",
"title": "Category name",
"description": "Enter the category to find discounted products",
"inputType": "text"
}
]
},
{
"id": "revenueSearch",
"context": [
"compose",
"commandBox"
],
"description": "Find products based on their revenue/period",
"title": "Revenue",
"type": "query",
"parameters": [
{
"name": "revenueRange",
"title": "Revenue range",
"description": "Enter 'high' or 'low' or enter a range of integers such as 0-10000 or 5000- using this exact format",
"inputType": "text"
}
]
}
]
Los parámetros de búsqueda deben tener buenas descripciones con parámetros aceptables, enumeraciones, acrónimos y formato de salida. Para obtener más información y ejemplos, vea Descripción de parámetros.
Solicitudes de ejemplo
La samplePrompts propiedad guía a los usuarios sobre cómo usar los distintos complementos dentro de Copilot. Copilot usa las solicitudes de ejemplo para mostrar las solicitudes del usuario. Los mensajes deben ser adaptables a diferentes configuraciones regionales y borrarse en distintos comandos. Las solicitudes de ejemplo están disponibles en las siguientes áreas dentro de Copilot para Microsoft 365:
- Primera experiencia de ejecución (FRE): cuando un usuario instala o habilita un complemento por primera vez.
- Biblioteca de mensajes o Copilot Lab: cuando un usuario busca ayuda con los avisos.
- Sugerencias de complementos: para guiar a los usuarios hacia mejores expresiones.
Nota:
- Si el manifiesto de la aplicación no especifica la
samplePromptspropiedad, no se muestran los mensajes. - La
samplePromptspropiedad es obligatoria para la validación de aplicaciones durante el proceso de envío de la aplicación. - Si define varios comandos para la aplicación, se muestran al usuario un máximo de tres mensajes (uno de cada uno de los tres comandos principales). Las solicitudes giran para proporcionar al usuario un conjunto diverso de mensajes en distintos comandos.
Te recomendamos que sigas estas directrices para aumentar las posibilidades de que la aplicación pase el proceso de envío de Microsoft Teams Store:
- Un complemento debe tener al menos tres mensajes y un máximo de cinco mensajes para cada comando.
- Cada mensaje no debe superar los 128 caracteres.
- Dos comandos dentro del mismo complemento no deben tener mensajes idénticos.
- Las solicitudes de ejemplo deben ser genéricas por naturaleza y no incluir referencias personalizadas. Por ejemplo, nombres de proyecto y nombre de tarea.
- Todas las solicitudes de ejemplo deben ser funcionales y devolver respuestas.
- El símbolo del sistema debe ser relevante para los comandos.
El código siguiente es un ejemplo de la propiedad en el samplePrompts manifiesto de la aplicación:
"composeExtensions": [
{
"canUpdateConfiguration": true,
"botId": "bxxxxxx5-xxxx-xxxx-xxxx-4xxxxxx16599",
"commands": [
{
"id": "orders",
"title": "Orders",
"context": [
"Commandbox",
"Compose"
],
"description": "Search for orders",
"semanticDescription": "Search for orders",
"samplePrompts": [
{
"text": "Search for all orders"
},
{
"text": "Search for orders related to Contoso"
},
{
"text": "Search for all pending orders"
},
{
"text": "Search for all completed ordered for Fabrikam"
}
]
}
]
}
]
Respuesta de tarjeta adaptable
Las extensiones de mensaje responden a una entrada de usuario con una tarjeta adaptable. Una tarjeta adaptable para un complemento de extensión de mensaje debe funcionar de forma eficaz, aparecer enriquecida y cumplir los siguientes requisitos:
La respuesta de tarjeta adaptable debe incluir contenido de tarjeta adaptable e información de la tarjeta de vista previa como parte de la misma plantilla. [Obligatorio]
Ejemplo de plantilla de respuesta de tarjeta adaptable
{ "$schema": "http://adaptivecards.io/schemas/adaptive-card.json", "type": "AdaptiveCard", "version": "1.5", "body": [ { "type": "Container", "items": [ { "type": "TextBlock", "text": "${companyName}", "size": "Medium", "wrap": true, "style": "heading" }, { "type": "TextBlock", "text": "${stockExchange} ${stockSymbol}", "isSubtle": true, "spacing": "None", "wrap": true }, { "type": "TextBlock", "text": "${formattedDate} ${formattedTime}", "wrap": true } ] }, { "type": "Container", "spacing": "None", "items": [ { "type": "ColumnSet", "columns": [ { "type": "Column", "width": "stretch", "items": [ { "type": "TextBlock", "text": "${currentPrice} ", "size": "ExtraLarge", "wrap": true }, { "type": "TextBlock", "text": "${priceChange} ${percentChange}", "color": "${changeColor}", "spacing": "None", "wrap": true } ] }, { "type": "Column", "width": "auto", "items": [ { "type": "FactSet", "facts": [ { "title": "Open", "value": "${openPrice} " }, { "title": "High", "value": "${highPrice} " }, { "title": "Low", "value": "${lowPrice} " } ] } ] } ] } ] } ], "previewCard": { "contentType": "application/vnd.microsoft.card.hero", "content": { "title": "${companyName}", "text": "${stockSymbol}" } } }Además del logotipo de la aplicación, el título, la miniatura y el título de la información, los datos de la tarjeta adaptable deben representar al menos dos fragmentos de información. Puede identificar los campos de los atributos buscados con más frecuencia, como los datos modificados, el autor, el estado y las marcas. [Obligatorio]
La tarjeta adaptable debe presentarse en escritorio, web y móvil (iOS y Android). [Obligatorio]
Una tarjeta adaptable debe contener al menos un botón de acción, pero no más de cuatro botones de acción. [Obligatorio]
Nota:
Los tipos de
imBackacción ,messageBackno se admiten en un objeto de datos.Se recomiendan los siguientes tipos de acción:
Action.OpenUrl: abre una dirección URL especificada desde la tarjeta.Action.ToggleVisibility: muestra u oculta uno o varios elementos de la tarjeta.Action.Execute: recopila los campos de entrada y los envía como una solicitud al servicio de bot.Action.Submit: abre un cuadro de diálogo o vista previa mediante la invocación de tipo en el objeto de datos.
Si un usuario puede cambiar cualquier información de la tarjeta a través del cuadro de diálogo, vista previa o directamente desde la tarjeta, se recomienda la tarjeta adaptable para admitir acciones universales y la actualización automática. [Recomendado]
Las tarjetas adaptables deben incluir una dirección URL como parte de los metadatos, lo que permite que las tarjetas se copien fácilmente de un centro a otro. [Recomendado]
Además de las miniaturas, cualquier imagen de una tarjeta adaptable debe tener un texto alternativo. [Recomendado]
Requisitos técnicos
Para que un complemento se valide, invoque y funcione sin problemas, asegúrese de que cumple los siguientes criterios:
| Criterios | Cumplimiento |
|---|---|
| Versión del manifiesto | La versión del manifiesto de la aplicación debe ser 1.13 o posterior. [Obligatorio] |
| Canal de Microsoft 365 | Para que los usuarios interactúen con la extensión de mensaje desde Outlook, debe agregar el canal de Microsoft 365 al bot. Para obtener más información, vea Agregar canal de Microsoft 365. [Obligatorio] |
| Tiempo de respuesta | El tiempo de respuesta no debe superar los 9 segundos para el 99 por ciento, 5 segundos para el 75 por ciento y 2 segundos para el 50 por ciento. [Obligatorio] |
| Confiabilidad | Las aplicaciones deben mantener una disponibilidad del 99,9 %. Por ejemplo, si Microsoft 365 Chat llama a un complemento 1000 veces, debe proporcionar una respuesta significativa 999 veces. [Obligatorio] |
| Regresiones cero | Si necesita volver a enviar la aplicación para su validación, la funcionalidad de extensión de mensaje existente que funcionaba anteriormente no debe interrumpirse. Este requisito solo se aplica a aplicaciones de proveedor de software independientes (ISV) y no a aplicaciones creadas para su organización. [Obligatorio] |
| Inicio de sesión único (SSO) | Si procede, actualice el registro de la aplicación de Microsoft Entra ID para el inicio de sesión único. [Recomendado] |
| Directiva de seguridad de contenido | Si procede, modifique los encabezados de la directiva de seguridad de contenido. [Recomendado] |
Importante
Si procede, actualice los encabezados de la directiva de seguridad de contenido y X-Frame-Options de acuerdo con Configurar encabezados de directiva de seguridad de contenido.
Ejemplos de código
| Ejemplo de nombre | Descripción | TypeScript |
|---|---|---|
| Extensión de mensaje de inventario de Northwind | En este ejemplo se muestra cómo usar una extensión de mensaje de Teams como complemento en Microsoft Copilot para Microsoft 365. | Ver |
Consulte también
Comentarios
Próximamente: A lo largo de 2024 iremos eliminando gradualmente GitHub Issues como mecanismo de comentarios sobre el contenido y lo sustituiremos por un nuevo sistema de comentarios. Para más información, vea: https://aka.ms/ContentUserFeedback.
Enviar y ver comentarios de