Pubblicare un agente nei canali del servizio Azure Bot

Puoi connettere il tuo agente ai canali del servizio Bot Azure esistenti , il che può essere utile se vuoi connettere il tuo agente ai clienti sui canali del servizio Bot Azure.

L'aggiunta dell'agente 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 l'agente 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 Pubblicare un agente ad app per dispositivi mobili o 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

• Un abbonamento al servizio Azure Bot.
• Un bot del servizio Azure Bot che usa SDK v4.
• .NET Core SDK versione 2.1.
• Pacchetto Nuget Microsoft.Bot.Connector.DirectLine.
• Un agente creato in Copilot Studio che vuoi connettere a un canale del servizio Azure Bot.
• Pubblicare un agente su app per dispositivi mobili o personalizzate.

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 ai seguenti documenti:

• Distribuire il bot in Azure per istruzioni sulla distribuzione del bot del servizio Azure Bot.
• Canali del servizio Azure Bot per connettersi a qualsiasi canale supportato dal servizio Azure Bot.
• Debug del servizio Azure Bot con l'emulatore per istruzioni sul debug del bot del servizio Azure Bot.

Creare o usare un bot del servizio Azure Bot esistente

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

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 dell'agente di Copilot Studio

Per connetterti all'agente che hai creato con Copilot Studio, devi recuperare il nome dell'agente e l'endpoint del token.

1. Copia il nome dell'agente in Copilot Studio.

   

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

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

   

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

   

Gestire le sessioni di conversazione con l'agente Copilot Studio

Possono esserci più conversazioni tra i canali del servizio Azure Bot e la connessione Direct Line con l'agente Copilot Studio.

Il bot del servizio Azure Bot deve mappare e inoltrare la conversazione dal canale del servizio Azure Bot alla conversazione Direct Line con l'agente 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 dell'agente Copilot Studio. Fai riferimento a Ottenere token Direct Line e Usare Direct Line per comunicare con l'agente 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 dell'agente Copilot Studio. Una conversazione dell'agente 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 dell'agente di Copilot Studio per il supporto dell'aggiornamento dei token Direct Line è definita come segue:

   /// <summary>
   /// Data model class for Copilot Studio agent conversation
   /// </summary>
   public class PowerVirtualAgentsConversation
   {
       public string ConversationtId { get; set; } // The Copilot Studio agent 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 agent
   }
   

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

   // After new Copilot Studio agent 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 all'agente 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 agent and get response
   protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
   {
       // Retrieve agent conversation from mapping table
       // If not exists for the given external conversation ID, start a new Copilot Studio agent 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 l'agente per sapere come ottenere la risposta dell'agente Copilot Studio. Quando ricevi la risposta dell'agente Copilot Studio, fai riferimento a Analizzare il payload di conversazioni dall'agente 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.