Configurare una competenza Bot Framework da utilizzare in Copilot Studio

Articolo
04/09/2024

Importante

Le capacità e funzionalità di Power Virtual Agents ora fanno parte di Microsoft Copilot Studio a seguito di investimenti significativi nell'intelligenza artificiale generativa e integrazioni migliorate in Microsoft Copilot.

Alcuni articoli e schermate potrebbero fare riferimento a Power Virtual Agents durante l'aggiornamento della documentazione e dei contenuti per il training.

Copilot Studio ti consente di estendere il tuo copilota usando le competenze Bot Framework. Se hai già creato e distribuito bot nella tua organizzazione (utilizzando gli strumenti di codice e SDK Bot Framework) per scenari specifici, puoi convertire i bot in una competenza e registrare la competenza in un copilota di Copilot Studio.

Nota

Per aggiungere una competenza dall'interno dell'app Copilot Studio in Microsoft Teams, ma hai bisogno di un abbonamento standalone di Microsoft Copilot Studio.

Questo articolo è destinato agli amministratori di sistema o ai professionisti IT che hanno familiarità con le competenze Bot Framework. Dopo che una competenza è stata registrata con un copilota Copilot Studio, gli autori possono perfettamente attivare le azioni Competenze durante la conversazione.

Prerequisiti

Revisiona le restrizioni e la convalida per le competenze utilizzate in Copilot Studio

Importante

I copiloti Copilot Studio supportano solo le competenze sviluppate usando Bot Framework SDK versione 4.12.0+.

I chatbot classici supportano solo le competenze sviluppate usando Bot Framework SDK version 4.7+.

Se utilizzi Bot Framework Composer, si consiglia vivamente di utilizzare Composer 2.x. Se desideri utilizzare un copilota Composer 1.x esistente, esegui la migrazione a Composer 2.x prima di usarlo come competenza.

Per configurare una competenza, la registrazione dell'app associata in Microsoft Entra ID per la tua competenza deve essere impostata su Configurazione multi-tenant.

Azioni di flussi e azioni di competenze

La tabella seguente ti aiuterà a stabilire quando usare le competenze per una conversazione.

	Azioni di flusso	Azioni competenze
Utente tipo	Gli autori dei copiloti possono creare flussi riutilizzabili da incorporare in qualsiasi conversazione di copilota	Gli sviluppatori possono creare, distribuire e ospitare competenze personalizzate nel proprio ambiente
Conversazione	Utilizza Flussi per operazioni semplici a turno singolo. Ad esempio, effettua un ordine o ottieni lo stato dell'ordine.	Usa le competenze per operazioni complesse a più turni. Ad esempio, pianifica una riunione o prenota un volo.
Risposta	Utilizza i flussi per emettere una risposta del copilota. Ad esempio, mostra un messaggio personalizzato o immagini inline.	Usa le competenze per emettere una risposta del copilota supportata. Ad esempio, mostra una scheda adattiva o invia risposte casuali.
Azioni	Utilizza i flussi per attivare le azioni a turno singolo lato server. Ad esempio, chiama un'API HTTP o attiva un connettore personalizzato.	Utilizza le competenze per attivare eventi e azioni lato server e lato client. Ad esempio, passa a una pagina dopo la risposta del copilota.

Configurare una competenza

Innanzitutto, utilizza Copilot Studio per creare un copilota e creare e distribuire la competenza usando strumenti pro-codice nella tua organizzazione.

Prima di registrare la competenza, fornisci l'ID del copilota allo sviluppatore delle competenze per autorizzare il copilota a chiamare azioni nella competenza. Ulteriori informazioni sull'elenco delle competenze consentite. Puoi ottenere l'ID del tuo copilota dalla finestra Aggiungi una competenza.

Per aggiungere una competenza al tuo copilota:

