Estendere l'agente con strumenti da un'API REST (anteprima)

[Questo articolo fa parte della documentazione non definitiva, pertanto è soggetto a modifiche.]

Puoi utilizzare le API REST (incluse le API OpenAI) per connettere un agente creato con sistemi esterni e accedere ai dati disponibili per l'uso all'interno dell'agente. È possibile connettere l'agente a un'API REST fornendo Copilot Studio tre elementi:

• Una specifica OpenAPI che definisce le funzioni dell'API e le azioni disponibili
• Dettagli sul tipo di autenticazione necessaria e dettagli di autenticazione per gli utenti che si connettono all'API per accedere al sistema esterno
• Descrizioni per aiutare il modello linguistico a determinare quando richiamare l'API per utilizzare i dati

È possibile aggiungere API REST agli agenti Copilot e agli agenti personalizzati tramite Copilot Studio.

Importante

Questo articolo contiene Microsoft Copilot Studio documentazione di anteprima ed è soggetto a modifiche.

Le funzionalità di anteprima non sono progettate per l'uso in produzione e possono avere funzionalità limitate. Queste funzionalità sono disponibili prima di una versione ufficiale in modo che sia possibile ottenere l'accesso iniziale e inviare commenti.

Se stai creando un agente pronto per la produzione, consulta Panoramica di Microsoft Copilot Studio.

Gli agenti Copilot consentono a un creatore di combinare più origini dati, come connettori, API, suggerimenti e fonti di conoscenza, in un singolo agente. Usare questo agente per estendere le esperienze degli agenti Microsoft, ad esempio Microsoft 365 Copilot.

Gli agenti personalizzati sono agenti autonomi che contengono connettori, API, richieste e fonti di conoscenza. È possibile utilizzare direttamente gli agenti personalizzati integrandoli nei siti Web o in altri canali.

Nota

È necessario creare strumenti api REST da una specifica OpenAPI v2. Questo requisito è dovuto al comportamento di Power Platform nelle specifiche dell'API di elaborazione. Se si invia una specifica v3, il processo di creazione lo converte automaticamente in una specifica v2.

Prerequisiti

• Credenziali a livello Maker e una licenza di Copilot Studio.
• Una copia della specifica OpenAPI per l'API REST a cui vuoi connetterti
• Conoscenza del tipo di autenticazione necessaria per connettersi all'API e dei dettagli dell'autenticazione.

Aggiungi uno strumento API REST al tuo agente

Per aggiungere uno strumento API REST all'agente, completare la procedura seguente:

1. Aggiungi un nuovo strumento per agenti e seleziona REST API
2. Fornire specifica, descrizione e soluzione API
3. Fornire i dettagli di autenticazione
4. Seleziona gli strumenti dall'API
5. Rivedere e pubblicare

Le sezioni seguenti ti guidano nel processo, passo dopo passo.

Il processo di aggiunta di un'API REST è lo stesso sia per gli agenti personalizzati che per gli agenti Microsoft 365 Copilot.

Aggiungi nuovo strumento agente e seleziona REST API

1. Vai alla pagina Panoramica del tuo agente.

2. Nella sezione Strumenti selezionare Aggiungi strumento. È anche possibile passare alla scheda Strumenti e selezionare Aggiungi uno strumento.

   Viene visualizzata la pagina Aggiungi strumento .

3. Selezionare New tool REST API ( Nuovo strumento>API REST).

Fornire specifica, descrizione e soluzione API

1. Caricare un file di specifica OpenAPI per l'API REST al quale si desidera stabilire la connessione. Puoi trascinare e rilasciare il file delle specifiche nella schermata Carica un'API REST o cerca nel sistema per individuare il file che desideri utilizzare.

   

   Nota

   La specifica OpenAPI deve essere un file JSON in formato v2. Se si invia una specifica v3, il processo di creazione lo converte automaticamente in una specifica v2.

   Dopo aver caricato la specifica, la schermata viene aggiornata per visualizzare il nome del file di specifica e i dettagli.

   

   Nei passaggi seguenti la procedura usa un esempio specifico di SunnyADO, un sistema di gestione dei ticket ADO. Nell'esempio, l'intenzione è quella di consentire agli utenti di recuperare e aggiornare i propri ticket tramite l'agente.

