ตั้งค่าพิมพ์เขียวเอเจนต์

แบบพิมพ์เขียวของเอเจนต์กำหนดข้อมูลประจำตัว สิทธิ์ และข้อกำหนดด้านโครงสร้างพื้นฐานของเอเจนต์ของคุณ สร้างอินสแตนซ์เอเจนต์ทั้งหมดจากแบบพิมพ์เขียวของเอเจนต์นี้

หมายเหตุ

การตั้งค่าแบบพิมพ์เขียวของเอเจนต์เป็นสิ่งจำเป็นเพื่อเปิดใช้งานความสามารถ ลงทะเบียน, Work IQ และเพื่อนร่วมทีม AI ดู เริ่มต้นใช้งานการพัฒนา Agent 365 เพื่อทําความเข้าใจว่าความสามารถใดบ้างที่ใช้ได้กับเอเจนต์ของคุณ

สำหรับข้อมูลเพิ่มเติมเกี่ยวกับข้อมูลประจำตัวของ Agent 365 โปรดดู ข้อมูลประจำตัวของ Agent 365

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

ก่อนที่คุณจะเริ่มต้น ตรวจสอบว่าคุณมีคุณสมบัติตรงตามข้อกำหนดเบื้องต้นต่อไปนี้:

1. Agent 365 CLI - โปรดดู การติดตั้ง Agent 365 CLI

2. สิทธิ์ที่จำเป็น:

   • ผู้ใช้ในผู้เช่าที่ถูกต้องที่มีบทบาทอย่างใดอย่างหนึ่งต่อไปนี้:
     • ผู้ดูแลระบบ Global
     • นักพัฒนารหัสเอเจนต์
   • เข้าถึงการสมัครใช้งาน Azure ที่มีสิทธิ์ในการสร้างทรัพยากร

   เคล็ดลับ

   เอเจนต์ (ไม่ใช่เพื่อนร่วมทีม AI) ไม่จำเป็นต้องมีไฟล์กำหนดค่า ใช้ a365 setup all --agent-name <name> และ CLI จะระบุผู้เช่าและแอปไคลเอ็นต์ของคุณโดยอัตโนมัติ การตั้งค่าเพื่อนร่วมทีม AI ต้องการ a365.config.json ที่สร้างด้วยตนเอง

สร้างแบบพิมพ์เขียวของเอเจนต์

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

ดำเนินการตั้งค่า

เรียกใช้คำสั่งการตั้งค่า:

a365 setup -h

คำสั่งมีตัวเลือกหลากหลาย คุณสามารถดำเนินการตั้งค่าทั้งหมดได้ในคำสั่งเดียวโดยใช้ a365 setup all หรือเลือกตัวเลือกแบบละเอียด

หมายเหตุ

a365 setup all ค่าเริ่มต้นเป็นโหมดเอเจนต์ของแบบพิมพ์เขียว หากต้องการตั้งค่าเอเจนต์เพื่อนร่วมทีม AI แทน ให้ส่งผ่าน --aiteammate สำหรับเอเจนต์ M365 (Teams, Copilot) ให้ส่งผ่าน --m365 เพื่อลงทะเบียนจุดเชื่อมต่อการส่งข้อความโดยอัตโนมัติ

การตั้งค่าเอเจนต์ (ค่าเริ่มต้น):

# With a config file
a365 setup all

# Config-free — no a365.config.json needed
a365 setup all --agent-name <your-agent-name>

การตั้งค่าเอเจนต์ M365 (Teams/Copilot):

# Registers the messaging endpoint via MCP Platform
a365 setup all --m365

การตั้งค่าเพื่อนร่วมทีม AI:

a365 setup all --aiteammate

กระบวนการตั้งค่าทั้งหมดจะดําเนินการเหล่านี้:

1. สร้างโครงสร้างพื้นฐาน Azure (ถ้ายังไม่มี):

   • กลุ่มทรัพยากร
   • แผนบริการแอปที่มี SKU ที่ระบุ
   • Azure Web App ที่เปิดใช้งานข้อมูลประจำตัวที่มีการจัดการ

