Publicera en agent till mobila eller Anpassade appar

2025-07-01

Du kan ansluta agent till en egen app så att appens användare kan interagera med agent direkt från appen.

I de flesta fall är din Anpassade app en mobilapp som antingen är en webbaserad app eller en inbyggd app eller adapter till andra tjänster som ditt företag kräver.

Det finns olika sätt att ansluta till din mobilapp, beroende på om din app är en webbaserad app eller en ursprunglig app.

Det är relativt enkelt att ansluta agenten till en webbaserad app, eftersom det innebär att kopiera en kodavsnitt i din app. Både webbaserade appar och egna eller Anpassade appar behöver emellertid fortfarande stora kunskaper i utvecklingsarbetet för att kunna integrera agenten i din app. Båda procedurerna beskrivs i den här artikeln.

Förutsättningar

.NET Core SDK version 2.1.
NuGet-paket Microsoft.Bot.Connector.DirectLine.
En agent som skapades i Copilot Studio som du vill ansluta till din app.

Ansluta agenten till en webbaserad app

I Copilot Studio, väljer Kanaler på navigeringsmenyn.
Välj panelen Mobilapp för att öppna konfigurationsfönstret.
Kopiera koden under avsnittet Webbaserade appar och lämna apputvecklare som ska läggas till i den webbaserade appen.

Anslut agenten till en egen eller egen app

Tips!

I det här avsnittet beskrivs hur du ansluter till en mobilapp, men samma process kan användas för Anpassade appar, t.ex. IoT (sakernas Internet).

Om målet är att ansluta till Azure Bot Service-kanalerna, utöver anvisningarna i det här avsnittet, kan dina utvecklare få mer information Publicera en agent till Azure Bot Service-kanaler.

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.

Referenser

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

Hämta dina parametrar för Copilot Studio-agent

Om du vill ansluta till den agent du skapade måste du hämta namnet på agenten och den token som slutpunkt för att identifiera den.

I Copilot Studio, gå till sidan Översikt av din agent och kopiera din agents namn.
Välj Kanaler>Mobilapp.
På sidan Mobilapp bredvid Tokenslutpunkt väljer du Kopiera. Du behöver denna slutpunkt för steget Hämta Direct Line-token.

Hämta Direct Line

För att starta en konversation med din agent, behöver du ett Direct Line-token. Denna token kan hämtas genom att göra en GET-förfrågan till slutpunkt som visas på Copilot Studio-skärmen. Denna token måste sedan användas som rubrik för efterföljande anrop till Directline API.

Exempel:

GET <BOT TOKEN ENDPOINT>

Om förfrågan lyckas returneras Direct Line-token, utgångstid och ett konversations-ID för den begärda agenten.

Exempel:

{
    "token": "RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xn",
    "expires_in": 3600,
    "conversationId": "abc123"
}

Hämta kodexempel för Direct Line-token

I följande exempel får man en Direct Line-token för en Copilot Studio-agent.

/// <summary>
/// Get directline token for connecting bot
/// </summary>
/// <returns>directline token as string</returns>
public async Task<DirectLineToken> GetTokenAsync(string url)
{
    try
    {
        return await _httpClient.GetFromJsonAsync<DirectLineToken>(url);
    }
    catch (HttpRequestException ex)
    {
        throw ex;
    }        
}

/// <summary>
/// class for serialization/deserialization DirectLineToken
/// </summary>
public class DirectLineToken
{
  public string Token { get; set; }
  public int Expires_in { get; set; }
  public string ConversationId { get; set; }
}

Svarsobjektet är samma som i GETGET-förfrågan som vi såg tidigare.

{
  "token": "RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xn",
  "expires_in": 3600,
  "conversationId": "abc123"
}

Använd Direct Line för att kommunicera med agenten

När du har hämtat Direct Line-token är du klar att få en konversation med din Copilot Studio-agent med Direct Line. Om du vill starta en konversation och skicka och ta emot meddelanden följer du anvisningarna i Bot Framework Direct Line API.

