ขยายตัวแทนของคุณด้วยเครื่องมือจาก REST API (ตัวอย่าง)

Note

บทความนี้อธิบายคุณสมบัติที่ใช้ในเอเจนต์หรือการไหลของเอเจนต์ที่ขับเคลื่อนโดยฮาร์เนสมาตรฐาน

[บทความนี้เป็นเอกสารก่อนการนำออกใช้ และอาจเปลี่ยนแปลงได้]

ใช้ REST API (รวมถึง OpenAI API) เพื่อเชื่อมต่อเอเจนต์ที่คุณสร้างกับระบบภายนอกและเข้าถึงข้อมูลที่มีอยู่เพื่อใช้งานภายในเอเจนต์ของคุณ เชื่อมต่อเอเจนต์ของคุณกับ REST API โดยให้ Copilot Studio มีสามสิ่ง:

• ข้อกำหนด OpenAPI ที่กำหนดฟังก์ชันของ API และการดำเนินการที่มีอยู่
• รายละเอียดเกี่ยวกับประเภทของการรับรองความถูกต้องที่จำเป็นและรายละเอียดการรับรองความถูกต้องสำหรับผู้ใช้ในการเชื่อมต่อกับ API เพื่อเข้าถึงระบบภายนอก
• คำอธิบายเพื่อช่วยให้โมเดลภาษากำหนดว่าเมื่อใดควรเรียกใช้ API ที่จะใช้ข้อมูล

เพิ่ม REST API ให้กับ Copilot agent และ custom agent ผ่าน Copilot Studio

สำคัญ

บทความนี้มีเอกสารรุ่นพรีวิว Microsoft Copilot Studio และอาจจะมีการเปลี่ยนแปลงในอนาคต

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

หากคุณกำลังสร้างเอเจนต์ที่พร้อมสำหรับการใช้งานจริง โปรดดู ภาพรวมของ Microsoft Copilot Studio

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

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

Note

คุณต้องสร้างเครื่องมือ REST API จากข้อกําหนด OpenAPI v2 ข้อกําหนดนี้เกิดเนื่องจากลักษณะการทํางานของ Power Platform ในการประมวลผลข้อกําหนด API หากคุณส่งข้อมูลจําเพาะ v3 กระบวนการสร้างจะแปลเป็นข้อกําหนด v2 โดยอัตโนมัติ

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

• ข้อมูลประจําตัวระดับผู้สร้าง และสิทธิ์การใช้งาน Copilot Studio
• สําเนาของข้อกําหนด OpenAPI สําหรับ REST API ที่คุณต้องการเชื่อมต่อ
• ความรู้เกี่ยวกับประเภทของการรับรองความถูกต้องที่จําเป็นในการเชื่อมต่อกับ API และรายละเอียดการรับรองความถูกต้อง

เพิ่มเครื่องมือ REST API ให้กับตัวแทนของคุณ

เมื่อต้องเพิ่มเครื่องมือ REST API ไปยังตัวแทนของคุณ ทําตามขั้นตอนต่อไปนี้:

1. เพิ่มเครื่องมือตัวแทนใหม่และเลือก REST API
2. ระบุข้อมูลจําเพาะ คําอธิบาย และโซลูชัน API
3. ระบุรายละเอียดการรับรองความถูกต้อง
4. เลือกเครื่องมือจาก API
5. ตรวจสอบและเผยแพร่

ส่วนต่อไปนี้จะแนะนําคุณตลอดกระบวนการทีละขั้นตอน

กระบวนการเพิ่ม REST API จะเหมือนกันสําหรับทั้งตัวแทนแบบกําหนดเองและตัวแทน Microsoft 365 Copilot

เพิ่มเครื่องมือตัวแทนใหม่และเลือก REST API

1. ไปที่หน้า ภาพรวม ของตัวแทนของคุณ

