Compartir a través de

Compilación de complementos de API para Microsoft 365 Copilot con la biblioteca de JavaScript de Office (versión preliminar)

Nota:

La característica de desarrollo descrita en este artículo está en versión preliminar. Le recomendamos que experimente con esta característica, pero no debe usarse en un complemento de producción. Las siguientes son las limitaciones durante la versión preliminar inicial:

  • La característica solo está habilitada para Office en Windows y Office en la Web. Estamos trabajando para ofrecer soporte técnico a Office en Mac.
  • La característica solo está habilitada para Excel, PowerPoint o Word. Estamos trabajando para ofrecer soporte técnico a Outlook.

Un complemento para un agente declarativo puede llamar a las API de la biblioteca de JavaScript de Office para realizar operaciones de lectura y escritura en el contenido y los metadatos de un documento de Office que está abierto actualmente en una aplicación de Office. Esta capacidad permite a Copilot trabajar con documentos de Office de maneras precisas y sin errores que, de lo contrario, requerirían un complemento de Office.

Relación de los agentes de Copilot con el marco de complementos de Office

Tanto los complementos de Office como los complementos de agente declarativo llaman a las API en la biblioteca de JavaScript de Office y una extensión de Microsoft 365 que usa la biblioteca puede incluir un complemento, un complemento o ambos. El mejor enfoque depende de los escenarios de usuario que la extensión debe habilitar.

  • Si la extensión debe proporcionar acciones simples y rápidas que no necesitan parámetros pasados, incluya solo un complemento con botones o menús personalizados de la cinta de opciones, denominados comandos de complemento.
  • Si la extensión necesita una experiencia de panel, necesita que el usuario configure la configuración, debe mostrar metadatos sobre el contenido del documento de Office o necesita una experiencia similar a una página por cualquier otro motivo, incluya un complemento con un panel de tareas.
  • Si la extensión necesita proporcionar acciones complejas que requieran parámetros pasados en tiempo de ejecución o necesiten una interfaz de lenguaje natural, incluya un agente de Copilot.

Escenarios

A continuación se muestran algunas maneras seleccionadas en las que un agente de Copilot que llama a las API de la biblioteca de JavaScript de Office mejora el valor de una extensión de Microsoft 365.

  • Análisis de contenido: Un agente se puede usar para analizar el contenido de un documento, una presentación o una hoja de cálculo y tomar medidas en función de lo que encuentre. Estos son algunos ejemplos.

    • Un agente analiza una solicitud de propuesta (RFP) y, a continuación, captura las respuestas a las preguntas del RFP desde un sistema back-end. El usuario simplemente pide al agente que "rellene las respuestas que conoce a las preguntas".
    • Un agente analiza un documento, o una tabla de una hoja de cálculo, para el contenido que implica que se deben realizar ciertas acciones, ya sea en el propio documento o en otro lugar de los sistemas empresariales del cliente. El usuario podría pedir al agente que "revise el documento de los elementos que faltó en la lista de auditoría".

  • Inserción de datos de confianza: Si hace una pregunta a un motor de IA típico, combina información que encuentra y compone una respuesta; un proceso que puede introducir imprecisiones. Pero un agente de Copilot basado en un complemento puede insertar datos sin cambios desde un origen de confianza. Por ejemplo:

    • Considere la posibilidad de un agente que permita la inserción de investigaciones legales en Word donde se pueda editar. Un usuario pregunta al agente "¿En qué circunstancias puede un arrendador romper unilateralmente una concesión de espacio residencial en Indiana?" A continuación, el agente captura el contenido, sin cambios, de los precedentes y estatutos, y lo inserta en el documento.
    • Considere la posibilidad de un agente que administre el inventario de recursos digitales. En el chat del agente de Copilot, un usuario pregunta "Insertar una tabla de nuestras fotos de color con el nombre de cada una, el número de veces que se descargó y su tamaño en megabytes, ordenados por orden de la mayoría descargados". A continuación, el agente captura estos datos, sin cambios, del sistema de registro e inserta la tabla en una hoja de cálculo de Excel.

