Ajouter un outil d’API (plug-in) à votre agent

Importante

Certaines informations contenues dans cet article concernent le produit en préversion, qui peut être considérablement modifié avant sa publication commerciale. Microsoft n’offre aucune garantie, explicite ou implicite, concernant les informations fournies ici.

Les développeurs d’agents doivent souvent effectuer des requêtes HTTP pour générer des cas d’usage complets.

Cet exemple illustre la création d’un agent qui tire parti d’un plug-in avec un outil API pour se connecter à un service d’API REST appelé freeipapi.com, qui fournit la fonctionnalité de recherche géo-IP.

Le processus global est le suivant :

1. Étape 1 : Créer et publier une spécification OpenAPI qui définit l’API

2. Étape 2 : Créer et charger le fichier manifeste dans Security Copilot

3. Étape 3 : Créer et charger un agent qui utilise le plug-in

4. Étape 4 : Publier le package dans le magasin de sécurité (applicable uniquement aux agents partenaires)

   Remarque

   Pour obtenir un exemple YAML de manifeste qui utilise l’outil API (compétence), consultez Générer l’agent à l’aide de plusieurs outils. Il vous fournit des instructions sur la façon de charger l’agent, de configurer et d’exécuter l’agent publié sur la page Agents actifs.

Étape 1 : Créer et publier une spécification OpenAPI

L’exemple s’intègre à l’API REST IP gratuite pour effectuer des recherches de géolocalisation d’adresses IP. Vous devez publier cette spécification en ligne (un gist GitHub fonctionne bien). Reportez-vous à l’exemple suivant pour créer et héberger votre spécification. Pour obtenir des exemples d’authentification, consultez Types d’authentification.

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

Étape 2 : Créer et charger le manifeste d’API (plug-in)

1. Créez un fichier appelé http_manifest.yaml au format APId’outil .

       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. Chargez le yaml dans Security Copilot. Les instructions pour le chargement du YAML sont décrites dans Manifeste de l’agent de build.

   Remarque

   Vous devez effectuer les étapes de configuration pour que le plug-in soit disponible et apparaisse dans la section Personnalisé . Le yaML chargé ou le manifeste est publié en tant qu’agent sur les agents actifs uniquement si le manifeste YAML a une définition d’agent (AgentDefinitions) définie.

3. Vous pouvez tester cet outil ou ce plug-in en accédant à Fonctionnalités système dans Requêtes et en recherchant lookupIpAddressGeolocation, qui est la operationId valeur de la spécification de l’API, que vous avez définie à l’étape 1.

   

   La réponse après l’exécution de l’outil s’affiche.

   

Étape 3 : Créer et charger un agent qui utilise le plug-in d’API

À présent, chargez l’agent qui utilise le plug-in d’API.

1. Lorsque vous chargez un agent, veillez à choisir Tout le monde dans cet espace de travail dans l’écran Ajouter un plug-in .

2. Chargez l’agent YAML dans Security Copilot.

Étape 4 : (facultatif) Publier le package dans le magasin de sécurité

Cette étape s’applique uniquement aux partenaires qui développent leur agent qui doit être publié dans le Magasin de sécurité.

Considérations importantes pour la publication d’un manifeste d’API dans le magasin de sécurité :

• Lors de la publication de votre package dans le Magasin de sécurité, doit openapispec.yaml être inclus dans le package.

• doit OpenApiSpecUrl référencer le chemin d’accès au fichier local dans le package.

• est EndpointUrl le point de terminaison hébergé publiquement pour la spécification OpenAPI.

• Si les ChildSkills sont référencés dans une spécification d’API Open, assurez-vous que l’URL globale de votre OpenAPISpec et le yaml OpenAPISpec local sont à jour.

• Doit openapispec.yaml se trouver dans le même dossier que le manifeste de l’agent yaml(http_manifest.yaml) et doit suivre la convention d’affectation de noms : openapispec_<number>.yaml.