Los agentes de Copilot son aplicaciones para Microsoft 365

Importante

• Actualmente, los complementos de API solo se admiten como acciones dentro de agentes declarativos. No se habilitan en Microsoft 365 Copilot. Para obtener un ejemplo que muestra cómo agregar un complemento de API a un agente declarativo, consulte Agregar un complemento.
• La funcionalidad está habilitada de forma predeterminada en todos los inquilinos con licencia de Microsoft 365 Copilot. Los administradores pueden deshabilitar esta funcionalidad en función del usuario y del grupo y controlar cómo se aprueban los complementos individuales para su uso y qué complementos están habilitados. Para obtener más información, consulte Administración de agentes de Copilot en aplicaciones integradas.

Al compilar un agente de Copilot, también está creando una aplicación para Microsoft 365. Las aplicaciones para Microsoft 365 comparten un esquema de manifiesto común y un formato de empaquetado, así como procesos y herramientas de administración y distribución unificados. El resultado final es que las aplicaciones y los agentes de Copilot llegan a la audiencia más amplia posible y aparecen contextualmente dentro del flujo de trabajo de los usuarios.

Este artículo le guiará por las partes clave del modelo de aplicaciones de Microsoft 365 para el desarrollo de agentes de Copilot.

Modelo de aplicación para Microsoft 365

El ecosistema de Microsoft 365 está evolucionando hasta convertirse en una plataforma de aplicaciones integrada, donde puede usar un modelo de aplicación común para definir y empaquetar la aplicación. Lo que comenzó como una manera de ampliar las aplicaciones de Teams para que se ejecuten en otras aplicaciones de Microsoft 365 se ha expandido desde entonces para admitir la distribución de conectores de Microsoft Graph, complementos de Outlook y ahora agentes de Copilot.

Paquete de la aplicación

El paquete de la aplicación para Microsoft 365, incluidos los agentes de Copilot, es un archivo ZIP que contiene uno o varios archivos de configuración (manifiesto) e iconos de la aplicación. La lógica de la aplicación y el almacenamiento de datos se hospedan en otro lugar y la aplicación host de Microsoft 365 tiene acceso a ella a través de HTTPS. Enviará el paquete de la aplicación al administrador para publicarlo en su organización o en el Centro de partners para publicarlo en Microsoft AppSource.

Como mínimo, un paquete de aplicación contiene:

• el manifiesto de la aplicación (manifest.json), que describe la configuración de la aplicación, las funcionalidades, los recursos necesarios y los atributos importantes,
• un icono de color grande (color.png), un icono de color completo de 92x92 para mostrar el agente en la interfaz de usuario de Microsoft Copilot y almacenar, y
• un pequeño icono de esquema (outline.png), un icono de 32 x 32 con fondo transparente (no se usa actualmente en Copilot, pero es necesario para pasar la validación)

El paquete de la aplicación también puede contener definiciones de complementos de API y agente declarativo, así como archivos de localización para otros idiomas admitidos.

Iconos de la aplicación

El paquete de la aplicación debe incluir una versión de color y esquema del icono de la aplicación, como archivos .png. Estos iconos tienen requisitos de tamaño específicos para pasar la validación del almacén.

Nota:

Actualmente solo se usa el icono de color para representar los agentes de Copilot al usuario final (tanto como su descripción de la tienda como dentro de Microsoft 365 Copilot interfaz de usuario), pero todavía se requiere un icono de esquema al enviar el paquete de la aplicación a Microsoft AppSource.

Para obtener más instrucciones de diseño sobre los iconos de color y esquema para el paquete de aplicaciones de Microsoft 365, iconos de aplicación para la Tienda Teams y la barra de aplicaciones.

Icono de color

El icono de color representa el agente en la interfaz de usuario de Microsoft Copilot y en los almacenes de aplicaciones del producto (Teams, Outlook, Microsoft 365).

Icono de color:

• Puede ser cualquier color
• Debe tener un total de 192 x 192 píxeles
• Debe tener 96 x 96 píxeles para el propio símbolo (para permitir 48 píxeles de relleno para escenarios de host donde se recorta)
• Debe sentarse sobre un fondo cuadrado totalmente sólido o totalmente transparente

Icono de esquema

El icono de esquema se usa para representar aplicaciones ancladas o activas en la barra de aplicaciones de Teams. Actualmente no se usa para los agentes de Copilot, pero sigue siendo necesario para que el paquete de la aplicación pase la validación.

