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

2025-04-14

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

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

Le API REST possono essere aggiunte agli agenti Copilot e agli agenti personalizzati tramite Copilot Studio.

Gli agenti Copilot consentono a un autore di combinare più origini dati come connettori, API, richieste e origini della Knowledge Base in un unico agente. Puoi usare questo agente per estendere le esperienze degli agenti con marchio Microsoft come Copilot di Microsoft 365.

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

Le azioni API devono essere create da una specifica v2 di OpenAPI. Questo requisito è dovuto al comportamento di Power Platform nell'elaborazione delle specifiche API. Se viene inviata una specifica v3, questa viene automaticamente convertita in una specifica v2 durante il processo di creazione.

Prerequisiti

Sono necessari alcuni prerequisiti per estendere le esperienze degli agenti a marchio Microsoft con le azioni dei connettori.

Per tutti i tipi di agente, devi disporre di credenziali a livello di autore e di una licenza Copilot Studio.

È inoltre necessaria una copia della specifica OpenAPI, la conoscenza del tipo di autenticazione necessaria e i dettagli di autenticazione.

Aggiungi un'azione API REST a un agente

L'aggiunta di un'API REST all'agente comporta alcuni passaggi. Le seguenti sezioni guidano attraverso il processo.

Il processo per aggiungere un'API REST è identico sia per gli agenti personalizzati che per gli agenti Copilot.

Ci sono alcuni passaggi nel processo.

Aggiungi un'azione all'agente

Inizia dalla pagina Panoramica del tuo agente.
Nella sezione Azioni, seleziona Aggiungi azione. Puoi anche andare alla scheda Azioni e selezionare Aggiungi azione.

La creazione guidata azione viene avviata con la pagina Scegli un'azione visualizzata.

Fornisci la soluzione, la descrizione e la specifica API

Nella parte inferiore della pagina, seleziona Aggiungi un'API per un connettore personalizzato.
Carica un file di specifiche OpenAPI per l'API REST a cui vuoi connetterti. 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

Le specifica OpenAPI deve essere un file JSON in formato v2. Se viene inviata una specifica v3, questa viene automaticamente convertita in una specifica v2 durante il processo di creazione.

Dopo aver caricato la specifica, la schermata si aggiorna per indicare il nome del file di specifica e i dettagli.

Nei passaggi che seguono, baseremo la procedura su 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.
Verifica i dettagli e quindi seleziona Avanti.

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

Il campo della descrizione verrà inizialmente compilato in base alla descrizione nella specifica API caricata. Fornisci una descrizione dettagliata, poiché l'orchestrazione agente usa la descrizione per determinare quando usare l'azione specifica. 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."
Inserisci una descrizione migliorata nel campo Descrizione.
In Soluzione, un menu a discesa elenca tutte le soluzioni disponibili nell'ambiente corrente. Seleziona la soluzione che vuoi usare. Per altre informazioni sulle soluzioni, vedi 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 in questo caso non vedi la soluzione predefinita o la soluzione predefinita CDS come opzione, ti consigliamo di avere una soluzione personalizzata per una facile gestione. Per altre informazioni, vedi Soluzione predefinita e soluzione personalizzata.
Con una soluzione selezionata, seleziona Avanti per procedere.

Fornisci i dettagli dell'autenticazione

Viene visualizzata la pagina Autenticazione per selezionare il tipo di autenticazione da utilizzare per l'API.

Nota

Attualmente le opzioni disponibili sono Nessuno, Auth 2.0 e API.

Seleziona il metodo di autenticazione.

Seleziona un metodo di autenticazione dall'elenco.
Compila i campi obbligatori per il metodo di autenticazione. I campi variano in base al metodo di autenticazione.
- Nessuno: non sono obbligatori altri campi.
- Chiave API:
  - Etichetta parametro: un'etichetta di testo per il parametro API.
  - Nome parametro: un nome testuale per il parametro API.
  - Posizione parametro: la posizione in cui è possibile trovare il parametro.