2. ลงทะเบียนแบบพิมพ์เขียวของเอเจนต์:

   • สร้างแบบพิมพ์เขียวของเอเจนต์ในผู้เช่า Microsoft Entra ของคุณ
   • สร้างการลงทะเบียนแอปพลิเคชัน Microsoft Entra
   • กําหนดค่าข้อมูลประจําตัวของเอเจนต์ด้วยสิทธิ์ที่จําเป็น
   • ตั้งค่า managerApplications บนแบบพิมพ์เขียว ซึ่งจําเป็นสําหรับความสามารถในการจัดการแพลตฟอร์ม

   สำคัญ

   แบบพิมพ์เขียวต้องมี managerApplications ตั้งค่าเป็นยอมรับโดยแพลตฟอร์ม CLI ตั้งค่านี้โดยอัตโนมัติ หากคุณมีแบบพิมพ์เขียวที่สร้างขึ้นก่อนที่ข้อกำหนดนี้จะถูกนำมาใช้ ให้ลบออกแล้วเรียกใช้ a365 setup all อีกครั้ง หรือแก้ไขด้วยตนเองผ่าน Graph API

3. กำหนดค่าสิทธิ์ API:

   • ตั้งค่าขอบเขต Microsoft Graph API
   • กำหนดค่าสิทธิ์ API ของบอทส่งข้อความ
   • กำหนดสิทธิ์ที่สามารถสืบทอดได้สำหรับอินสแตนซ์ของเอเจนต์

4. อัปเดตไฟล์การกำหนดค่า:

   • บันทึกรหัสที่สร้างขึ้นและจุดเชื่อมต่อลงในไฟล์ใหม่ในไดเรกทอรีการทำงานของคุณที่ชื่อว่า a365.generated.config.json
   • บันทึกข้อมูลประจำตัวที่ได้รับการจัดการและข้อมูลทรัพยากร

หมายเหตุ

โดยทั่วไป การตั้งค่าจะใช้เวลา 3-5 นาที และบันทึกการกำหนดค่าอัตโนมัติเป็น a365.generated.config.json หากคุณใช้งานในฐานะผู้ดูแลระบบส่วนกลาง CLI อาจเปิดหน้าต่างเบราว์เซอร์เพื่อขอความยินยอมจากผู้ดูแลระบบ - โปรดดำเนินขั้นตอนการให้ความยินยอมเพื่อดำเนินการต่อ หากคุณใช้งานในฐานะนักพัฒนารหัสเอเจนต์ จะไม่มีหน้าต่างเบราว์เซอร์ปรากฏขึ้น; CLI จะสร้าง URL สำหรับการขอความยินยอมให้ผู้ดูแลระบบส่วนกลางดำเนินการในภายหลัง

การตั้งค่าโดยใช้นักพัฒนารหัสเอเจนต์

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

ขั้นตอนที่ดำเนินการโดยอัตโนมัติ:

• โครงสร้างพื้นฐาน Azure (กลุ่มทรัพยากร, แผนบริการแอป, เว็บแอป)
• การลงทะเบียนแบบพิมพ์เขียวของเอเจนต์
• สิทธิ์ที่สืบทอดได้สำหรับอินสแตนซ์ของเอเจนต์

ขั้นตอนใดบ้างที่ต้องการผู้ดูแลระบบส่วนกลาง:

• การให้สิทธิ์ที่ได้รับมอบหมาย OAuth2 (ความยินยอม AllPrincipals) สำหรับ Microsoft Graph, เครื่องมือ Agent 365, API บอทส่งข้อความ, API การเฝ้าสังเกต และ Power Platform API

วิธีตั้งค่าให้เสร็จสมบูรณ์โดยใช้บัญชีที่ไม่ใช่ผู้ดูแลระบบ:

ขั้นตอน	ใคร	การดำเนินการ
1	นักพัฒนา	รัน a365 setup all CLI ทําตามขั้นตอนทั้งหมดที่ทําได้และพิมพ์ขั้นตอนถัดไป รวมถึง URL ความยินยอมสําหรับผู้ดูแลระบบส่วนกลางเพื่อเปิด
2	นักพัฒนา	แชร์ URL สำหรับการยินยอมที่ได้จากผลลัพธ์ของ CLI กับผู้ดูแลระบบส่วนกลางของคุณ
3	ผู้ดูแลระบบส่วนกลาง	เปิด URL ความยินยอมในเบราว์เซอร์ที่ลงชื่อเข้าใช้ในฐานะผู้ดูแลระบบส่วนกลาง และให้สิทธิ์ที่ร้องขอ

การเรียกใช้คำสั่ง:

