Aggiungere un copilota Copilot Studio ai canali del servizio Azure Bot

  • Articolo

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.

Puoi collegare il tuo copilota ai canali del servizio Azure Bot esistenti. Questo può essere utile se vuoi connettere il copilota agli utenti finali sui canali del servizio Azure Bot.

L'aggiunta del copilota ai canali del servizio Azure Bot richiede una notevole competenza degli sviluppatori. Questo articolo è scritto per amministratori IT o sviluppatori che hanno esperienza nello sviluppo e nella scrittura di codice.

Suggerimento

Non è necessario seguire questo documento per aggiungere il copilota Copilot Studio al sito web, Facebook o Microsoft Teams. Se il tuo obiettivo è connettere il bot a un'app Web o nativa personalizzata, gli sviluppatori possono trovare altre informazioni in Aggiungere copilota ad app per dispositivi mobili e personalizzate.

Importante

Le istruzioni in questa sezione richiedono lo sviluppo del software da parte tua o degli sviluppatori. È destinato a professionisti IT esperti, come amministratori IT o sviluppatori che hanno una solida conoscenza di strumenti di sviluppo, utilità e IDE.

Prerequisiti

Esempi di codice

I frammenti di codice utilizzati in questo documento provengono dal codice di esempio del bot di inoltro.

Riferimenti

Le istruzioni in questo documento fanno riferimento a quanto segue:

Creare o usare un bot del servizio Azure Bot esistente

È necessario un bot del servizio Azure Bot in grado di inoltrare conversazioni tra i copiloti Copilot Studio e i canali di servizio Azure Bot.

Diagramma del bot di inoltro.

Il codice di esempio del bot di inoltro è un buon punto di partenza se non hai di un bot del servizio Azure Bot esistente. È creato dal codice di esempio del bot Microsoft Bot Framework che può essere compilato e distribuito nel servizio Azure Bot. Il codice di esempio deve essere utilizzato come punto di partenza e non deve essere utilizzato direttamente in produzione. Dovrai aggiungere codice e ottimizzazione per soddisfare le tue esigenze aziendali.

Se già hai un bot del servizio Azure Bot, devi aggiungere un connettore Copilot Studio e il codice per gestire le sessioni di conversazione. Quindi puoi distribuire il bot nel servizio Azure Bot e connetterti ai canali con il portale di Azure.

Ottenere i parametri del copilota Copilot Studio

Per connetterti al copilota che hai creato con Copilot Studio, sarà necessario recuperare il nome, l'ID del copilota e l'endpoint del token.

  1. Copia il nome del tuo copilota in Copilot Studio.

    Ottenere il nome del bot.

  2. Nel menu di navigazione, in Impostazioni seleziona Canali.

  3. Seleziona il canale a cui vuoi connetterti. Questo scenario usa Slack come esempio.

    Canale Slack.

  4. Per copiare e salvare il valore Endpoint token, seleziona Copia. Avrai bisogno dell'endpoint per connettere il copilota al canale Servizio Azure Bot.

    Ottenere i parametri del bot.

Gestire le sessioni di conversazione con il copilota Copilot Studio

Possono esserci più conversazioni tra i canali del servizio Azure Bot e la connessione Direct Line con il tuo copilota Copilot Studio.

Il bot del servizio Azure Bot dovrà mappare e inoltrare la conversazione dal canale del servizio Azure Bot alla conversazione Direct Line con il copilota Copilot Studio e viceversa.

Codice di esempio

L'esempio seguente utilizza frammenti del codice di esempio del bot di inoltro.

  1. Ad ogni nuovo avvio di conversazione del canale del servizio Azure Bot esterno, viene avviata una conversazione con il copilota di Copilot Studio. Fai riferimento a Ottenere token Direct Line e Usare Direct Line per comunicare con il copilota per istruzioni su come iniziare una nuova conversazione con il bot.

    using (var httpRequest = new HttpRequestMessage())
{   
    httpRequest.Method = HttpMethod.Get;
    UriBuilder uriBuilder = new UriBuilder(TokenEndPoint);
    httpRequest.RequestUri = uriBuilder.Uri;
    using (var response = await s_httpClient.SendAsync(httpRequest))
    {
        var responseString = await response.Content.ReadAsStringAsync();
        string token = SafeJsonConvert.DeserializeObject<DirectLineToken>(responseString).Token;
    }
}

