Создание подключаемых модулей API для Microsoft 365 Copilot с помощью библиотеки JavaScript для Office (предварительная версия)

Подключаемый модуль для декларативного агента может вызывать API-интерфейсы в библиотеке JavaScript Для Office для выполнения операций чтения и записи содержимого и метаданных документа Office, открытого в настоящее время в приложении Office. Эта возможность позволяет Copilot работать с документами Office точными и безошибочными способами, которые в противном случае потребуют наличия надстройки Office.

Связь агентов Copilot с платформой надстройки Office

Надстройки Office и декларативные подключаемые модули агента вызывают API в библиотеке Office JavaScript, а расширение Microsoft 365, использующее библиотеку, может включать подключаемый модуль, надстройку или и то, и другое. Оптимальный подход зависит от пользовательских сценариев, которые должно включить расширение.

• Если расширение должно предоставлять простые и быстрые действия, для которых не требуются параметры, добавьте только надстройку с настраиваемыми кнопками ленты или меню, называемыми командами надстройки.
• Если расширению требуется интерфейс панели мониторинга, пользователь должен настраивать параметры, отображать метаданные о содержимом документа Office или по любой другой причине требуется интерфейс, похожий на страницу, включите надстройку с областью задач.
• Если расширение должно предоставлять сложные действия, требующие параметров, передаваемых во время выполнения, или требует интерфейса естественного языка, включите агент Copilot.

Сценарии

Ниже приведены некоторые выбранные способы, с помощью которых агент Copilot, вызывающий API библиотеки JavaScript для Office, повышает ценность расширения Microsoft 365.

• Анализ содержимого: Агент можно использовать для анализа содержимого документа, презентации или электронной таблицы и выполнения действий в зависимости от того, что он находит. Ниже приведены примеры.

  • Агент анализирует запрос на предложение (RFP), а затем получает ответы на вопросы в RFP из серверной системы. Пользователь просто просит агента "Заполнить ответы, которые вы знаете на вопросы".
  • Агент анализирует документ или таблицу в электронной таблице на предмет содержимого, которое подразумевает, что должны быть выполнены определенные действия либо в самом документе, либо в другом месте бизнес-систем клиента. Пользователь может попросить агента "Проверить документ на наличие элементов, пропущенных в списке аудита".

• Доверяемая вставка данных: Если вы задаете типичный механизм ИИ вопрос, он объединяет информацию, которую он находит, и создает ответ; процесс, который может привести к неточностям. Но агент Copilot на основе надстройки может вставлять данные без изменений из надежного источника. Примеры:

  • Рассмотрим агент, который позволяет вставлять юридические исследования в Word, где их можно изменить. Пользователь спрашивает агента: "При каких обстоятельствах арендатор может в одностороннем порядке разорвать аренду жилых помещений в Индиане?" Затем агент извлекает содержимое из прецедентов и уставов и вставляет его в документ.
  • Рассмотрим агента, который управляет инвентаризацией цифровых активов. В чате агента Copilot пользователь спрашивает: "Вставьте таблицу с нашими цветными фотографиями с именем каждого из них, числом скачанных файлов и размером в мегабайтах, отсортированных по порядку из наиболее загруженных". Затем агент получает эти данные без изменений из системы записей и вставляет таблицу в электронную таблицу Excel.

При объединении агента с надстройкой включается еще больше сценариев. Включение агента Microsoft 365 Copilot с надстройкой Office обеспечивает по крайней мере два преимущества надстройки:

• Copilot становится интерфейсом естественного языка для функциональности надстройки.
• Агент может передавать параметры вызываемому коду JavaScript, что невозможно при вызове команды функции в надстройке из кнопки или пункта меню.

Изучение того, как использовать надстройку, — это один из способов, с помощью которым агент может улучшить надстройку. Если пользователю необходимо выполнить несколько шагов или задач с надстройкой для достижения цели, интерфейс чата Copilot может упростить процесс начала работы с надстройкой. Например, рассмотрим юридическую фирму, которая должна иметь список вопросов, на которые необходимо ответить о каждой аренде, которую она подготавливает. Создание этого списка вопросов может быть трудоемким и трудоемким. Но агенту Copilot может быть предложено создать первый черновик списка вопросов и вставить их в документ Word с помощью библиотеки JavaScript Office.

Создание первого подключаемого модуля библиотеки JavaScript для Office

Ниже приведены основные шаги по созданию подключаемого модуля API для агента Copilot, который вызывает API библиотеки JavaScript для Office.

• Убедитесь, что выполнены предварительные требования.
• Создание проекта
• Настройка манифеста
• Настройка декларативного агента
• Настройка подключаемого модуля
• Создание функций JavaScript
• Копирование файлов конфигурации проекта
• Тестирование агента и подключаемого модуля
• Внесение изменений в агент