# Developer runs:
a365 setup all
# Setup completes all steps it can. The CLI prints the next steps
# for a Global Administrator directly in the output, including a
# direct link or consent URL they can open to complete the grants.

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

ตรวจสอบการตั้งค่า

เมื่อการตั้งค่าเสร็จสิ้น คุณจะเห็นสรุปขั้นตอนที่ดำเนินการเสร็จสิ้นทั้งหมด ตรวจสอบทรัพยากรที่สร้างขึ้น:

1. ตรวจสอบการกําหนดค่าที่สร้างขึ้น:

   เปิด a365.generated.config.json ในไดเรกทอรีการทํางานของคุณ หรือใช้ PowerShell:

   Get-Content a365.generated.config.json | ConvertFrom-Json
   

   ผลลัพธ์ที่คาดหวังประกอบด้วยค่าที่สำคัญเหล่านี้:

   {
   "managedIdentityPrincipalId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
   "agentBlueprintId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
   "agentBlueprintObjectId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
   "agentBlueprintServicePrincipalObjectId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
   "agentBlueprintClientSecret": "xxx~xxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
   "agentBlueprintClientSecretProtected": true,
   "botId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
   "botMsaAppId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
   "messagingEndpoint": "https://your-app.azurewebsites.net/api/messages",
   "resourceConsents": [],
   "completed": true,
   "completedAt": "xxxx-xx-xxTxx:xx:xxZ",
   "cliVersion": "x.x.xx"
   }
   

   ฟิลด์สำคัญที่ต้องตรวจสอบ:

   ฟิลด์	วัตถุประสงค์	สิ่งที่ต้องตรวจสอบ
   managedIdentityPrincipalId	การรับรองความถูกต้องข้อมูลประจำตัวที่มีการจัดการใน Azure	ควรเป็น GUID ที่ถูกต้อง
   agentBlueprintId	รหัสเฉพาะของเอเจนต์ของคุณ	ใช้ในพอร์ทัลนักพัฒนาและศูนย์การจัดการ
   agentBlueprintObjectId	Microsoft Entra ID ของแบบพิมพ์เขียว
   messagingEndpoint	การกำหนดเส้นทางข้อความ	ปลายทางที่ Teams/Outlook ส่งข้อความถึงเอเจนต์ของคุณ
   agentBlueprintClientSecret	ข้อมูลลับการรับรองความถูกต้อง	ควรมีอยู่ (ค่าถูกปิดบัง)
   resourceConsents	สิทธิ์ API	ควรมีทรัพยากร เช่น Microsoft Graph, เครื่องมือ Agent 365, API บอทส่งข้อความ, API การเฝ้าสังเกต
   completed	สถานะการตั้งค่า	ควรเป็น true

   หมายเหตุ

   หากคุณดำเนินการตั้งค่าในฐานะผู้ดูแลระบบรหัสเอเจนต์หรือนักพัฒนารหัสเอเจนต์ resourceConsents อาจว่างเปล่า และ completed อาจเป็น false จนกว่าผู้ดูแลระบบส่วนกลางจะดำเนินการให้สิทธิ์ OAuth2 ตามขั้นตอนถัดไปที่ CLI แสดง

2. ตรวจสอบทรัพยากร Azure ใน พอร์ทัล Azure:

   หรือใช้คำสั่ง az resource list PowerShell

   # List all resources in your resource group
   az resource list --resource-group <your-resource-group> --output table
   

   ตรวจสอบว่ามีการสร้างทรัพยากรต่อไปนี้:

   • กลุ่มทรัพยากร:

     • ไปที่ กลุ่มทรัพยากร> เลือกกลุ่มทรัพยากรของคุณ
     • ตรวจสอบว่าในกลุ่มทรัพยากรของคุณมีแผนบริการแอปและเว็บแอปของคุณ

   • แผนบริการแอป:

     • ไปที่ บริการแอป>แผนบริการแอป
     • ค้นหาแผนของคุณและตรวจสอบว่าระดับราคาตรงกับ SKU ของการกำหนดค่าของคุณ

   • เว็บแอป:

     • ไปที่ บริการแอป>เว็บแอป
     • ค้นหาเว็บแอปของคุณ จากนั้นไปที่ การตั้งค่า>ข้อมูลประจำตัว>กำหนดโดยระบบ
     • สถานะยืนยันเป็น เปิด
     • โปรดทราบว่า รหัสออบเจ็กต์ (บริการหลัก) ตรงกับ managedIdentityPrincipalId

