Aggiungere uno strumento API (plug-in) all'agente

Importante

Alcune informazioni in questo articolo fanno riferimento alle caratteristiche di un prodotto prima del rilascio, che possono essere modificate sostanzialmente prima della distribuzione al pubblico. Microsoft non fornisce alcuna garanzia, esplicita o implicita, in relazione alle informazioni contenute in questo documento.

Gli sviluppatori di agenti spesso devono effettuare richieste HTTP per compilare casi d'uso completi.

Questo esempio illustra la creazione di un agente che sfrutta un plug-in con uno strumento API per connettersi a un servizio API REST denominato freeipapi.com, che fornisce la funzionalità di ricerca GEO-IP.

Il processo complessivo è il seguente:

1. Passaggio 1: Creare e pubblicare una specifica OpenAPI che definisce l'API

2. Passaggio 2: Creare e caricare il file manifesto in Security Copilot

3. Passaggio 3: Creare e caricare un agente che usa il plug-in

4. Passaggio 4: Pubblicare il pacchetto nell'archivio sicurezza (applicabile solo agli agenti partner)

   Nota

   Per un esempio YAML manifesto che usa lo strumento API (competenza), vedere Compilare l'agente usando più strumenti. Fornisce istruzioni su come caricare l'agente, configurare ed eseguire l'agente pubblicato nella pagina Agenti attivi.

Passaggio 1: Creare e pubblicare una specifica OpenAPI

L'esempio si integra con l'API REST ip gratuita per eseguire ricerche di georilevazione degli indirizzi IP. È necessario pubblicare questa specifica online (un gist di GitHub funziona bene). Fare riferimento all'esempio seguente per creare e ospitare la specifica. Per esempi sull'autenticazione, vedere Tipi di autenticazione.

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

Passaggio 2: Creare e caricare il manifesto dell'API (plug-in)

1. Creare un file denominato http_manifest.yaml nel formato APIdello strumento .

       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. Caricare lo yaml in Security Copilot. Le istruzioni per il caricamento di YAML sono illustrate in Manifesto dell'agente di compilazione.

   Nota

   È necessario completare i passaggi di configurazione per rendere disponibile il plug-in per l'uso e visualizzarlo nella sezione Personalizzata . Il manifesto o YAML caricato viene pubblicato come agente negli agenti attivi solo se il manifesto YAML ha una definizione dell'agente (AgentDefinitions).

3. È possibile testare questo strumento o plug-in passando a Funzionalità di sistema in Prompt e cercando lookupIpAddressGeolocation, ovvero il operationId valore della specifica API definita nel passaggio 1.

   

   Viene visualizzata la risposta dopo l'esecuzione dello strumento.

   

Passaggio 3: Creare e caricare un agente che usa il plug-in API

Caricare ora l'agente che usa il plug-in API.

1. Quando si carica un agente, assicurarsi di scegliere Chiunque nell'area di lavoro nella schermata Aggiungi plug-in .

2. Caricare l'agente YAML in Security Copilot.

Passaggio 4: (facoltativo) Pubblicare il pacchetto nell'archivio sicurezza

Questo passaggio è applicabile solo ai partner che sviluppano l'agente che devono essere pubblicati in Security Store.

Considerazioni importanti per la pubblicazione di un manifesto API nell'archivio sicurezza:

• Quando si pubblica il pacchetto in Security Store, deve openapispec.yaml essere incluso nel pacchetto.

• Deve OpenApiSpecUrl fare riferimento al percorso del file locale all'interno del pacchetto.

• è EndpointUrl l'endpoint ospitato pubblicamente per la specifica OpenAPI.

• ChildSkills Se viene fatto riferimento a in una specifica open API, assicurarsi che l'URL globale per OpenAPISpec e il yaml OpenAPISpec locale siano aggiornati.

• Deve openapispec.yaml trovarsi nella stessa cartella del manifesto dell'agente yaml(http_manifest.yaml) e deve seguire la convenzione di denominazione: openapispec_<number>.yaml.