Directrices para crear y actualizar agentes
Importante
- Los agentes de Microsoft 365 Copilot están en versión preliminar y solo funcionan en Microsoft 365 Copilot.
- Los agentes de extensión de mensajes están en versión preliminar.
- Los agentes de extensiones de mensaje de Microsoft 365 Copilot están en versión preliminar pública para Microsoft Word y PowerPoint.
- Asegúrese de que Microsoft 365 Copilot está disponible para su organización. Tiene dos maneras de obtener un entorno de desarrollador para Microsoft 365 Copilot:
- Un inquilino de Espacio aislado de Microsoft 365 con Microsoft 365 Copilot (disponible en versión preliminar limitada mediante la pertenencia a TAP).
- Un entorno de producción de clientes empresariales con licencias de Microsoft 365 Copilot. Para obtener más información sobre las directrices de validación para que los agentes aumenten su posibilidad de aparecer en team store, consulta directrices de validación para agentes.
Los agentes 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 agentes de extensión de mensajes permiten que Microsoft 365 Copilot interactúen con las API de otros servicios y software a través de un bot. Con Microsoft 365 Copilot, puede:
- Busque 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 Microsoft 365 Copilot. Las extensiones de mensaje deben admitir uno o varios comandos de búsqueda. Dado que Microsoft 365 Copilot los reconoce como aptitudes, puede ejecutar comandos en nombre del usuario.
Definición de descripciones de aplicaciones, comandos y parámetros
[Se debe corregir]
Una buena descripción ofrece un resumen claro y conciso de las características de la aplicación y permite a Microsoft 365 Copilot 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 agente de extensión de mensaje debe invocarse desde Microsoft 365 Copilot.
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 agente en Microsoft 365 Copilot, modifique la descripción de la aplicación para que se adapte a los siguientes requisitos de agente:
- La descripción larga debe explicar claramente la funcionalidad y el uso del agente de extensión de mensajes en Microsoft 365 Copilot. Por ejemplo, use la nube de Contoso en Microsoft 365 Copilot 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.
Los fragmentos de código siguientes muestran 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."
},
Descripción del comando de búsqueda
Descripción del comando asigna la intención y la expresión del usuario al comando de búsqueda dentro de un agente y debe compilarse en función del análisis de la intención del usuario y las palabras clave. Las descripciones de comandos de búsqueda 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
[Buena solución]
La propiedad semanticDescription se usa para proporcionar una descripción detallada de un comando para Microsoft 365 Copilot. 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, Microsoft 365 Copilot 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.
En los fragmentos de código siguientes se muestran los ejemplos de descripción semántica y de comandos para cada categoría:
Descripción: busque tareas de alta prioridad 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"
],
Importante
Para activar el vínculo de inicio de sesión de OAuth en el agente, asegúrese de establecer la initialRun propiedad true en para los comandos de búsqueda dentro del manifiesto de la aplicación.
Descripción del parámetro
Cada comando de extensión de mensaje tiene una propiedad correspondiente parameters , que admite hasta cinco parámetros. 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 365 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, Microsoft 365 Copilot 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.
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: busque tareas relacionadas con Northwind.
- Búsqueda avanzada: busque tareas de alta prioridad 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"
}]
Mejora de la extensión de mensaje para recuperar información a través de expresiones compuestas
[Se debe corregir]
Nota:
No se admite la búsqueda a través del cuadro de diálogo (denominado módulo de tareas en TeamsJS v1.x) en Microsoft 365 Copilot.
Para Microsoft 365 Copilot, 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 mediante la actualización del manifiesto de aplicación (anteriormente denominado manifiesto de aplicación de Teams) y asegurarse 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.
Microsoft 365 Copilot 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
parameters, que admite hasta cinco 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, consulte la descripción del parámetro.
Definición de solicitudes de ejemplo
[Se debe corregir]
La samplePrompts propiedad guía a los usuarios sobre cómo usar los distintos agentes dentro de Microsoft 365 Copilot. Microsoft 365 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 para first run experience (FRE) en Microsoft 365 Copilot cuando un usuario instala o habilita un agente por primera vez.
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.
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"
}
]
}
]
}
]
Creación de respuestas de tarjeta adaptable enriquecidas
[Se debe corregir]
Las extensiones de mensaje responden a una entrada de usuario con una tarjeta adaptable. Una tarjeta adaptable para un agente de extensión de mensajes 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. [Se debe corregir]
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}" } } }Nota:
Los tipos de
imBackacción ymessageBackno 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 la información de la tarjeta a través de un cuadro de diálogo, vista previa o directamente desde la tarjeta, se recomienda que la tarjeta adaptable admita acciones universales y 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]
Agentes de extensión de mensajes en aplicaciones Microsoft 365 Copilot
[Se debe corregir]
Importante
Los agentes de extensión de mensajes de Microsoft 365 Copilot aplicaciones están en versión preliminar privada limitada para Word y PowerPoint. Más detalles que se publicarán después de que se anuncie una versión preliminar pública.
Los agentes personalizan y amplían la experiencia de Microsoft 365 Copilot aportando más aptitudes y conocimientos a Microsoft 365 Copilot para una experiencia de usuario personalizada. Mediante el uso de agentes, que son un subconjunto de agentes, los usuarios pueden integrar funcionalidades adicionales en Microsoft 365 Copilot interactuando con aplicaciones de terceros, ya sea para recuperar o modificar información dentro de esas aplicaciones. Por ejemplo, los agentes de extensión de mensajes facilitan la búsqueda de datos en otras aplicaciones para que Microsoft 365 Copilot puedan presentarlos a petición cuando se active el agente.
Si ha desarrollado un agente para Microsoft 365 Copilot en Teams o copilot.microsoft.com, ya conoce las ventajas que ofrece a los usuarios dentro de su flujo de trabajo.
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 agente en Microsoft 365 Copilot. | Ver |