Crea plug-in API da un'API esistente per Microsoft 365 Copilot

Importante

I plug-in MCP e API forniscono azioni all'interno di agenti dichiarativi. Non sono pacchetti di plugin installabili autonomamente: solo l'agente contenitore può accedere alle loro funzioni e ai loro strumenti. Per informazioni sulla relazione tra pacchetto e manifesto dell'azione, vedere Plug-in e azioni dichiarative dell'agente.

Suggerimento

Consigliato: Inizia con Work IQ Dev Tools per scenari di agenti dichiarativi e plug-in pro-code supportati. Vedere la guida introduttiva di WIQD. Le istruzioni basate su toolkit rimangono disponibili per i progetti e i flussi di lavoro esistenti che le richiedono. Controlla il supporto per le funzionalità e l'esperienza di destinazione prima di scegliere uno strumento: WIQD non si rivolge agli agenti del motore personalizzato.

I plug-in API consentono a un agente dichiarativo di chiamare l'API REST esistente. Usare Microsoft 365 Agents Toolkit per creare un progetto agente con un'integrazione delle azioni API basata sulla specifica OpenAPI dell'API.

Prerequisiti

Suggerimento

Per ottenere risultati ottimali, assicurarsi che la specifica OpenAPI segua le linee guida descritte in dettaglio in Come rendere efficace un documento OpenAPI nell'estensione di Copilot.

Per seguire questa guida, scarica l'API di esempio Budget Tracker e configurala per l'esecuzione nel computer di sviluppo locale. Compila l'esempio almeno una volta per generare il file BudgetTracker.json per l'API.

Creare l'agente e il plug-in API

Nota

Gli screenshot e i riferimenti all'interfaccia utente in questo articolo usano una versione finale di Microsoft 365 Agents Toolkit. Le versioni non definitive potrebbero differire dall'interfaccia utente visualizzata.

La configurazione del plug-in API include:

  • Specifica OpenAPI per l'API REST.
  • Un manifesto del plug-in che fa riferimento alla specifica OpenAPI inclusa e descrive le operazioni disponibili, il metodo di autenticazione e i formati di risposta.

Includere questi file nel pacchetto dell'app dell'agente contenitore insieme al manifesto dell'app, alla definizione dell'agente e alle icone. Il manifesto del plug-in API non è di per sé un pacchetto installabile.

  1. Apri Visual Studio Code. Se Agents Toolkit non è già installato, consulta Installare Agents Toolkit per le istruzioni di installazione.

  2. Seleziona l'icona di Microsoft 365 Agents Toolkit nella barra delle attività a sinistra.

  3. Selezionare Crea un nuovo agente/app nel riquadro attività Toolkit agenti.

    Screenshot dell'interfaccia di Agents Toolkit

  4. Selezionare Agente dichiarativo.

  5. Selezionare Aggiungi un'azione, quindi selezionare Avvia con un documento di descrizione OpenAPI.

  6. Selezionare Sfoglia e passare alla posizione della specifica OpenAPI dall'esempio Budget Tracker, disponibile in ./openapi/BudgetTracker.json.

  7. Seleziona tutte le operazioni da abilitare per il plug-in.

    L'interfaccia utente di Agents Toolkit per selezionare le operazioni

  8. Scegli una posizione per il progetto agente.

  9. Immetti Budget Tracker come nome per il progetto agente.

Una volta completati questi passaggi, Agents Toolkit genera il progetto agente e la configurazione del plug-in API e apre il progetto in una nuova finestra di Visual Studio Code.

Nota

La chiave di prova per lo scambio di codice (PKCE) è abilitata per impostazione predefinita. Se il server di identità non supporta PKCE, disabilitarlo aggiungendo la riga seguente a m365agents.yml nel progetto agente.

isPKCEEnabled: false

Effettuare il provisioning e trasferire localmente l'agente

Il trasferimento locale rende disponibile l'agente contenitore e la relativa azione API per i test di sviluppo. Non installa il plug-in API come funzionalità indipendente. Questa procedura non è un metodo di distribuzione generale per un pacchetto di plug-in composto. Per i percorsi di condivisione e pubblicazione, consulta Scegliere come pubblicare e distribuire il plug-in.

  1. Apri il progetto agente in Visual Studio Code.

  2. Seleziona l'icona di Microsoft 365 Agents Toolkit nella barra delle attività a sinistra.

  3. Nel riquadro Account selezionare Accedi a Microsoft 365. (Se hai già effettuato l'accesso, continua con il passaggio successivo).

  4. Verifica che sia il caricamento dell'app personalizzato abilitato che l'accesso Copilot abilitato vengano visualizzati nel tuo account Microsoft 365. In caso contrario, rivolgersi all'amministratore dell'organizzazione. Per informazioni dettagliate, vedi Requisiti per le opzioni di estensibilità di Copilot .

  5. Nel riquadro Ciclo di vita selezionare Provisioning.

  6. Quando viene richiesto di immettere l'ID client per la registrazione OAuth..., immettere l'ID client del plug-in.

  7. Quando viene richiesto di immettere il segreto client per la registrazione OAuth..., immettere il segreto client del plug-in.

  8. Leggere il messaggio nella finestra di dialogo e selezionare Conferma per continuare.

  9. Attendi che il toolkit segnali che il provisioning è completato.

    Il messaggio di Agents Toolkit che conferma il provisioning riuscito

L'agente è ora disponibile per il test con il tuo account utente in Microsoft 365 Copilot in Microsoft Teams.

Testare l'azione dell'API dell'agente

  1. Apri Teams nel browser e accedi con l'account Microsoft 365 usato per trasferire localmente l'agente.

  2. Seleziona Chat nella barra attività a sinistra.

  3. Seleziona Copilot nel riquadro Chat.

  4. Seleziona Monitoraggio budget nell'elenco Agenti sul lato destro. Se l'elenco non è disponibile, seleziona l'icona Chat di Copilot e altro nell'angolo in alto a destra.

    Screenshot dell'elenco Agenti in Microsoft Teams

  5. Porre una domanda sui budget. Ad esempio, prova How much is left in the Fourth Coffee lobby renovation budget?. Quando richiesto, scegliere Consenti sempre o Consenti una volta per procedere.

  6. Quando viene richiesto di accedere, selezionare Accedi a Monitoraggio budget.