Cuando el agente se combina con un complemento, se habilitan aún más escenarios. Incluir un agente de Microsoft 365 Copilot con un complemento de Office proporciona al menos dos ventajas al complemento:

  • Copilot se convierte en una interfaz de lenguaje natural para la funcionalidad del complemento.
  • El agente puede pasar parámetros al JavaScript que invoca, lo que no es posible cuando se invoca un comando de función en un complemento desde un botón o elemento de menú.

Aprender a usar el complemento es una manera de que un agente pueda mejorar un complemento. Cuando un usuario necesita realizar varios pasos o tareas con el complemento para lograr un objetivo, la interfaz de chat de Copilot puede facilitar el proceso de introducción al complemento. Por ejemplo, considere una firma legal que necesita tener una lista de preguntas que se deben responder sobre cada concesión que prepara. La creación de esta lista de preguntas puede llevar mucho tiempo y consumir mucho trabajo. Pero se puede pedir a un agente de Copilot que genere un primer borrador de lista de preguntas y que las inserte en un documento de Word mediante la biblioteca de JavaScript de Office.

Creación del primer complemento de la biblioteca de JavaScript de Office

Estos son los pasos principales para crear un complemento de API para un agente de Copilot que llama a las API de la biblioteca de JavaScript de Office.

Requisitos previos

Cree el proyecto

Empiece por crear un agente declarativo básico.

  1. Abra Visual Studio Code.

  2. Seleccione Microsoft 365 Agents Toolkit en la barra de actividad.

  3. Seleccione Crear un nuevo agente o aplicación.

    Captura de pantalla del botón Crear un nuevo agente o aplicación en la barra de aplicaciones de Microsoft 365 Agents Toolkit

  4. Seleccione Agente declarativo.

    Captura de pantalla de las opciones de Nuevo proyecto con el Agente declarativo en la parte superior.

  5. Seleccione Sin acción para crear un agente declarativo básico.

  6. En la lista Carpeta del área de trabajo, seleccione Carpeta predeterminada para almacenar la carpeta raíz del proyecto en la ubicación predeterminada o vaya a una carpeta donde quiera colocar el nuevo proyecto de agente.

  7. Escriba Excel Agent como nombre de la aplicación y presione Entrar.

  8. El proyecto se abre en una nueva ventana de Visual Studio Code. Cierre la ventana de Visual Studio Code original.

Configuración del manifiesto

Los pasos siguientes configuran el manifiesto.

  1. Abra el archivo manifest.json en la carpeta appPackage .

  2. Debe usar la versión preliminar del esquema de manifiesto, por lo que debe reemplazar las $schema propiedades y manifestVersion por lo siguiente.

    "$schema": "https://developer.microsoft.com/json-schemas/teams/vDevPreview/MicrosoftTeams.schema.json",
"manifestVersion": "devPreview",

  3. En la raíz del manifiesto, agregue la siguiente propiedad de autorización . Esta propiedad concede al agente permiso para leer y escribir en documentos de Office.

    "authorization": {
  "permissions": {
    "resourceSpecific": [
      {
        "name": "Document.ReadWrite.User",
        "type": "Delegated"
      }
    ]
  }
}

  4. En la raíz del manifiesto, agregue la siguiente propiedad extensiones . Sobre este código, tenga en cuenta lo siguiente.

    • La requirements.scopes propiedad garantiza que el agente solo está disponible en Excel, no en otras aplicaciones de Office.
    • El objeto de runtimes configura el entorno de ejecución de JavaScript que Usa Office para ejecutar las API de biblioteca de JavaScript de Office que invoca el agente.
    • La code.script propiedad especifica la dirección URL de un archivo JavaScript que contiene las funciones que llaman a las API de la biblioteca de JavaScript de Office. Ese mismo archivo contiene una invocación del método Office.actions.associate para asignar la función a un identificador de acción. Este archivo se crea en un paso posterior.
    • La code.page propiedad especifica la dirección URL de una página web que contiene una etiqueta incrustada <script> que carga el archivo al que se hace referencia en la code.page propiedad . Este archivo se crea en un paso posterior.
    • El objeto en tiempo de ejecución incluye una actions matriz que incluye un objeto de acción.
    • El valor de la actions.id propiedad es el mismo identificador de acción que se pasa a la llamada de associate.
    • La actions.type propiedad se establece en executeDataFunction, que es el tipo que puede aceptar parámetros cuando copilot lo invoca.
    "extensions": [
  {
    "requirements": {
      "scopes": [
        "workbook"
      ]
    },
    "runtimes": [
      {
        "id": "ContosoAgentRuntime",
        "type": "general",
        "code": {
          "page": "https://localhost:3000/commands.html",
          "script": "https://localhost:3000/commands.js"
        },
        "lifetime": "short",
        "actions": [
          {
            "id": "FillColor",
            "type": "executeDataFunction"
          }
        ]
      }
    ]
  }
]

