Добавление средства API (подключаемого модуля) в агент

Важно!

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

Разработчикам агентов часто приходится отправлять HTTP-запросы для создания полных вариантов использования.

В этом примере показано создание агента, который использует подключаемый модуль со средством API для подключения к службе REST API с именем freeipapi.com, которая предоставляет функции поиска по гео IP.

Общий процесс выглядит следующим образом:

  1. Шаг 1. Создание и публикация спецификации OpenAPI, определяющей API

  2. Шаг 2. Создание и отправка файла манифеста в Security Copilot

  3. Шаг 3. Отправка агента, использующего подключаемый модуль

  4. Шаг 4. Публикация пакета в хранилище безопасности (применимо только для агентов партнеров)

    Примечание.

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

Шаг 1. Создание и публикация спецификации OpenAPI

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

В этом примере выполняется интеграция с REST API бесплатного IP-адреса для поиска по географическому расположению IP-адресов. Эту спецификацию необходимо опубликовать в интернете (GitHub gist работает хорошо). См. следующий пример, чтобы создать и разместить спецификацию. Примеры проверки подлинности см. в разделе Типы проверки подлинности.

openapi: 3.0.0

info:
    title: Free IP API
    description: A free IP lookup API
    version: "v1"

servers:
    - url: https://freeipapi.com/api/

paths:
    /json/{ipaddress}:
        get: 
            operationId: lookupIpAddressGeolocation
            summary: Lookup IP Address Geolocation information
            parameters:
                - in: path
                  name: ipaddress
                  schema:
                      type: string
                  required: true
                  description: The ip address to lookup
            responses:
                "200":
                    description: OK
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/lookupIpAddressGeolocationResponse"

components:
    schemas:
        lookupIpAddressGeolocationResponse:
            type: object
            properties:
                ipVersion:
                    type: integer
                    description: The IP address version
                ipAddress:
                    type: string
                    description: The IP address
                latitude:
                    type: number
                    description: The latutude
                longitude:
                    type: number
                    description: The longitude
                countryName:
                    type: string
                    description: The country
                zipCode:
                    type: string
                    description: The zip code
                cityName:
                    type: string
                    description: The city
                regionName:
                    type: string
                    description: The region
                continent:
                    type: string
                    description: The continent

Шаг 2. Создание и отправка манифеста API (подключаемый модуль)

  1. Создайте файл с именем http_manifest.yaml в формате APIсредства .

        Descriptor:
      Name: DCA_SampleAPIPlugin
      DisplayName: TESTDCA_Free IP API
      Description: Skills for looking up geolocation information for an IP address using the Free IP API

    SkillGroups:
      - Format: API
        Settings:
          OpenApiSpecUrl: <Reference to your openapispec.yaml schema created in Step 1>
          EndpointUrl: https://sampleurl <The server endpoint that is hosting the API>

  2. Отправьте yaml в Security Copilot. Инструкции по отправке YAML описаны в разделе Манифест агента сборки.

    Примечание.

    Необходимо выполнить действия по настройке, чтобы подключаемый модуль был доступен для использования и появился в разделе Пользовательские . Отправленный YAML или манифест публикуется в качестве агента активным агентам только в том случае, если манифест YAML имеет определение агента (AgentDefinitions).

  3. Вы можете протестировать это средство или подключаемый модуль, перейдя к разделу Возможности системы в Запросы.

  4. lookupIpAddressGeolocationНайдите значение , которое является значением operationId из спецификации API, определенной на шаге 1.

    Изображение подстановки инструмента в Security Copilot

    После выполнения средства отображается ответ.

    Изображение ответа запуска средства в Security Copilot

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

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

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

  2. Отправьте агент YAML в Security Copilot.

Шаг 4. Публикация пакета в хранилище безопасности (необязательно)

Этот шаг применим только к партнерам, разрабатывающим свой агент, который должен быть опубликован в Хранилище безопасности.

Важные рекомендации по публикации манифеста API в хранилище безопасности:

  • При публикации пакета в хранилище openapispec.yaml безопасности необходимо включить в пакет.

  • Объект OpenApiSpecUrl должен ссылаться на локальный путь к файлу в пакете.

  • — EndpointUrl это общедоступная конечная точка для спецификации OpenAPI.

  • ChildSkills Если на указаны ссылки в спецификации Open API, убедитесь, что глобальный URL-адрес для OpenAPISpec и локального yaml OpenAPISpec обновлен.

  • Объект openapispec.yaml должен находиться в той же папке, что и манифест агента yaml(http_manifest.yaml) и должен соответствовать соглашению об именовании: openapispec_<number>.yaml.

  • Last updated on