Agentin julkaiseminen mobiilisovelluksiin tai mukautettuihin sovelluksiin

Voit yhdistää agenttisi mukautettuun sovellukseen siten, että sovelluksen käyttäjät voivat olla yhteydessä agenttiin suoraan sovelluksestasi.

Useimmissa tapauksissa mukautettu sovelluksesi on mobiililaitteen sovellus, joka on joko verkkopohjainen tai alkuperäinen sovellus. Se voi olla myös sovitin muihin yrityksesi edellyttämään palveluihin.

Voit muodostaa yhteyden mobiilisovellukseen eri tavoin sen mukaan, onko sovellus verkkopohjainen vai alkuperäinen sovellus.

Agenttien yhdistäminen verkkopohjaiseen sovellukseen on suhteellisen suoraviivaista, koska siihen liittyy koodikatkelman kopiointi sovellukseen. Sekä verkkopohjaiset että natiivit tai mukautetut sovellukset edellyttävät kuitenkin merkittävää kehittäjäkokemusta, jotta agentti saadaan integroitua täysin sovellukseen. Tässä artikkelissa kuvataan molemmat menettelyt.

Vaatimukset

• .NET Core SDK -versio 2.1.
• NuGet-paketti Microsoft.Bot.Connector.DirectLine.
• Copilot Studiossa luotu sovellukseen yhdistettävä agentti.

Agentin yhdistäminen verkkopohjaiseen sovellukseen

1. Valitse Copilot Studio siirtymisvalikossa Kanavat.

2. Valitse Mobiilisovellus-ruutu avataksesi määritysikkunan.

3. Kopioi Verkkopohjaiset sovellukset -osan koodi ja välitä se sovelluskehittäjille verkkopohjaiseen sovellukseesi lisäämistä varten.

   

Agentin yhdistäminen natiiviin tai mukautettuun sovellukseen

Jos haluat muodostaa yhteyden Azure Bot Service kanaviin, katso Julkaise agentti Azure Bot Service kanaviin.

Viitteet

Tämän asiakirjan ohjeissa viitataan seuraavaan lähdemateriaaliin:

• Bot Framework Direct Line -ohjelmointirajapinta
• Direct Line -todennus
• Siirron yhteydessä saatavilla olevat kontekstimuuttujat
• Microsoft Bot Framework -aktiviteetti

Palauta Copilot Studio -agenttisi parametrit

Jos haluat muodostaa yhteyden muodostamaasi agenttiin, nouda agenttisi nimi ja tunnus päätepiste tunnistaaksesi sen.

1. Siirry Copilot Studio agenttisi Overview -sivulle ja kopioi agenttisi nimi.

2. Valitse Kanavat>Mobiilisovellus.

3. Valitse Mobiilisovellus-sivulla Tunnuksen päätepiste -kodan vieressä Kopioi. Tätä päätepistettä tarvitaan vaiheessa Direct Line -tunnuksen hakeminen.

   

Hae Direct Line -tunnus

Keskustelun aloittamiseen agentin kanssa tarvitaan Direct Line -tunnus. Hanki tämä tunnus lähettämällä GET-pyyntö Copilot Studio näytössä näkyvään päätepisteeseen. Käytä tätä tunnusta otsikoksi seuraaville suoran rivin ohjelmointirajapinnan kutsuille.

Esimerkki:

GET <BOT TOKEN ENDPOINT>

Jos pyyntö onnistuu, päätepiste palauttaa pyydetyn agentin Direct Line -tunnuksen, vanhentumisajan ja conversationId-tunnuksen.

Esimerkki:

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

Direct Line -tunnuksen hakemisen koodiesimerkki

Seuraavassa esimerkissä saadaan Direct Line -tunnus Copilot Studio -agentille.

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

Vastausobjekti on sama kuin GET aiemmin näkemäsi pyyntö.

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

Direct Linen käyttäminen viestintään agentin kanssa

Kun olet noutanut Direct Line tunnuksen, voit keskustella Copilot Studio agentin kanssa Direct Line avulla. Lisätietoja keskustelun aloittamisesta sekä viestien lähettämisestä ja vastaanottamisesta on kohdassa Bot Framework Direct Line -ohjelmointirajapinta.

Seuraava esimerkki aloittaa keskustelun ja lähettää ja vastaanottaa viestejä Copilot Studio -agentilta.

1. Alusta DirectLineClient-esiintymä Direct Line -tunnuksen avulla ja aloita keskustelu:

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

2. Kun yhteys on aloitettu, voit tunnistaa jokaisen keskustelun ja muodostaa siihen yhteyden käyttämällä - ja token-yhdistelmääconversationtId. Käyttäjäviestin lähettäminen aiemmin luotuun keskusteluun:

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

3. Nouda agentin vastaus käyttämällä samoja tokenconversationIdja . Noudetut Direct Line -vastausaktiviteetit sisältävät sekä käyttäjän että agentin viestit. Voit suodattaa agentin vastausaktiviteetteja agentin nimen perusteella, jotta saat vain kyseisen agentin vastausviestejä.

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

Direct Line -tunnuksen päivittäminen

Direct Line -tunnuksen päivittäminen saattaa edellyttää koodin lisäämistä, jos sovelluksella on pitkä keskustelu agentin kanssa. Tunnus vanhenee, mutta sen voi päivittää ennen sen vanhenemista. Lisätietoja on artikkelissa Direct Line Authentication.

Seuraava esimerkki päivittää nykyisen Copilot Studio -keskustelun tunnuksen:

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

Jäsennä agentilta saadut keskustelutiedot

Kun keskustelu agentin kanssa on aloitettu, keskustelun JSON-tiedoissa käytetään vakiomuotoista Microsoft Bot Framework Direct Line -aktiviteettia. Lisätietoja on artikkelissa Bot Framework Direct Line API.

Siirtoaktiviteetin käsitteleminen

Jos sovelluksesi on suoritettava siirto live-agenttitarjoajalle, sinun on käsiteltävä siirtotoiminto. Luovutusaktiviteetti lähetetään, kun Siirto agentille -solmuun isketään. Voit tutustua tarkemmin kunkin siirtoaktiviteetin tietoihin.

Tervetuloviestin käynnistys

Jos haluat, että agenttisi lähettää automaattisesti tervehdysjärjestelmän aiheen, kun käyttäjä aloittaa keskustelun, lähetä aktiviteetti ön ja Type=eventkanssaName=startConversation.