ทดสอบเอเจนต์โดยใช้ Microsoft Agent 365 SDK

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

เมื่อเอเจนต์ของคุณทำงานในเครื่องได้แล้ว ให้ดำเนินตามวงจรการพัฒนา Agent 365 เพื่อทดสอบในแอปพลิเคชัน Microsoft 365 เช่น Teams, Word และ Outlook

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

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

ข้อกำหนดเบื้องต้นทั่วไป

ข้อกำหนดเบื้องต้นเฉพาะภาษา

กำหนดค่าสภาพแวดล้อมการทดสอบเอเจนต์

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

ตั้งค่าสภาพแวดล้อมการทดสอบเอเจนต์ของคุณโดยทำตามลำดับขั้นตอนนี้:

  1. กำหนดค่าสภาพแวดล้อมของคุณ - สร้างหรืออัปเดตไฟล์กำหนดค่าสภาพแวดล้อมของคุณ

  2. การกำหนดค่า LLM - รับคีย์ API และกำหนดการตั้งค่า OpenAI หรือ Azure OpenAI

  3. กำหนดค่าการรับรองความถูกต้อง - ตั้งค่าการรับรองความถูกต้องแบบเอเจนต์

  4. การอ้างอิงตัวแปรสภาพแวดล้อม - กำหนดค่าตัวแปรสภาพแวดล้อมที่จำเป็น:

    1. ตัวแปรการรับรองความถูกต้อง
    2. การกำหนดค่าปลายทาง MCP
    3. ตัวแปร Observability
    4. การกำหนดค่าเซิร์ฟเวอร์แอปพลิเคชันของเอเจนต์

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

ขั้นตอนที่ 1: กำหนดค่าสภาพแวดล้อมของคุณ

ตั้งค่าไฟล์การกำหนดค่าของคุณ:

cp .env.template .env

หมายเหตุ

สำหรับแม่แบบการกำหนดค่าที่แสดงฟิลด์ที่จำเป็น โปรดดู ตัวอย่าง Microsoft Agent 365 SDK

ขั้นตอนที่ 2: การกำหนดค่า LLM

กำหนดค่าการตั้งค่า OpenAI หรือ Azure OpenAI สำหรับการทดสอบภายในเครื่อง เพิ่มคีย์ API และตำแหน่งปลายทางบริการจากข้อกำหนดเบื้องต้นไปยังไฟล์การกำหนดค่าของคุณ พร้อมกับพารามิเตอร์โมเดลใด ๆ

เพิ่มไปยังไฟล์ .env ของคุณ:

# Replace with your actual OpenAI API key
OPENAI_API_KEY=

# Azure OpenAI Configuration
AZURE_OPENAI_API_KEY=
AZURE_OPENAI_ENDPOINT=
AZURE_OPENAI_DEPLOYMENT=
AZURE_OPENAI_API_VERSION=

ตัวแปรสภาพแวดล้อม Python LLM

ตัวแปร คำอธิบาย จำเป็นต้องระบุ ตัวอย่าง
OPENAI_API_KEY คีย์ API สำหรับบริการ OpenAI สำหรับ OpenAI sk-proj-...
AZURE_OPENAI_API_KEY คีย์ API สำหรับบริการ Azure OpenAI สำหรับ Azure OpenAI a1b2c3d4e5f6...
AZURE_OPENAI_ENDPOINT URL ปลายทางบริการ Azure OpenAI สำหรับ Azure OpenAI https://your-resource.openai.azure.com/
AZURE_OPENAI_DEPLOYMENT ชื่อการปรับใช้ใน Azure OpenAI สำหรับ Azure OpenAI gpt-4
AZURE_OPENAI_API_VERSION เวอร์ชัน API สำหรับ Azure OpenAI สำหรับ Azure OpenAI 2024-02-15-preview

ขั้นตอนที่ 3: กำหนดค่าการรับรองความถูกต้องสำหรับเอเจนต์ของคุณ

เลือกหนึ่งในวิธีการรับรองความถูกต้องต่อไปนี้สำหรับเอเจนต์ของคุณ:

การรับรองความถูกต้องเชิงเอเจนต์

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

Value คำอธิบาย
agentBlueprintId รหัสไคลเอนต์ของเอเจนต์ของคุณ
agentBlueprintClientSecret ข้อมูลลับไคลเอ็นต์ของเอเจนต์ของคุณ
tenantId รหัสผู้เช่า Microsoft Entra ID ของคุณ

