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

Os desenvolvedores de agentes geralmente precisam fazer solicitações HTTP para criar casos de uso completos.

Este exemplo demonstra a criação de um Agente que aproveita um plug-in com uma ferramenta de API para se conectar a um serviço de API REST chamado freeipapi.com, que fornece a funcionalidade de pesquisa de Geo-IP.

O processo geral é o seguinte:

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

2. Etapa 2: criar e carregar o arquivo de manifesto no Security Copilot

3. Etapa 3: Carregue o agente que usa o plug-in

4. Etapa 4: Publicar o pacote no Repositório de Segurança (aplicável apenas para agentes de parceiros)

   Observação

   Para obter um exemplo de YAML de manifesto que usa a ferramenta de API (habilidade), consulte Criar agente usando várias ferramentas. Ele fornece instruções sobre como fazer upload do agente, configurar e executar o agente publicado na página de agentes ativos.

Etapa 1: criar e publicar a especificação OpenAPI

As seções a seguir explicam como criar um agente usando um plug-in de API e a especificação OpenAPI para pesquisas de geolocalização.

O exemplo se integra à API REST de IP Gratuito para realizar pesquisas de geolocalização de Endereço IP. Você deve publicar essa especificação online (um GitHub gist funciona bem). Consulte o exemplo a seguir para criar e hospedar sua especificação. Para obter exemplos sobre autenticação, consulte 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

Etapa 2: criar e carregar o manifesto da API (plug-in)

1. Crie um arquivo chamado http_manifest.yaml que é do formato APIde 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 no Security Copilot. As instruções para carregar o YAML são abordadas em, Manifesto do agente de compilação.

   Observação

   Você precisa concluir as etapas de configuração para que o plug-in esteja disponível para uso e apareça na seção Personalizado . O YAML ou manifesto carregado será publicado como um agente para agentes ativos somente se o manifesto YAML tiver uma definição de agente (AgentDefinitions) definida.

3. Você pode testar essa ferramenta ou plug-in navegando até Recursos do sistema em Prompts.

4. lookupIpAddressGeolocationPesquise , que é o operationId valor da especificação da API, que você definiu na Etapa 1.

   

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

   

Etapa 3: Carregue o agente que usa o plug-in de API

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

1. Ao fazer upload de um agente, certifique-se de escolher Qualquer pessoa neste espaço de trabalho na tela Adicionar um plug-in .

2. Carregue o YAML do agente no Security Copilot.

Etapa 4: Publicar o pacote no Repositório de Segurança (opcional)

Esta etapa é aplicável somente a parceiros que desenvolvem seu agente que deve ser publicado no Repositório de Segurança.

Considerações importantes para publicar um manifesto de API no Repositório de Segurança:

• Ao publicar seu pacote no Repositório de Segurança, ele openapispec.yaml deve ser incluído no pacote.

• Eles OpenApiSpecUrl devem fazer referência ao caminho do arquivo local dentro do pacote.

• Ele EndpointUrl é o ponto de extremidade hospedado publicamente para a especificação OpenAPI.

• Se forem ChildSkills referenciados em uma especificação de API aberta, verifique se a URL global do seu OpenAPISpec e do yaml OpenAPISpec local estão atualizadas.

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