เพิ่ม Copilot ในแอปสำหรับอุปกรณ์เคลื่อนที่หรือแบบกำหนดเอง

สำคัญ

ความสามารถและคุณลักษณะต่างๆ ของ Power Virtual Agents เป็น ส่วนหนึ่งของ Microsoft Copilot Studio แล้ว ภายหลังการลงทุนที่สำคัญใน Generative AI และการรวมที่ได้รับการปรับปรุงใน Microsoft Copilot

บทความและภาพหน้าจอบางรายการอาจอ้างถึง Power Virtual Agents ในขณะที่เราอัปเดตคู่มือและเนื้อหาการฝึกอบรม

คุณสามารถเชื่อมต่อ Copilot ของคุณกับแอปที่กำหนดเองเพื่อให้ผู้ใช้แอปโต้ตอบกับ Copilot ได้โดยตรงจากภายในแอปของคุณ

ในกรณีส่วนใหญ่ แอปที่กำหนดเองของคุณเป็นแอปบนอุปกรณ์เคลื่อนที่ที่เป็นทั้งแอปบนเว็บหรือแอปดั้งเดิมหรืออะแดปเตอร์สำหรับบริการอื่น ๆ ที่ธุรกิจของคุณต้องการ

มีขั้นตอนต่าง ๆ ในการเชื่อมต่อกับแอปบนมือถือของคุณ ขึ้นอยู่กับว่าแอปของคุณเป็นแอปที่ทำงานบนเว็บหรือแอปดั้งเดิม

การเชื่อมต่อ Copilot ของคุณกับแอปบนเว็บนั้นค่อนข้างตรงไปตรงมาเนื่องจากเป็นการคัดลอกส่วนย่อยของโค้ดลงในแอปของคุณ อย่างไรก็ตาม ทั้งแอปบนเว็บและแอปดั้งเดิมหรือแอปที่กำหนดเองยังคงต้องใช้ความเชี่ยวชาญของนักพัฒนาในการผสานรวม Copilot เข้ากับแอปของคุณอย่างสมบูรณ์ ทั้งสองกระบวนงานจะอธิบายในบทความนี้

ข้อกำหนดเบื้องต้น

• .NET Core SDK รุ่น 2.1
• แพ็คเกจ NuGet Microsoft.Bot.Connector.DirectLine
• Copilot ที่สร้างขึ้นใน Copilot Studio ที่คุณต้องการเชื่อมต่อกับแอปของคุณ

เชื่อมต่อ Copilot ของคุณกับแอปบนเว็บ

1. ใน Copilot Studio ในเมนูนำทาง ภายใต้ การตั้งค่า เลือก ช่องทาง

2. เลือกไทล์ แอปบนมือถือ เพื่อเปิดหน้าต่างการกำหนดค่า

3. คัดลอกรหัสภายใต้ส่ว แอปบนเว็บ และมอบให้กับนักพัฒนาแอปของคุณเพื่อเพิ่มลงในแอปบนเว็บของคุณ

   

เชื่อมต่อ Copilot ของคุณกับแอปดั้งเดิมหรือกำหนดเอง

เคล็ดลับ

แม้ว่าส่วนนี้จะอธิบายถึงวิธีการเชื่อมต่อกับแอปบนมือถือ แต่กระบวนการเดียวกันนี้สามารถนำไปใช้กับแอปแบบกำหนดเองหรือแบบดั้งเดิม เช่น แอป IoT (Internet of Things)

หากเป้าหมายของคุณคือการเชื่อมต่อกับช่องทางบริการ Azure Bot นอกจากทำตามคำแนะนำที่นี่แล้ว นักพัฒนาของคุณสามารถเรียนรู้เพิ่มเติมได้ที่ เชื่อมต่อบอทของคุณกับช่องทางบริการ Azure Bot

สำคัญ

คำแนะนำในส่วนนี้ต้องการการพัฒนาซอฟต์แวร์จากคุณหรือนักพัฒนาของคุณ ซึ่งมีไว้สำหรับผู้เชี่ยวชาญด้านไอทีที่มีประสบการณ์ เช่น ผู้ดูแลระบบไอทีหรือนักพัฒนาที่มีความเข้าใจอย่างถ่องแท้เกี่ยวกับเครื่องมือสำหรับนักพัฒนา ระบบสาธารณูปโภค และ IDE

ตัวอย่างโค้ด

ส่วนย่อยของโค้ดที่ใช้ในเอกสารนี้มาจาก:

• โค้ดตัวอย่างตัวเชื่อมต่อ

การอ้างอิง

คำแนะนำในเอกสารนี้อ้างอิงเอกสารต้นทางต่อไปนี้:

• Bot Framework Direct Line API
• การรับรองความถูกต้อง Direct Line
• ตัวแปรตามบริบทพร้อมใช้งานเมื่อส่งต่อ
• กิจกรรม Microsoft Bot Framework

เรียกข้อมูลพารามิเตอร์ Copilot ของ Copilot Studio ของคุณ

ในการเชื่อมต่อกับ Copilot ที่คุณสร้างขึ้นด้วย คุณต้องดึงข้อมูลชื่อและตำแหน่งข้อมูลโทเค็นเพื่อระบุ