Nel riquadro di spostamento a sinistra espandi Impostazioni, quindi seleziona Competenze.
Nella parte superiore della pagina Competenze, seleziona Aggiungi competenza.
Copia l'ID del tuo copilota e forniscilo allo sviluppatore delle tue competenze.
Immettere l'URL nel manifest di competenza. Il manifest di una competenza contiene le informazioni necessarie al copilota per attivare le azioni all'interno di una competenza.
Seleziona Avanti per iniziare il processo di convalida. Una volta che la convalida ha esito positivo, la tua abilità viene aggiunta al tuo copilota. Puoi ora usare questa competenza nei tuoi argomenti.

Considerazioni sulla conformità

Per proteggere la privacy degli utenti, è necessario che le competenze siano registrate come un'app nel tenant Microsoft Entra ID dell'utente che ha effettuato l'accesso.

Risoluzione di errori durante la registrazione delle competenze

Viene eseguita una serie di controlli di convalida sull'URL. Questi controlli assicurano la conformità, la governance e l'usabilità della competenza aggiunta al copilota. Dovrai correggere questi errori prima di registrare una competenza.

Messaggio di errore	Risoluzione dei problemi / Mitigazione
Si è verificato un problema durante il recupero del manifesto delle competenze. (`MANIFEST_FETCH_FAILED`)	Prova ad aprire l'URL del manifest in un browser Web. Se l'URL visualizza la pagina entro 10 secondi, registra nuovamente la tua competenza.
Il manifest è incompatibile. (`MANIFEST_MALFORMED`)	(a) Verifica se il manifest è un file JSON valido. (b) Verifica se il manifest contiene le proprietà richieste Ad esempio, (`name`, `msaAppId`, `endpoint` singolo, `activities`/`id`, `activities`/`description`, `activities`/`type` (solo `event` o `message` supportato)).
C'è una discrepanza nei tuoi endpoint (`MANIFEST_ENDPOINT_ORIGIN_MISMATCH`)	Controlla se l'endpoint della competenza corrisponde al campo registrazione dell'applicazione Microsoft Entra `Publisher domain` (preferibile) o al campo `Home page URL`. Ulteriori informazioni sull'impostazione della home page per gli endpoint.
Per aggiungere una competenza, è necessario prima registrarla (`APPID_NOT_IN_TENANT`)	Controlla se l'ID dell'applicazione della tua competenza è registrato nel tenant Microsoft Entra ID dell'organizzazione.
Il collegamento non è valido. Deve iniziare con https:// (`URL_MALFORMED`? `URL_NOT_HTTPS`)	Immetti nuovamente il collegamento come URL sicuro.
Il manifesto è troppo grande. (`MANIFEST_TOO_LARGE`)	Controlla la dimensione del manifest. Deve essere uguale o minore a 500 KB.
Questa competenza è già stata aggiunta al tuo copilota. (`MANIFEST_ALREADY_IMPORTED`)	Elimina la competenza e prova a registrarla di nuovo.
La competenza è limitata a 100 azioni. (`LIMITS_TOO_MANY_ACTIONS`)	Esistono troppe azioni di competenza definite nel manifest della competenza. Rimuovi le azioni e riprova.
Le azioni sono limitate a 25 input. (`LIMITS_TOO_MANY_INPUTS`)	Esistono troppi parametri di input dell'azione di competenza. Rimuovi i parametri e riprova.
Le azioni sono limitate a 25 output. (`LIMITS_TOO_MANY_OUTPUTS`)	Esistono troppi parametri di output dell'azione di competenza. Rimuovi i parametri e riprova.
Il tuo copilota può avere un massimo di 100 competenze. (`LIMITS_TOO_MANY_SKILLS`)	Ci sono troppe competenze aggiunte in un copilota. Rimuovi una competenza esistente e riprova.
Apparentemente si è verificato un errore. (`AADERROR_OTHER`)	Si è verificato un errore temporaneo durante la convalida della tua competenza. Riprova.
Si è verificato un errore durante il controllo della competenza. (`ENDPOINT_HEALTHCHECK_FAILED`, `HEALTH_PING_FAILED`)	Controlla se l'endpoint della competenza è online e risponde ai messaggi.
Questa competenza non l'autorizzazione per essere elencata nel copilota (`ENDPOINT_HEALTHCHECK_UNAUTHORIZED`)	Controlla se il tuo copilota è stato aggiunto all'elenco Consenti delle competenze.