3. ตรวจสอบแอปพลิเคชัน Microsoft Entra ใน พอร์ทัล Azure:

   ไปที่ Azure Active Directory>การลงทะเบียนแอป>แอปพลิเคชันทั้งหมด:

   • ค้นหาแบบพิมพ์เขียวของเอเจนต์ของคุณตาม agentBlueprintId

   • เปิดแอปพลิเคชันและเลือก สิทธิ์ API

   • ตรวจสอบว่าสิทธิ์ได้รับการอนุมัติแล้วโดยมีเครื่องหมายถูกสีเขียว:

     • สิทธิ์ Microsoft Graph (แบบมอบหมายและแบบแอปพลิเคชัน)
     • สิทธิ์ API บอทส่งข้อความ

   • สิทธิ์ทั้งหมดแสดงเป็น "ได้รับการอนุญาตสำหรับ [ผู้เช่าของคุณ]"

4. ตรวจสอบไฟล์การกำหนดค่าที่สร้างขึ้น:

   คุณควรมีไฟล์ชื่อ a365.generated.config.json ที่มีข้อมูลการกำหนดค่าทั้งหมด

   ใช้คำสั่ง Test-Path ใน PowerShell เพื่อตรวจสอบว่าไฟล์นั้นมีอยู่หรือไม่

   # Check file exists
   Test-Path a365.generated.config.json
   # Should return: True
   

   สำคัญ

   บันทึกทั้งไฟล์ a365.config.json และ a365.generated.config.json คุณต้องใช้ค่าเหล่านี้สำหรับการปรับใช้งานและการแก้ไขปัญหา

5. ตรวจสอบว่าเว็บแอปเปิดใช้งานข้อมูลประจําตัวที่มีการจัดการ:

   ใช้คำสั่ง az webapp identity show เพื่อตรวจสอบว่าข้อมูลที่มีการจัดการถูกเปิดใช้งานหรือไม่

   az webapp identity show --name <your-web-app> --resource-group <your-resource-group>
   

   สิ่งที่คาดไว้:

   {
   "principalId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
   "tenantId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
   "type": "SystemAssigned"
   }
   

6. ตรวจสอบว่าแบบพิมพ์เขียวของเอเจนต์ได้ถูกลงทะเบียนใน Microsoft Entra แล้ว:

   ไปที่ ศูนย์การจัดการ Microsoft Entra แล้วค้นหา agentBlueprintId หรือค้นหาตามชื่อ

   ตรวจสอบว่า:

   ✅ การลงทะเบียนแอปและแอปพลิเคชันองค์กรจะปรากฏขึ้น
   ✅ ในแบบพิมพ์เขียวการลงทะเบียนแอป แท็บ สิทธิ์ API จะแสดงสิทธิ์ทั้งหมด
   ✅ สถานะแสดง "ให้สิทธิ์กับ [ผู้เช่าของคุณ]"

สำหรับความช่วยเหลือเพิ่มเติม โปรดดู:

• ปัญหาแอปไคลเอ็นต์แบบกำหนดเอง

สิทธิ์ของเอเจนต์

ก่อนที่แอปและเอเจนต์จะสามารถอ่านหรือเขียนข้อมูล Microsoft 365 (ผู้ใช้, อีเมล, ไฟล์, Teams, เอเจนต์ ฯลฯ) คุณต้องให้สิทธิ์ Microsoft Graph อย่างชัดเจนแก่พวกเขา สิทธิ์ของ Microsoft Graph คือรูปแบบการอนุญาตที่ควบคุมว่าข้อมูลและการดำเนินการใดที่แอปหรือบริการสามารถเข้าถึงผ่าน Microsoft Graph API ทั่วทั้ง Microsoft 365 และ Microsoft Entra ID ได้

เรียนรู้เพิ่มเติม: ภาพรวมของสิทธิ์ Microsoft Graph

หากต้องการใช้สิทธิ์ Graph สําหรับอินสแตนซ์เอเจนต์ Agent 365 นักพัฒนาต้องประกาศในแบบพิมพ์เขียวของเอเจนต์ เมื่อผู้ดูแลระบบเปิดใช้งานแบบพิมพ์เขียวในศูนย์การจัดการ Microsoft 365 พอร์ทัลจะตรวจสอบสิทธิ์ของ Microsoft Graph ในแบบพิมพ์เขียว และขอความยินยอมจากผู้ดูแลระบบ