La documentación de referencia del JSON del manifiesto se encuentra en La referencia del esquema del manifiesto de aplicación de Microsoft 365.

Configuración del agente declarativo

  1. Abra el archivo declarativeAgent.json en la carpeta appPackage .

  2. Reemplace su contenido por el código siguiente. Sobre este JSON, tenga en cuenta lo siguiente:

    • La actions.id propiedad de este archivo es el identificador colectivo de todas las funciones del archivo especificado en actions.file. Normalmente no debe coincidir con en extensions.runtimes.actions.id el manifiesto, que es el identificador de una acción específica.
    • El archivo que especifique en la actions.file propiedad se creará en un paso siguiente posterior.
    {
  "$schema": "https://developer.microsoft.com/json-schemas/copilot/declarative-agent/v1.4/schema.json",
  "version": "v1.4",
  "name": "Excel Agent",
  "description": "Agent for working with Excel cells.",
  "instructions": "You are an agent for working with an add-in. You can work with any cells, not just a well-formatted table.",
  "conversation_starters": [
    {
      "title": "Change cell color",
      "text": "I want to change the color of cell B2 to orange"
    }
  ],
  "actions": [
    {
      "id": "ExcelActions",
      "file": "Office-API-local-plugin.json"
    }
  ]
}

La documentación de referencia de los agentes declarativos se encuentra en el esquema de agente declarativo 1.4 para Microsoft 365 Copilot.

Configuración del complemento

  1. Cree un archivo en la carpeta appPackage y asígnele el nombre asignado a la actions.file propiedad en el archivo declarativeAgent.json : Office-API-local-plugin.json.

  2. Pegue el siguiente contenido en el archivo. Sobre este JSON, tenga en cuenta los detalles siguientes:

    • El archivo de configuración del complemento de API especifica las funciones del complemento en el sentido de las acciones del agente, no las funciones de JavaScript. Incluye las instrucciones para cada acción. También configura el tiempo de ejecución para Copilot. (Ha configurado el tiempo de ejecución de Office en el manifiesto en un paso anterior).
    • functions.name debe coincidir con la extensions.runtimes.actions.id propiedad del manifiesto del complemento: FillColor.
    • La runtimes.run_for_functions matriz debe incluir la misma cadena functions.name que o una cadena comodín que coincida con ella.
    • La runtimes.spec.local_endpoint propiedad especifica que la función de JavaScript asociada a la FillColor cadena está disponible en la biblioteca de JavaScript de Office, en lugar de en algún punto de conexión REST.
    {
  "$schema": "https://developer.microsoft.com/json-schemas/copilot/plugin/v2.3/schema.json",
  "schema_version": "v2.3",
  "name_for_human": "Excel Agent",
  "description_for_human": "Excel actions in agent",
  "namespace": "addInFunction",
  "functions": [
    {
      "name": "FillColor",
      "description": "FillColor changes a single cell location to a specific color.",
      "parameters": {
        "type": "object",
        "properties": {
          "Cell": {
            "type": "string",
            "description": "A cell location in the format of A1, B2, etc.",
            "default": "B2"
          },
          "Color": {
            "type": "string",
            "description": "A color in hex format, e.g., #30d5c8",
            "default": "#30d5c8"
          }
        },
        "required": [
          "Cell",
          "Color"
        ]
      },
      "returns": {
        "type": "string",
        "description": "A string indicating the result of the action."
      },
      "states": {
        "reasoning": {
          "description": "`FillColor` changes the color of a single cell based on the grid location and a color value.",
          "instructions": "The user will pass ask for a color that isn't in the hex format needed in most cases, make sure to convert to the closest approximation in the right format."
        },
        "responding": {
          "description": "`FillColor` changes the color of a single cell based on the grid location and a color value.",
          "instructions": "If there is no error present, tell the user the cell location and color that was set."
        }
      }
    }
  ],
  "runtimes": [
    {
      "type": "LocalPlugin",
      "spec": {
        "local_endpoint": "Microsoft.Office.Addin"
      },
      "run_for_functions": [
        "FillColor"
      ]
    }
  ]
}