Icono de esquema:

• Debe tener 32 x 32 píxeles
• Debe ser blanco con un fondo transparente o transparente con un fondo blanco.
• No debe contener relleno adicional alrededor del símbolo

Manifiesto de la aplicación

El manifiesto de aplicación para Microsoft 365 es un archivo JSON que describe la funcionalidad y las características de la aplicación. En esencia, el manifiesto de aplicación para Microsoft 365 es el esquema para compilar aplicaciones de Teams, pero desde entonces se ha expandido (desde la versión 1.13) para definir aplicaciones que se ejecutan en hosts de Microsoft 365, además de Teams.

Si usa Microsoft Copilot Studio para crear un agente declarativo, el manifiesto de aplicación se genera automáticamente en función de la información que proporcione durante el proceso de creación.

Cada manifiesto de aplicación debe incluir la siguiente información:

Campo Manifiesto	Descripción
version	Número de versión de la aplicación, con el formato MAJOR. MENOR. PATCH (estándar de semver ).
id	Identificador único generado para esta aplicación desde el Portal de registro de aplicaciones de Microsoft (apps.dev.microsoft.com), en formato GUID.
desarrollador	Información sobre el desarrollador, incluido el nombre, el sitio web y los vínculos a la directiva de privacidad y los términos de uso. Para las aplicaciones enviadas a AppSource, los valores deben coincidir con el valor proporcionado en el formulario de envío de aplicaciones del Centro de partners.
name	Nombre de la aplicación, tal como se muestra a los usuarios finales en el host de la aplicación.
description	Descripciones cortas y largas de la aplicación para los usuarios. Para las aplicaciones enviadas a AppSource, estos valores deben coincidir con la información de la entrada de AppSource.
Iconos	Rutas de acceso relativas a los archivos de icono de color y esquema.
accentColor	Color que se va a usar con y como fondo para los iconos de esquema, en el valor hexadecimal RGB, por ejemplo #4464ee.
Definiciones de funcionalidades de aplicación específicas	Definición de cada funcionalidad de aplicación, como pestañas personales (staticTabs), extensiones de mensaje (composeExtensions) o bots. Los agentes declarativos y los complementos de API se definen en el nodo copilotAgents .

En el ejemplo siguiente se muestra un manifiesto de aplicación con secciones de marcador de posición al final para las funcionalidades de extensión de mensaje y aplicación de agente declarativo:

{
    "$schema": "https://developer.microsoft.com/en-us/json-schemas/teams/v1.18/MicrosoftTeams.schema.json",
    "manifestVersion": "1.18",
    "version": "1.0.0",
    "id": "00000000-0000-0000-0000-000000000000",
    "developer": {
        "name": "Northwind Traders",
        "websiteUrl": "https://www.example.com",
        "privacyUrl": "https://www.example.com/termofuse",
        "termsOfUseUrl": "https://www.example.com/privacy"
    },
    "icons": {
        "color": "Northwind-Logo-196.png",
        "outline": "Northwind-Logo-32.png"
    },
    "name": {
        "short": "Northwind Inventory",
        "full": "Northwind Inventory App"
    },
    "description": {
        "short": "App allows you to find and update product inventory information",
        "full": "Northwind Inventory is the ultimate tool for managing your product inventory. With its intuitive interface and powerful features, you'll be able to easily find your products by name, category, inventory status, and supplier city. You can also update inventory information with the app."
    },
    "accentColor": "#3690E9",
    "composeExtensions": {
        ...
    },
    "copilotAgents": {
        ...
    }
}

Para obtener más información, consulte la referencia del esquema del manifiesto de aplicación de versión preliminar para desarrolladores.

copilotAgents Definiciones

Los agentes declarativos y los complementos de API tienen sus propios esquemas de definición. Se hace referencia al archivo de definición de un agente declarativo desde el copilotAgents objeto del manifiesto de aplicación.

En el ejemplo siguiente se muestra cómo hacer referencia a un agente declarativo:

    "copilotAgents": {
        "declarativeAgents": [
            {
                "id": "agent1",
                "file": "declarativeAgent1.json"
            }
        ]
    },

Se hace referencia a la definición de un complemento de API desde la definición del agente declarativo.

Tenga en cuenta lo siguiente:

• Actualmente solo se admite una definición de agente declarativo por manifiesto de aplicación. Solo se admite un complemento de API por agente declarativo.