I följande exempel startar en konversation och skickar och tar emot meddelanden från en Copilot Studio-agent.

Initiera en DirectLineClient-instans med Direct Line-token och starta en konversation:

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

När en konversation har startats kan den identifieras och kopplas ihop med hjälp av kombinationen token och conversationtId. Skicka ett användarmeddelande till en befintlig konversation:

   // Use the retrieved token to create a DirectLineClient instance
   // Use the conversationId from above step
   // endConversationMessage is your predefined message indicating that user wants to quit the chat
   while (!string.Equals(inputMessage = /*Get_User_Input()*/, endConversationMessage, StringComparison.OrdinalIgnoreCase))
   {
       using (var directLineClient = new DirectLineClient(token))
       {
           // Send user message using directlineClient
           // Payload is a Microsoft.Bot.Connector.DirectLine.Activity
           await directLineClient.Conversations.PostActivityAsync(conversationtId, new Activity()
           {
               Type = ActivityTypes.Message,
               From = new ChannelAccount { Id = "userId", Name = "userName" },
               Text = inputMessage,
               TextFormat = "plain",
               Locale = "en-Us",
           });
       }
   }

Hämta agentens svar med samma token och conversationId. De hämtade Direct Line svarsaktiviteterna innehåller både användarens och agentens meddelanden. Du kan filtrera svarsaktiviteten efter din agents namn om du endast vill få agentmeddelandet.

   // Use the same token to create a directLineClient
   using (var directLineClient = new DirectLineClient(token))
   {
       // To get the first response set string watermark = null
       // More information about watermark is available at
       // https://learn.microsoft.com/azure/bot-service/rest-api/bot-framework-rest-direct-line-1-1-receive-messages?view=azure-bot-service-4.0

       // response from bot is of type Microsoft.Bot.Connector.DirectLine.ActivitySet
       ActivitySet response = await directLineClient.Conversations.GetActivitiesAsync(conversationtId, watermark);

       // update watermark from response
       watermark = response?.Watermark;

       // response contains set of Activity from both user and bot
       // To display bot response only, filter Activity.From.Name equals to your bot name
       List<Activity> botResponses = response?.Activities?.Where(x =>
                 x.Type == ActivityTypes.Message &&
                   string.Equals(x.From.Name, /*Bot_Name*/, StringComparison.Ordinal)).ToList();

       // Display botResponses
   }

Uppdatera Direct Line-token

Du kan behöva lägga till kod för att uppdatera Direct Line-token om programmet har en lång konversation med agenten. Token förfaller men kan uppdateras innan den upphör att gälla. Läs mer på Direct Line-autentisering.

I följande exempel uppdateras token för en befintlig Copilot Studio-konversation:

  // DirectLine provides a token refresh method
  // Requires the currentToken valid when refreshing
  string refreshToken = new DirectLineClient(currentToken).Tokens.RefreshToken().Token;
  // create a new directline client with refreshToken
  directLineClient = new DirectLineClient(refreshToken);
  // use new directLineClient to communicate to your bot

Analysera konversationens nyttolast från agenten

När du har startat en konversation med agenten använder konversationens JSON-nyttolast standardaktiviteten för Microsoft Bot Framework Direct Line. Du kan läsa mer i Bot Framework Direct Line API.

Hantera överlämnande av aktivitet

Om ditt program behöver överlämnas till en live-handläggare måste du överlämna aktiviteten. Överlämningsaktiviteten skickas när noden ”Överför till handläggare” trycks ned. Du kan läsa mer om nyttolast för av överlämningsaktiviteten.

Utlösa ett välkomstmeddelande

Om du vill att din agent ska skicka hälsningssystemets ämne automatiskt när en användare startar en konversation, kan du skicka en aktivitet med Type=event och Name=startConversation.