หากต้องการทำความเข้าใจและตรวจสอบว่าสิทธิ์ของ Graph มีผลต่อการทำงานของเอเจนต์ของคุณอย่างไร คุณสามารถ:

• ดู สิทธิ์ของ Graph ทั้งหมดที่มีให้ใช้งาน
• ไปที่ ตัวสำรวจ Graph เพื่อลองส่งคำค้นหา, ตรวจสอบการตอบกลับ, และทำความเข้าใจสิทธิ์
• ใช้ Microsoft 365 Agents Playground เพื่อทดสอบเอเจนต์ของคุณในสภาพแวดล้อมภายในเครื่องก่อนการปรับใช้งาน

กำหนดสิทธิ์ให้กับแบบพิมพ์เขียวของคุณ

ใช้ a365 setup permissions custom เพื่อใช้สิทธิ์ API แบบกําหนดเองให้สอดคล้องกับแบบพิมพ์เขียวของคุณใน Microsoft Entra

a365 setup permissions custom `
  --resource-app-id 00000003-0000-0000-c000-000000000000 `
  --scopes Mail.Read,Mail.Send,Chat.Read,Chat.ReadWrite,Chat.Create,User.Read

สําหรับรายละเอียดทั้งหมดเกี่ยวกับการกําหนดค่าและการลบสิทธิ์ที่กําหนดเอง โปรดดู setup permissions custom

ขั้นตอนถัดไป

ปรับใช้โค้ดเอเจนต์ของคุณไปยังระบบคลาวด์:

Azure

Amazon Web Services (AWS)

Google Cloud Platform (GCP)

เผยแพร่เอเจนต์ไปยังศูนย์การจัดการ Microsoft

กำลังแก้ไขปัญหา

ส่วนนี้อธิบายปัญหาทั่วไปเมื่อตั้งค่าแบบพิมพ์เขียวของเอเจนต์

เคล็ดลับ

คู่มือการแก้ไขปัญหา Agent 365 ประกอบด้วยคำแนะนำการแก้ไขปัญหาระดับสูง แนวทางปฏิบัติที่ดีที่สุด และลิงก์ไปยังเนื้อหาการแก้ไขปัญหาสำหรับแต่ละส่วนของวงจรการพัฒนา Agent 365

ปัญหาเหล่านี้บางครั้งเกิดขึ้นระหว่างการลงทะเบียน:

• ข้อผิดพลาดสิทธิ์ไม่เพียงพอ
• ไม่มีการรับรองความถูกต้องของ Azure CLI
• มีทรัพยากรอยู่แล้ว
• การให้ความยินยอมของผู้ดูแลระบบยังไม่เสร็จสมบูรณ์
• ไฟล์การกำหนดค่าไม่มีอยู่หรือไม่ถูกต้อง
• การตั้งค่าเสร็จสมบูรณ์ แต่ยังไม่ได้สร้างทรัพยากร:
• แบบพิมพ์เขียวของเอเจนต์ยังไม่ได้ลงทะเบียนใน Microsoft Entra
• ไม่ได้สิทธิ์ API
• ไม่ได้เปิดใช้งานข้อมูลประจำตัวที่มีการจัดการ
• การตั้งค่าใช้เวลานานผิดปกติหรือหยุดตอบสนอง
• ล้างเอเจนต์ที่ไม่มีการกำหนดค่า
• ไม่สามารถส่งข้อความแรกใน Teams ได้

ข้อผิดพลาดสิทธิ์ไม่เพียงพอ

อาการ: ข้อผิดพลาดสิทธิ์ไม่เพียงพอในระหว่างการเรียกใช้a365 setup คำสั่ง

คุณต้องมีบทบาทอย่างใดอย่างหนึ่งต่อไปนี้ในผู้เช่า Microsoft Entra ของคุณ:

• ผู้ดูแลระบบ Global
• นักพัฒนารหัสเอเจนต์

และสิทธิ์เข้าถึงในฐานะผู้สนับสนุนหรือเจ้าของการสมัครใช้งาน Azure

การแก้ไขปัญหา: ตรวจสอบว่าคุณมีสิทธิ์ที่จำเป็นใน Microsoft Entra

