Pubblica un agente sui canali Azure servizio Bot

Articolo
12/09/2024

Puoi usare Connetti per inviare il tuo agente ai canali Azure servizio Bot esistenti , il che può essere utile se vuoi inviare il tuo agente agli utenti finali sui canali Azure servizio Bot.

Aggiungere agente ai canali Azure servizio Bot richiede una notevole competenza di sviluppo. 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 tuo Copilot Studio agente al tuo sito web, Facebook, oppure Microsoft Teams. Se il tuo obiettivo è quello di Connetti su un'app personalizzata basata sul Web o nativa, i tuoi sviluppatori possono saperne di più su Pubblica un agente su app 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 Connetti su un canale Azure Connetti.
Pubblica un agente su app 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

Hai bisogno di un Azure servizio Bot bot che possa trasmettere le conversazioni tra i tuoi canali agente e Azure servizio Bot. Copilot Studio

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.

Ottieni i tuoi parametri agente Copilot Studio

Per Connetti sul agente che hai creato con Copilot Studio, devi recuperare il nome del tuo agente e il token endpoint.

Copia il nome del tuo agente in Copilot Studio.
Nel menu di navigazione, in Impostazioni seleziona Canali.
Seleziona il canale a cui vuoi connetterti. Questo scenario usa Slack come esempio.
Per copiare e salvare il valore Endpoint token, seleziona Copia. Devi usare endpoint per usare Connetti e agente sul canale Azure servizio Bot.

Gestisci le sessioni di conversazione con il tuo Copilot Studio agente

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

Il tuo Azure servizio Bot bot deve mappare e inoltrare la conversazione dal canale Azure servizio Bot alla Direct Line conversazione con Copilot Studio agente e viceversa.

Codice di esempio

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

Ad ogni nuova conversazione sul canale esterno Azure servizio Bot, avvia una conversazione Copilot Studio agente. Fare riferimento a Ottieni Direct Line token e Utilizza Direct Line per comunicare con agente per istruzioni su come avviare una nuova conversazione con 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;
 }

Per gestire più sessioni, è necessario mantenere un mapping di conversazioni del canale esterno Azure servizio Bot con le corrispondenti Copilot Studio conversazioni agente. Una conversazione Copilot Studio agente può essere identificata e collegata 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 agente per supportare l'aggiornamento dei token è definita come segue: Copilot Studio Direct Line

/// <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
}

Quando inizia una nuova conversazione agente, aggiungi una coppia chiave-valore ( Copilot Studio ,external_Azure_Bot_Service_channel_conversationID) alla tabella mapping. PowerVirtualAgentsConversation

// 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,
  };

Per continuare una conversazione esistente, dopo aver ricevuto un nuovo messaggio sul canale esterno Azure servizio Bot, recupera la conversazione esistente dalla tabella mapping, inoltra l'attività della conversazione esterna al tuo Copilot Studio agente e ottieni un 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;
}

Fare riferimento a Usa Direct Line per comunicare con agente per sapere come ottenere Copilot Studio agente's risposta. Quando viene ricevuto Copilot Studio agente's risposta, fare riferimento a Analizza il payload della conversazione da agente per informazioni su come analizzare risposta nel canale Azure servizio Bot esterno risposta.

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.

Condividi tramite