Предварительные условия

• Требования, указанные в разделе Требования к параметрам расширяемости Copilot
• Visual Studio Code
• Node.js 18, 20, 22 или 24
• Microsoft 365 Agents Toolkit

Создание проекта

Начните с создания базового декларативного агента.

1. Откройте Visual Studio Code.

2. Выберите Microsoft 365 Agents Toolkit (Набор средств агентов Microsoft 365) на панели действий.

3. Выберите Создать агент или приложение.

   

4. Выберите Декларативный агент.

   

5. Выберите Нет действий , чтобы создать базовый декларативный агент.

6. В списке Папка рабочей области выберите папку По умолчанию , чтобы сохранить корневую папку проекта в расположении по умолчанию, или перейдите в папку, в которую вы хотите поместить новый проект агента.

7. Введите Агент Excel имя приложения и нажмите клавишу ВВОД.

8. Проект откроется в новом окне Visual Studio Code. Закройте исходное окно Visual Studio Code.

Настройка манифеста

Выполните следующие действия по настройке манифеста.

1. Откройте файл manifest.json в папке appPackage .

2. Необходимо использовать предварительную версию схемы манифеста, поэтому замените $schema свойства и manifestVersion следующими.

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

3. В корне манифеста добавьте следующее свойство авторизации . Это свойство дает агенту разрешение на чтение и запись в документы Office.

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

4. В корне манифеста добавьте следующее свойство extensions . Обратите внимание на следующие сведения об этом коде.

   • Свойство requirements.scopes гарантирует, что агент доступен только в Excel, но не в других приложениях Office.
   • Объект в runtimes настраивает среду выполнения JavaScript, которую Office использует для запуска API библиотеки JavaScript для Office, вызываемых агентом.
   • Свойство code.script указывает URL-адрес файла JavaScript, который содержит функции, вызывающие API библиотеки JavaScript для Office. Этот же файл содержит вызов метода Office.actions.associate для сопоставления функции с идентификатором действия. Этот файл будет создан позже.
   • Свойство code.page задает URL-адрес веб-страницы, содержащей внедренный <script> тег, который загружает файл, который является ссылкой в свойстве code.page . Этот файл будет создан позже.
   • Объект среды выполнения включает actions массив, включающий объект действия.
   • Значение actions.id свойства — это тот же идентификатор действия, который передается вызову associate.
   • Свойству actions.typeexecuteDataFunctionприсвоено значение , которое является типом, который может принимать параметры при вызове Copilot.

   "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"
             }
           ]
         }
       ]
     }
   ]
   

Справочная документация по JSON манифеста приведена в справочнике по схеме манифеста приложения Microsoft 365.

Настройка декларативного агента

1. Откройте файл declarativeAgent.json в папке appPackage .

2. Замените его содержимое следующим кодом. Обратите внимание на следующее:

   • Свойство actions.id в этом файле является коллективным идентификатором всех функций в файле, указанном в actions.file. Обычно он не должен совпадать с extensions.runtimes.actions.id в манифесте, который является идентификатором определенного действия.
   • Вы создадите файл, указанный в свойстве actions.file , на следующем шаге.

   {
     "$schema": "https://developer.microsoft.com/json-schemas/copilot/declarative-agent/v1.5/schema.json",
     "version": "v1.5",
     "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"
       }
     ]
   }
   

Справочная документация по декларативным агентам приведена в разделе Схема декларативного агента для Microsoft 365 Copilot.

Настройка подключаемого модуля

1. Создайте файл в папке appPackage и присвойте ему имя, присвоенное свойству actions.file в файле declarativeAgent.json : Office-API-local-plugin.json.

2. Вставьте в файл следующее содержимое. Обратите внимание на следующие сведения об этом JSON:

   • В файле конфигурации подключаемого модуля API указываются функции подключаемого модуля в смысле действий агента, а не функции JavaScript. Он содержит инструкции для каждого действия. Он также настраивает среду выполнения для Copilot. (Вы настроили среду выполнения для Office в манифесте на предыдущем шаге.)
   • Объект functions.name должен соответствовать свойству extensions.runtimes.actions.id в манифесте надстройки: FillColor.
   • Массив runtimes.run_for_functions должен содержать ту же строку или functions.name строку с подстановочными знаками, которая ей соответствует.
   • Свойство runtimes.spec.local_endpoint указывает, что функция JavaScript, связанная со строкой FillColor , доступна в библиотеке JavaScript для Office, а не в какой-то конечной точке 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"
         ],
         "auth": {
           "type": "None"
         }
       }
     ]
   }
   