2. ในส่วน เครื่องมือ เลือก เพิ่มเครื่องมือ คุณยังสามารถไปที่แท็บ เครื่องมือ และเลือก เพิ่มเครื่องมือ

   หน้า เพิ่มเครื่องมือ จะแสดงขึ้น

3. เลือกREST API>ใหม่

ระบุข้อมูลจําเพาะ คําอธิบาย และโซลูชัน API

1. อัปโหลดไฟล์ข้อมูลจำเพาะ OpenAPI สำหรับ REST API ที่คุณต้องการเชื่อมต่อ คุณสามารถลากและวางไฟล์สเปคลงในหน้าจอ อัปโหลด REST API หรือเรียกใช้งานในระบบเพื่อค้นหาไฟล์ที่ต้องการใช้

   

   Note

   ข้อมูลจำเพาะ OpenAPI ต้องเป็นไฟล์ JSON ในรูปแบบ v2 หากคุณส่งข้อมูลจําเพาะ v3 กระบวนการสร้างจะแปลเป็นข้อกําหนด v2 โดยอัตโนมัติ

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

   

   ในขั้นตอนต่อไปนี้ ขั้นตอนนี้ใช้ตัวอย่างเฉพาะของ SunnyADO ซึ่งเป็นระบบการจัดการตั๋ว ADO ในตัวอย่างนี้ จุดประสงค์คือเพื่อให้ผู้ใช้สามารถดึงและอัปเดตตั๋วของตนผ่านตัวแทน

2. ตรวจสอบรายละเอียด จากนั้นเลือก ถัดไป

   คุณจะเห็น หน้ารายละเอียดปลั๊กอิน API ที่คุณสามารถให้ข้อมูลเพิ่มเติมเกี่ยวกับ API ได้

   

   เริ่มต้นเขตข้อมูลคําอธิบายจะถูกสร้างขึ้นตามคําอธิบายในข้อมูลจําเพาะของ API ที่คุณอัปโหลด ระบุคำอธิบายโดยละเอียด เนื่องจากการจัดการตัวแทนของคุณจะใช้คำอธิบายนี้เพื่อตัดสินใจว่าเมื่อใดควรใช้เครื่องมือเฉพาะ ระบุรายละเอียด รวมถึงคำพ้องความหมาย เพื่อช่วยเอเจนต์ของคุณในกระบวนการคัดเลือก

   ตัวอย่างเช่น คำอธิบายเบื้องต้นที่ให้ไว้คือ: "บริการง่ายๆ ในการจัดการตั๋ว"

   คำอธิบายที่ดีกว่าคือ: "ระบบที่ใช้ในการรับ ดึง ค้นหา และแสดงตั๋วที่มีอยู่จาก SunnyADO ซึ่งช่วยให้ผู้ใช้สามารถอัปเดต เปลี่ยนแปลง และจัดการตั๋วเพื่อให้ข้อมูลเพิ่มเติมเพื่อปรับปรุงบันทึกข้อมูล"

3. ป้อนคำอธิบายที่ได้รับการปรับปรุงภายใต้ฟิลด์ คำอธิบาย

4. ภายใต้ โซลูชัน เมนูดรอปดาวน์แสดงรายการโซลูชันทั้งหมดที่มีอยู่ในสภาพแวดล้อมปัจจุบัน เลือกโซลูชันที่คุณต้องการใช้ เรียนรู้เพิ่มเติมเกี่ยวกับโซลูชันใน แนวคิดโซลูชัน

   หากคุณมีโซลูชันที่ต้องการหรือตัวเชื่อมต่อที่คุณเลือกอยู่ในโซลูชันอยู่แล้ว โซลูชันนั้นจะถูกเลือกโดยอัตโนมัติ

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

   Note

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

5. เมื่อเลือกโซลูชันแล้ว ให้เลือก ถัดไป เพื่อดำเนินการต่อ

ระบุรายละเอียดการรับรองความถูกต้อง

หน้า การรับรองความถูกต้อง จะปรากฏขึ้น เลือกชนิดของการรับรองความถูกต้องที่จะใช้สําหรับ API