2. Verificare i dettagli e quindi selezionare Avanti.

   Viene visualizzata una pagina dei dettagli del plug-in API in cui è possibile fornire ulteriori informazioni sull'API.

   

   Il campo della descrizione viene inizialmente popolato in base alla descrizione nella specifica dell'API caricata. Fornisci una descrizione dettagliata, perché l'orchestrazione degli agenti utilizza la descrizione per determinare quando impiegare lo specifico strumento. Fornisci dettagli, inclusi sinonimi, per aiutare il tuo agente nel processo di selezione.

   Ad esempio, la descrizione iniziale fornita è: "Un semplice servizio per gestire i ticket".

   Una descrizione migliore è: "Un sistema utilizzato per ottenere, recuperare, trovare e visualizzare i ticket esistenti da SunnyADO." Consente agli utenti di aggiornare, modificare e gestire i ticket per fornire più dati per migliorare i record."

3. Inserisci una descrizione migliorata nel campo Descrizione.

4. In Soluzione, un menu a discesa elenca tutte le soluzioni disponibili nell'ambiente corrente. Seleziona la soluzione che vuoi usare. Altre informazioni sulle soluzioni sono disponibili in Concetti relativi alle soluzioni.

   

   Se hai una soluzione preferita o il connettore selezionato è già presente nella soluzione, tale soluzione verrà selezionata automaticamente.

   Puoi selezionare una soluzione o lasciarla vuota. Se lasci vuota la soluzione, viene creata automaticamente una soluzione con il nome dell'azione e l'editore predefinito. Memorizzare la tua azione in una soluzione ti consente di spostarla facilmente tra gli ambienti.

   Nota

   Se non viene visualizzata la soluzione predefinita o la soluzione predefinita CDS come opzione in questo caso, aggiungere una soluzione personalizzata per semplificare la gestione. Per altre informazioni, vedere Soluzione predefinita e soluzione personalizzata.

5. Con una soluzione selezionata, seleziona Avanti per procedere.

Fornire i dettagli di autenticazione

Verrà visualizzata la pagina Autenticazione . Selezionare il tipo di autenticazione da usare per l'API.

1. Seleziona un metodo di autenticazione dall'elenco. Selezionare una delle tre opzioni seguenti:

   • Nessuno: non è richiesta autenticazione per accedere all'API.
   • Chiave API: Seleziona questa opzione se la tua API richiede una chiave API per l'autenticazione. Durante l'esecuzione, quando l'agente vuole utilizzare lo strumento API, l'agente chiede all'utente di autenticarsi. L'utente fornisce una chiave API e l'agente si collega all'API usando quella chiave.
   • Auth 2.0: Seleziona questa opzione se il tuo server MCP utilizza OAuth 2.0 per l'autenticazione. OAuth 2.0 consente agli utenti individuali di autenticarsi all'API tramite un provider di identità. Questo metodo di autenticazione consente all'utente di concedere autorizzazioni all'applicazione (agente) senza condividere le credenziali con l'agente.

2. Inserisci i campi richiesti per il metodo di autenticazione selezionato. I campi variano in base al metodo di autenticazione.

   • Nessuna: nessuna informazione da fornire.
   • Chiave API:
     • Etichetta parametro: Un'etichetta di testo per il parametro API da presentare agli utenti.
     • Nome parametro: nome effettivo per il parametro della chiave API da usare nell'intestazione o nella stringa di query.
     • Ubicazione del parametro: Come inviare la chiave per l'API. Seleziona Header o Query.
   • Autenticazione 2.0:
     • ID cliente: l'identificatore cliente che il provider di identità genera quando si registra la tua app. L'ID client consente al provider di identità di sapere qual è l'app che effettua la richiesta.
     • Segreto del client: il segreto del client che il provider di identità genera quando registri l'app. L'agente invia il segreto client insieme all'ID client per dimostrare che l'agente è autorizzato a richiedere token di accesso per il server MCP.
     • URL di autorizzazione: l'endpoint del provider di identità a cui l'utente viene reindirizzato dall'agente per accedere e concedere le autorizzazioni all'agente (scheda di consenso presentata nella chat dell'agente). L’utente si autentica qui e il fornitore di identità risponde all’agente tramite l’URL di callback con un codice di autorizzazione.
     • URL del token: L'endpoint dove il tuo agente scambia il codice di autorizzazione (o token di aggiornamento) con un token di accesso e un token di aggiornamento. Il token di accesso consente all'agente di usare il server MCP per conto dell'utente. I token di aggiornamento consentono all'agente di ottenere nuovi token di accesso e di aggiornamento dall'endpoint di aggiornamento alla scadenza del token di accesso precedente.
     • URL di refresh: l'endpoint per richiedere un nuovo token di accesso usando un token di aggiornamento (in modo che l'utente non debba accedere di nuovo alla scadenza del token).
     • Ambito: (Opzionale): I permessi richiesti dalla tua app, come una lista separata da spazi.
     • Quale organizzazione di Microsoft 365 accede agli endpoint: questa impostazione limita l'accesso all'origine all'organizzazione del creatore o a tutte le organizzazioni. Selezionare una delle due operazioni seguenti:
       • Solo la mia organizzazione
       • Qualsiasi organizzazione Microsoft 365
     • Quale app (client) può utilizzare gli endpoint: GUID che definisce il sistema client che può essere utilizzato per accedere a questi dati. Le app possono includere Microsoft 365, Power Automate e altre opzioni.

