Использование службы агента Foundry с указанными средствами OpenAPI (классическая модель)

Теперь агент ИИ Azure можно подключить к внешнему API с помощью указанного средства OpenAPI 3.0, что позволяет масштабировать взаимодействие с различными приложениями. С помощью управляемых удостоверений (Microsoft Entra ID) для проверки подлинности, можно безопасно разрешить вашим кастомизированным инструментам аутентифицировать доступ и подключения. Этот подход идеально подходит для интеграции с существующей инфраструктурой или веб-службами.

Указанное средство OpenAPI улучшает интерфейс вызова функций, предоставляя стандартизированные, автоматизированные и масштабируемые интеграции API, которые повышают возможности и эффективность агента. Спецификации OpenAPI предоставляют формальный стандарт для описания API HTTP. Этот стандарт помогает людям понять, как работает API, как работает последовательность API, и поддерживает создание клиентского кода, создание тестов, применение стандартов проектирования и многое другое. В настоящее время указанные средства OpenAPI 3.0 поддерживают три типа проверки подлинности: anonymous, API keyи managed identity.

Поддержка использования

Необходимые условия

1. Убедитесь, что предварительные требования и действия по настройке выполнены в кратком руководстве.
2. Проверьте спецификацию OpenAPI для следующих требований:
   1. Хотя спецификация OpenAPI этого не требует, каждая функция должна иметь operationId для работы с инструментом OpenAPI.
   2. Элемент operationId должен содержать только буквы, - и _. Его можно изменить в соответствии с этим требованием. Используйте описательное имя, чтобы помочь моделям эффективно решить, какую функцию следует использовать.

Проверка подлинности с помощью ключа API

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

1. Обновите схемы безопасности спецификаций OpenAPI. Он содержит securitySchemes раздел и одну схему типа apiKey. Например:

    "securitySchemes": {
        "apiKeyHeader": {
                "type": "apiKey",
                "name": "x-api-key",
                "in": "header"
            }
    }
   

   Обычно нужно только обновить name поле, соответствующее имени key в соединении. Если схемы безопасности включают несколько схем, сохраните только одну из них.

2. Обновите спецификацию OpenAPI, чтобы включить security раздел:

   "security": [
        {  
        "apiKeyHeader": []  
        }  
    ]
   

3. Удалите любой параметр в спецификации OpenAPI, требующей ключа API, так как ключ API хранится и передается через подключение, как описано далее в этой статье.

4. custom keys Создайте подключение для хранения ключа API.

   1. Перейдите на портал Microsoft Foundry и выберите центр Management в области навигации слева.

      

   2. Выберите подключенные ресурсы в проекте искусственного интеллекта на левой панели навигации.

   3. Выберите +создать подключение на странице параметров.

      Примечание

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

      

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

      

   5. Введите следующие сведения

      • ключ: name поле вашей схемы безопасности. В этом примере должно быть x-api-key

        "securitySchemes": {
            "apiKeyHeader": {
                    "type": "apiKey",
                    "name": "x-api-key",
                    "in": "header"
                }
        }
        

      • значение: YOUR_API_KEY

      • Имя подключения: YOUR_CONNECTION_NAME (это имя подключения используется в примере кода ниже.)

      • Доступ: вы можете выбрать только этот проект или предоставить общий доступ ко всем проектам. Просто убедитесь, что в приведенном ниже примере кода строка соединения, введенная для проекта, имеет доступ к этому подключению.

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

Аутентификация с помощью управляемого удостоверения (Microsoft Entra ID)

Microsoft Entra ID — это облачная служба управления удостоверениями и доступом, которую сотрудники могут использовать для доступа к внешним ресурсам. Используя Microsoft Entra ID, вы можете добавить дополнительную безопасность при проверке подлинности API без необходимости использовать ключи API. После того как вы настроите проверку подлинности для управляемой идентичности, средство Foundry, используемое вашим агентом, будет обрабатывать проверку подлинности.

При настройке проверки подлинности управляемого удостоверения необходимо указать значение Audience. Аудитория — это идентификатор ресурса OAuth2 (также называемый URI области или идентификатора приложения), который определяет, к каким API или службе может получить доступ управляемое удостоверение.

Общие значения аудитории:

• Средства Foundry (ранее Azure AI services или Cognitive Services): https://cognitiveservices.azure.com/
• API управления ресурсами Azure: https://management.azure.com/
• Microsoft Graph: https://graph.microsoft.com/
• Пользовательские API, зарегистрированные в Microsoft Entra ID: используйте URI идентификатора приложения Application ID, найденный в регистрации приложения для API.

Чтобы настроить проверку подлинности с помощью управляемого удостоверения, выполните следующее:

1. Убедитесь, что для вашего ресурса Foundry включена назначенная системой управляемая идентичность.

   

2. Создайте ресурс для службы, к которой вы хотите подключиться через спецификацию OpenAPI.

3. Назначьте правильный доступ к ресурсу.

   1. Выберите контроль доступа для ресурса.

   2. Выберите "Добавить " и добавьте назначение ролей в верхней части экрана.

      

   3. Выберите нужное назначение роли. Как правило, для нее требуется по крайней мере роль ЧИТАТЕЛЯ . Затем нажмите кнопку "Далее".

   4. Выберите управляемое удостоверение и выберите участников.

   5. В раскрывающемся меню управляемого удостоверения найдите Foundry Tools, а затем выберите Foundry Tool вашего агента.

   6. Нажмите кнопку "Готово".

4. После завершения установки можно использовать средство с помощью портала Foundry, пакета SDK или REST API. Используйте вкладки в верхней части этой статьи, чтобы просмотреть примеры кода.