คู่มือเริ่มต้นใช้งานอย่างรวดเร็ว (quickstart) สำหรับ Microsoft Foundry Agent Service เขียนขึ้นสำหรับ Python ซึ่งมันซ่อนความซับซ้อนของระบบหลังบ้าน Azure ไว้ภายใต้โครงสร้าง (scaffolding) ที่หนาแน่นเสียจนคุณสามารถทำตามบทช่วยสอนจนจบได้โดยไม่รู้เลยว่าจริงๆ แล้วมีการสร้างทรัพยากรอะไรขึ้นมาบ้าง หากคุณสร้างบน .NET คุณจะเริ่มด้วยความเสียเปรียบ: ตัวอย่างโค้ดชี้ไปผิดทาง ชื่อแพ็กเกจเปลี่ยนไปโดยไม่มีการแจ้งเตือน และการเปลี่ยนแบรนด์จาก Azure AI Foundry เป็น Microsoft Foundry เมื่อเร็วๆ นี้ ทำให้มีเอกสารสองชุดที่แย่งกันปรากฏในผลการค้นหา

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

ทรัพยากร 4 อย่างที่คุณจำเป็นต้องใช้จริง

คุณไม่จำเป็นต้องใช้บริการ Azure เป็นโหลเพื่อรัน Prompt Agent พื้นฐาน คุณต้องการเพียง 4 อย่างเท่านั้น และ CLI จะทำให้คุณเห็นสิ่งเหล่านี้ในแบบที่ Python notebooks ทำไม่ได้

อย่างแรก คือทรัพยากร Foundry ที่มี kind เป็น AIServices ซึ่งทำหน้าที่เป็นขีดความสามารถหลัก (parent capacity) สำหรับโมเดลที่คุณจะเรียกใช้ อย่างที่สอง คือ project ภายในทรัพยากรนั้น โปรเจกต์คือขอบเขตที่คำจำกัดความของเอเจนต์, เธรดการสนทนา และการตั้งค่าการ deploy อาศัยอยู่ อย่างที่สาม คือ deployed model หากไม่มีการ deploy ที่ใช้งานอยู่ เอเจนต์จะไม่มี endpoint สำหรับเรียกใช้งาน อย่างที่สี่ คือ role assignment สำหรับตัวตนของคุณเอง เพื่อให้ SDK สามารถยืนยันตัวตนกับโปรเจกต์ได้

แค่นั้นเอง ไม่ต้องมี Kubernetes cluster, ไม่ต้องมี custom compute, ไม่ต้องมี Redis cache สำหรับประวัติการสนทนาที่ต้องจัดการเอง

Prompt Agents เทียบกับ Hosted Agents

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

Prompt Agents เป็นเส้นทางที่ง่ายกว่า คุณเลือกโมเดล เขียนคำสั่งระบบ (system instructions) และ Foundry จะรันเอเจนต์ให้คุณเอง คุณไม่ต้องจัดการเรื่อง compute, containers หรือ routing logic ซึ่งเหมาะสำหรับเครื่องมือภายใน, บอท helpdesk และการตอบคำถามจากเอกสารแบบตรงไปตรงมา

Hosted Agents กำหนดให้คุณต้องเขียนโค้ดแอปพลิเคชัน, แพ็กมันเป็น container และเชื่อมต่อเข้ากับ Foundry คุณจะเลือกเส้นทางนี้ก็ต่อเมื่อคุณต้องการตรรกะทางธุรกิจที่กำหนดเอง (custom business logic) ซึ่ง Foundry ไม่สามารถแสดงออกผ่าน prompt และเครื่องมือที่มีมาให้ได้ เช่น การเรียกใช้ internal API ที่มีการยืนยันตัวตนแบบไม่มาตรฐาน

คู่มือนี้จะเน้นไปที่ Prompt Agents เพราะเป็นวิธีที่เร็วที่สุดในการตรวจสอบว่าการตั้งค่า .NET ของคุณถูกต้อง ก่อนที่คุณจะไปลงทุนกับ Docker files และ orchestration

การตั้งค่าผ่าน Command Line

การใช้ CLI บังคับให้คุณเห็นทรัพยากรแต่ละอย่าง ซึ่งเป็นสิ่งที่ quickstart ของ Python ปิดบังไว้ สร้าง resource group ใน East US 2 การเลือกภูมิภาค (region) มีความสำคัญมากที่นี่ Foundry เริ่มเปิดใช้งานการรองรับเครื่องมือต่างๆ ไม่พร้อมกัน และปัจจุบัน East US 2 มีชุดเครื่องมือที่ครอบคลุมที่สุด หากคุณเลือกภูมิภาคที่ขาด code interpreter หรือเครื่องมือค้นหาไฟล์ (file search tools) การเรียกสร้างเอเจนต์ของคุณจะล้มเหลวพร้อมข้อผิดพลาดที่คลุมเครือเกี่ยวกับความสามารถที่ไม่รองรับ

สร้างทรัพยากร Foundry ด้วย flag --allow-project-management หากไม่มี flag นั้น ทรัพยากรจะยังคงเป็นเพียง cognitive services endpoint แบบเดี่ยวๆ และจะไม่ยอมรับการ deploy ที่มีขอบเขตระดับโปรเจกต์ตามที่เอเจนต์ต้องการ จากนั้นให้สร้างโปรเจกต์, deploy โมเดลของคุณ และกำหนดบทบาท Foundry User ให้กับตัวเอง

ใช้ GUID ของบทบาทที่เสถียรแทนชื่อที่แสดง (display name):

53ca6127-db72-4b80-b1b0-d745d6d5456d

ชื่อบทบาทจะแพร่กระจายผ่าน Azure Active Directory ด้วยความเร็วที่แตกต่างกันขึ้นอยู่กับ tenant บางองค์กรอาจเห็น Foundry User ในพอร์ทัลวันนี้ แต่อีกองค์กรอาจต้องรออีกหลายวัน การใช้ GUID จะชี้ไปยังคำจำกัดความโดยตรงและจะไม่ล้มเหลวระหว่างการ rollout รายละเอียดเล็กๆ น้อยๆ นี้สามารถช่วยประหยัดเวลาในการ debug ข้อผิดพลาด permission-denied ที่ดูเหมือนจะเป็นปัญหาด้านนโยบาย (policy) แต่จริงๆ แล้วเป็นปัญหาเรื่องการระบุชื่อ (label-resolution)

หลีกเลี่ยงแพ็กเกจ NuGet ที่ผิด

นี่คือจุดที่นักพัฒนา .NET มักจะติดขัด คุณจะเห็นการอ้างอิงถึง Azure.AI.Projects.OpenAI ในโค้ดตัวอย่างเก่าๆ แพ็กเกจนั้นเป็นเวอร์ชัน preview เท่านั้น และมันมีความซ้ำซ้อนกับ Azure.AI.Extensions.OpenAI ทั้งคู่มีการกำหนด extension methods และ types ใน namespace ที่คล้ายกัน หากคุณติดตั้งพวกมันไว้คู่กัน การ build ของคุณจะพังด้วยข้อผิดพลาด ambiguous reference ที่