• ไปที่: ศูนย์การจัดการ Microsoft Entra> โปรไฟล์ของคุณ > บทบาทที่ได้รับมอบหมาย
• ตรวจสอบการเข้าถึงการสมัครใช้งาน Azure โดยใช้คำสั่ง az account show ใน PowerShell

หมายเหตุ

หากคุณมีบทบาทผู้ดูแลระบบรหัสเอเจนต์หรือนักพัฒนารหัสเอเจนต์ (ไม่ใช่ผู้ดูแลระบบส่วนกลาง) a365 setup all จะยังคงทำงานสําเร็จแต่ข้ามการให้สิทธิ์ OAuth2 หลังจากการตั้งค่าเสร็จสิ้น CLI จะพิมพ์ขั้นตอนถัดไปสําหรับผู้ดูแลระบบส่วนกลางเพื่อดําเนินการให้สิทธิ์ที่เหลือเสร็จสมบูรณ์ เวิร์กโฟลว์นี้คาดว่าจะใช้สําหรับองค์กรที่นักพัฒนาเอเจนต์และผู้ดูแลระบบส่วนกลางเป็นคนละคนกัน

ไม่มีการรับรองความถูกต้องของ Azure CLI

อาการ: การตั้งค่าล้มเหลว โดยมีข้อผิดพลาดในการรับรองความถูกต้อง

การแก้ไขปัญหา: ตรวจสอบให้แน่ใจว่าคุณเชื่อมต่อกับ Azure และยืนยันบัญชีและการสมัครใช้งานของคุณ

# Authenticate with Azure
az login

# Verify correct account and subscription
az account show

มีทรัพยากรอยู่แล้ว

อาการ: การตั้งค่าล้มเหลวโดยมีข้อผิดพลาด Resource already exists สำหรับกลุ่มทรัพยากร แผนบริการแอป หรือเว็บแอป

การแก้ไขปัญหา: เลือกวิธีใดวิธีหนึ่งต่อไปนี้.

• ใช้ทรัพยากรที่มีอยู่

  หากมีทรัพยากรอยู่และคุณต้องการใช้งาน ให้ตรวจสอบให้แน่ใจว่าตรงกับการกำหนดค่าของคุณ ใช้คำสั่ง az resource list ใน PowerShell

  az resource list --resource-group <your-resource-group>
  

• ลบทรัพยากรที่ขัดแย้งกัน

  ลบกลุ่มทรัพยากรหรือเปลี่ยนชื่อทรัพยากรของคุณใน a365.config.json แล้วดำเนินการตั้งค่าใหม่อีกครั้ง

  ใช้คำสั่ง az group delete ใน PowerShell เพื่อลบกลุ่มทรัพยากร

  # WARNING: This command deletes all resources in it
  az group delete --name <your-resource-group>
  

• ใช้คำสั่ง "cleanup" เพื่อเริ่มต้นใหม่

  ใช้คำสั่ง cleanup เพื่อลบทรัพยากร Agent 365 ทั้งหมด แล้วใช้คำสั่ง a365 setup all เพื่อเริ่มการตั้งค่าใหม่อีกครั้ง

  คำเตือน

  การเรียกใช้ a365 cleanup จะลบข้อมูลอย่างถาวร

  a365 cleanup
  a365 setup all
  

การให้ความยินยอมของผู้ดูแลระบบยังไม่เสร็จสมบูรณ์

อาการ: คุณเปิดหน้าต่างเบราว์เซอร์ระหว่างการตั้งค่า แต่ปิดหน้าต่างก่อนจะให้ความยินยอมเสร็จ หรือการตั้งค่าเสร็จสิ้นแล้วแต่การอนุมัติสิทธิ์ OAuth2 ยังไม่เสร็จสมบูรณ์

การแก้ไขปัญหา: เลือกตามบทบาทของคุณ:

• ผู้ดูแลระบบส่วนกลาง: เรียกใช้ a365 setup all อีกครั้ง CLI แจ้งให้ผู้ดูแลระบบยินยอม ทําตามขั้นตอนความยินยอมในหน้าต่างเบราว์เซอร์ที่ปรากฏขึ้น