ใช้ค่าเหล่านี้เพื่อกำหนดค่าการรับรองความถูกต้องเชิงเอเจนต์ในเอเจนต์ของคุณ

เพิ่มการตั้งค่าต่อไปนี้ลงในไฟล์ .env ของคุณ โดยแทนค่าตัวยึดตำแหน่งด้วยข้อมูลประจำตัวจริงของคุณ:

USE_AGENTIC_AUTH=true
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID=<agentBlueprintId>
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTSECRET=<agentBlueprintClientSecret>
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__TENANTID=<your-tenant-id>
ตัวแปร คำอธิบาย จำเป็นต้องระบุ ตัวอย่าง
USE_AGENTIC_AUTH เปิดใช้งานโหมดการรับรองความถูกต้องแบบเอเจนต์ ใช่ true
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID ข้อมูลลับไคลเอ็นต์ของพิมพ์เขียวเอเจนต์จาก a365.generated.config.json ใช่ 11112222-bbbb-3333-cccc-4444dddd5555
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTSECRET ข้อมูลลับไคลเอ็นต์ของพิมพ์เขียวเอเจนต์จาก a365.generated.config.json ใช่ abc~123...
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__TENANTID รหัสผู้เช่า Microsoft Entra ID จาก a365.generated.config.json ใช่ 22223333-cccc-4444-dddd-5555eeee6666

การรับรองความถูกต้อง OBO

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

การรับรองความถูกต้องแบบ OBO เหมาะสำหรับสถานการณ์การใช้งานจริงที่:

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

สำหรับรายละเอียดเกี่ยวกับวิธีการทำงานของโฟลว์ OBO โปรดดู โฟลว์การรับรองความถูกต้อง สำหรับตัวอย่างการใช้งานที่สมบูรณ์ โปรดดู ตัวอย่างการให้สิทธิ์ OBO ใน SDK เอเจนต์สำหรับ Microsoft 365

การรับรองความถูกต้องโดยโทเค็นแบบแบเรอร์

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

ขั้นแรก ให้ใช้ a365 develop add-permissions เพื่อเพิ่มสิทธิ์เซิร์ฟเวอร์ MCP ที่จำเป็นให้กับแอปพลิเคชันของคุณ:

a365 develop add-permissions

จากนั้น ให้ใช้ a365 develop get-token เพื่อดึงและกำหนดค่าโทเค็นแบบแบเรอร์:

a365 develop get-token

คำสั่ง get-token จะดำเนินการโดยอัตโนมัติ:

  • อ่าน ToolingManifest.json เพื่อค้นหาเซิร์ฟเวอร์ MCP ที่กำหนดค่าไว้ทั้งหมด
  • รับโทเค็นหนึ่งชุดต่อเป้าหมาย โดยเซิร์ฟเวอร์ MCP แต่ละเครื่องจะได้รับโทเค็นที่ผูกกับ App ID ของแอปนั้น ๆ; ส่วนเซิร์ฟเวอร์ ATG ที่ใช้ร่วมกันจะได้รับโทเค็นที่ผูกกับ App ID ของ เอเจนต์ Tools Gateway ที่ใช้ร่วมกัน (ea9ffc3e-8a23-4a7d-836d-234d7c7565c1)
  • เขียนโทเค็นไปยังไฟล์การกำหนดค่าโครงการของคุณ:
    • โทเค็นต่อเซิร์ฟเวอร์: BEARER_TOKEN_<SERVER_NAME> (เช่น BEARER_TOKEN_MCP_MAILTOOLS)
    • โทเค็น ATG ที่ใช้ร่วมกัน: BEARER_TOKEN

ก่อนดำเนินการ get-token ให้เพิ่มรายการตัวยึดตำแหน่งลงในไฟล์การกำหนดค่าโปรเจ็กต์ของคุณ:

  • .NET: ให้เพิ่ม "BEARER_TOKEN": "" และ/หรือ "BEARER_TOKEN_<SERVER_NAME>": "" ลงใน environmentVariables ในแต่ละโปรไฟล์ใน Properties/launchSettings.json คำสั่งจะอัปเดตเฉพาะโปรไฟล์ที่มีการกำหนดคีย์เหล่านี้ไว้แล้ว
  • Python/Node.js: สร้างไฟล์ .env ที่มี BEARER_TOKEN= และ/หรือ BEARER_TOKEN_<SERVER_NAME>= ก่อนรัน ถ้าไฟล์หายไป คำสั่งจะข้ามการบันทึกและแสดงคำแนะนำ

หมายเหตุ

