Поделиться через

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

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

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

Основные компоненты декларативных агентов с подключаемыми модулями API

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

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

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

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

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

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

В манифесте подключаемого модуля каждая функция должна сопоставляться с соответствующим идентификатором 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 только при сборе всех значений.		 Пользователь: "Какая погода?"
Агент: "Каково ваше расположение?"
Пользователь: "Лондон"
Агент: "Вы предпочитаете информацию о погоде в Метриках или Имперских единицах?"
Пользователь: "Метрика"
Агент: "Вам нужна погода на сегодня или прогноз на завтра?"
Пользователь: "Сегодня"
Агент: "Я буду проверка погоду для Лондона на сегодня"
Агент звонит: getWeather(location="London", forecast="today", system="Metric")

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

Вызовы функций цепочки в подключаемых модулях API

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

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

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

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

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

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

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

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

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

Цепочки с помощью знаний SharePoint

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

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

Инструкции для агента Поток агента
— Чтобы получить состояния проекта, используйте sharepoint knowledge ProjectDeadlines.
— Всегда создавайте задачи для каждого проекта, используя обновление состояния для заголовка.		 Пользователь: "Можете ли вы предоставить обновление состояния всех проектов?"
Агент: Извлекает данные о состоянии проекта из SharePoint, а затем использует createTask для создания задачи задач для каждого проекта.

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

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

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

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

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

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

  • Last updated on