Adicionar uma ferramenta de API (plug-in) ao agente

Importante

Algumas informações neste artigo estão relacionadas ao produto pré-lançado que pode ser modificado substancialmente antes de ser lançado comercialmente. A Microsoft não faz garantias, expressas ou implícitas, quanto às informações fornecidas aqui.

Os programadores de agentes precisam frequentemente de fazer pedidos HTTP para criar casos de utilização completos.

Este exemplo demonstra a criação de um Agente que tira partido de um plug-in com uma ferramenta de API para ligar a um serviço de API REST chamado freeipapi.com, que fornece a funcionalidade de pesquisa de Ip Geográfico.

O processo geral é o seguinte:

1. Passo 1: Criar e publicar uma especificação OpenAPI que define a API

2. Passo 2: criar e carregar o ficheiro de manifesto para Security Copilot

3. Passo 3: criar e carregar um agente que utiliza o plug-in

4. Passo 4: publicar o pacote no Arquivo de Segurança (aplicável apenas a agentes parceiros)

   Observação

   Para obter um exemplo yaml de manifesto que utiliza a ferramenta de API (competência), veja Build agent using multiple tools (Criar agente com várias ferramentas). Fornece-lhe instruções sobre como carregar o agente, configurar e executar o agente publicado na página Agentes ativos.

Passo 1: Criar e publicar uma especificação OpenAPI

O exemplo integra-se com a API REST de IP Gratuito para efetuar pesquisas de geolocalização de Endereços IP. Tem de publicar esta especificação online (uma essência do GitHub funciona bem). Veja o exemplo seguinte para criar e alojar a sua especificação. Para obter exemplos sobre autenticação, veja Tipos de autenticação.

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

Passo 2: Criar e carregar o manifesto da API (plug-in)

1. Crie um ficheiro chamado http_manifest.yaml que tenha o formato APIda ferramenta .

       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. Carregue o yaml para Security Copilot. As instruções para carregar o YAML são abordadas em Manifesto do agente de compilação.

   Observação

   Tem de concluir os passos de configuração para que o plug-in esteja disponível para utilização e apareça na secção Personalizado . O YAML ou manifesto carregado é publicado como um agente para Agentes ativos apenas se o manifesto YAML tiver uma definição de agente (AgentDefinitions) definida.

3. Pode testar esta ferramenta ou plug-in ao navegar para As Capacidades do Sistema no Prompts e procurar lookupIpAddressGeolocation, que é o operationId valor da especificação da API, que definiu no Passo 1.

   

   A resposta após a execução da ferramenta é apresentada.

   

Passo 3: criar e carregar um agente que utiliza o plug-in da API

Agora, carregue o agente que utiliza o plug-in da API.

1. Ao carregar um agente, certifique-se de que seleciona Qualquer pessoa nesta área de trabalho em Adicionar um ecrã de plug-in .

2. Carregue o AGENTE YAML para Security Copilot.

Passo 4: (opcional) Publicar o pacote no Arquivo de Segurança

Este passo só é aplicável aos parceiros que desenvolvam o respetivo agente que têm de ser publicados no Arquivo de Segurança.

Considerações importantes para publicar um manifesto de API no Arquivo de Segurança:

• Ao publicar o seu pacote no Arquivo de Segurança, o openapispec.yaml tem de ser incluído no pacote.

• O OpenApiSpecUrl tem de referenciar o caminho do ficheiro local no pacote.

• É EndpointUrl o ponto final alojado publicamente para a especificação OpenAPI.

• Se os ChildSkills forem referenciados numa especificação de Open API, certifique-se de que o URL global do openAPISpec e do yaml openAPISpec local estão atualizados.

• O openapispec.yaml tem de estar na mesma pasta que o yaml(http_manifest.yaml) do manifesto do Agente e tem de seguir a convenção de nomenclatura: openapispec_<number>.yaml.