1. เลือกวิธีการรับรองความถูกต้องจากรายการ มีตัวเลือกอยู่สามตัวเลือกคือ

   • ไม่มี: ไม่จําเป็นต้องตรวจสอบสิทธิ์เพื่อเข้าถึง API
   • คีย์ API: เลือกตัวเลือกนี้หาก API ของคุณต้องใช้คีย์ API สําหรับการตรวจสอบสิทธิ์ เมื่อเรียกใช้ เมื่อเอเจนต์ต้องการใช้เครื่องมือ API เอเจนต์จะแจ้งให้ผู้ใช้ตรวจสอบสิทธิ์ ผู้ใช้ให้คีย์ API และเอเจนต์เชื่อมต่อกับ API โดยใช้คีย์นั้น
   • การตรวจสอบสิทธิ์ 2.0: เลือกตัวเลือกนี้หากเซิร์ฟเวอร์ MCP ใช้ OAuth 2.0 ในการตรวจสอบสิทธิ์ OAuth 2.0 ช่วยให้ผู้ใช้แต่ละรายตรวจสอบสิทธิ์กับ API ผ่านผู้ให้บริการข้อมูลประจําตัวได้ วิธีการรับรองความถูกต้องนี้ช่วยให้ผู้ใช้ให้สิทธิ์แอปพลิเคชันของคุณ (ตัวแทน) โดยไม่ต้องแชร์ข้อมูลประจําตัวของพวกเขากับตัวแทน

2. ป้อนฟิลด์ที่จําเป็นสําหรับวิธีการรับรองความถูกต้องที่เลือก ฟิลด์จะแตกต่างกันไปตามวิธีการรับรองความถูกต้อง

   • ไม่มี: ไม่มีข้อมูลที่จะให้
   • คีย์ API:
     • ป้ายกํากับพารามิเตอร์: ป้ายกํากับข้อความสําหรับพารามิเตอร์ API เพื่อแสดงต่อผู้ใช้
     • ชื่อพารามิเตอร์: ชื่อจริงสําหรับพารามิเตอร์คีย์ API ที่จะใช้ในส่วนหัวหรือสตริงข้อความค้นหา
     • ตําแหน่งพารามิเตอร์: วิธีที่คุณส่งคีย์สําหรับ API เลือก ส่วนหัว หรือ คิวรี
   • การรับรองความถูกต้อง 2.0:
     • ID ไคลเอ็นต์: ตัวระบุไคลเอ็นต์ที่ออกโดยตัวให้บริการข้อมูลประจําตัวเมื่อคุณลงทะเบียนแอปพลิเคชันของคุณ ID ไคลเอ็นต์ช่วยให้ผู้ให้บริการข้อมูลประจําตัวทราบว่าแอปใดที่กําลังร้องขอ
     • ความลับของไคลเอ็นต์: ข้อมูลลับไคลเอ็นต์ของผู้ให้บริการข้อมูลประจําตัวเมื่อคุณลงทะเบียนแอปของคุณ ตัวแทนของคุณส่งความลับของไคลเอ็นต์พร้อมกับ ID ไคลเอ็นต์เพื่อพิสูจน์ว่าตัวแทนของคุณได้รับอนุญาตให้ร้องขอโทเค็นการเข้าถึงสําหรับเซิร์ฟเวอร์ MCP
     • URL การอนุญาต: จุดสิ้นสุดของผู้ให้บริการข้อมูลประจําตัวที่ตัวแทนของคุณเปลี่ยนเส้นทางผู้ใช้เพื่อลงชื่อเข้าใช้ และให้สิทธิ์แก่ตัวแทนของคุณ (บัตรความยินยอมที่แสดงในการสนทนาตัวแทน) ผู้ใช้รับรองความถูกต้องที่นี่ แล้วตัวให้บริการข้อมูลประจําตัวตอบกลับไปยังตัวแทนที่ URL การเรียกกลับด้วยรหัสการให้สิทธิ์
     • URL โทเค็น: จุดสิ้นสุดที่ตัวแทนของคุณแลกเปลี่ยนรหัสการให้สิทธิ์ (หรือโทเค็นการรีเฟรช) เป็นโทเค็นการเข้าถึงและโทเค็นการรีเฟรช โทเค็นการเข้าถึงอนุญาตให้ตัวแทนของคุณใช้เซิร์ฟเวอร์ MCP ในนามของผู้ใช้ โทเค็นรีเฟรชช่วยให้เจ้าหน้าที่ของคุณได้รับโทเค็นการเข้าถึงและการรีเฟรชใหม่จากจุดสิ้นสุดการรีเฟรชเมื่อโทเค็นการเข้าถึงก่อนหน้านี้หมดอายุ
     • URL รีเฟรช: จุดสิ้นสุดเพื่อร้องขอโทเค็นการเข้าถึงใหม่โดยใช้โทเค็นรีเฟรช (เพื่อให้ผู้ใช้ไม่ต้องลงชื่อเข้าใช้อีกครั้งเมื่อโทเค็นหมดอายุ)
     • ขอบเขต: (ไม่บังคับ): สิทธิ์ที่แอปของคุณขอเป็นรายการที่คั่นด้วยช่องว่าง
     • องค์กรใดของ Microsoft 365 ที่เข้าถึงจุดสิ้นสุด: การตั้งค่านี้จะจำกัดการเข้าถึงแหล่งข้อมูลไปยังองค์กรของผู้พัฒนา หรือองค์กรทั้งหมด เลือกอย่างใดอย่างหนึ่งต่อไปนี้
       • องค์กรของฉันเท่านั้น
       • องค์กร Microsoft 365 ใด ๆ
     • แอป (ไคลเอ็นต์) ใดที่สามารถใช้ปลายทาง: GUID ที่กําหนดระบบไคลเอ็นต์ที่สามารถใช้เพื่อเข้าถึงข้อมูลนี้ แอปอาจรวมถึง Microsoft 365 Power Automate และตัวเลือกอื่น ๆ