/// <summary>
/// class for serialization/deserialization DirectLineToken
/// </summary>
public class DirectLineToken
{
    public string Token { get; set; }
}

     // Use the retrieved token to create a DirectLineClient instance
 using (var directLineClient = new DirectLineClient(token))
 {
     var conversation = await directLineClient.Conversations.StartConversationAsync();
     string conversationtId = conversation.ConversationId;
 }

  2. Per gestire più sessioni, devi mantenere un mapping delle conversazioni del canale del servizio Azure Bot esterno su corrispondenti conversazioni del copilota di Copilot Studio. Una conversazione del copilota di Copilot Studio può essere identificata e connessa con due proprietà: ConversationtId e Token.

    Dictionary<string, PowerVirtualAgentsConversation> ConversationRouter = new Dictionary<string, PowerVirtualAgentsConversation>();

    Per gestire il ciclo di vita della conversazione, aggiorna i token Direct Line o pulisci le conversazioni inattive. Per ulteriori informazioni sull'aggiornamento dei token vai a Aggiornare un token Direct Line. Una conversazione del copilota di Copilot Studio per il supporto è definita come segue:

    /// <summary>
/// Data model class for Copilot Studio copilot conversation
/// </summary>
public class PowerVirtualAgentsConversation
{
    public string ConversationtId { get; set; } // The Copilot Studio copilot conversation ID retrieved from step 1

    public string Token { get; set; } // The DirectLine token retrieved from step 1

    public string WaterMark { get; set; } // Identify turn in a conversation

    public DateTime LastTokenRefreshTime { get; set; } = DateTime.Now; // Timestamp of last token refresh

    public DateTime LastConversationUpdateTime { get; set; } = DateTime.Now; // Timestamp of last active user message sent to copilot
}

  3. Quando una nuova conversazione del copilota di Copilot Studio inizia aggiungi una coppia di valori chiave (external_Azure_Bot_Service_channel_conversationID, PowerVirtualAgentsConversation) alla tabella di mapping.

    // After new Copilot Studio copilot conversation starts
ConversationRouter[external_Azure_Bot_Service_channel_conversationID] = new PowerVirtualAgentsConversation()
  {
    Token = token,
    ConversationtId = conversationId,
    WaterMark = null,
    LastConversationUpdateTime = DateTime.Now,
    LastTokenRefreshTime = DateTime.Now,
  };

  4. Per continuare una conversazione esistente, dopo aver ricevuto un nuovo messaggio sul canale del servizio Azure Bot esterno, recupera la conversazione esistente dalla tabella di mapping, inoltra l'attività di conversazione esterna al copilota Copilot Studio e ottieni una risposta.

    L'esempio seguente mostra l'inoltro della conversazione ignorando il metodo ActivityHandler.OnMessageActivityAsync((ITurnContext<IMessageActivity>, CancellationToken)

    // Invoked when a message activity is received from the user
// Send the user message to Copilot Studio copilot and get response
protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
{
    // Retrieve copilot conversation from mapping table
    // If not exists for the given external conversation ID, start a new Copilot Studio copilot conversation
    ConversationRouter.TryGetValue(externalCID, out PowerVirtualAgentsConversation currentConversation) ?
            currentConversation : /*await StartBotConversationAsync(externalCID)*/;

    // Create DirectLine client with the token associated to current conversation
    DirectLineClient client = new DirectLineClient(currentConversation.Token);

    // Send user message using directlineClient
    await client.Conversations.PostActivityAsync(currentConversation.ConversationtId, new DirectLineActivity()
    {
      Type = DirectLineActivityTypes.Message,
      From = new ChannelAccount { Id = turnContext.Activity.From.Id, Name = turnContext.Activity.From.Name },
      Text = turnContext.Activity.Text,
      TextFormat = turnContext.Activity.TextFormat,
      Locale = turnContext.Activity.Locale,
    });

    // Update LastConversationUpdateTime for session management
    currentConversation.LastConversationUpdateTime = DateTime.Now;
}

  5. Fai riferimento a Usare Direct Line per comunicare con il copilota per sapere come ottenere la risposta del copilota Copilot Studio. Quando ricevi la risposta del copilota Copilot Studio, fai riferimento a Analizzare il payload di conversazioni dal copilota per sapere come analizzare la risposta per la risposta del canale del servizio Azure Bot esterno.

Un esempio di analisi della risposta è disponibile nel codice di esempio del bot di inoltro ResponseConverter.cs.

Distribuire al servizio Azure Bot

Dopo aver preparato il bot di inoltro del servizio Azure Bot, è necessario distribuire il bot nel servizio Azure Bot.

Configurare i canali del servizio Azure Bot

Puoi configurare i canali a cui connettersi accedendo al portale di Azure e selezionando il gruppo di risorse del servizio Azure Bot in cui è stato distribuito. Vedi le istruzioni specifiche per ciascun canale in Canali del servizio Azure Bot.