หากคุณรัน a365 develop get-token --app-id <id> โดยไม่มีไฟล์ a365.config.json โทเค็นจะไม่ได้รับการบันทึกโดยอัตโนมัติ คัดลอกและวางโทเค็นเหล่านั้นด้วยตนเองลงใน Properties/launchSettings.json (สำหรับ .NET) หรือไฟล์ .env (สำหรับ Python/Node.js) ของคุณ

โทเค็นแบบแบเรอร์จะหมดอายุหลังจากผ่านไปประมาณหนึ่งชั่วโมง ใช้ a365 develop get-token เพื่อรีเฟรชโทเค็นที่หมดอายุ

ขั้นตอนที่ 4: การอ้างอิงตัวแปรสภาพแวดล้อม

ตั้งค่าสภาพแวดล้อมของคุณให้เสร็จสมบูรณ์โดยกำหนดค่าตัวแปรสภาพแวดล้อมที่จำเป็นต่อไปนี้:

ตัวแปรการรับรองความถูกต้อง

ตั้งค่าการจัดการการยืนยันตัวตนที่จำเป็นสำหรับการยืนยันตัวตนแบบเอเจนต์เพื่อให้ทำงานได้อย่างถูกต้อง

เพิ่มไปยังไฟล์ .env ของคุณ:

# Agentic Authentication Settings
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__TYPE=AgenticUserAuthorization
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__SCOPES=https://graph.microsoft.com/.default
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__ALTERNATEBLUEPRINTCONNECTIONNAME=service_connection

# Connection Mapping
CONNECTIONSMAP_0_SERVICEURL=*
CONNECTIONSMAP_0_CONNECTION=SERVICE_CONNECTION
ตัวแปร คำอธิบาย จำเป็นต้องระบุ
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__TYPE ประเภทตัวจัดการการรับรองความถูกต้อง ใช่
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__SCOPES ขอบเขตการรับรองความถูกต้องสำหรับ Microsoft Graph ใช่
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__ALTERNATEBLUEPRINTCONNECTIONNAME ชื่อการเชื่อมต่อพิมพ์เขียวสำรอง ใช่
CONNECTIONSMAP_0_SERVICEURL รูปแบบ URL ของบริการสำหรับการแมปการเชื่อมต่อ ใช่
CONNECTIONSMAP_0_CONNECTION ชื่อการเชื่อมต่อสำหรับการแมป ใช่

ตัวแปรโทเค็นแบบแบเรอร์ (การพัฒนาในระบบเท่านั้น)

ตัวแปร คำอธิบาย จำเป็นต้องระบุ
BEARER_TOKEN โทเค็นแบบแบเรอร์ที่ใช้ร่วมกันสำหรับเซิร์ฟเวอร์ ATG MCP ที่ใช้ร่วมกัน คำสั่ง a365 develop get-token จะสร้างโทเค็นนี้โดยอัตโนมัติ สำหรับนักการพัฒนาภายในเครื่อง ATG ที่ใช้ร่วมกัน
BEARER_TOKEN_<SERVER_NAME> โทเค็นแบบแบเรอร์ต่อเซิร์ฟเวอร์ SDK จะนำชื่อโดยการแปลง mcpServerName ให้เป็นตัวพิมพ์ใหญ่จาก ToolingManifest.json (ตัวอย่างเช่น mcp_MailTools → BEARER_TOKEN_MCP_MAILTOOLS) คำสั่ง a365 develop get-token จะสร้างโทเค็นนี้โดยอัตโนมัติ สำหรับการพัฒนาภายในเครื่องต่อเซิร์ฟเวอร์
SKIP_TOOLING_ON_ERRORS ตั้งค่าเป็น true เพื่อกลับไปใช้ LLM พื้นฐาน หากเครื่องมือ MCP ไม่สามารถโหลดได้ จะมีผลเฉพาะเมื่อ ASPNETCORE_ENVIRONMENT หรือ ENVIRONMENT เป็น Development ไม่

สำคัญ

โทเค็นแบบแบเรอร์มีไว้สำหรับการพัฒนาในระบบเท่านั้น อย่าตั้งค่า BEARER_TOKEN หรือ BEARER_TOKEN_<SERVER_NAME> ในการพัฒนาเพื่อการใช้งานจริง

การกำหนดค่าปลายทาง MCP