• Cuando se usa Copilot Studio para compilar agentes de Copilot, se genera un único id para cada uno, como parte de la generación general del manifiesto de la aplicación. Al crear agentes con Teams Toolkit o su propio IDE, se asigna usted id mismo, según sus propias convenciones o nombre descriptivo.

Manifiesto del agente declarativo

El manifiesto del agente declarativo incluye instrucciones para las respuestas de Copilot, mensajes de ejemplo de inicio de conversación, orígenes de datos usados para la puesta en tierra y una lista de acciones (aptitudes del complemento de API) que el agente puede realizar.

Para más información, consulte Esquema de manifiesto del agente declarativo para Microsoft 365 Copilot.

Manifiesto del complemento de API

El manifiesto del complemento de API describe las funcionalidades del complemento, incluidas las API que admite y las operaciones que puede realizar. También incluye metadatos como nombre, descripción, versión y una referencia a la definición de OpenAPI de las API REST con las que interactúa. Se puede hacer referencia a los complementos de API desde un manifiesto de agente declarativo que se usará en la experiencia del agente declarativo.

Para más información, consulte Esquema de manifiesto del complemento de API para Microsoft 365 Copilot.

Localización del agente

La forma en que localiza un agente de Copilot es ligeramente diferente de cómo localizar otras funcionalidades (como pestañas, bots y extensiones de mensaje) en el manifiesto de la aplicación.

Usará el mismo archivo de localización (por idioma) para las funcionalidades de aplicaciones clásicas de Teams y el agente de Copilot. Sin embargo, aunque se hace referencia a todos los demás campos de manifiesto de aplicación mediante expresiones JSONPath en los archivos de idioma, simplemente se hace referencia a los campos relacionados con el agente de Copilot mediante claves de diccionario. A diferencia de las funcionalidades de aplicaciones clásicas de Teams, que usan cadenas de idioma predeterminadas en el propio manifiesto de la aplicación, los agentes de Copilot localizados requieren un archivo de idioma para el idioma predeterminado, así como para cada idioma adicional.

En los pasos siguientes se muestra cómo admitir idiomas adicionales (más allá del valor predeterminado) para los agentes de Copilot.

1. Actualizar los manifiestos del agente de Copilot con claves tokenizadas

Actualice los manifiestos del complemento de API o agente declarativo con claves tokenizadas (indicadas con corchetes dobles, por ejemplo [[PLUGIN_NAME]]) para los valores de campo que desee localizar. Las claves de localización coinciden mucho con esta expresión regular: ^[a-zA-Z_][a-zA-Z0-9_]*$

En el ejemplo siguiente se muestra un manifiesto de agente declarativo con valores tokenizados para su nombre y descripción:

{
    "$schema": "https://developer.microsoft.com/json-schemas/copilot/declarative-agent/v1.0/schema.json",
    "name": "[[DA_Name]]",
    "description": "[[DA_Description]]",
    "instructions": "# You are an assistant..."
}

2. Agregar localizationInfo al manifiesto de la aplicación

Agregue la localizationInfo sección al manifiesto de la aplicación, con etiquetas de idioma y rutas de acceso relativas a cada archivo de idioma admitido dentro del paquete de la aplicación.

Si el agente de Copilot admite más de un idioma, debe especificar un archivo de idioma independiente para cada idioma admitido, incluido el idioma predeterminado.

En el ejemplo siguiente se muestra la sección de información de localización en un manifiesto de aplicación:

"localizationInfo": {
    "defaultLanguageTag": "en",
    "defaultLanguageFile": "en.json",
    "additionalLanguages": [
        {
            "languageTag": "fr",
            "file": "fr.json"
        }
    ]
},

Si el agente de Copilot no admite idiomas adicionales, las cadenas de idioma predeterminadas se representan en el propio archivo de manifiesto de la aplicación. (Los paquetes de aplicaciones de un solo idioma no requieren un archivo de idioma independiente para el idioma predeterminado).

3. Crear un archivo de localización para cada idioma adicional

Cree un archivo de localización para cada idioma compatible adicional con valores para las claves tokenizadas, con los nombres de archivo especificados (para defaultLanguageFile y file las propiedades) en el manifiesto de la aplicación del paso anterior.

En el ejemplo siguiente se muestra un archivo de idioma, fr.json, con cadenas localizadas para un agente de Copilot y pestañas personales:

