Legg til en Copilot Studio-kopilot i Azure Bot Service-kanaler

Artikkel
04/22/2024

Viktig!

Power Virtual Agents-funksjoner er nå en del av Microsoft Copilot Studio etter betydelige investeringer i generativ kunstig intelligens og forbedrede integreringer på tvers av Microsoft Copilot.

Enkelte artikler og skjermbilder kan henvise til Power Virtual Agents når vi oppdaterer dokumentasjons- og opplæringsinnhold.

Du kan koble kopiloten til eksisterende Azure Bot Service-kanaler. Dette kan være nyttig hvis du vil koble kopiloten din til sluttbrukere i Azure Bot Service-kanaler.

For å legge til kopiloten i Azure Bot Service-kanaler kreves det betydelig utviklingsekspertise. Denne artikkelen er skrevet for IT-administratorer eller utviklere som har erfaring med å utvikle og skrive kode.

Tips

Du trenger ikke å følge dette dokumentet for å legge til en Copilot Studio-kopilot på nettstedet, Facebook eller Microsoft Teams. Hvis målet er å koble til en egendefinert nettbasert eller innebygd app, kan utviklerne finne ut mer på Legg til kopiloten i mobilapper og egendefinerte apper.

Viktig!

Instruksjonene i denne delen krever programvareutvikling fra deg eller utviklerne. Den er beregnet på erfarne IT-medarbeidere, for eksempel IT-administratorer eller utviklere som har en solid forståelse av utviklerverktøy, og integrerte utviklingsmiljøer (IDE).

Forutsetninger

Et Azure Bot Service-abonnement.
En Azure Bot Service-robot som bruker v4 SDK.
.NET Core SDK versjon 2.1.
NuGet-pakke Microsoft.Bot.Connector.DirectLine.
En kopilot som er opprettet i Copilot Studio, og som du vil koble til en Azure Bot Service-kanal.
Koble kopiloten til mobilapper og egendefinerte apper.

Kodeeksempler

Kodesnutter som brukes i dette dokumentet, er fra eksempelkode for relérobot.

Referanser

Instruksjonene i dette dokumentet refererer til følgende:

Distribuer roboten din til Azure hvis du vil ha instruksjoner om hvordan du distribuerer Azure Bot Service-roboten.
Azure Bot Service-kanaler for å koble til kanaler som støttes av Azure Bot Service.
Feil søking for Azure Bot Service med emulatoren for instruksjoner om hvordan du feilsøker Azure Bot Service-roboten.

Opprett eller bruk en eksisterende Azure Bot Service-robot

Du trenger en Azure Bot Service-robot som kan videresende samtaler mellom Copilot Studio-kopiloten og Azure Bot Service-kanaler.

Diagram for relérobot.

Eksempel koden for relérobot er et godt utgangspunkt hvis du ikke har en eksisterende Azure Bot Service-robot. Den er bygget ut ifra Microsoft Bot Framework-roboten eksempelkode som kan kompileres og distribueres til Azure Bot Service. Eksempelkoden er ment å skulle brukes som utgangspunkt, og er ikke ment å brukes direkte i produksjonen. Du må legge til kode og optimalisering som samsvarer med dine forretningsbehov.

Hvis du allerede har en Azure Bot Service-robot, må du legge til en Copilot Studio-kobling og kode for å administrere samtaleøkter. Du kan deretter distribuere roboten til Azure Bot Service og koble til kanaler med Azure-portalen.

Hent parameterne for Copilot Studio-kopiloten

Hvis du vil koble til kopiloten du har bygd med Copilot Studio, må du hente kopilotens navn og tokenendepunktet.

Kopier navnet på kopiloten i Copilot Studio.
Velg Kanaler under Innstillinger på navigasjonsmenyen.
Velg kanalen du ønsker å koble til. I dette scenarioet brukes Slack som eksempel.
Hvis du vil kopiere og lagre verdien for Tokenendepunkt, velger du Kopier. Du trenger endepunktene for å koble kopiloten til Azure Bot Service-kanalen.

Administrere samtaleøkter med Copilot Studio-kopiloten

Det kan være flere samtaler mellom Azure Bot Service-kanalene og Direct Line-tilkoblingen med Copilot Studio-kopiloten.

Azure Bot Service-roboten må tilordne og videresende samtalen fra Azure Bot Service-kanalen til Direct Line-samtalen med Copilot Studio-kopiloten og omvendt.

Eksempel på eksempelkode

Eksemplet nedenfor bruker eksempler fra eksempelkoden for relérobot.

Start en Copilot Studio-kopilotsamtale ved starten på hver nye, eksterne Azure Bot Service-kanalsamtale. Se Hente Direct Line-token og Bruke Direct Line til å kommunisere med kopiloten hvis du vil ha instruksjoner om hvordan du starter en ny samtale 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;
 }

Hvis du vil administrere flere økter, må du opprettholde en tilordning av eksterne Azure Bot Service-kanalsamtaler til tilsvarende Copilot Studio-kopilotsamtaler. En Copilot Studio-kopilotsamtale kan identifiseres og kobles til ved hjelp av to egenskaper: ConversationtId og Token.

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

Du kan administrere samtalelivssyklusen ved å oppdatere Direct Line-tokener eller rydde opp i inaktive samtaler. Finn ut mer om tokenoppdatering under Oppdater Direct Line-token. En Copilot Studio-kopilotsamtale for å støtte disse er definert som følger:

/// <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-kopilotsamtale starter, legger du til et nøkkelverdipar (external_Azure_Bot_Service_channel_conversationID, PowerVirtualAgentsConversation) i tilordningstabellen.

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

Hvis du vil fortsette med en eksisterende samtale etter å ha mottatt en ny ekstern melding i Azure Bot Service-kanalen, henter du den eksisterende diskusjonen fra tilordningstabellen, videresender den eksterne samtaleaktiviteten til Copilot Studio-kopiloten, og får et svar.

Eksempelet nedenfor viser videresending av samtale ved overstyring av ActivityHandler.OnMessageActivityAsync((ITurnContext<IMessageActivity>, CancellationToken)-metoden

// 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 Bruk Direct Line til å kommunisere med kopiloten for instruksjoner om hvordan du får svaret fra Copilot Studio-kopiloten. Når Copilot Studio-kopilotens svar er mottatt, kan du se Dele opp samtalens nyttelast fra kopiloten for hvordan du kan dele opp svaret til svaret i en ekstern Azure Bot Service-kanal.

Et eksempel på svaroppdeling finner du i eksempelkode for relérobot ResponseConverter.cs.

Distribuere til Azure Bot Service

Når du har en Azure Bot Service-relérobot klar, må du distribuere roboten til Azure Bot Service.

Konfigurere Azure Bot Service-kanaler

Du kan angi hvilke kanaler du vil koble til, ved å logge på Azure-portalen og velge ressursgruppen for Azure Bot Service du har distribuert til. Se de spesifikke instruksjonene for hver kanal på Azure Bot Service-kanaler.

Del via