ระบุจุดปลายทางแพลตฟอร์ม Agent 365 ที่เอเจนต์ของคุณเชื่อมต่อ เมื่อคุณสร้างไฟล์ manifest ที่กำหนด เซิร์ฟเวอร์เครื่องมือ สำหรับเอเจนต์ของคุณ ให้ระบุปลายทางแพลตฟอร์ม MCP ปลายทางนี้จะกำหนดสภาพแวดล้อม (preprod, ทดสอบ หรือการใช้งานจริง) ที่เซิร์ฟเวอร์เครื่องมือ MCP เชื่อมต่อเพื่อการผสานรวมกับ Microsoft 365

เพิ่มไปยังไฟล์ .env ของคุณ:

# MCP Server Configuration
MCP_PLATFORM_ENDPOINT=<MCP endpoint>
ตัวแปร คำอธิบาย ต้องมี ค่าเริ่มต้น ตัวอย่าง
MCP_PLATFORM_ENDPOINT URL ปลายทางของแพลตฟอร์ม MCP (preprod, test หรือ prod) ไม่ ปลายทางการใช้งานจริง

สำคัญ: หากคุณไม่ระบุ MCP_PLATFORM_ENDPOINT แอปจะใช้ปลายทางการใช้งานจริง

หมายเหตุ

หากคุณใช้เซิร์ฟเวอร์ mock tooling จาก CLI ให้ตั้งค่าปลายทางเป็น http://localhost:<port> โดยใช้หมายเลขพอร์ตที่คุณใช้ พอร์ตเริ่มต้นคือ 5309

ตัวแปร Observability

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

หมายเหตุ

การกำหนดค่าการสังเกตการณ์จะเหมือนกันในทุกภาษา สำหรับรายละเอียดเพิ่มเติม ดูที่ การกำหนดค่า

ตัวแปร คำอธิบาย ค่าเริ่มต้น ตัวอย่าง
ENABLE_A365_OBSERVABILITY_EXPORTER ส่งออกการติดตามไปยังบริการการสังเกตการณ์ เมื่อ false ให้ส่งออกช่วงไปยังคอนโซลแทน false true
A365_OBSERVABILITY_LOG_LEVEL ระดับการบันทึกล็อกภายในสำหรับ Observability SDK มีประโยชน์สำหรับการดีบักปัญหาการส่งออกระหว่างการทดสอบ none info, warn, error, debug

การกำหนดค่าเซิร์ฟเวอร์แอปพลิเคชันของเอเจนต์

กำหนดค่าพอร์ตที่เซิร์ฟเวอร์แอปพลิเคชันเอเจนต์ของคุณทำงาน การตั้งค่านี้เป็นทางเลือกและใช้กับเอเจนต์ Python และ JavaScript

เพิ่มไปยังไฟล์ .env ของคุณ:

# Server Configuration
PORT=3978
ตัวแปร คำอธิบาย ต้องมี ค่าเริ่มต้น ตัวอย่าง
PORT หมายเลขพอร์ตที่เซิร์ฟเวอร์เอเจนต์ทำงาน ไม่ 3978 3978

ติดตั้งไลบรารีที่จำเป็นและเริ่มเซิร์ฟเวอร์แอปพลิเคชันเอเจนต์

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

ติดตั้งการขึ้นต่อกัน

uv pip install -e .

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

เริ่มเซิร์ฟเวอร์ของแอปพลิเคชันเอเจนต์

python <main.py>

แทนที่ <main.py> ด้วยชื่อไฟล์ Python หลักของคุณที่เป็นจุดเริ่มต้นของแอปพลิเคชันเอเจนต์ (ตัวอย่างเช่น start_with_generic_host.py, app.py หรือ main.py)

หรือใช้ uv:

uv run python <main.py>

เซิร์ฟเวอร์เอเจนต์ของคุณกำลังทำงานอยู่และพร้อมที่จะรับคำขอจาก Agents Playground หรือแอปพลิเคชันใน Microsoft 365

ทำการทดสอบเอเจนต์ใน Agents Playground

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

กำหนดค่า Agents Playground สำหรับการรับรองความถูกต้องแบบเอเจนต์

หมายเหตุ

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