{
    "$schema": "https://developer.microsoft.com/json-schemas/teams/vDevPreview/MicrosoftTeams.Localization.schema.json`",
    "name.short": "Agent de Communications",
    "name.full": "Agent pour les Communications",
    "description.short": "Outils pour les professionnels de la communication",
    "description.full": "Outils pour les professionnels de la communication Contoso, y compris la galerie de ressources et les assistants personnels",
    "localizationKeys": {
        "DA_Name": "Agent de Communications",
        "DA_Description": "Un assistant pour les professionnels de la communication et des relations publiques chez Contoso."
    },
    "staticTabs[0].name": "Accueil",
    "staticTabs[1].name": "Galerie de ressources",
    "staticTabs[2].name": "À propos de Contoso"
}

Campos localizables en el manifiesto de aplicación

Para cada archivo de idioma, especifique las siguientes propiedades del esquema de localización de la aplicación que se deben localizar:

Campo Manifiesto	Descripción	Longitud máxima	Obligatorio
@schema	Dirección URL del esquema de localización. Para los agentes de Copilot, use devPreview: https://developer.microsoft.com/en-us/json-schemas/teams/vDevPreview/MicrosoftTeams.Localization.schema.json. La versión del esquema de manifiesto debe ser la misma para los archivos de manifiesto y localización de la aplicación.		✔️
name.short	Reemplaza el nombre corto del manifiesto de aplicación por el valor proporcionado.	30 caracteres	✔️
name.full	Reemplaza el nombre completo del manifiesto de aplicación por el valor proporcionado.	100 caracteres	✔️
description.short	Reemplaza la breve descripción del manifiesto de aplicación por el valor proporcionado.	80 caracteres	✔️
description.full	Reemplaza la descripción completa del manifiesto de la aplicación por el valor proporcionado.	4000 caracteres	✔️
Pares clave-valor para cadenas localizadas en agentes de Copilot	Para los agentes de Copilot, use claves tokenizadas (como se especifica en la aplicación manifest.json, pero sin corchetes dobles) con sus valores localizados. Por ejemplo: "DA_Name": "Agent de Communications"
Pares JSONPath/value para cadenas localizadas de cualquier otro componente de la aplicación	Para todos los demás componentes de aplicación (clásicos de Teams), use expresiones JSONPath como claves para los valores localizados. Por ejemplo: "staticTabs[0].name": "Accueil"

Para obtener más información, consulte Localización de la aplicación (Microsoft Teams) y la referencia del esquema de localización.

Campos localizables en el manifiesto del agente declarativo

Los campos siguientes son localizables dentro del manifiesto del agente declarativo:

Campo Manifiesto	Descripción	Longitud máxima	Obligatorio
name	Nombre del agente declarativo. Debe contener al menos un carácter que no sea de espacio en blanco.	100 caracteres	✔️
description	Descripción del agente declarativo. Debe contener al menos un carácter que no sea de espacio en blanco.	1000 caracteres	✔️
conversation_starters	Lista (matriz) de ejemplos de preguntas que el agente declarativo puede responder, donde cada ejemplo está representado por un objeto con title y text, que son localizables.	6 objetos de la matriz

Para obtener más información, consulte Referencia del manifiesto del agente declarativo.

Campos localizables en el manifiesto del complemento de API

Los campos siguientes son localizables dentro del manifiesto del complemento de API:

Campo Manifiesto	Descripción	Longitud máxima	Obligatorio
name_for_human	Un nombre corto y legible para el complemento. Debe contener al menos un carácter que no sea de espacio en blanco.	20 caracteres	✔️
description_for_model	Descripción del complemento que se proporciona al modelo, incluido para qué es el complemento y en qué circunstancias son pertinentes sus funciones.	2 048 caracteres
description_for_human	Descripción legible del complemento.	100 caracteres	✔️
logo_url	Dirección URL que se usa para capturar un logotipo que puede usar el orquestador.
legal_info_url	Dirección URL absoluta que busca un documento que contiene los términos de servicio del complemento.
privacy_policy_url	Dirección URL absoluta que busca un documento que contiene la directiva de privacidad del complemento.

Para obtener más información, consulte Referencia del manifiesto del complemento de API.

Vea también

• Administración de la extensibilidad de Microsoft 365 Copilot
• Publicación de agentes para Microsoft 365 Copilot