Creare descrizioni OpenAPI efficaci per estendere Microsoft 365 Copilot

I plug-in API consentono agli agenti di Microsoft 365 Copilot di interagire con i servizi Web e accedere alle informazioni in tempo reale. Un plug-in API consente agli utenti di interagire con i dati in tempo reale del loro sistema line-of-business (LOB) tramite comandi in linguaggio naturale a un agente all'interno di Copilot Chat.

Un plug-in API è composto da un servizio API, dalla sua descrizione OpenAPI e da un file manifesto. Il manifesto del plug-in informa l'agente di orchestrazione Copilot sulle funzionalità dell'API. Il manifesto del plug-in include una descrizione OpenAPI per il servizio API. La descrizione OpenAPI è importante perché descrive a Copilot come connettersi all'API. Per ottenere risultati ottimali per l'individuazione e le prestazioni dei plug-in con Copilot, fornire una descrizione chiara e significativa dell'API OpenAPI.

Questo articolo descrive gli elementi che rendono efficace una descrizione OpenAPI per un plug-in che estende le funzionalità dell'agente Copilot.

Elementi di descrizione di OpenAPI

Questa sezione descrive gli elementi di una descrizione OpenAPI e come ottimizzarli per gli agenti Copilot.

Convalida OpenAPI: un buon primo passo è verificare che la descrizione di OpenAPI segua le regole della specifica OpenAPI. Puoi usare Hidi, uno strumento da riga di comando in grado di convalidare le descrizioni OpenAPI tra gli altri casi d'uso, o qualsiasi altro strumento a tua scelta. Una descrizione OpenAPI valida non solo funziona bene con Copilot, ma garantisce anche che la descrizione OpenAPI possa funzionare con altri strumenti.

Sezione informazioni: il campo della descrizione è facoltativo nella specifica OpenAPI, ma è essenziale per una descrizione OpenAPI destinata ad estendere le competenze di Copilot. Copilot ha bisogno del campo descrizione per sapere cosa fa l'API e quando usare il plug-in. Quando si genera un file manifest del plugin da un documento OpenAPI, la descrizione nella sezione info viene usata come descrizione per il file manifest del plugin. Per questo motivo, è importante disporre sempre di un campo descrizione breve e chiaro. Ad esempio, ecco una sezione info della descrizione OpenAPI di un'officina di riparazione.

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

ID operazione: Una tecnica utile per migliorare l'usabilità di una descrizione OpenAPI è l'aggiunta di una operationID combinazione per ogni percorso API e metodo HTTP offerta dall'API. Gli ID operazione sono identificatori univoci per un'operazione nell'API e vengono utilizzati da Copilot per creare funzioni che vengono eseguite quando si risponde alla richiesta di un utente.

Aggiungere anche una descrizione significativa di ogni operazione supportata dall'API. Dopo che Copilot sceglie di usare un plug-in in base alla richiesta dell'utente e alla descrizione del plug-in, Copilot esegue una ricerca nelle descrizioni dei percorsi per determinare l'endpoint da usare per soddisfare la richiesta dell'utente.

Gli ID operazione vengono visualizzati durante il debug come funzioni per indicare le operazioni che Copilot sta tentando di eseguire. Ecco un esempio di documento OpenAPI e un esempio dell'output del debugger corrispondente:

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

Output del debugger:

Immagine del debugger che mostra la funzione selezionata di un plug-in.

Parametri: Se un'operazione supportata dall'API accetta parametri, includerli nella descrizione di OpenAPI. Includere un campo di descrizione per ogni parametro per descriverlo brevemente e, se necessario, fornire un esempio di utilizzo del parametro. I parametri vengono usati da Copilot per ottenere tutte le informazioni necessarie dalla richiesta di un utente per effettuare una richiesta all'API.

Ecco un esempio:

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

Risposte: Definire chiaramente tutte le risposte possibili per ogni operazione, incluse le risposte di esito positivo e di errore. Ogni risposta deve avere un codice di stato e una descrizione di ciò che rappresenta. Includere esempi di risposte aiuta Copilot a capire cosa aspettarsi dall'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