Configurare una competenza Bot Framework da utilizzare in Copilot Studio

Copilot Studio ti consente di estendere il tuo agente 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 agente 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 agente 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

Gli agenti 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 agente Composer 1.x esistente, migralo a Composer 2.x prima di usarlo come competenza.

Per configurare una competenza, la registrazione dell'app associata in Microsoft Entra ID per la competenza deve essere impostata sulla 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 di agenti possono creare flussi riutilizzabili da incorporare in qualsiasi conversazione di agenti.	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.
Response	Utilizza i flussi per emettere una risposta dell'agente. Ad esempio, mostra un messaggio personalizzato o immagini inline.	Usa le competenze per emettere una risposta dell'agente 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 dell'agente.

Configurare una competenza

Innanzitutto usa Copilot Studio per creare un agente e crea e distribuisci la competenza usando strumenti pro-codice nella tua organizzazione.

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

Per aggiungere una competenza al tuo agente:

1. Nel riquadro di spostamento a sinistra espandi Impostazioni, quindi seleziona Competenze.

2. Nella parte superiore della pagina Competenze, seleziona Aggiungi competenza.

3. Copia l'ID del tuo agente e forniscilo allo sviluppatore delle tue competenze.

4. Immettere l'URL nel manifest di competenza. Il manifest di una competenza contiene le informazioni necessarie all'agente per attivare le azioni all'interno di una competenza.

5. Seleziona Avanti per iniziare il processo di convalida. Una volta che la convalida è andata a buon fine, la tua competenza viene aggiunta al tuo agente. 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 all'agente. 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. Altre 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 all'agente. (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.
L'agente può avere un massimo di 100 competenze. (LIMITS_TOO_MANY_SKILLS)	Ci sono troppe competenze aggiunte in un agente. 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 nell'agente (ENDPOINT_HEALTHCHECK_UNAUTHORIZED)	Controlla se l'agente è stato aggiunto all'elenco Consenti delle competenze.