Справочная документация по подключаемым модулям приведена в статье Схема манифеста подключаемого модуля 2.4 для Microsoft 365 Copilot.

Создание функций JavaScript

1. В корневой папке проекта создайте папку с именем src, а затем создайте вложенную папку с именем commands.

2. В папке commands создайте файл с именем commands.ts и предоставьте ему следующее содержимое. Обратите внимание на следующие сведения об этом коде.

   • Функция fillColor задает цвет фона указанной ячейки в указанный цвет. Он вызывает объекты и методы из библиотеки JavaScript Office, которая загружается в среду выполнения JavaScript файлом, который вы создадите на следующем шаге.
   • Первый параметр associate метода должен точно соответствовать как свойству extensions.runtimes.actions.id в манифесте, так и свойству functions.name в JSON подключаемых модулей API.
   • Параметр message представляет собой объект, передаваемый средой выполнения Copilot в среду выполнения JavaScript в Office. Это объект, который содержит адрес ячейки и параметры цвета, указанные пользователем в запросе на естественном языке, например "Задать ячейку C4 в зеленый".

   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. В папке commands создайте файл с именем commands.html и предоставьте ему следующее содержимое. Этот файл необходим, так как файлы JavaScript не могут быть загружены напрямую в тип среды выполнения, используемый Office для подключаемых модулей API Copilot. Вместо этого HTML-файл с элементом <script> загружает JavaScript. Обратите внимание на следующие сведения об этом файле.

   • Так как файл предназначен только для загрузки других файлов, <body> элемент пуст. Файл не имеет пользовательского интерфейса и никогда не отображается для пользователей.
   • Он загружает файл office.js, который является библиотекой Office JavaScript, с сервера Майкрософт.
   • У него <script>нет элемента для загрузки файлаcommands.js (преобразованного из созданного commands.ts), так как этот <script> элемент добавляется во время сборки файлом, который вы добавите на следующем шаге.
   • Когда проект создается и обслуживается на сервере, URL-адрес этого HTML-файла соответствует значению extensions.runtimes.code.page свойства в манифесте. См . раздел Настройка манифеста ранее в этой статье.

   <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>
   

Копирование файлов конфигурации проекта

Office использует инфраструктуру надстроек Office для запуска подключаемых модулей API для библиотеки Office JavaScript. В течение начального периода предварительной версии для локальных подключаемых модулей API Office шаблон набора средств агентов для этого типа проекта не существует. По этой причине в проект необходимо добавить некоторые файлы, используемые набором средств агентов для разработки надстроек Office. Самый быстрый способ создать эти файлы — создать проект надстройки, скопировать необходимые файлы из проекта надстройки в этот проект агента, а затем внести несколько легких изменений.

1. Откройте новое окно Visual Studio Code.

2. Выберите Microsoft 365 Agents Toolkit (Набор средств агентов Microsoft 365) на панели действий.

3. Выберите Создать агент или приложение.

4. Выберите Надстройка Office.

5. Выберите Область задач.

6. В списке Папка рабочей области выберите папку По умолчанию , чтобы сохранить корневую папку проекта в расположении по умолчанию, или перейдите в папку, в которую вы хотите поместить новый проект агента.

7. Введите любую строку в качестве имени приложения и нажмите клавишу ВВОД.

8. Проект откроется в новом окне Visual Studio Code. Закройте новое окно Visual Studio Code и окно, из которого вы создали проект.

9. Скопируйте следующие файлы из корневого каталога созданного проекта надстройки в корневой каталог проекта подключаемого модуля API. После копирования файлов удалите папку проекта надстройки.

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

   Примечание.

   Некоторые из этих файлов не требуются для проекта подключаемого модуля API. В остальных шагах в этом разделе вы вносите в эти файлы только минимальные изменения, необходимые для правильной загрузки и запуска подключаемого модуля. Мы работаем над созданием шаблона проекта набора средств агентов для подключаемых модулей, которые вызывают API библиотеки JavaScript для Office.

10. В Visual Studio Code откройте файлwebpack.config.js.

11. Найдите определение entry объекта, а затем удалите taskpane из него свойство . По завершении entry свойство должно выглядеть следующим образом.

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

12. Найдите определение массива plugins . В верхней части находится вызов области задач надстройки new HtmlWebpackPlugin . Удалите этот вызов new HtmlWebpackPlugin. По завершении весь plugins массив должен выглядеть следующим образом.

    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. В папке appPackage есть два файла изображений; color.png и outline.png. Для работы с инфраструктурой инструментов надстройки эти файлы необходимо переместить. Создайте вложенную папку assets в папке appPackage и переместите в нее два файла.