La documentación de referencia de los complementos de API se encuentra en el esquema de manifiesto del complemento de API 2.3 para Microsoft 365 Copilot.

Creación de las funciones de JavaScript

  1. En la raíz del proyecto, cree una carpeta denominada src y, a continuación, cree una subcarpeta bajo los comandos con nombre.

  2. En la carpeta de comandos , cree un archivo denominado commands.ts y asígnele el siguiente contenido. Tenga en cuenta los siguientes detalles sobre este código.

    • La fillColor función establece el color de fondo de la celda especificada en el color especificado. Llama a objetos y métodos de la biblioteca de JavaScript de Office, que se carga en el entorno de ejecución de JavaScript mediante un archivo que se crea en un paso posterior.
    • El primer parámetro del associate método debe coincidir exactamente con la extensions.runtimes.actions.id propiedad del manifiesto y con la functions.name propiedad del JSON de complementos de API.
    • El message parámetro es un objeto pasado por el entorno de ejecución de Copilot al runtime de JavaScript en Office. Se trata de un objeto que contiene la dirección de celda y los parámetros de color que el usuario especificó en un símbolo del sistema de lenguaje natural, como "Establecer la celda C4 en verde".
    async function fillColor(cell, color) {
  // @ts-ignore
  await Excel.run(async (context) => {
    context.workbook.worksheets.getActiveWorksheet().getRange(cell).format.fill.color = color;
    await context.sync();
  })
}
// @ts-ignore
Office.onReady((info) => {
  // @ts-ignore
  Office.actions.associate("FillColor", async (message) => {
    const { Cell: cell, Color: color } = JSON.parse(message);
    await fillColor(cell, color);
    return "Cell color changed.";
  })
});

  3. En la carpeta de comandos , cree un archivo denominado commands.html y asígnele el siguiente contenido. Este archivo es necesario porque los archivos de JavaScript no se pueden cargar directamente en el tipo de tiempo de ejecución que Office usa para los complementos de api de Copilot. En su lugar, un archivo HTML con un <script> elemento carga JavaScript. Tenga en cuenta los siguientes detalles sobre este archivo.

    • Dado que el único propósito del archivo es cargar otros archivos, el <body> elemento está vacío. El archivo no tiene interfaz de usuario y nunca se muestra a los usuarios.
    • Carga el archivo office.js, que es la biblioteca de JavaScript de Office, desde un servidor de Microsoft.
    • No tiene un <script> elemento para cargar un archivo commands.js (transpilado desde el commands.ts que creó) porque este <script> elemento se agrega en tiempo de compilación mediante un archivo que se agrega en un paso posterior.
    • Cuando el proyecto se compila y sirve en un servidor, la dirección URL de este archivo HTML coincide con el valor de la extensions.runtimes.code.page propiedad en el manifiesto. Consulte Configuración del manifiesto anteriormente en este artículo.
    <html>

<head>
    <meta charset="UTF-8" />
    <meta http-equiv="X-UA-Compatible" content="IE=Edge" />

    <!-- Office JavaScript API -->
    <script type="text/javascript" src="https://appsforoffice.microsoft.com/lib/1.1/hosted/office.js"></script>
</head>

<body>
</body>

</html>

Copia de archivos de configuración del proyecto

