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

7 мин

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

Декларативный агент

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

{
  "$schema": "https://developer.microsoft.com/json-schemas/copilot/declarative-agent/v1.0/schema.json",
  "version": "v1.0",
  "name": "Il Ristorante",
  "description": "Order the most delicious Italian dishes and drinks from the comfort of your desk.",
  "instructions": "$[file('instruction.txt')]",
  "actions": [
    {
      "id": "menuPlugin",
      "file": "ai-plugin.json"
    }
  ]
}

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

Определение подключаемого модуля

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

Основные сведения

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

{
  "$schema": "https://developer.microsoft.com/json-schemas/copilot/plugin/v2.1/schema.json",
  "schema_version": "v2.1",
  "namespace": "ilristorante",
  "name_for_human": "Il Ristorante",
  "description_for_human": "See the today's menu and place orders",
  "description_for_model": "Plugin for getting the today's menu, optionally filtered by course and allergens, and placing orders",
  "functions": [
  ],
  "runtimes": [
  ],
  "capabilities": {
    "localization": {},
    "conversation_starters": []
  }
}

Содержимое свойств name_for_human и description_for_human является исключительно информативным. Свойство description_for_model важно, так как агент использует его, чтобы решить, следует ли вызывать подключаемый модуль для запроса пользователя. Если агент не вызывает подключаемый модуль для определенных запросов, следует проверка, если описание модели содержит необходимые сведения, которые агент считает нужным.

Другим важным свойством является пространство имен , которое является обязательным и которое агент использует для дизамбига действий в разных подключаемых модулях. Если удалить его или указать недопустимое значение, не соответствующее схеме, это может помешать агенту использовать подключаемый модуль. Пространство имен должно соответствовать следующему регулярному выражению ^[A-Za-z0-9_]+, что означает, что оно должно состоять по крайней мере из одного символа, например A-Z, a-z, 0-9или _. Любой другой символ недопустим.

Функции

Следующий раздел определения подключаемого модуля — функции. Функции определяют одну или несколько операций API, которые может выполнять подключаемый модуль API, и указывают агенту, как показать данные, получаемые от API. В следующем фрагменте кода показан пример функции:

{
  "functions": [
    {
      "name": "getDishes",
      "description": "Returns information about the dishes on the menu. Can filter by course (breakfast, lunch or dinner), name, allergens, or type (dish, drink).",
      "capabilities": {
        "response_semantics": {
          "data_path": "$.dishes",
          "properties": {
            "title": "$.name",
            "subtitle": "$.description"
          },
          "static_template": {
            ...trimmed for brevity
          }
        }
      }
    }
  ]
}

Каждая функция состоит из нескольких элементов.

Имя

Имя однозначно идентифицирует операцию в подключаемом модуле API, которая должна точно соответствовать идентификатору operationId из соответствующей спецификации API. Если указанное имя не соответствует ни одной операции, microsoft 365 Agents Toolkit выдает ошибку при сборке проекта. При развертывании функции с именем, которое не соответствует идентификатору operationId, агент не сможет вызвать эту функцию.

Описание

Агент использует описание для сопоставления функции с запросом пользователя. При описании функции обязательно объясните, какие задачи она выполняет, включая любые варианты, такие как фильтрация или сортировка информации. Если описание является неточным или неполным, агент не может сопоставить его с конкретным запросом и не может вызвать функцию.

Семантика ответа

Свойство response_semantics указывает агенту, как он должен отображать данные, полученные от API. Он состоит из трех свойств: data_path, свойств и static_template.

Если API возвращает сложную структуру данных и требуется, чтобы агент отображал только определенную ее часть, используйте свойство data_path , чтобы указать выражение пути JSON, указывающее на соответствующую часть ответа API. Рассмотрим следующий ответ API:

{
  "dishes": [
    {
      "id": 1,
      "name": "Classic Italian Frittata",
      "description": "A fluffy omelette filled with sautéed mushrooms, onions, and melted pecorino, served with a side of roasted cherry tomatoes.",
      "image_url": "https://raw.githubusercontent.com/pnp/copilot-pro-dev-samples/main/samples/da-ristorante-api/assets/frittata.jpeg",
      "price": 8.99,
      "allergens": [
        "eggs",
        "dairy"
      ],
      "course": "breakfast",
      "type": "dish"
    },
    ...trimmed for brevity
  ]
}

