Crie descrições de OpenAPI eficazes para estender o Microsoft 365 Copilot

Os plug-ins de API permitem que os agentes do Microsoft 365 Copilot interajam com serviços Web e acessem informações em tempo real. Um plug-in de API permite que os usuários interajam com dados em tempo real de seu sistema de linha de negócios (LOB) por meio de comandos de linguagem natural para um agente no Copilot Chat.

Um plug-in de API é composto por um serviço de API, sua descrição OpenAPI e um arquivo de manifesto. O manifesto do plug-in informa o orquestrador do Copilot sobre os recursos da API. O manifesto do plug-in inclui uma descrição OpenAPI para o serviço de API. A descrição da OpenAPI é importante porque descreve ao Copilot como se conectar à API. Para obter a capacidade de descoberta e o desempenho ideais do plug-in com o Copilot, forneça uma descrição clara e significativa do OpenAPI.

Este artigo descreve os elementos que tornam uma descrição do OpenAPI eficaz para um plug-in que estende os recursos do agente do Copilot.

Elementos de descrição de OpenAPI

Esta seção descreve os elementos de uma descrição do OpenAPI e como otimizá-los para agentes do Copilot.

Validação OpenAPI: Um primeiro passo bom é verificar se a descrição do OpenAPI segue as regras da Especificação OpenAPI. Você pode usar Hidi, uma ferramenta de linha de comando que pode validar descrições de OpenAPI entre outros casos de uso, ou qualquer outra ferramenta de escolha. Uma descrição válida da OpenAPI não só funciona bem com o Copilot, mas também garante que sua descrição da OpenAPI funcione com outras ferramentas.

A seção de informações: o campo de descrição é opcional na especificação do OpenAPI, mas é essencial para uma descrição do OpenAPI destinada a estender as habilidades do Copilot. O Copilot precisa do campo de descrição para saber o que a API faz e quando usar o plug-in. Ao gerar um manifesto de plug-in a partir de um documento OpenAPI, a descrição na seção de informações é usada como a descrição do manifesto do plug-in. Portanto, é importante sempre ter um campo de descrição breve e claro. Por exemplo, aqui está uma seção de informações da descrição de uma loja de reparos OpenAPI.

info:
  title: Repair Service
  description: A simple service to manage repairs for various items
  version: 1.0.0

IDs da operação: Uma técnica útil para melhorar a usabilidade de uma descrição OpenAPI é adicionar uma operationID combinação para cada de caminho de API e método HTTP oferecido pela API. As IDs de operação são identificadores exclusivos de uma operação na API e são usadas pelo Copilot para criar funções que são executadas ao responder à solicitação de um usuário.

Além disso, adicione uma descrição significativa de cada operação compatível com sua API. Depois que o Copilot escolhe usar um plug-in com base no prompt do usuário e na descrição do plug-in, ele pesquisa as descrições dos caminhos para determinar o ponto de extremidade a ser usado para atender à solicitação do usuário.

As IDs de operação são mostradas durante a depuração como funções para indicar quais operações o Copilot está tentando executar. Aqui está um exemplo de um documento OpenAPI e um exemplo da saída do depurador correspondente:

paths:
  /repairs:
    get:
      operationId: listRepairs
      summary: List all repairs
      description: Returns a list of repairs with their details and images

Saída do depurador:

Imagem do depurador mostrando a função selecionada de um plug-in.

Parâmetros: Se uma operação compatível com sua API incluir parâmetros, inclua os parâmetros na descrição do OpenAPI. Inclua um campo de descrição para cada parâmetro para descrevê-lo brevemente e, quando necessário, dê um exemplo do uso do parâmetro. Os parâmetros são usados pelo Copilot para obter todas as informações necessárias do prompt de um usuário para fazer uma solicitação à API.

Veja um exemplo:

parameters:
  - name: assignedTo
    in: query
    description: The name or ID of the person or team to whom the repair is assigned.
    schema:
      type: string
    required: false

Respostas: Defina claramente todas as respostas possíveis para cada operação, incluindo respostas de sucesso e erro. Cada resposta deve ter um código de status e uma descrição do que ela representa. Incluir exemplos de respostas ajuda o Copilot a entender o que esperar da API.

responses:
  '200':
    description: A list of repairs
    content:
      application/json:
        schema:
          type: array
          items:
            $ref: '#/components/schemas/Repair'
        examples:
          example1:
            value:
              [
                {
                  "id": "1",
                  "item": "Laptop",
                  "status": "In Progress",
                  "assignedTo": "John Doe"
                }
              ]
  '404':
    description: No repairs found
  '500':
    description: Server error

Conteúdo relacionado

  • Last updated on