Написание эффективных инструкций для декларативных агентов с помощью API-плагинов

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

В этой статье описывается архитектура агента и приводятся рекомендации по написанию инструкций для декларативных агентов, включающих подключаемые модули API.

Основные компоненты декларативных агентов с API-плагинами

Декларативные агенты, вызывающие подключаемые модули API, включают несколько компонентов, обеспечивающих эффективную интеграцию и функциональность. Понимание этой архитектуры поможет эффективно спроектировать агент. Архитектура включает в себя следующие компоненты:

• Манифест приложения — описывает, как настроено ваше приложение, и ссылается на манифест декларативного агента.
• Декларативный манифест агента — определяет конфигурацию агента, включая инструкции, возможности, инициаторы беседы и действия. Ссылается на манифест подключаемого модуля.
• Манифест подключаемого модуля — описывает конфигурацию подключаемого модуля, включая доступные функции и ссылку на спецификацию OpenAPI.
• Спецификация OpenAPI — предоставляет подробные определения конечных точек API, включая пути, параметры, форматы запросов и ответов, а также проверку подлинности.

Вместе эти файлы определяют поведение агента и его взаимодействие с базовым API.

Дополнительные сведения о плагинах API см. в разделе:

• Подключаемые модули для Microsoft 365 Copilot
• Как сделать документ OpenAPI эффективным при расширении возможностей Copilot

Сопоставление функций в манифесте подключаемого модуля

В манифесте плагина каждая функция должна соответствовать соответствующему operationId в спецификации OpenAPI. Это гарантирует, что когда агент вызывает функцию (например, createTask), агент знает, какую конечную точку API вызвать.

В следующих примерах показано сопоставление в манифесте подключаемого модуля и сопоставленная функция в спецификации OpenAPI.

"functions": [
  {
    "name": "createTask",
    "description": "Creates a new task in the specified task list."
  }
]

paths:
  /me/todo/lists/{listId}/tasks:
    post:
      operationId: createTask
      summary: Create a new task
      description: Creates a new task in the specified task list.
      parameters:

Рекомендации по инструкциям для агентов

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

При написании инструкций для декларативных агентов с помощью плагинов API примените следующие рекомендации:

• Избегайте двусмысленных или негативных инструкций. Контрастные или отрицательные инструкции могут внести двусмысленность и запутать модель. Сосредоточьтесь на определении допустимых вариантов использования с помощью положительных примеров. Важно различать допустимые и недопустимые запросы, приведите четкие критерии и примеры, определяющие ожидаемый ответ агента для каждого из них.
• Использование примеров Предоставьте четкие примеры для руководства поведением агента. Например, вы можете:

Ввод данных: Какая погода в Праге? Вызов агента: getWeather(location="Prague") Ввод данных пользователем: "Нужен ли мне зонтик завтра?" Вызов агента: getWeather(location=user_location, forecast="tomorrow")

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

• Создавайте инструкции для разговоров с несколькими поворотами. При интеграции плагинов API разработайте инструкции для агента по обработке многооборотных разговоров.

Например, если функции требуется несколько параметров, в дополнение к определению необходимых параметров в спецификации OpenAPI поручить агенту собрать все параметры перед выполнением вызова API. Это гарантирует, что агент собирает все необходимые сведения в логической последовательности.

В следующем примере показано, как настроить прогноз погоды для многоэтапных бесед и результирующего потока агентов.

Инструкции для агента

Поток агента

Если пользователь спрашивает о погоде: - Спросите пользователя о местоположении. - Спросите пользователя о дне прогноза. - Попросите пользователя о системе единиц измерения. - Вызывайте getWeather только тогда, когда вы собираете все значения.

Пользователь: — Какая погода? Агент: — Где ты находишься? Пользователь: "London" Agent: "Вы предпочитаете информацию о погоде в метрических или британских единицах?" Пользователь: "Metric" Агент: "Вам нужна погода на сегодня или прогноз на завтра?" Пользователь: "Сегодня" Агент: "Я проверка прогноз погоды в Лондоне на сегодня" Агент звонит: getWeather(location="London", forecast="today", system="Metric")

Общие рекомендации по инструкциям для агентов см. в разделе Написание эффективных инструкций.

Цепочка вызовов функций в плагинах API

Связывание вызовов функций позволяет декларативным агентам объединять несколько действий API в одном бесшовном потоке. В следующих разделах описаны распространенные шаблоны и инструкции для каждого из них.

Цепочка вызовов функций с выходом в качестве входного параметра

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

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

Инструкции для агента	Поток агента
Чтобы узнать погоду, всегда используйте действие getWeather , затем создайте задачу с заголовком "температура в системе" и добавьте в название задачи местоположение и температуру, указанные в погоде.	Пользователь: "Узнать прогноз погоды в Праге" Agent: вызывает getWeather (location="Prague", forecast="today")Agent : использует данные из первого вызова для создания задачи todo createTask (title ="{weather output}")

Цепочка на основе истории бесед в пределах одного оператора

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

В следующем примере агент удаляет задачу по имени.

Инструкции для агента	Поток агента
1. Когда пользователь просит составить список всех задач, вызовите getTasks , чтобы получить список задач с заголовком и идентификатором. 2. Если пользователь просит удалить задачу после перечисления задач, используйте идентификатор из ответа для вызова deleteTask.	Пользователь: "Показать все задачи в папке "Задачи?" Agent: alls getTasks (folderId="Tasks") и отображает все задачи с идентификаторами. Пользователь: "Delete TaskMaster Pro to-do "Agent: использует сведения из журнала бесед для поиска идентификатора задачи и удаляет задачу с помощью вызова deleteTask.

Связывание с помощью знаний SharePoint

Цепочка вызовов API позволяет агенту объединять источники знаний и действия для проектирования более сложных рабочих процессов.

В следующем примере агент получает данные о состоянии проекта из SharePoint и создает соответствующие задачи в Microsoft To-Do для отслеживания.

Инструкции для агента	Поток агента
- Для получения статусов проектов используйте ProjectDeadlines с помощью знаний Sharepoint. - Всегда создавайте задачу для каждого проекта, используя обновление статуса для названия.	Пользователь: "Не могли бы вы предоставить обновленную информацию о состоянии всех проектов?" Агент: Извлекает данные о состоянии проекта из SharePoint, а затем создает с помощью createTask задачу для каждого проекта.

Связывание с помощью интерпретатора кода

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

В приведенном ниже примере агент создает диаграмму на основе данных в задачах из списка дел.

Инструкции для агента	Поток агента
Когда пользователь просит составить список всех задач, вызовите getTasks , чтобы получить список дел с заголовком и идентификатором, а также постройте диаграмму для выходных данных.	Пользователь: "Получить все задачи в Задачах" Agent: вызывает getTasks (folderId="Tasks") и отображает все задачи с идентификаторами. Агент: Вызывает интерпретатор кода для инициации создания диаграммы на основе выходных данных первого вызова.

В этом примере также выполняется несколько действий одновременно. Это полезно при инициировании ряда связанных действий, не требующих ввода нескольких пользователей.

Когда интерпретатор кода создает файл (например, изображение диаграммы или электронную таблицу), Copilot автоматически представляет ссылку для скачивания в ответе, позволяя пользователям сохранить файл локально. Дополнительные сведения см. в разделе "Создание загружаемых файлов".

Связанные материалы

• Создание декларативного агента с помощью Visual Studio Code
• Подключаемые модули для Microsoft 365 Copilot