เผยแพร่เอเจนต์ไปยังแอปสำหรับอุปกรณ์เคลื่อนที่หรือแบบกำหนดเอง

เชื่อมต่อเอเจนต์ Copilot Studio ที่เผยแพร่แล้วกับแอปมือถือหรือแอปที่กําหนดเอง เพื่อให้ผู้ใช้สามารถโต้ตอบกับเอเจนต์ได้โดยไม่ต้องออกจากแอป

เลือกการผสานรวมที่เหมาะสมกับแอปของคุณ:

• โค้ดฝังเว็บ: เพิ่มอินเทอร์เฟซแชทที่จัดเตรียมไว้ลงในเว็บแอป
• Direct Line: ส่งและรับกิจกรรมโดยทางโปรแกรมจากแอปเนทีฟ อินเทอร์เฟซเว็บที่กำหนดเอง หรืออะแดปเตอร์ไปยังบริการอื่น

สําหรับการผสานรวมแบบแยกที่ใช้ SDK ดูรายละเอียดเพิ่มเติมได้ที่ ผสานรวมเว็บหรือแอปเนทีฟกับ SDK เอเจนต์สำหรับ Microsoft 365

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

• เอเจนต์ Copilot Studio ที่ตีพิมพ์แล้ว เรียนรู้เพิ่มเติมในส่วน เผยแพร่และปรับใช้เอเจนต์ของคุณ
• สำหรับตัวอย่าง C# ต้องมี .NET SDK ที่รองรับ และแพ็กเกจ NuGet Microsoft.Bot.Connector.DirectLine กับ Microsoft.Rest.ClientRuntime ตัวอย่างเหล่านี้ใช้ System.Net.Http.Json และ System.Text.Json.Serialization สําหรับการตอบสนองแบบโทเคน
• เครื่องมือพัฒนาที่เหมาะสมกับแอปของคุณ ข้อกําหนดเบื้องต้นของ .NET ใช้ได้เฉพาะกับตัวอย่าง C# เท่านั้น ไม่ใช่กับทุกการผสานรวม

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

1. ใน Copilot Studio ในเมนูการนำทาง ให้เลือก ช่องทาง

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

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

   

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

หากต้องการเชื่อมต่อกับช่องทาง Azure Bot Service เรียนรู้เพิ่มเติมเกี่ยวกับ เผยแพร่ตัวแทนไปยังช่องทาง Azure Bot Service

การอ้างอิง

คําแนะนําในบทความนี้ใช้ข้อมูลอ้างอิงดังต่อไปนี้:

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

ดึงข้อมูลพารามิเตอร์เอเจนต์ Copilot Studio ของคุณ

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

1. Copilot Studio ไปที่หน้า Overview ของเจ้าหน้าที่ และคัดลอกชื่อของเจ้าหน้าที่

2. เลือก ช่องทาง>แอปสำหรับอุปกรณ์เคลื่อนที่

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

   

รับโทเค็น Direct Line

เพื่อเริ่มการสนทนากับเอเจนต์ของคุณ ให้รับโทเค็น Direct Line โดยส่งคําขอ GET ไปยังปลายทางโทเค็นที่คุณคัดลอกมาจาก Copilot Studio ปลายทางนี้คือปลายทางโทเค็น Copilot Studio ไม่ใช่ปลายทาง Direct Line tokens/generate ใช้โทเค็นที่คืนมาสําหรับคําขอ Direct Line ครั้งถัดไป

โทเค็น Direct Line ให้สิทธิ์เข้าถึงการสนทนา ไม่ใช่โทเค็นลงชื่อเข้าใช้ของผู้ใช้ปลายทาง อย่าใส่ซีเคร็ต Direct Line ในโค้ดเบราว์เซอร์หรือแอปมือถือ เรียนรู้เพิ่มเติมเกี่ยวกับการตรวจสอบสิทธิ์ Direct Line

GET <TokenEndpoint>

หากคำขอสำเร็จ ปลายทางจะส่งคืนโทเค็น อายุการใช้งานของโทเค็นเป็นวินาทีใน expires_in และ conversationId ใช้อายุการใช้งานที่ส่งคืนมาแทนที่จะสมมติว่ามีระยะเวลาหมดอายุที่ตายตัว

{
    "token": "<DirectLineToken>",
    "expires_in": 3600,
    "conversationId": "<ConversationId>"
}

รับตัวอย่างรหัสโทเค็น Direct Line

เพิ่มเมธอดและประเภทการตอบสนองต่อไปนี้ลงในคลาสแอปพลิเคชันของคุณ นําเข้า System.Net.Http.Json และ System.Text.Json.Serialization.

