Crear descripciones eficaces de OpenAPI para ampliar Microsoft 365 Copilot

Los complementos de API permiten a los agentes de Microsoft 365 Copilot interactuar con los servicios web y acceder a información en tiempo real. Un complemento de API permite a los usuarios interactuar con datos en tiempo real de su sistema de línea de negocio (LOB) a través de comandos de lenguaje natural a un agente dentro de Copilot Chat.

Un complemento de API se compone de un servicio API, su descripción OpenAPI y un archivo de manifiesto. El manifiesto del complemento informa al orquestador de Copilot sobre las capacidades de la API. El manifiesto del complemento incluye una descripción OpenAPI para el servicio de API. La descripción de OpenAPI es importante porque describe a Copilot cómo conectarse a la API. Para una óptima detectabilidad de complementos y rendimiento con Copilot, proporciona una descripción clara y significativa de OpenAPI.

En este artículo se describen los elementos que hacen que una descripción de OpenAPI sea eficaz para un complemento que amplía las capacidades del agente de Copilot.

Elementos de descripción de OpenAPI

En esta sección se describen los elementos de una descripción de OpenAPI y cómo optimizarlos para los agentes de Copilot.

Validación de OpenAPI: Un buen primer paso es verificar que la descripción de OpenAPI sigue las reglas de la especificación OpenAPI. Puede usar Hidi, una herramienta de línea de comandos que puede validar descripciones de OpenAPI entre otros casos de uso, o cualquier otra herramienta de elección. Una descripción de OpenAPI válida no solo funciona bien con Copilot, sino que también garantiza que la descripción de OpenAPI pueda funcionar con otras herramientas.

La sección de información: El campo de descripción es opcional en la especificación OpenAPI, pero es esencial para una descripción OpenAPI destinada a ampliar las habilidades de Copilot. Copilot necesita el campo de descripción para saber qué hace la API y cuándo usar el complemento. Cuando se genera un manifiesto de complemento a partir de un documento OpenAPI, la descripción de la sección de información se usa como descripción del manifiesto del complemento. Por lo tanto, es importante tener siempre un campo de descripción que sea breve y claro. Por ejemplo, aquí hay una sección de información de la descripción de OpenAPI de un taller de reparaciones.

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

Id. de operación: Una técnica útil para mejorar la usabilidad de una descripción de OpenAPI es agregar un operationID para cada combinación de ruta de API y método HTTP ofrecido por la API. Los identificadores de operación son identificadores únicos de una operación de la API y Copilot los usa para crear funciones que se ejecutan al responder a la indicación de un usuario.

Además, agregue una descripción significativa de cada operación admitida por la API. Después de que Copilot elige usar un complemento en función del mensaje del usuario y la descripción del complemento, busca en las descripciones de las rutas para determinar el punto de conexión que se usará para satisfacer la solicitud del usuario.

Los identificadores de operación se muestran durante la depuración como funciones para indicar qué operaciones está intentando ejecutar Copilot. Este es un ejemplo de un documento OpenAPI y un ejemplo de la salida del depurador correspondiente:

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

Salida del depurador:

Imagen de depurador que muestra la función seleccionada de un complemento.

Parámetros: Si una operación compatible con la API incluye parámetros, incluye los parámetros en la descripción de OpenAPI. Incluye un campo de descripción para cada parámetro para describirlo brevemente y, si es necesario, da un ejemplo del uso del parámetro. Copilot usa los parámetros para obtener toda la información necesaria de la solicitud de un usuario para realizar una solicitud a la API.

Aquí le mostramos un ejemplo:

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

Respuestas: Defina claramente todas las respuestas posibles para cada operación, incluidas las respuestas correctas y erróneas. Cada respuesta debe tener un código de estado y una descripción de lo que representa. Incluir ejemplos de respuestas ayuda a Copilot a comprender qué esperar de la 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