3. เมื่อคุณกรอกข้อมูลในเขตข้อมูลทั้งหมดแล้ว ให้เลือก ถัดไป

   หน้า เลือกและกําหนดค่าเครื่องมือของคุณ จะปรากฏขึ้น ซึ่งคุณสามารถเลือกเครื่องมือเพื่อเปิดใช้งานจาก API

   

เลือกเครื่องมือจาก API

เลือกเครื่องมือที่รองรับ API จาก REST API เพื่อเพิ่มไปยังตัวแทนของคุณ โดยทั่วไป REST API มีเครื่องมือมากมายผ่านการผสมผสานระหว่างวิธีการปลายทางและ HTTP (รับ ใส่ โพสต์ ลบ และอื่นๆ) ที่กําหนดไว้ในข้อกําหนด API ในบางกรณี คุณอาจไม่ต้องการให้ผู้ใช้ของเอเจนต์มีความสามารถในการดำเนินการ ทุกอย่าง ที่ API เสนอให้โดยทั่วไป ตัวอย่างเช่น ข้อมูลจําเพาะ API ของคุณอาจมีความสามารถในการอัปเดตและลบ แต่คุณต้องการให้ผู้ใช้ของตัวแทนสามารถสร้างระเบียนได้

1. เลือกเครื่องมือจากรายการเพื่อกําหนดค่า

   หน้า การกําหนดค่าเครื่องมือของคุณ จะแสดงขึ้น

   