Office usa la infraestructura de complementos de Office para ejecutar complementos de API para la biblioteca de JavaScript de Office. Durante el período de versión preliminar inicial de los complementos de api de Office locales, no hay una plantilla de Agents Toolkit para este tipo de proyecto. Por este motivo, algunos archivos usados por Agents Toolkit para el desarrollo de complementos de Office deben agregarse al proyecto. La forma más rápida de generar esos archivos es crear un proyecto de complemento, copiar los archivos necesarios del proyecto de complemento en este proyecto de agente y, a continuación, realizar algunas modificaciones ligeras.

  1. Abra una nueva ventana Visual Studio Code.

  2. Seleccione Microsoft 365 Agents Toolkit en la barra de actividad.

  3. Seleccione Crear un nuevo agente o aplicación.

  4. Seleccione Complemento de Office.

  5. Seleccione Panel de tareas.

  6. En la lista Carpeta del área de trabajo, seleccione Carpeta predeterminada para almacenar la carpeta raíz del proyecto en la ubicación predeterminada o vaya a una carpeta donde quiera colocar el nuevo proyecto de agente.

  7. Escriba cualquier cadena como nombre de aplicación y presione Entrar.

  8. El proyecto se abre en una nueva ventana de Visual Studio Code. Cierre la nueva ventana Visual Studio Code y la que creó el proyecto.

  9. Copie los siguientes archivos de la raíz del proyecto de complemento que creó en la raíz del proyecto de complemento de API. Después de copiar los archivos, elimine la carpeta del proyecto del complemento.

    • babel.config.json
    • package.json
    • tsconfig.json
    • webpack.config.js

    Nota:

    Parte del contenido de estos archivos no es necesario para el proyecto de complemento de API. En los pasos restantes de esta sección, solo realizará los cambios mínimos en estos archivos que son necesarios para asegurarse de que el complemento se instala de forma local y se ejecuta correctamente. Estamos trabajando duro para desarrollar una plantilla de proyecto de Agents Toolkit para complementos que llamen a las API de la biblioteca de JavaScript de Office.

  10. En Visual Studio Code, abra el archivo webpack.config.js.

  11. Busque la definición del entry objeto y, a continuación, elimine la taskpane propiedad de él. Cuando haya terminado, la entry propiedad debe tener un aspecto similar al siguiente.

    entry: {
  polyfill: ["core-js/stable", "regenerator-runtime/runtime"],
  commands: "./src/commands/commands.ts",
},

  12. Busque la definición de la plugins matriz. En la parte superior hay una llamada de para un panel de new HtmlWebpackPlugin tareas de complemento. Elimine esta llamada de new HtmlWebpackPlugin. Cuando haya terminado, toda plugins la matriz debería tener un aspecto similar al siguiente.

    plugins: [
  new CopyWebpackPlugin({
    patterns: [
      {
        from: "appPackage/assets/*",
        to: "assets/[name][ext][query]",
      },
      {
        from: "appPackage/manifest*.json",
        to: "[name]" + "[ext]",
        transform(content) {
          if (dev) {
            return content;
          } else {
            return content.toString().replace(new RegExp(urlDev, "g"), urlProd);
          }
        },
      },
    ],
  }),
  new HtmlWebpackPlugin({
    filename: "commands.html",
    template: "./src/commands/commands.html",
    chunks: ["polyfill", "commands"],
  }),
],

  13. En la carpeta appPackage , hay dos archivos de imagen; color.png y outline.png. Para trabajar con la infraestructura de herramientas de complemento, estos archivos deben moverse. Cree una subcarpeta denominada assets en la carpeta appPackage y mueva los dos archivos a ella.

  14. Abra manifest.json y cambie los valores de las color propiedades y outline para que coincidan con sus nuevas ubicaciones. Cuando haya terminado, la icons propiedad debe tener un aspecto similar al siguiente.

    "icons": {
    "outline": "assets/outline.png",
    "color": "assets/color.png"
},