1. คัดลอกชื่อ Copilot ของคุณใน Copilot Studio

   

2. ในเมนูนำทาง ภายใต้ การตั้งค่า เลือก ช่องทาง

3. เลือก แอปบนมือถือ

   

4. ถัดจาก ตำแหน่งข้อมูลโทเค็น เลือก คัดลอก คุณต้องการตำแหน่งข้อมูลนี้สำหรับขั้นตอน รับโทเค็น Direct Line

   

รับโทเค็น Direct Line

ในการเริ่มการสนทนากับ Copilot คุณต้องการโทเค็น Direct Line โทเค็นนี้สามารถขอรับได้โดยส่งคำขอ GET ไปที่ตำแหน่งข้อมูลที่ระบุภายในหน้าจอ Copilot Studio โทเค็นนี้จะต้องใช้เป็นส่วนหัวสำหรับการเรียก Directline API ในภายหลัง

ตัวอย่าง:

GET <BOT TOKEN ENDPOINT>

หากคำขอสำเร็จ ระบบจะส่งคืนโทเค็น Direct Line เวลาการหมดอายุและ conversationId สำหรับ Copilot ที่ร้องขอ ตัวอย่าง:

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

โค้ดตัวอย่าง

ตัวอย่างต่อไปนี้ใช้ตัวอย่างจาก โค้ดตัวอย่างตัวเชื่อมต่อ เพื่อรับโทเค็น Direct Line สำหรับ Copilot ของ Copilot Studio

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

ออบเจ็กต์การตอบสนองเหมือนกับคำขอ GET ที่เราเห็นก่อนหน้านี้

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

ใช้ Direct Line เพื่อสื่อสารกับ Copilot

หลังจากดึงข้อมูลโทเค็น Direct Line คุณพร้อมที่จะสนทนากับ Copilot ของ Copilot Studio ของคุณด้วย Direct Line หากต้องการเริ่มการสนทนาและส่งและรับข้อความ ให้ทำตามคำแนะนำที่ Bot Framework Direct Line API

ตัวอย่างต่อไปนี้ใช้ตัวอย่างจาก โค้ดตัวอย่างตัวเชื่อมต่อ เพื่อเริ่มการสนทนาและส่งและรับข้อความจาก Copilot ของ Copilot Studio

1. เริ่มต้นอินสแตนซ์ DirectLineClient ด้วยโทเค็น Direct Line และเริ่มการสนทนา:

      // 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. เมื่อเริ่มต้นแล้ว สามารถระบุและเชื่อมต่อการสนทนาแต่ละรายการโดยใช้การรวมกันของ token และ conversationtId ส่งข้อความผู้ใช้ไปยังการสนทนาที่มีอยู่:

      // 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. ดึงการตอบของ Copilot โดยใช้ token และ conversationId เดียวกัน กิจกรรมการตอบของ Direct Line ที่ดึงข้อมูลมีทั้งข้อความของผู้ใช้และ Copilot คุณสามารถกรองกิจกรรมการตอบรับด้วยชื่อ Copilot ของคุณเพื่อรับเฉพาะข้อความการตอบของ Copilot

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

คุณอาจต้องเพิ่มรหัสเพื่อรีเฟรชโทเค็น Direct Line หากแอปพลิเคชันของคุณมีการสนทนากับ Copilot เป็นเวลานาน โทเค็นหมดอายุ แต่สามารถรีเฟรชได้ก่อนหมดอายุ เรียนรู้เพิ่มเติมได้ที่ การรับรองความถูกต้อง Direct Line

ตัวอย่างต่อไปนี้ใช้ตัวอย่างจาก โค้ดตัวอย่างตัวเชื่อมต่อ เพื่อรีเฟรชโทเค็นสำหรับการสนทนา Copilot Studio ที่มีอยู่:

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

แยกวิเคราะห์ส่วนข้อมูลการสนทนาจาก Copilot

หลังจากเริ่มการสนทนากับ Copilot ส่วนข้อมูล JSON ของการสนทนาจะใช้กิจกรรม Microsoft Bot Framework Direct Line มาตรฐาน คุณสามารถเรียนรู้เพิ่มเติมได้ที่ Bot Framework Direct Line API

จัดการกิจกรรมการส่งต่อ

หากแอปพลิเคชันของคุณจำเป็นต้องส่งต่อไปยังผู้ให้บริการตัวแทนสนทนาสด คุณต้องจัดการกิจกรรมการส่งต่อ กิจกรรมการส่งต่อจะถูกส่งเมื่อกดโหนด "โอนให้ตัวแทน" คุณสามารถ เรียนรู้เพิ่มเติมเกี่ยวกับส่วนข้อมูลของกิจกรรมการส่งต่อ

ทริกเกอร์ข้อความต้อนรับ

หากคุณต้องการให้ Copilot ของคุณส่งหัวข้อระบบคำทักทายโดยอัตโนมัติเมื่อผู้ใช้เริ่มการสนทนา คุณสามารถส่งกิจกรรมด้วย Type=event และ Name=startConversation