2. กําหนดค่าชื่อและคําอธิบายสําหรับเครื่องมือที่เลือก คล้ายกับ API โดยรวม ให้ใส่ ชื่อเครื่องมือ และ คําอธิบายเครื่องมือ คำอธิบายจะถูกเติมไว้ล่วงหน้าในขั้นต้นจากคำอธิบายในข้อกำหนด API ชื่อไม่จําเป็นต้องไม่ซ้ํากัน แต่ควรแสดงเครื่องมือเอง คําอธิบาย เช่นเดียวกับคําอธิบาย API โดยรวม ควรมีความเฉพาะเจาะจงเพียงพอที่จะให้รายละเอียดแก่โมเดลภาษาเพื่อระบุได้ดีขึ้นว่าคิวรีของคุณสอดคล้องกับเครื่องมือเฉพาะนี้หรือไม่

3. เมื่อกรอกข้อมูลในฟิลด์แล้ว ให้เลือก ถัดไป

   หน้า ตรวจสอบพารามิเตอร์ของเครื่องมือคุณ จะแสดงขึ้น

   

   หน้านี้แสดงค่าที่คาดไว้สําหรับอินพุตและค่าเอาต์พุตที่ส่งคืน คุณไม่สามารถเปลี่ยนค่าเหล่านี้ แต่คุณสามารถอัปเดตคําอธิบายของอินพุตและเอาต์พุตได้ เนื้อหาทั้งหมดในหน้านี้ดึงมาจากข้อกำหนด API ที่อัปโหลดโดยตรง

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

5. หลังจากที่คุณกรอกคําอธิบายเสร็จแล้ว ให้เลือก ถัดไป

   เครื่องมือแรกจะได้รับการกําหนดค่าและปรากฏในรายการของเครื่องมือที่เลือกบนหน้าเลือกและกําหนดค่าเครื่องมือปลั๊กอินของคุณ

   

6. เพิ่มเครื่องมืออื่นๆ จาก API ที่คุณต้องการรวมในขณะนี้ เมื่อคุณเพิ่มเครื่องมือที่คุณต้องการให้เจ้าหน้าที่ของคุณสนับสนุนเสร็จแล้ว ให้เลือก ถัดไป

   หน้า ตรวจสอบเครื่องมือของคุณ จะแสดงขึ้น หน้าจะมีรายละเอียดของเครื่องมือ REST API ที่กําหนดค่าไว้

   

ตรวจสอบและเผยแพร่

1. ถ้าคุณจําเป็นต้องทําการปรับปรุงใดๆ ให้เลือก ย้อนกลับ และทําการเปลี่ยนแปลงของคุณ มิฉะนั้น เลือก ถัดไป

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

2. เลือก สร้างการเชื่อมต่อ เพื่อดําเนินการต่อ คุณจะถูกกลับไปที่หน้าจอเพิ่มเครื่องมือ

3. เลือก REST API ในตัวเลือกประเภทเครื่องมือ คุณสามารถดูเครื่องมือที่สร้างขึ้นใหม่ได้จาก API ของคุณ ควรมี 1 รายการต่อเครื่องมือที่คุณเพิ่มจาก API

4. สําหรับแต่ละเครื่องมือที่กําหนดค่าใหม่จาก API ให้สร้างหรือเลือกการเชื่อมต่อกับ API และเพิ่มเครื่องมือไปยังตัวแทนของคุณ:

   1. บนหน้าจอ เพิ่มเครื่องมือ ให้เลือกเครื่องมือ
   2. ภายใต้ การเชื่อมต่อ ให้เลือกการเชื่อมต่อที่มีอยู่ หรือเลือก สร้างการเชื่อมต่อใหม่
   3. ใส่ข้อมูลใดๆ ที่จําเป็นสําหรับการเชื่อมต่อ จากนั้นเลือก สร้าง เพื่อสร้างการเชื่อมต่อไปยังเครื่องมือ
   4. เลือก เพิ่ม และกําหนดค่า เพื่อเพิ่มเครื่องมือให้กับตัวแทนของคุณ

   

เครื่องมือจาก REST API พร้อมใช้งานในเอเจนต์ของคุณแล้ว

Tip

หากต้องการค้นหาเครื่องมือของคุณได้ง่ายขึ้น ให้ใช้แถบค้นหาเพื่อค้นหา