• ส่วนกลางผู้ดูแลระบบรหัสเอเจนต์หรือนักพัฒนารหัสเอเจนต์: คุณไม่สามารถดำเนินการให้สิทธิ์ OAuth2 โดยตรงได้ เรียกใช้ a365 setup all — สรุปการตั้งค่าจะพิมพ์ขั้นตอนถัดไปสำหรับผู้ดูแลระบบส่วนกลาง รวมถึงลิงก์โดยตรงหรือ URL สำหรับการให้ความยินยอมเพื่อดำเนินการให้สิทธิ์ให้เสร็จสมบูรณ์ แชร์รายละเอียดเหล่านั้นกับผู้ดูแลระบบส่วนกลางของคุณ

ไฟล์การกำหนดค่าไม่มีอยู่หรือไม่ถูกต้อง

อาการ: การติดตั้งล้มเหลว โดยมี "ไม่พบการกำหนดค่า" หรือข้อผิดพลาดในการตรวจสอบความถูกต้อง

การแก้ไขปัญหา:

1. ตรวจสอบว่าไฟล์ a365.config.json มีอยู่หรือไม่
2. หากขาดหายไปหรือไม่ถูกต้อง ให้สร้างด้วยตนเองหรือใช้ a365 setup all --agent-name <name> (เอเจนต์เท่านั้น)

# Verify a365.config.json exists
Test-Path a365.config.json

การตั้งค่าเสร็จสมบูรณ์ แต่ยังไม่ได้สร้างทรัพยากร:

อาการ: คำสั่งการตั้งค่าสำเร็จ แต่ทรัพยากร Azure ไม่ถูกสร้าง

การแก้ไขปัญหา:

1. ตรวจสอบทรัพยากรที่สร้างขึ้นโดยเปิด a365.generated.config.json ในไดเรกทอรีการทำงานของคุณ
2. ตรวจสอบว่าทรัพยากร Azure มีอยู่โดยใช้ az resource listคําสั่ง
3. หากทรัพยากรขาดหายไป ให้ตรวจสอบข้อผิดพลาดในเอาต์พุตการตั้งค่าและเรียกใช้การตั้งค่าใหม่โดยใช้คำสั่ง a365 setup all

# Check created resources
Get-Content a365.generated.config.json | ConvertFrom-Json

# Verify Azure resources exist
az resource list --resource-group <your-resource-group> --output table

# If resources missing, check for errors in setup output and re-run
a365 setup all

แบบพิมพ์เขียวของเอเจนต์ยังไม่ได้ลงทะเบียนใน Microsoft Entra

อาการ: การตั้งค่าเสร็จสมบูรณ์ แต่ไม่พบแบบพิมพ์เขียวของเอเจนต์ในศูนย์การจัดการ Microsoft Entra

การแก้ไขปัญหา:

1. รับรหัสแบบพิมพ์เขียวจาก a365.generated.config.json

   Get-Content a365.generated.config.json | ConvertFrom-Json | Select-Object agentBlueprintId
   

2. ค้นหาในศูนย์การจัดการ Microsoft Entra:

   1. ไปที่: ศูนย์การจัดการ Microsoft Entra
   2. ไปที่ การลงทะเบียนแอป>แอปทั้งหมด
   3. ค้นหา agentBlueprintId ของคุณ

3. หากไม่พบ ให้เรียกใช้การตั้งค่าอีกครั้งโดยใช้คำสั่ง a365 setup all

   a365 setup all
   

ไม่ได้รับสิทธิ์ API

อาการ: การตั้งค่าเสร็จสมบูรณ์ แต่สิทธิ์การเข้าถึงแสดงเป็น "ยังไม่ได้รับอนุมัติ" ใน Microsoft Entra

การแก้ไขปัญหา:

1. เปิด ศูนย์การจัดการ Microsoft Entra

2. ค้นหาการลงทะเบียนแอปแบบพิมพ์เขียวของเอเจนต์ของคุณ

3. ไปที่ สิทธิ์ API

4. ให้ความยินยอมของผู้ดูแลระบบ:

   1. เลือก ให้ความยินยอมของผู้ดูแลระบบสำหรับ [ผู้เช่าของคุณ]
   2. ยืนยันการดำเนินการ

5. ตรวจสอบว่าสิทธิ์ทั้งหมดแสดงเครื่องหมายถูกสีเขียว

ไม่ได้เปิดใช้งานข้อมูลประจำตัวที่มีการจัดการ

อาการ: มีเว็บแอปอยู่ แต่ไม่ได้เปิดใช้งานข้อมูลประจําตัวที่มีการจัดการ