- Auth 2.0:
  - ID client: GUID client per il servizio di destinazione.
  - Segreto client: valore del segreto per il client. Il segreto non viene visualizzato quando l'utente apre il pannello di modifica in seguito. Tuttavia, conserva il segreto, perché ne avrai bisogno se scegli di apportare ulteriori modifiche.
  - URL di autorizzazione: URL utilizzato per autorizzare il sistema di origine.
  - URL token: URL in cui è possibile recuperare il token.
  - URL di aggiornamento: l'URL a cui vieni reindirizzato in uno scenario di aggiornamento.
  - Ambito: l'URL dell'ambito assegnato all'API per le app Microsoft Entra.
  - Quale organizzazione Microsoft 365 accede agli endpoint: limita l'accesso all'origine all'organizzazione dell'autore o a tutte le organizzazioni.
  - Quale app (client) può usare gli endpoint: GUID che definisce il sistema client che può essere usato per accedere a questi dati. Le app possono includere Microsoft 365, Power Automate e altre opzioni.
Una volta compilati tutti i campi, seleziona Avanti.

Viene visualizzata la pagina Seleziona e configura l'azione del plug-in in cui puoi selezionare le azioni da abilitare per l'API.

Seleziona azioni per l'API

Scegli le azioni supportate dalle API da abilitare. In genere, un'API REST offre una gamma di azioni tramite le varie combinazioni di endpoint e metodo HTTP (get, put, post, delete e così via) 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 dell'API potrebbe includere azioni per l'aggiornamento e l'eliminazione ma si desidera che solo gli utenti dell'agente siano in grado di creare record.

Seleziona un'azione dall'elenco da configurare.

Viene visualizzata la pagina Configurare l'azione del plug-in.
Configura l'azione selezionata. Come per l'API complessiva, ti viene chiesto di fornire un Nome dell'azione e una Descrizione dell'azione. Le descrizioni sono inizialmente precompilate dalle descrizioni nella specifica API. Non è necessario che il nome sia univoco, ma deve rappresentare l'azione stessa. La descrizione, come la descrizione generale dell'API, deve essere sufficientemente specifica da fornire al modello linguistico i dettagli per identificare meglio che la query è allineata a questa azione specifica.
Una volta compilati tutti i campi, seleziona Avanti.

Viene visualizzata la pagina Rivedi i parametri dell'azione.

Questa pagina mostra i valori forniti come parte dei possibili valori di input e output. Questi valori non possono essere modificati, tuttavia le descrizioni degli input e degli output possono essere aggiornate. Tutto il contenuto di questa pagina viene estratto direttamente dalla specifica dell'API caricata.
Immetti i valori necessari per le descrizioni. Le descrizioni forniscono una definizione dello scopo per cui vengono utilizzati i valori. Se una qualsiasi delle descrizioni è vuota, deve essere completata prima di poter procedere. Puoi incollare il nome se non hai una descrizione migliore.
Dopo aver completato le descrizioni, seleziona Avanti.

La prima azione è ora configurata e viene visualizzata nell'elenco Azioni selezionate nella pagina Seleziona e configura l'azione del plug-in.
Aggiungi eventuali altre azioni che desideri includere in questo momento. Dopo aver aggiunto le azioni che vuoi che il tuo agente supporti, seleziona Avanti.

Viene visualizzata la pagina Rivedi la tua azione. La pagina fornisce i dettagli dell'azione dell'API REST configurata.

Rivedere e pubblicare

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

Viene visualizzata una schermata che indica che la tua azione è in fase di pubblicazione mentre il processo è in fase di completamento. Riceverai una notifica al termine della pubblicazione.
Al termine della pubblicazione, viene visualizzata nuovamente la schermata Scegli un'azione. Qui è possibile aggiungere l'API REST appena configurata all'agente Copilot o all'agente personalizzato e completare la configurazione del componente.

L'azione API REST è ora disponibile per l'uso nell'agente.

Suggerimento

Per trovare più facilmente la tua azione, utilizza la barra di ricerca per individuarla.

Condividi tramite