Publicera en agent till Azure Bot Service-kanaler

Artikel
12/31/2024

Du kan ansluta din agent till befintliga Azure Bot Service-kanaler, vilket kan vara användbart om du vill ansluta din agent till kunder i Azure Bot Service-kanaler.

För att du ska kunna lägga till agenten 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.

Tips!

Du behöver inte följa det här dokumentet om du vill lägga till Copilot Studio agent på webbplatsen, Facebook eller Microsoft Teams. Om målet är att ansluta till ett anpassat webbaserat eller lokalt program kan dina utvecklare få mer information i Publicera en agent i mobila eller anpassade program.

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 agent som skapats i Copilot Studio som du vill ansluta till en Azure Bot Service-kanal.
Publicera en agent till mobila eller 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 dokument:

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-agent 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 agentparametrar

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

Kopiera namnet på agenten 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 agent till Azure Bot Service-kanalen.

Hantera konversationssessioner med Copilot Studio-agent

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

Din Azure Bot Service-agent kommer att behöva mappa och vidarebefordra konversationen från Azure Bot Service-kanalen till Direct Line-konversationen med Copilot Studio-agenten 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-agentkonversation. Se Hämta Direct Line-token och Använda Direct Line för att kommunicera med agenten 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-agentkonversation. En Copilot Studio-agentkonversation 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 agentkonversation för att stödja uppdatering av token för Direct Line som definieras enligt följande:

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

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

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

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

Se Använda Direct Line för att kommunicera med agenten för information om hur man får svar från Copilot Studio-agenten. När Copilot Studio-agentens svar tas emot läser du Parsa konversationens nyttolast från agenten 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