Данные, которые нужно отобразить агенту, содержатся в свойстве dishes, поэтому для свойства $.dishesdata_path задается выражение JSONPath, которое ссылается на свойство dishes корневого объекта, обозначаемого .$

Следующая часть семантики ответа — свойства. С помощью свойств агенту сообщается, какие из свойств данных из ответа API представляют свойства элемента, такие как заголовок, описание или URL-адрес. Когда API возвращает несколько элементов, агент использует семантическое сопоставление для включения наиболее релевантных сведений в ответ. Рассмотрим следующее семантическое сопоставление:

{
  "response_semantics": {
    "properties": {
      "title": "$.name",
      "subtitle": "$.description"
    }
  }
}

Когда агент отвечает, он выдает следующий ответ:

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

Последняя часть семантики ответа — static_template. Статический шаблон используется для определения шаблона адаптивной карточки, который агент должен использовать для отображения данных из API.

Совет

Дополнительные сведения об использовании шаблонов адаптивных карточек с подключаемыми модулями API см. в модуле Использование адаптивных карточек для отображения данных в подключаемых модулях API для декларативных агентов в разделе Дополнительные ресурсы в конце этого модуля learn.

Runtimes

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

{
  "type": "OpenApi",
  "auth": {
    "type": "None"
  },
  "spec": {
    "url": "apiSpecificationFile/ristorante.yml"
  },
  "run_for_functions": [
    "getDishes",
    "placeOrder"
  ]
}

Начните с определения типа описания API. Сейчас подключаемые модули API поддерживают только OpenAPI.

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

Совет

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

В следующем разделе с именем spec вы предоставите ссылку на документ спецификации локального API, в котором описывается API, который может использовать подключаемый модуль API. С помощью свойства url укажите относительный путь к файлу в проекте.

Последняя часть — это свойство run_for_functions , указывающее, какие из указанных функций относятся к этому API.

Совет

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

Спецификация API

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

Расположение API.
Если API требует проверки подлинности, и если да, то каким образом.
Какие операции поддерживает API.
Для каждой операции— какие данные она ожидает и как она может реагировать.

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

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

Совет

Если вам нужно использовать часть существующей спецификации API, рассмотрите возможность использования Hidi. Это средство, созданное корпорацией Майкрософт, которое позволяет легко извлечь соответствующую часть спецификации API вместе со всеми связанными сущностями. Дополнительные сведения см. в конце этого модуля learn.

Агенты поддерживают спецификации API OpenAPI в YAML и JSON.

Совет

Когда вы создаете пользовательский API для использования подключаемым модулем API и запускаете его с локального компьютера, необходимо предоставить его в Интернет, чтобы агент смог вызвать его. Вы можете предоставить доступ к API с помощью туннель разработки — средства, созданного корпорацией Майкрософт для совместного использования локальных служб через Интернет. Если вы используете Microsoft 365 Agents Toolkit для создания агента с подключаемым модулем API, он не только автоматически запускает туннель разработки, но и автоматически обновляет URL-адрес API в спецификации API, что позволяет сосредоточиться на создании решения.

Как он подходит вместе

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

Приложения Microsoft Teams используются для упаковки и распространения агентов. Каждое приложение Teams может содержать один или несколько декларативных агентов, каждый из которых оптимизирован для определенного сценария. Агент, в зависимости от его назначения, может содержать ноль или несколько подключаемых модулей API, которые позволяют ему взаимодействовать с внешними системами. Подключаемый модуль определяет одну или несколько функций. Каждая функция выполняет определенную задачу и ссылается только на одну операцию API. Рядом с функциями подключаемый модуль API ссылается на одну или несколько спецификаций API, описывающих используемые им API. В свою очередь каждая спецификация API определяет одну или несколько операций, которые подключаемый модуль может использовать через свои функции.

Обратная связь

Были ли сведения на этой странице полезными?