วิธีการนี้ยอมรับการจัดการ HttpClient โดยผู้โทรและโยนหากปลายทางส่งคืนโทเค็นที่ใช้งานได้ ข้อผิดพลาด HTTP และ JSON จะส่งไปยังผู้เรียก

public static async Task<DirectLineToken> GetTokenAsync(
    HttpClient httpClient, string tokenEndpoint)
{
    var response = await httpClient.GetFromJsonAsync<DirectLineToken>(
        tokenEndpoint);

    if (response is null || string.IsNullOrWhiteSpace(response.Token))
    {
        throw new InvalidOperationException(
            "The token endpoint returned no Direct Line token.");
    }

    return response;
}

public sealed class DirectLineToken
{
    [JsonPropertyName("token")]
    public string Token { get; set; } = string.Empty;

    [JsonPropertyName("expires_in")]
    public int ExpiresIn { get; set; }

    [JsonPropertyName("conversationId")]
    public string ConversationId { get; set; } = string.Empty;
}

ใช้ Direct Line เพื่อสื่อสารกับเอเจนต์

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

โค้ดต่อไปนี้อยู่ในเมธอดอะซิงโครนัสเดียวกันในคลาสแอปพลิเคชันที่มี GetTokenAsync. นําเข้า Microsoft.Bot.Connector.DirectLine และ System.Linq. แทนที่ <TokenEndpoint> และ <AgentName> ด้วยค่าของเอเจนต์ของคุณ และระบุตัวระบุผู้ใช้เฉพาะแอปแทน <UserId>.

1. รับโทเคน เริ่มต้น DirectLineClient และเริ่มบทสนทนา เก็บ client และ conversation ID ให้อยู่ในสโคปสําหรับการดําเนินการดังต่อไปนี้:

   using var httpClient = new HttpClient();
   var tokenResponse = await GetTokenAsync(httpClient, "<TokenEndpoint>");
   using var directLineClient = new DirectLineClient(tokenResponse.Token);
   
   var conversation =
       await directLineClient.Conversations.StartConversationAsync();
   string conversationId = conversation.ConversationId;
   string? watermark = null;
   string agentName = "<AgentName>";
   

2. ส่งข้อความไปยังบทสนทนานั้น:

   string inputMessage = "Hello";
   await directLineClient.Conversations.PostActivityAsync(
       conversationId,
       new Activity
       {
           Type = ActivityTypes.Message,
           From = new ChannelAccount { Id = "<UserId>" },
           Text = inputMessage,
           TextFormat = "plain"
       });
   

3. ดึงกิจกรรมโดยใช้ไคลเอนต์และรหัสการสนทนาเดียวกัน ผลลัพธ์สามารถประกอบด้วยทั้งกิจกรรมของผู้ใช้และเอเจนต์ ตัวอย่างนี้แสดงกิจกรรมข้อความจากชื่อเอเจนต์ที่กําหนดค่าไว้:

   var response = await directLineClient.Conversations.GetActivitiesAsync(
       conversationId, watermark);
   watermark = response.Watermark ?? watermark;
   
   foreach (var activity in response.Activities.Where(activity =>
       activity.Type == ActivityTypes.Message &&
       string.Equals(activity.From?.Name, agentName, StringComparison.Ordinal)))
   {
       Console.WriteLine(activity.Text);
   }
   

   ทําซ้ําการดําเนินการรับเพื่อเก็บกิจกรรมที่มาถึงในภายหลัง;คําขอเพียงครั้งเดียวอาจยังไม่มีการตอบกลับของตัวแทน ส่ง watermark ล่าสุดในแต่ละคำขอ และเก็บค่าก่อนหน้าไว้หากการตอบกลับไม่ได้ระบุค่า watermark นั้น เรียนรู้เพิ่มเติมได้ที่ รับกิจกรรมจากบอท

   ตัวกรองข้อความมีไว้สําหรับการแสดงผลเท่านั้น แอปของคุณต้องจัดการกิจกรรมประเภทอื่น ๆ รวมถึง เหตุการณ์ handoff แยกต่างหาก

รีเฟรชโทเค็น Direct Line

สําหรับการสนทนาที่ยาวนาน ให้รีเฟรชโทเค็นก่อนหมดอายุ โดยใช้ค่าที่คืนมา expires_in เพื่อวางแผนการรีเฟรช ไม่สามารถรีเฟรชโทเค็นที่หมดอายุได้ เรียนรู้เพิ่มเติมเกี่ยวกับการตรวจสอบสิทธิ์ Direct Line

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

var refreshedTokenResponse =
    await directLineClient.Tokens.RefreshTokenAsync();
using var refreshedClient = new DirectLineClient(refreshedTokenResponse.Token);

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

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

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

จัดการกระบวนการส่งต่อ

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

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

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