Prueba del agente y el complemento

  1. En la interfaz de la línea de comandos (CLI), vaya a la raíz del proyecto del complemento de API y ejecute npm install. Espere a que termine la instalación.

  2. Cierre todas las aplicaciones de Office.

  3. En Visual Studio Code, seleccione Microsoft 365 Agents Toolkit en la barra de actividad y, a continuación, en el panel CUENTAS, asegúrese de que ha iniciado sesión en una cuenta de Microsoft 365 en la que se habilita la compatibilidad con Copilot y para cargar aplicaciones personalizadas.

  4. Seleccione Aprovisionar en el panel CICLO DE VIDA .

    Captura de pantalla de la opción Aprovisionar en el panel Ciclo de vida del kit de herramientas de agentes

    Entre otras cosas, el aprovisionamiento crea una carpeta de compilación dentro de la carpeta appPackage con el archivo zip del paquete. El archivo contiene el manifiesto y los archivos JSON para el agente y el complemento.

  5. En la CLI de la raíz del proyecto, ejecute npm run dev-server para iniciar el servidor en localhost.

    Nota:

    Si se le pide que elimine un certificado antiguo o que instale uno nuevo, acepte ambas solicitudes.

    Espere hasta que vea una línea en la ventana del servidor similar al ejemplo siguiente que indica que la aplicación se compiló correctamente. Esta salida significa que el servidor está ejecutando y sirviendo los archivos.

    webpack 5.99.8 compiled successfully in 1090 ms

  6. El primer paso en las pruebas depende de la plataforma.

    • Para probar en Office en Windows, abra Excel y, a continuación, abra (o cree) un libro.
    • Para probar en Office en la Web, en un explorador, vaya a y, a https://excel.cloud.microsoftcontinuación, abra (o cree) un libro.

  7. Abra Copilot en la cinta de opciones y seleccione el control de hamburguesa en el panel Copilot . El Agente de Excel debe estar en la lista de agentes. (Es posible que tenga que seleccionar Ver más para asegurarse de que todos los agentes están en la lista). Si el agente no aparece en la lista, pruebe una o ambas de las siguientes acciones.

    • Espere unos minutos y vuelva a cargar Copilot.
    • Con Copilot abierto a la lista de agentes, coloque el cursor en la ventana de Copilot y presione Ctrl+R.

    Captura de pantalla de la lista de agentes en el panel Copilot de una aplicación de Office

  8. Seleccione Agente de Excel, seleccione el inicio de conversación Cambiar color de celda y, a continuación, seleccione el control Enviar en el cuadro de conversación de la parte inferior del panel. En unos segundos, debería ver un mensaje de confirmación similar al siguiente.

    Captura de pantalla del agente de Excel que indica

  9. Seleccione Confirmar en respuesta al mensaje de confirmación. El color de la celda debe cambiar.

    Captura de pantalla de un libro de Excel con la celda B2 color naranja. A la derecha, el agente de Excel en el panel Copilot dice

    Sugerencia

    Si Copilot informa de un error, repita el mensaje, pero agregue la siguiente oración al mensaje: "Si recibe un error, notifique el texto completo del error a mí".

  10. Intente escribir otras combinaciones de celda y color en el cuadro de conversación, como "Establecer la celda G5 en el color del cielo".

Realizar cambios en el agente

No se admite la recarga activa ni la recarga activa de un complemento de API de Office en el período de vista previa. Para realizar cambios, apague primero el servidor y desinstale el agente con estos pasos.

  1. Apagar el servidor depende de la ventana en la que se ejecuta.

    • Si el servidor web se ejecuta en el mismo símbolo del sistema o Visual Studio Code TERMINAL donde ejecutó npm run dev-server, asigne el foco de la ventana y presione Ctrl+C. Para finalizar el proceso, elija "Y" en respuesta al aviso.
    • Si el servidor web se ejecuta en una ventana independiente, en un símbolo del sistema, un shell de Bash o Visual Studio Code TERMINAL en la raíz del proyecto, ejecute npm run stop. Se cierra la ventana del servidor.

  2. Borre la memoria caché de Office siguiendo las instrucciones de Borrar manualmente la memoria caché.

  3. Abra Teams y seleccione Aplicaciones en la barra de actividad y, a continuación, seleccione Administrar las aplicaciones en la parte inferior del panel Aplicaciones .

  4. Busque Agente de Exceldev en la lista de aplicaciones.

  5. Para expandir su fila, seleccione la flecha hacia la izquierda del nombre.

    Captura de pantalla de la fila de la aplicación Agente de Excel en la página Aplicaciones de Teams. Hay un icono de papelera en el extremo derecho de la fila.

  6. Seleccione el icono de papelera cerca del extremo derecho de la fila y, a continuación, seleccione Quitar en el símbolo del sistema.

Realice los cambios y repita los pasos descritos en Probar el agente y el complemento.