3. Al termine di tutti i campi, selezionare Avanti.

   Viene visualizzata la pagina Seleziona e configura lo strumento in cui è possibile selezionare gli strumenti da abilitare dall'API.

   

Seleziona gli strumenti dall'API

Seleziona gli strumenti supportati dall'API REST da aggiungere al tuo agente. Generalmente, un'API REST offre una gamma di strumenti attraverso le varie combinazioni di metodi endpoint e HTTP (get, put, post, delete, ecc.) definite nella specifica API. In alcuni casi, potresti non volere che gli utenti dell'agente abbiano la possibilità di eseguire tutte le azioni generalmente offerte dall'API. Ad esempio, la specifica della tua API potrebbe includere la possibilità di aggiornare e cancellare, ma vuoi che solo gli utenti del tuo agente possano creare record.

1. Selezionare uno strumento dall'elenco da configurare.

   Viene visualizzata la pagina Configura il tuo strumento .

   

2. Configura il nome e la descrizione dello strumento selezionato. Analogamente all'API complessiva, specificare un nome strumento e una descrizione dello strumento. Le descrizioni sono inizialmente precompilate dalle descrizioni nella specifica API. Il nome non deve essere univoco, ma deve rappresentare lo strumento stesso. La descrizione, come la descrizione generale dell'API, dovrebbe essere sufficientemente specifica da fornire al modello linguistico dettagli per identificare meglio se la tua query è allineata a questo strumento specifico.

3. Una volta compilati tutti i campi, seleziona Avanti.

   Viene visualizzata la pagina Rivedi i parametri dello strumento .

   

   Questa pagina mostra i valori attesi per l'input e quelli in output restituiti. Non è possibile modificare questi valori, ma è possibile aggiornare le descrizioni degli input e degli output. Tutto il contenuto di questa pagina viene estratto direttamente dalla specifica dell'API caricata.

4. Aggiorna le descrizioni se necessario. Le descrizioni forniscono una definizione dello scopo per cui vengono utilizzati i valori. Se una delle descrizioni è vuota, è necessario completarle prima di procedere. Se non si dispone di una descrizione migliore, è possibile incollare il nome.

5. Dopo aver completato le descrizioni, seleziona Avanti.

   Il primo strumento è ora configurato e viene visualizzato nell'elenco Strumenti selezionati nella pagina Selezionare e configurare lo strumento plug-in .

   

6. Aggiungere qualsiasi altro strumento dall'API da includere in questo momento. Al termine dell'aggiunta di strumenti che si vuole che l'agente supporti, selezionare Avanti.

   Viene visualizzata la pagina Rivedi lo strumento . La pagina fornisce i dettagli dello strumento DELL'API REST configurato.

   

Rivedere e pubblicare

1. Se è necessario apportare aggiornamenti, selezionare Indietro e apportare le modifiche. In caso contrario, selezionare Avanti.

   Viene visualizzata una schermata che indica che lo strumento è in corso di pubblicazione mentre il processo è in corso. Riceverai una notifica al termine della pubblicazione.

2. Seleziona Crea connessione per continuare. Torni alla schermata Aggiungi strumento .

3. Seleziona REST API nel selettore di tipi di strumento. Puoi vedere gli strumenti appena creati dalla tua API. Dovrebbe esserci una voce per ogni strumento che hai aggiunto dall'API.

4. Per ognuno degli strumenti appena configurati dall'API, creare o selezionare una connessione all'API e aggiungere lo strumento all'agente:

   1. Nella schermata Aggiungi strumento , seleziona lo strumento.
   2. Sotto Connessione, seleziona una connessione esistente oppure seleziona Crea nuova connessione.
   3. Immettere le informazioni necessarie per la connessione e quindi selezionare Crea per creare la connessione allo strumento.
   4. Seleziona Aggiungi e configura per aggiungere lo strumento al tuo agente.

   

Gli strumenti dell'API REST sono ora disponibili per l'uso nel tuo agente.

Suggerimento

Per trovare più facilmente lo strumento, usare la barra di ricerca per individuarla.