เมื่อคุณใช้การรับรองความถูกต้องแบบเอเจนต์ ให้กำหนดค่าไฟล์ YAML ของ Agents Playground ด้วยรายละเอียดของเอเจนต์ของคุณ:

  1. ตั้งค่าไฟล์การกำหนดค่า: สร้างหรืออัปเดตไฟล์ .m365agentsplayground.yml ในโฟลเดอร์ที่คุณใช้งาน Agents Playground สำหรับคำสั่งในการตั้งค่าอย่างละเอียด โปรดดู ปรับแต่งบริบทของ Teams

  2. อัปเดตการกำหนดค่าบอท: เพิ่มรายละเอียดบอทต่อไปนี้ลงในไฟล์ .m365agentsplayground.yml โดยแทนที่ค่าตัวยึดตำแหน่งด้วยข้อมูลรับรองของเอเจนต์ของคุณ:

    bot:
  id: <your-agent-email>@<your-tenant>.onmicrosoft.com
  name: <Your Agent Name>
  role: agenticUser
  agenticUserId: <your-agentic-user-id>
  agenticAppId: <your-agentic-app-id>
    คุณสมบัติ รายละเอียด จำเป็นต้องระบุ
    id อีเมลของผู้ใช้เอเจนต์ในรูปแบบ agentusername@tenant.onmicrosoft.com ใช่
    name ชื่อแสดงสำหรับผู้ใช้เอเจนต์ของคุณ ใช่
    role ต้องตั้งค่าเป็น agenticUser สำหรับการรับรองความถูกต้องแบบเอเจนต์ ใช่
    agenticUserId รหัสออบเจ็กต์ของผู้ใช้เอเจนต์ ค้นหาค่านี้ได้ในศูนย์การจัดการ Microsoft Entra บนหน้าโปรไฟล์ของผู้ใช้เอเจนต์ ใช่
    agenticAppId รหัสเอเจนต์ของผู้ใช้เอเจนต์ ค้นหาค่านี้ได้ในศูนย์การจัดการ Microsoft Entra บนหน้าโปรไฟล์ของผู้ใช้เอเจนต์ ใช่

เปิดหน้าต่างเทอร์มินัลใหม่ (PowerShell บน Windows) แล้วเริ่มใช้งาน Agents Playground:

agentsplayground

คำสั่งนี้จะเปิดเว็บเบราว์เซอร์พร้อมอินเทอร์เฟซของ Agents Playground เครื่องมือนี้แสดงอินเทอร์เฟซแชทที่คุณสามารถส่งข้อความถึงเอเจนต์ของคุณได้

การทดสอบพื้นฐาน

เริ่มต้นด้วยการตรวจสอบว่าเอเจนต์ของคุณได้รับการกำหนดค่าอย่างถูกต้อง ส่งข้อความถึงเอเจนต์:

What can you do?

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

  • เอเจนต์ของคุณทำงานอย่างถูกต้อง
  • เอเจนต์สามารถประมวลผลข้อความและตอบกลับได้
  • การสื่อสารระหว่าง Agents Playground และเอเจนต์ของคุณกำลังทำงานอยู่

การทดสอบการเรียกใช้เครื่องมือ

หลังจากกำหนดค่าเซิร์ฟเวอร์เครื่องมือ MCP ใน toolingManifest.json (ดู เครื่องมือ สำหรับคำแนะนำการตั้งค่า) ให้ทดสอบการเรียกใช้งานเครื่องมือโดยใช้ตัวอย่างต่อไปนี้:

ขั้นแรก ให้ตรวจสอบว่ามีเครื่องมือใดบ้าง:

List all tools I have access to

จากนั้นทดสอบการเรียกใช้เครื่องมือที่เฉพาะเจาะจง:

เครื่องมืออีเมล

Send email to your-email@example.com with subject "Test" and message "Hello from my agent"

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

เครื่องมือปฏิทิน

List my calendar events for today

การตอบกลับที่คาดหวัง: เอเจนต์จะดึงข้อมูลและแสดงกิจกรรมในปฏิทินของคุณสำหรับวันปัจจุบัน

เครื่องมือ SharePoint

List all SharePoint sites I have access to

การตอบสนองที่คาดไว้: เอเจนต์สอบถาม SharePoint และส่งกลับรายการไซต์ที่คุณมีสิทธิ์เข้าถึง

คุณสามารถดูการเรียกใช้เครื่องมือได้ใน:

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

ทดสอบด้วยกิจกรรมการแจ้งเตือน

ขณะพัฒนาในเครื่อง ให้ทดสอบสถานการณ์แจ้งเตือนโดยใช้ทริกเกอร์การแจ้งเตือนที่มีอยู่ใน Agents Playground

ภาพหน้าจอแสดงอินเทอร์เฟซ Agents Playground โดยมีเมนู Mock an Activity ที่ขยายออก แสดงตัวเลือก Trigger Notification Activity เช่น Send email และ Mention in Word

ก่อนทดสอบกิจกรรมการแจ้งเตือน โปรดแน่ใจว่า:

ทดสอบการแจ้งเตือนทางอีเมล

