Lägga till en Copilot Studio copilot i Azure Bot Service-kanaler

Artikel
04/22/2024

Viktigt

Power Virtual Agents-funktioner ingår nu i Microsoft Copilot Studio efter betydande investeringar i generativ AI och förbättrade integrationer mellan Microsoft Copilot.

Vissa artiklar och skärmbilder kan referera till Power Virtual Agents när vi uppdaterar dokumentation och utbildning.

Du kan koppla copilot till befintliga kanaler i Azure Bot Service. Detta kan vara till hjälp om du vill ansluta copilot till slutanvändare på Azure Bot Service-kanaler.

För att du ska kunna lägga till copilot på Azure Bot Service-kanaler krävs avsevärd utvecklarexpertis. Den här artikeln är avsett för IT-administratörer eller utvecklare som har erfarenhet av utveckling och skrivning av kod.

Dricks

Du behöver inte följa det här dokumentet om du vill lägga till Copilot Studio copilot på webbplatsen, Facebook eller Microsoft Teams. Om målet är att ansluta till en anpassad webbapp eller en egen app kan dina utvecklare få mer information på Lägg till copilot i mobila och anpassade appar.

Viktigt

Instruktioner i det här avsnittet kräver programvaruutveckling från dig eller dina utvecklare. Den är avsedd för erfarna IT-proffs, t.ex. IT-administratörer eller IT-utvecklare med en gedigen förståelse för utvecklarverktyg, verktyg samt IDE:er.

Förutsättningar

En Azure Bot Service-prenumeration.
En Azure Bot Service-robot med v4 SDK.
.NET Core SDK version 2.1.
NuGet-paket Microsoft.Bot.Connector.DirectLine.
En copilot som skapats i Copilot Studio som du vill ansluta till en Azure Bot Service-kanal.
Anslut din copilot till mobila och anpassade appar.

Kodexempel

Kodfragment som används i det här dokumentet kommer från vidarebefordran av exempelkoden för robot.

Referenser

Anvisningarna i det här dokumentet hänvisar till följande:

Distribuera din robot till Azure för instruktioner om hur du distribuerar Azure Bot Service-robot.
Azure Bot Service-kanaler för att ansluta till alla Azure Bot Service-kanaler som stöds.
Fel sökning av Bot Service med emulatorn för instruktioner om hur du felsöker Azure Bot Service-robot.

Skapa eller använda en befintlig Azure Bot Service-robot

Du behöver en Azure Bot Service-robot som kan vidarebefordra samtal mellan dina Copilot Studio-copilot och Azure Bot Service-kanaler.

Vidarebefordra robotdiagram.

Vidarebefordra exempelkoden för robot är en bra startpunkt om du inte har någon befintlig Azure Bot Service-robot. Den är byggd från Microsoft Bot Framework-robot exempelkod som kan kompileras och distribueras till Azure Bot Service. Exempelkoden är avsedd att användas som utgångspunkt och inte är avsedd att användas i tillverkningen direkt. Du måste lägga till kod och optimering för att uppfylla dina affärsbehov.

Om du redan har en Azure Bot Service-robot måste du lägga till en Copilot Studio-koppling och kod för att hantera sessioner med konversationer. Du kan distribuera robot till Azure Bot Service och ansluta till kanaler med Azure-portalen.

Hämta dina Copilot Studio copilot-parametrar

Om du vill ansluta till den copilot som du har skapat med Copilot Studio måste du hämta din copilot namn och tokenslutpunkt.

Kopiera namnet på copilot till Copilot Studio.
I navigeringsmenyn, under Inställningar, väljer du Kanaler.
Välj den kanal du vill ansluta till. I scenario använder Slack som exempel.
Om du vill kopiera och spara värdet tokenslutpunkt väljer du Kopiera. Du behöver din slutpunkt för att ansluta din copilot till Azure Bot Service-kanalen.

Hantera konversationssessioner med Copilot Studio-copilot

Det kan finnas flera konversationer mellan Azure Bot Service-kanaler och Direct Line-anslutningen med din Copilot Studio-copilot.

Din Azure Bot Service-robot kommer att behöva mappa och vidarebefordra konversationen från Azure Bot Service-kanalen till Direct Line-konversationen med Copilot Studio-copilot och vice versa.

Exempel på exempelkod

I följande exempel används exempel från vidarebefordran av exempelkoden för robot.

Starta en konversation på alla nya externa Azure Bot Service-kanaler konversationens start, starta en Copilot Studio copilot-konversation. Se Hämta Direct Line-token och Använda Direct Line för att kommunicera med copilot för instruktioner om hur man startar en ny konversation med roboten.

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

Om du vill hantera flera sessioner måste du upprätthålla en mappning av externa Azure Bot Service-kanalkonversationer till motsvarande Copilot Studio copilot-konversation. En Copilot Studio copilot-konversation kan identifieras med och vara ansluten med två egenskaper: ConversationtId och Token.

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

Om du vill hantera konversations livscykeln uppdaterar du Direct Line token eller rensar bort inaktiva konversationer. Läs mer om tokenuppdatering på uppdatera Direct Line token. En Copilot Studio copilot-konversation för att stödja de som definieras enligt följande:

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

När en ny Copilot Studio copilot-konversation startar lägger du till ett nyckelvärdespar (external_Azure_Bot_Service_channel_conversationID, PowerVirtualAgentsConversation) i mappningstabellen.

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

Om du vill fortsätta på en befintlig konversation klickar du på ett nytt externt Azure Bot Service-kanalmeddelande som togs emot, hämtar den befintliga konversationen från mappningstabellen, vidarebefordrar den externa konversationsaktiviteten till Copilot Studio-copilot och får svar.

I följande exempel visas vidarebefordring av konversation genom åsidosätta metoden 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;
}

Se Använda Direct Line för att kommunicera med copilot för information om hur man får svar från Copilot Studio-copilot. När Copilot Studio-copilot svar tas emot läser du Parsa konversationens nyttolast från copilot för hur du ska tolka svaret på det externa Azure Bot Service-kanalsvaret.

Exempel på hur du tolkar svar finns i vidarebefordran av exempelkoden för robot ResponseConverter.cs.

Distribuera till Azure Bot Service

När du har en Azure Bot Service Relay vidarebefordringsrobot klar måste du distribuera roboten till din Azure Bot Service.

Ange Azure Bot Service-kanaler

Du kan konfigurera de kanaler du vill ansluta till genom att logga in på Azure-portalen och välja vilken resursgrupp för Azure Bot Service som du har distribuerat till. Visa de specifika anvisningarna för varje kanal i Azure Bot Service-kanaler.

Dela via