การแก้ไขปัญหา:

1. ตรวจสอบสถานะข้อมูลประจําตัวที่มีการจัดการโดยใช้คำสั่ง az webapp identity show
2. หากไม่ได้เปิดใช้งาน ให้เปิดใช้งานด้วยตนเองโดยใช้คำสั่ง az webapp identity assign
3. ตรวจสอบว่าเปิดใช้งานโดยใช้คำสั่ง az webapp identity show

# Check managed identity status
az webapp identity show --name <your-web-app> --resource-group <your-resource-group>

# If not enabled, enable it manually
az webapp identity assign --name <your-web-app> --resource-group <your-resource-group>

# Verify it's enabled
az webapp identity show --name <your-web-app> --resource-group <your-resource-group>

การตั้งค่าใช้เวลานานผิดปกติหรือหยุดตอบสนอง

อาการ: คำสั่งการตั้งค่าทำงานนานกว่า 10 นาทีโดยไม่เสร็จสิ้น

การแก้ไขปัญหา:

1. หากคุณกำลังทำงานในฐานะผู้ดูแลระบบส่วนกลาง ให้ตรวจสอบว่าหน้าต่างเบราว์เซอร์กำลังรอความยินยอมจากผู้ดูแลระบบหรือไม่ ดำเนินการขั้นตอนความยินยอมเพื่อปลดล็อกการตั้งค่า

2. หากการตั้งค่าหยุดตอบสนองโดยสิ้นเชิง ให้ยกเลิก (Ctrl+C) แล้วตรวจสอบรายการที่ถูกสร้างขึ้น

   # Check generated config
   Get-Content a365.generated.config.json | ConvertFrom-Json
   
   # Check Azure resources
   az resource list --resource-group <your-resource-group>
   

3. ล้างข้อมูลและลองอีกครั้ง

   a365 cleanup
   a365 setup all
   

ล้างเอเจนต์ที่ไม่มีการกำหนดค่า

อาการ: คุณสร้างเอเจนต์โดยใช้ a365 setup all --agent-name <name> และตอนนี้ต้องการลบออก แต่คุณไม่มีไฟล์ a365.config.json

วิธีการแก้ไข: ใช้ a365 cleanup --agent-name เพื่อลบเอเจนต์โดยไม่ต้องใช้ไฟล์กำหนดค่า CLI จะอ่านรหัสทรัพยากรจากไฟล์กำหนดค่าส่วนกลางที่สร้างขึ้นโดยอัตโนมัติ ซึ่งถูกเขียนขึ้นระหว่างขั้นตอนการตั้งค่า Bootstrap.

a365 cleanup --agent-name <your-agent-name>

เคล็ดลับ

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

หากคุณไม่มีไฟล์กำหนดค่าที่สร้างจากส่วนกลาง (เช่น หลังจากติดตั้ง CLI) ให้ใช้ a365 cleanup ที่มี a365.config.json ที่สร้างแบบขั้นต่ำ หรือลบทรัพยากรโดยตรงผ่าน พอร์ทัล Azure และ ศูนย์การจัดการ Microsoft Entra

ไม่สามารถส่งข้อความแรกใน Teams ได้

อาการ: หลังจากเตรียมใช้งานอินสแตนซ์เอเจนต์แล้ว จะไม่สามารถส่งข้อความต้อนรับไปยังผู้จัดการเอเจนต์ได้

การแก้ไขปัญหา: จำเป็นต้องมีสิทธิ์ [Chat.Create][perm-chatcreate] เพื่อสร้างออบเจ็กต์แชทใหม่ หากมีการแชทแบบหนึ่งต่อหนึ่งอยู่แล้ว การดำเนินการนี้จะส่งคืนแชทที่มีอยู่และไม่สร้างแชทใหม่

• หากต้องการนำไปใช้ ให้กำหนดค่าสิทธิ์ที่สืบทอดได้ของแบบพิมพ์เขียวของคุณเพื่อรวมขอบเขต Chat.Create นี้เข้าไปด้วย
• กำหนดค่าข้อความแชท Teams เพื่อส่งเมื่อมีการเตรียมใช้งานอินสแตนซ์ของเอเจนต์
• สร้างอินสแตนซ์เอเจนต์ใหม่จากแบบพิมพ์เขียวและทดสอบข้อความที่เรียกใช้ครั้งแรก