เพื่อทดสอบการจัดการการแจ้งเตือนทางอีเมล:

  1. เริ่มเอเจนต์และ Agents Playground ของคุณ
  2. ใน Agents Playground, ไปที่ จำลองกิจกรรม>ทริกเกอร์กิจกรรมการแจ้งเตือน
  3. เลือก ส่งอีเมล
  4. ในกล่องโต้ตอบเพย์โหลด ให้อัปเดตรายละเอียดอีเมลจำลอง เช่น ชื่อผู้ส่งและเนื้อหาอีเมลตามต้องการ
  5. เลือก ส่งกิจกรรม
  6. ดูผลลัพธ์ได้ทั้งในการสนทนาแชทและแผงล็อก

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

ทดสอบการแจ้งเตือนการกล่าวถึงใน Word

เพื่อทดสอบการแจ้งเตือนการกล่าวถึงในเอกสาร Word:

  1. เริ่มเอเจนต์และ Agents Playground ของคุณ
  2. ใน Agents Playground, ไปที่ จำลองกิจกรรม>ทริกเกอร์กิจกรรมการแจ้งเตือน
  3. เลือก การอ้างถึงใน Word
  4. ในหน้าต่างเพย์โหลด แก้ไขรายละเอียดของข้อคิดเห็นจำลอง เช่น รหัสเอกสารและข้อความข้อคิดเห็นตามต้องการ
  5. เลือก ส่งกิจกรรม
  6. ดูผลลัพธ์ได้ทั้งในการสนทนาแชทและแผงล็อก

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

ทดสอบเหตุการณ์การติดตั้งและถอนการติดตั้งของเอเจนต์

เมื่อ Agents Playground เชื่อมต่อกับเอเจนต์ของคุณ จะส่งกิจกรรม InstallationUpdate ที่มีการดำเนินการ add โดยอัตโนมัติ หากคุณใช้ตัวจัดการการติดตั้ง ข้อความต้อนรับของเอเจนต์ของคุณจะปรากฏในแชททันทีที่เชื่อมต่อสำเร็จ

เพื่อยืนยันการจัดการเหตุการณ์การติดตั้ง:

  1. เริ่มเซิร์ฟเวอร์เอเจนต์ของคุณ
  2. เปิด Agents Playground Agents Playground เชื่อมต่อกับเอเจนต์ของคุณและทริกเกอร์เหตุการณ์การติดตั้งโดยอัตโนมัติ
  3. ยืนยันว่าข้อความต้อนรับปรากฏในการสนทนาแชท

ภาพหน้าจอแสดงอินเทอร์เฟซ Agents Playground โดยมีข้อความต้อนรับของเอเจนต์ว่า 'ขอบคุณที่จ้างฉัน! ตั้งตารอที่จะช่วยเหลือคุณในเส้นทางอาชีพของคุณ!' ปรากฏในแชทสนทนาและแผงบันทึกหลังจากเหตุการณ์การติดตั้งถูกทริกเกอร์โดยอัตโนมัติ

สำหรับรายละเอียดเกี่ยวกับการใช้งานตัวจัดการ โปรดดูที่ จัดการเหตุการณ์การติดตั้งและถอนการติดตั้งเอเจนต์

ดูบันทึกการสังเกตการณ์

ในการดูบันทึกการสังเกตการณ์ระหว่างการพัฒนาแบบโลคอล ให้ผสานโค้ดการสังเกตการณ์เข้ากับเอเจนต์ของคุณ (ดู Observability สำหรับตัวอย่างโค้ด) และกำหนดค่าตัวแปรสภาพแวดล้อมตามที่อธิบายไว้ใน ตัวแปร Observability สำหรับคำสั่งการตรวจสอบทีละขั้นตอนและผลลัพธ์บันทึกที่คาดไว้ ดูที่ ตรวจสอบภายในเครื่อง เมื่อกำหนดค่าแล้ว คุณจะเห็นข้อมูลการติดตามแบบเรียลไทม์ปรากฏในคอนโซล ซึ่งแสดง:

  • การติดตามการเรียกใช้เอเจนต์
  • รายละเอียดการดำเนินการของเครื่องมือ
  • การเรียกใช้งานการอนุมานของ LLM
  • ข้อความอินพุตและเอาต์พุต
  • การใช้โทเค็น
  • เวลาในการตอบสนอง
  • ข้อมูลข้อผิดพลาด

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

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

หลังจากทดสอบเอเจนต์ของคุณในเครื่องแล้ว ให้ปรับใช้กับ Azure และเผยแพร่ไปยัง Microsoft 365

