Condividi tramite

Configurare le competenze per l'uso negli agenti di Copilot Studio

Copilot Studio consente di estendere l'agente usando skills. Se nell'organizzazione sono già stati compilati e distribuiti agenti (usando il Microsoft 365 Agents SDK o altri strumenti pro-code) per scenari specifici, è possibile convertire tali bot in una competenza e registrare tale competenza in un agente di Copilot Studio.

Nota

Per aggiungere una competenza dall'interno dell'app Copilot Studio in Microsoft Teams, è necessario disporre di una sottoscrizione autonoma Microsoft Copilot Studio.

Questo articolo è destinato agli amministratori di sistema o ai professionisti IT che hanno familiarità con le competenze.

Dopo aver registrato un'abilità con un agente di Copilot Studio, è possibile attivare senza problemi azioni delle abilità nella conversazione.

Prerequisiti

Importante

Gli agenti di Copilot Studio supportano solo le competenze create usando il Legacy Bot Framework SDK versione 4.12.0+ e il Microsoft 365 Agents SDK v1.0.0+. Le nuove competenze devono essere create usando Microsoft 365 Agents SDK.

Per configurare un'abilità, impostare la registrazione dell'app associata in Microsoft Entra ID per una configurazione a tenant singolo.

Quando usare flussi di agenti e competenze

La tabella seguente ti aiuta a stabilire quando usare i flussi di agenti o le competenze per una conversazione.

Fattore Quando utilizzare i flussi di agenti Quando usare le abilità
Persona 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.
Tipo di 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 dell'agente. Ad esempio, mostra un messaggio personalizzato o immagini inline. Usa le competenze per emettere qualsiasi risposta supportata dall'agente. 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 un'abilità

Prima di tutto, usare Copilot Studio per creare un agente e creare e distribuire una competenza usando strumenti pro-code nell'organizzazione. Fai riferimento a questi esempi:

Prima di registrare l'abilità, fornisci l'ID dell'agente allo sviluppatore dell'abilità per autorizzare l'agente a eseguire azioni nell'abilità. Scopri di più sulla lista dei permessi per una competenza. Puoi ottenere l'ID del tuo agente dalla finestra Aggiungi una competenza.

Per aggiungere una competenza al tuo agente:

  1. Vai al tuo agente.

  2. Seleziona Impostazioni>Competenze per passare alla pagina delle competenze.

  3. Seleziona Aggiungi una competenza.

  4. Copia l'ID agente. È necessario fornire l'ID agente allo sviluppatore delle tue competenze.

  5. Immetti 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.

  6. Seleziona Avanti per iniziare il processo di convalida. Una volta che la convalida è andata a buon fine, la tua abilità viene aggiunta al tuo agente. Puoi ora usare questa competenza nei tuoi argomenti.

Considerazioni sulla conformità

Per proteggere la privacy degli utenti, è necessario registrare le competenze come app nel tenant di Microsoft Entra ID dell'utente connesso.

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. È necessario correggere questi errori prima di registrare una competenza.

Messaggio d'errore Risoluzione dei problemi / Mitigazione
Abbiamo avuto problemi a ottenere il manifesto delle abilità.
(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 manifesto è incompatibile.
(MANIFEST_MALFORMED)		 (a) Controlla se il manifest è un file JSON valido.
(b) Verificare se il manifesto contiene le proprietà richieste
Ad esempio, (name, msaAppId, singola endpoint, activities/id,activities/description ,activities/type (solo event o message supportata)).
C'è una discrepanza nei tuoi endpoint
(MANIFEST_ENDPOINT_ORIGIN_MISMATCH)		 Controllare se l'endpoint della competenza corrisponde all'applicazione registrata con Microsoft Entra ID nel campo Publisher domain (preferito) o Home page URL. Ulteriori informazioni sull'impostazione della home page per gli endpoint.
Per aggiungere un'abilità, deve prima essere registrata
(APPID_NOT_IN_TENANT)		 Controllare se l'ID applicazione della competenza è registrato nel tenant Microsoft Entra ID dell'organizzazione.
Il link non è valido; Il collegamento deve iniziare con https://
(URL_MALFORMED, URL_NOT_HTTPS)		 Rivedi il collegamento per aggiungere un 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 agente.
(MANIFEST_ALREADY_IMPORTED)		 Elimina l'abilità e prova a ribregistrarla.
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)		 Ci sono troppi parametri di input dell'azione di abilità. Rimuovi i parametri e riprova.
Le azioni sono limitate a 25 risultati.
(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 uno skill esistente e riprova.
Sembra che qualcosa sia andato storto.
(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 skill è online e sta rispondendo ai messaggi. Verifica anche che la registrazione dell'app della competenza per singolo tenant sia stata distribuita nello stesso tenant.
Questa abilità non ha permesso di inserire il tuo agente
(ENDPOINT_HEALTHCHECK_UNAUTHORIZED)		 Controlla se il tuo agente è stato aggiunto alla lista di autorizzazione delle skill.
  • Last updated on