Объединение агентов Copilot с надстройками Office (предварительная версия)

Включение агента Microsoft 365 Copilot в надстройку Office обеспечивает два преимущества:

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

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

Сценарии

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

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

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

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

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

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

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

Агент Copilot — это интерфейс естественного языка для надстройки.

Надстройку можно настроить так, чтобы она была только навыком в агенте Copilot. Он не обязательно должен включать область задач, настраиваемые кнопки ленты или настраиваемые меню. но он может иметь любое из них в дополнение к навыку Копилота. Оптимальный подход зависит от пользовательских сценариев, которые должна включить надстройка.

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

Основные задачи

Существует две основные задачи настройки надстройки в качестве навыка Copilot, и они аналогичны двум задачам по настройке команд функций для надстройки .

• Создание функций JavaScript, которые реализуют действия агента.
• Используйте JSON, чтобы указать имена этих функций для Office и сред выполнения JavaScript.

Конфигурация JSON

Для настройки надстройки, чтобы быть навыком Copilot, требуется три файла в формате JSON, которые описаны в следующих подразделах.

Унифицированный манифест для Microsoft 365

Вы настраиваете две части манифеста. Сначала создайте объект действия, который идентифицирует функцию JavaScript, вызываемую действием. Ниже приведен пример (с опущенной посторонней разметкой). Обратите внимание на указанные ниже аспекты этого кода.

• Свойство page указывает URL-адрес веб-страницы, содержащей внедренный тег скрипта, который, в свою очередь, указывает URL-адрес файла JavaScript, в котором определена функция. Этот же файл содержит вызов метода Office.actions.associate для сопоставления функции с идентификатором действия.
• Свойство "actions.id" в манифесте — это тот же идентификатор действия, который передается вызову associate.
• Свойство "actions.type" имеет значение "executeDataFunction", который является типом, который может принимать параметры и может вызываться Copilot.

"extensions": [

    ...

    "runtimes": [
        {
            "id": "CommandsRuntime",
            "type": "general",
            "code": {
                "page": "https://localhost:3000/commands.html",
                "script": "https://localhost:3000/commands.js"
            },
            "lifetime": "short",
            "actions": [
                {
                    "id": "fillcolor",
                    "type": "executeDataFunction",
                }
            ]
        }
    ]
]

Во-вторых, создайте декларативный объект агента, который идентифицирует файл, содержащий подробную конфигурацию агента. Ниже приведен пример.

"copilotAgents": {
    "declarativeAgents": [
        {
        "id": "ContosoCopilotAgent",
        "file": "declarativeAgent.json"
        }
    ]
}

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

Конфигурация декларативного агента

Файл конфигурации агента содержит инструкции для агента и указывает один или несколько файлов конфигурации подключаемого модуля API, которые будут содержать подробную конфигурацию действий агента. Ниже приведен пример. Обратите внимание на следующие сведения об этом JSON.

• Начальный элемент беседы отображается на холсте чата Copilot.
• Свойство "actions.id" в этом файле является коллективным идентификатором всех функций в файле, указанном в "actions.file". Он не обязательно должен соответствовать "actions.id" в манифесте.

{
    "$schema": "https://developer.microsoft.com/json-schemas/copilot/declarative-agent/v1.6/schema.json",
    "version": "v1.6",
    "name": "Excel Add-in + 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": "localExcelPlugin",
            "file": "Excel-API-local-plugin.json"
        }
    ]
}

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

Конфигурация подключаемого модуля Api Copilot

Файл конфигурации подключаемого модуля API указывает "функции" подключаемого модуля в смысле действий агента, а не функций JavaScript, включая инструкции для действия. Он также настраивает среду выполнения JavaScript для Copilot. Ниже приведен пример. Обратите внимание на следующее:

• Объект "functions.name" должен соответствовать свойству "extensions.runtimes.actions.id" в манифесте надстройки.
• И "reasoning.description""reasoning.instructions" ссылаются на функцию JavaScript, а не REST API.
• Свойство "responding.instructions" предоставляет только рекомендации для Copilot о том, как реагировать. Он не накладывает никаких ограничений или структурных требований к ответу.
• Массив "runtimes.run_for_functions" должен содержать ту же строку или "functions.name" строку с подстановочными знаками, которая ей соответствует.
• Свойство "runtimes.spec.local_endpoint" указывает, что функция JavaScript, связанная со строкой fillcolor, доступна в надстройке Office, а не в какой-то конечной точке REST.
• Свойство "runtimes.spec.allowed_host" указывает, что агент должен быть виден только в Excel.
• Для "runtimes.auth.type" агентов надстроек Office свойство всегда имеет значение None.

{
    "$schema": "https://developer.microsoft.com/json-schemas/copilot/plugin/v2.4/schema.json",
    "schema_version": "v2.4",
    "name_for_human": "Excel Add-in + Agent",
    "description_for_human": "Add-in Actions in Agents",
    "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 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",
                "allowed_host": ["workbook"]
            },
            "run_for_functions": ["fillcolor"],
            "auth": {
                "type": "None"
            }
        }
    ]
}

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

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

Функции JavaScript, которые будут вызваны агентом Copilot, создаются точно так же, как и команды функций . Ниже приведен пример. Обратите внимание на указанные ниже аспекты этого кода.

• В отличие от команды функции, функция, связанная с действием Copilot, может принимать параметры.
• Первый параметр associate метода должен соответствовать как свойству "extensions.runtimes.actions.id" в манифесте надстройки, так и свойству "functions.name" в JSON подключаемого модуля API.

async function fillColor(cell, color) {
    await Excel.run(async (context) => {
        context.workbook.worksheets.getActiveWorksheet().getRange(cell).format.fill.color = color;
        await context.sync();
    })
}

Office.onReady((info) => {
    Office.actions.associate("fillcolor", async (message) => {
        const {cell, color} = JSON.parse(message);
        await fillColor(cell, color);
        return "Cell color changed.";
    });
});

После создания функций создайте HTML-файл без пользовательского интерфейса, содержащий <script> тег, который загружает файл JavaScript с функциями. URL-адрес этого HTML-файла должен соответствовать значению "extensions.runtimes.code.page" свойства в манифесте. См. раздел Унифицированный манифест для Microsoft 365 ранее в этой статье.

Устранение неполадок с объединенными агентами и надстройками

Ниже приведены некоторые распространенные проблемы и предлагаемые решения.

• Действие агента завершается сбоем с сообщением о том, что действие не найдено в надстройке. Ниже приведены некоторые возможные причины.

  • Значение "functions.name" свойства в ФОРМАТЕ JSON подключаемого модуля не соответствует ни одному "extensions.runtimes.actions.id" свойству в манифесте надстройки.
  • В манифесте есть совпадение "actions.id" , но одноуровневое "actions.type" значение для одного и того же объекта действия не является "executeDataFunction".

• Сбой действия агента с сообщением о том, что регистрация обработчика действия не найдена. Ниже приведена возможная причина.

  • JavaScript надстройки не имеет вызова Office.actions.associate с первым параметром , точно соответствующим значению "functions.name" свойства в ФОРМАТЕ JSON подключаемого модуля.

Дальнейшие действия

• Создание первой надстройки в качестве навыка Copilot
• Добавление агента Copilot в надстройку