หากต้องการทดสอบเอเจนต์ของคุณในแอปพลิเคชัน Microsoft 365 เช่น Teams, Word และ Outlook โปรดดู วงจรการพัฒนา Agent 365

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

ส่วนนี้เสนอวิธีแก้ไขปัญหาที่พบบ่อยซึ่งคุณอาจพบขณะทดสอบเอเจนต์ของคุณในเครื่อง

เคล็ดลับ

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

ปัญหาการเชื่อมต่อและสภาพแวดล้อม

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

ปัญหาการเชื่อมต่อกับ Agents Playground

อาการ: Agents Playground ไม่สามารถเชื่อมต่อกับเอเจนต์ของคุณได้

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

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

เวอร์ชัน Agents Playground ที่ล้าสมัย

อาการ: ข้อผิดพลาดที่ไม่คาดคิดหรือคุณลักษณะที่ขาดหายไปใน Agents Playground

การแก้ไขปัญหา: ถอนการติดตั้งและติดตั้ง Agents Playground ใหม่

winget uninstall agentsplayground
winget install agentsplayground

ความขัดแย้งของพอร์ต

อาการ: ข้อผิดพลาดที่ระบุว่าพอร์ตมีการใช้งานอยู่แล้ว

วิธีแก้ไข:

  • หยุดอินสแตนซ์อื่นๆ ของเอเจนต์ของคุณ
  • เปลี่ยนหมายเลขพอร์ตในการกำหนดค่าของคุณ
  • ปิดกระบวนการที่ใช้งานพอร์ต
# Windows PowerShell
Get-Process -Id (Get-NetTCPConnection -LocalPort <port>).OwningProcess | Stop-Process

ไม่สามารถเพิ่ม DeveloperMCPServer ได้

อาการ: ข้อผิดพลาดในการเพิ่ม DeveloperMCPServer ใน Visual Studio Code.

การแก้ไขปัญหา: ปิดและเปิด Visual Studio Code ใหม่ จากนั้นลองเพิ่มเซิร์ฟเวอร์อีกครั้ง

ปัญหาการรับรองความถูกต้องและโทเค็น

ปัญหาเหล่านี้เกิดขึ้นเมื่อเอเจนต์ของคุณไม่สามารถตรวจสอบสิทธิ์กับบริการ Microsoft 365 ได้อย่างถูกต้อง หรือเมื่อข้อมูลประจำตัวหมดอายุหรือมีการกำหนดค่าไม่ถูกต้อง

อาการ:

  • 401 ข้อผิดพลาดที่ไม่ได้รับอนุญาต
  • ข้อความ "โทเค็นแบบแบเรอร์หมดอายุ"
  • การรับรองความถูกต้องแบบเอเจนต์ล้มเหลว

สาเหตุหลัก:

  • โทเค็นจะหมดอายุหลังจากผ่านไปประมาณหนึ่งชั่วโมง
  • การกำหนดค่าการรับรองความถูกต้องไม่ถูกต้อง
  • ข้อมูลประจำตัวขาดหายไปหรือไม่ถูกต้อง

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

  • สำหรับการหมดอายุของโทเค็นผู้ถือ

    รีเฟรชโทเค็นของคุณและอัปเดตตัวแปรสภาพแวดล้อมของคุณ

    # Get a new token
a365 develop get-token

# Update your .env file with the new token

  • สำหรับความล้มเหลวของโทเค็นแบบแบเรอร์ในแต่ละเซิร์ฟเวอร์

    ตรวจสอบว่าไฟล์กำหนดค่าของคุณมีรายการตัวยึดตำแหน่งสำหรับแต่ละเซิร์ฟเวอร์ BEARER_TOKEN_<SERVER_NAME> จากนั้นรันซ้ำ a365 develop get-token เพื่อเติมข้อมูลเหล่านั้น SDK จะกำหนดชื่อตัวแปรโดยการนำค่า mcpServerName ใน ToolingManifest.json ไปแปลงเป็นตัวอักษรพิมพ์ใหญ่ทั้งหมด และแทนที่ยัติภังค์ด้วยขีดล่าง (ตัวอย่าง mcp_MailTools → BEARER_TOKEN_MCP_MAILTOOLS)

  • สำหรับข้อผิดพลาดในการตรวจสอบสิทธิ์ของเอเจนต์ (Python)

    ตรวจสอบไฟล์ .env:

    # Should be (with underscore):
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__ALT_BLUEPRINT_NAME=SERVICE_CONNECTION