14. Откройте manifest.json и измените значения свойств и outline в color соответствии с их новым расположением. По завершении icons свойство должно выглядеть следующим образом.

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

Тестирование агента и подключаемого модуля

1. В интерфейсе командной строки (CLI) перейдите к корню проекта подключаемого модуля API, а затем запустите npm install. Дождитесь завершения установки.

2. Закройте все приложения Office.

3. В Visual Studio Code выберите Microsoft 365 Agents Toolkit на панели действий, а затем в области Учетные записи убедитесь, что вы вошли в учетную запись Microsoft 365, в которой включена поддержка Copilot и отправки пользовательских приложений.

4. Выберите Подготовить в области ЖИЗНЕННЫЙ ЦИКЛ .

   

   Помимо прочего, при подготовке в папке appPackage создается папка сборки с ZIP-файлом пакета. Файл содержит манифест и файлы JSON для агента и подключаемого модуля.

5. В интерфейсе командной строки в корневом каталоге проекта выполните команду npm run dev-server , чтобы запустить сервер на localhost.

   Примечание.

   Если вам будет предложено удалить старый сертификат и (или) установить новый, примите оба запроса.

   Подождите, пока в окне сервера не появится строка, аналогичная приведенному в следующем примере, которая указывает, что приложение успешно скомпилировано. Эти выходные данные означают, что сервер работает и обслуживает файлы.

   webpack 5.99.8 compiled successfully in 1090 ms
   

6. Первый шаг тестирования зависит от платформы.

   • Чтобы выполнить тестирование в Office в Windows, откройте Excel, а затем откройте (или создайте) книгу.
   • Чтобы протестировать в Office в Интернете, в браузере перейдите по адресу https://excel.cloud.microsoft, а затем откройте (или создайте) книгу.

7. Процесс открытия агента зависит от пользовательского интерфейса Copilot в приложениях Office, который находится на этапе перехода.

   • Если на ленте отображается кнопкаCopilot (не раскрывающееся меню), нажмите кнопку Copilot, чтобы открыть панель Copilot.
   • Если вы видите раскрывающееся меню Copilot , откройте меню и выберите Навыки приложения в раскрывающемся списке, чтобы открыть панель Copilot .

8. Выберите элемент управления Гамбургер на панели Copilot .

9. В области агент Excel должен находиться в списке агентов. Чтобы просмотреть список всех агентов, может потребоваться выбрать Пункт Дополнительные сведения. Если агент отсутствует в списке, попробуйте выполнить одно или оба следующих действия.

   • Подождите несколько минут и перезагрузите Copilot.
   • Открыв список агентов Copilot, поместите курсор в область Copilot и нажмите клавиши CTRL+R.

   

10. Выберите Агент Excel, выберите начальный элемент Изменить цвет ячейки беседы, а затем выберите элемент управления Отправить в поле беседы в нижней части панели. Через несколько секунд появится запрос на подтверждение, аналогичный приведенному ниже.

    

11. Выберите Подтвердить в ответ на запрос на подтверждение. Цвет ячейки должен измениться.

    

    Совет

    Если Copilot сообщает об ошибке, повторите запрос, но добавьте в запрос следующее предложение: "Если вы получаете ошибку, сообщите мне полный текст ошибки".

12. Попробуйте ввести другие сочетания ячейки и цвета в поле беседы, например "Задать для ячейки G5 цвет неба".

Внесение изменений в агент

Динамическая перезагрузка и горячая перезагрузка для подключаемого модуля API Office не поддерживаются в период предварительной версии. Чтобы внести изменения, сначала завершите работу сервера и удалите агент, выполнив следующие действия.

1. Завершение работы сервера зависит от того, в каком окне он работает.

   • Если веб-сервер работает в той же командной строке или Visual Studio Code терминале, где вы запустили npm run dev-server, наведите фокус на окне и нажмите клавиши CTRL+C. Чтобы завершить процесс, в ответ на запрос выберите "Y".
   • Если веб-сервер работает в отдельном окне, в командной строке, оболочке bash или Visual Studio Code TERMINAL в корневом каталоге проекта выполните команду npm run stop. Окно сервера закрывается.

2. Очистите кэш Office, следуя инструкциям в разделе Очистка кэша вручную.

3. Откройте Teams и выберите Приложения на панели действий, а затем выберите Управление приложениями в нижней части области Приложения .

4. Найдите Excel Agentdev в списке приложений.

5. Чтобы развернуть строку, щелкните стрелку слева от имени.

   

6. Щелкните значок корзины рядом с правой частью строки, а затем выберите Удалить в командной строке.

Внесите изменения, а затем повторите действия, описанные в разделе Тестирование агента и подключаемого модуля.