Comment utiliser le service d'agent Foundry avec les outils spécifiés par OpenAPI

Vous pouvez maintenant connecter votre agent Azure AI à une API externe à l’aide d’un outil spécifié OpenAPI 3.0, ce qui permet une interopérabilité évolutive avec différentes applications. En utilisant des identités managées (MICROSOFT Entra ID) pour l’authentification, vous pouvez activer en toute sécurité vos outils personnalisés pour authentifier l’accès et les connexions. Cette approche est idéale pour l’intégration à l’infrastructure ou aux services web existants.

Les outils spécifiés OpenAPI enrichissent votre expérience d’appel de fonction en fournissant des intégrations d’API standardisées, automatisées et scalables qui améliorent les fonctionnalités et l’efficacité de votre agent. Les spécifications OpenAPI offrent une norme officielle pour décrire les API HTTP. Cette norme aide les personnes à comprendre le fonctionnement d’une API, la façon dont une séquence d’API fonctionne ensemble et prend en charge la génération de code client, la création de tests, l’application de normes de conception, etc. Actuellement, les outils spécifiés OpenAPI 3.0 prennent en charge trois types d’authentification : anonymous, API keyet managed identity.

Assistance à l'utilisation

Prerequisites

1. Vérifiez que vous remplissez les conditions préalables et les étapes de configuration dans le guide de démarrage rapide.
2. Vérifiez les spécifications OpenAPI pour connaître les conditions suivantes :
   1. Bien que non requise par la spécification OpenAPI, chaque fonction doit avoir un operationId pour fonctionner avec l'outil OpenAPI.
   2. Le operationId seul doit contenir des lettres, -et _. Vous pouvez le modifier pour répondre à cette exigence. Utilisez un nom descriptif pour aider les modèles à choisir efficacement la fonction à utiliser.

S’authentifier avec la clé API

En utilisant l’authentification par clé API, vous pouvez authentifier votre spécification OpenAPI par le biais de différentes méthodes, telles qu’une clé API ou un jeton porteur. Chaque spécification OpenAPI ne prend en charge qu’un seul schéma de sécurité de clé API. Si vous avez besoin de plusieurs schémas de sécurité, créez plusieurs outils de spécification OpenAPI.

1. Mettez à jour vos schémas de sécurité de spécification OpenAPI. Il a une securitySchemes section et un schéma de type apiKey. Par exemple:

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

   Vous devez généralement mettre à jour le champ name, qui correspond au nom key dans la connexion. Si les schémas de sécurité incluent plusieurs schémas, ne conservez qu’un seul d’entre eux.

2. Mettez à jour votre spécification OpenAPI pour inclure une security section :

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

3. Supprimez n’importe quel paramètre dans la spécification OpenAPI qui a besoin de la clé API, car la clé API est stockée et transmise via une connexion, comme décrit plus loin dans cet article.

4. Créez une connexion custom keys pour stocker votre clé API.

   1. Accédez au portail Microsoft Foundry et sélectionnez Centre de gestion dans le volet de navigation gauche.

      

   2. Sélectionnez Ressources connectées sous le projet IA dans le volet de navigation gauche.

   3. Sélectionnez + nouvelle connexion dans la page des paramètres.

      Note

      Si vous regénérez la clé API à une date ultérieure, vous devez mettre à jour la connexion avec la nouvelle clé.

      

   4. Sélectionnez Clés personnalisées dans Autres types de ressources.

      

   5. Entrez les informations ci-après

      • clé : name champ de votre schéma de sécurité. Dans cet exemple, cela devrait être x-api-key

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

      • valeur : YOUR_API_KEY

      • Nom de la connexion : YOUR_CONNECTION_NAME (vous utilisez ce nom de connexion dans l’exemple de code ci-dessous.)

      • Accès : vous pouvez choisir ce projet uniquement ou partagée avec tous les projets. Assurez-vous juste que, dans l’exemple de code ci-dessous, le projet pour lequel vous avez entré la chaîne de connexion a accès à cette connexion.

5. Après avoir créé une connexion, utilisez-la via le Kit de développement logiciel (SDK) ou l’API REST. Utilisez les onglets en haut de cet article pour afficher des exemples de code.

S’authentifier avec une identité managée (ID Microsoft Entra)

Microsoft Entra ID est un service de gestion des identités et des accès cloud que vos employés peuvent utiliser pour accéder aux ressources externes. À l’aide de l’ID Microsoft Entra, vous pouvez ajouter une sécurité supplémentaire lorsque vous authentifiez vos API sans avoir à utiliser de clés API. Après avoir configuré l’authentification d’identité managée, l’outil Foundry que votre agent utilise gère l’authentification.

Lors de la configuration de l’authentification d’identité managée, vous devez fournir une valeur d'audience . L’audience est l’identificateur de ressource OAuth2 (également appelé URI d’étendue ou d’ID d’application) qui identifie l’API ou le service auquel l’identité managée peut accéder.

Valeurs d’audience courantes :

• Foundry Tools (anciennement Azure AI Services ou Cognitive Services) : https://cognitiveservices.azure.com/
• API Azure Resource Manager : https://management.azure.com/
• Microsoft Graph : https://graph.microsoft.com/
• API personnalisées inscrites dans Microsoft Entra ID : utilisez l'URI d’ID d’application disponible dans l’inscription de l’application de l’API

Pour configurer l’authentification à l’aide de Managed Identity :

1. Vérifiez que votre ressource Foundry dispose d’une identité managée affectée par le système activée.

   

2. Créez une ressource pour le service auquel vous souhaitez vous connecter via la spécification OpenAPI.

3. Attribuez l’accès approprié à la ressource.

   1. Sélectionnez Contrôle d’accès pour votre ressource.

   2. Sélectionnez Ajouter , puis ajoutez une attribution de rôle en haut de l’écran.

      

   3. Sélectionnez l’attribution de rôle appropriée nécessaire. En règle générale, il nécessite au moins le rôle LECTEUR . Ensuite, sélectionnez Suivant.

   4. Sélectionnez Identité managée , puis sélectionnez membres.

   5. Dans le menu déroulant identité gérée, recherchez Foundry Tools et sélectionnez ensuite le Foundry Tool de votre agent.

   6. Sélectionnez Terminer.

4. Une fois l’installation terminée, vous pouvez utiliser l’outil via le portail Foundry, le Kit de développement logiciel (SDK) ou l’API REST. Utilisez les onglets en haut de cet article pour afficher des exemples de code.