# Not:
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__ALT_BLUEPRINT_NAME=ServiceConnection

  • สำหรับข้อมูลประจำตัวที่ขาดหายไป

    ตรวจสอบให้แน่ใจว่ามีข้อมูลประจำตัวที่จำเป็นก่อนทดสอบ

    ตรวจสอบให้แน่ใจว่า .env หรือ appsettings.json มีรายการดังต่อไปนี้:

    • คีย์ API และข้อมูลลับ
    • รหัสผู้เช่า
    • รหัสไคลเอ็นต์
    • Blueprint ID (หากใช้การรับรองความถูกต้องแบบเอเจนต์)

    การตรวจสอบ:

    ทดสอบโดยส่งคำขอแบบง่ายใน Agents Playground คุณควรได้รับการตอบโดยไม่มีข้อผิดพลาด 401

  • ปัญหาเกี่ยวกับเครื่องมือและการแจ้งเตือน

    ปัญหาเหล่านี้เกี่ยวข้องกับการเรียกใช้เครื่องมือ การโต้ตอบกับเซิร์ฟเวอร์ MCP และการส่งการแจ้งเตือน

ไม่ได้รับอีเมล

อาการ: เอเจนต์ระบุว่าอีเมลถูกส่งไปแล้ว แต่คุณไม่ได้รับอีเมล

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

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

การตอบข้อคิดเห็นใน Word ไม่ทำงาน

ปัญหาที่ทราบ: บริการแจ้งเตือนไม่สามารถตอบกลับคอมเมนต์ของ Word ได้โดยตรง ฟังก์ชันนี้อยู่ระหว่างการพัฒนา

ข้อความไม่ถึงเอเจนต์

อาการ: แอปพลิเคชันเอเจนต์ของคุณไม่ได้รับข้อความที่ส่งไปยังเอเจนต์ใน Teams

สาเหตุที่เป็นไปได้:

  • ยังไม่ได้ตั้งค่า Blueprint ของเอเจนต์ในพอร์ทัลนักพัฒนา
  • ปัญหา Azure Web App (เช่น ความล้มเหลวในการปรับใช้ แอปไม่ทำงาน หรือข้อผิดพลาดในการกำหนดค่า)
  • อินสแตนซ์ของเอเจนต์ไม่ได้ถูกสร้างขึ้นอย่างถูกต้องใน Teams

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

  • ตรวจสอบการกำหนดค่าพอร์ทัลนักพัฒนา:

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

  • ตรวจสอบสุขภาพ Azure Web App:

    หากคุณปรับใช้เอเจนต์ของคุณไปยัง Azure ให้ตรวจสอบว่า Web App ทำงานอย่างถูกต้อง:

    1. ไปที่ พอร์ทัล Azure
    2. ไปที่ทรัพยากรเว็บแอปของคุณ
    3. ตรวจสอบ ภาพรวม>สถานะ (ควรแสดง "กำลังทำงาน")
    4. ตรวจสอบ การสตรีมบันทึก ภายใต้ การตรวจสอบ เพื่อหาข้อผิดพลาดรันไทม์
    5. ตรวจทานบันทึกของ ศูนย์การปรับใช้ เพื่อยืนยันว่าการปรับใช้สำเร็จ
    6. ตรวจสอบ การกำหนดค่า>การตั้งค่าแอปพลิเคชัน มีตัวแปรสภาพแวดล้อมที่จำเป็นทั้งหมด

  • ตรวจสอบการสร้างอินสแตนซ์ของเอเจนต์:

    ตรวจสอบให้แน่ใจว่าคุณสร้างอินสแตนซ์เอเจนต์อย่างถูกต้องใน Microsoft Teams:

    1. เปิด Microsoft Teams
    2. ไปที่ แอป และค้นหาเอเจนต์ของคุณ
    3. ตรวจสอบว่าเอเจนต์ปรากฏในผลการค้นหา
    4. หากไม่พบ ให้ตรวจสอบว่ามีการเผยแพร่ในศูนย์การจัดการ Microsoft 365 - เอเจนต์
    5. สร้างอินสแตนซ์ใหม่โดยเลือก เพิ่ม บนเอเจนต์ของคุณ
    6. สำหรับคำสั่งโดยละเอียด โปรดดู การเริ่มต้นใช้งานเอเจนต์

แก้ไขปัญหาบันทึกความสามารถในการสังเกตการณ์

หากบันทึกการสังเกตการณ์ของเอเจนต์ของคุณไม่ปรากฏตามที่คาดไว้ โปรดดู การแก้ไขปัญหา ในคู่มือการสังเกตการณ์

  • Last updated on