راهنمای شروع سریع (quickstart) برای Microsoft Foundry Agent Service برای زبان Python نوشته شده است. این راهنما، جزئیات فنی زیرساخت‌های Azure را درون ساختارهای پوششی چنان پیچیده‌ای پنهان می‌کند که می‌توانید آموزش را بدون اینکه بدانید واقعاً چه منابعی ایجاد شده‌اند، به پایان برسانید. اگر با .NET کار می‌کنید، از ابتدا با یک محدودیت روبرو هستید: نمونه‌ها مسیر اشتباهی را نشان می‌دهند، نام پکیج‌ها بدون هشدار تغییر می‌کنند و تغییر برند اخیر از Azure AI Foundry به Microsoft Foundry باعث شده است که دو مجموعه از مستندات در نتایج جستجو با هم رقابت کنند.

من اخیراً اولین agent خود را با C# ساختم. اگر نویزها را حذف کنید و مراحل ضروری را از سردرگمی‌های مربوط به نسخه‌های پیش‌نمایش (preview) جدا کنید، این سرویس به خوبی کار می‌کند. در اینجا نقشه‌ راهی را آورده‌ام که ای کاش در روز اول داشتم.

چهار منبعی که واقعاً به آن‌ها نیاز دارید

برای اجرای یک Prompt Agent ساده، نیازی به ده‌ها سرویس Azure ندارید. شما دقیقاً به چهار چیز نیاز دارید و CLI آن‌ها را به گونه‌ای نمایش می‌دهد که در نوت‌بوک‌های Python دیده نمی‌شوند.

اول، یک منبع Foundry با نوع AIServices. این منبع به عنوان ظرفیت اصلی برای مدل‌هایی که فراخوانی خواهید کرد، عمل می‌کند. دوم، یک project درون آن منبع. پروژه همان محدوده (scope) است که تعاریف agent، رشته‌های گفتگو (conversation threads) و تنظیمات استقرار (deployment) شما در آن قرار دارند. سوم، یک deployed model. بدون یک استقرار فعال، agent نقطه انتهایی (endpoint) برای فراخوانی ندارد. چهارم، یک role assignment برای هویت خودتان تا SDK بتواند نسبت به پروژه احراز هویت انجام دهد.

همین و بس. بدون نیاز به کلاستر Kubernetes، بدون نیاز به محاسبات اختصاصی (custom compute) و بدون نیاز به مدیریت دستی Redis cache برای تاریخچه گفتگو.

Prompt Agents در مقابل Hosted Agents

Foundry دو راه برای اجرای agentها به شما می‌دهد. به سراغ گزینه پیچیده‌تر نروید.

Prompt Agents مسیر ساده‌تری هستند. شما یک مدل را انتخاب می‌کنید، دستورالعمل‌های سیستم را می‌نویسید و Foundry agent را برای شما اجرا می‌کند. شما نیازی به مدیریت محاسبات، کانتینرها یا منطق مسیریابی (routing logic) ندارید. این روش برای ابزارهای داخلی، بات‌های میز خدمت (helpdesk) و پاسخگویی مستقیم به سوالات بر اساس اسناد مناسب است.

Hosted Agents مستلزم آن هستند که شما کد اپلیکیشن را بنویسید، آن را به صورت یک کانتینر بسته‌بندی کنید و آن را به Foundry متصل کنید. شما تنها زمانی این مسیر را انتخاب می‌کنید که به منطق تجاری سفارشی نیاز داشته باشید که Foundry نمی‌تواند از طریق promptها و ابزارهای داخلی آن را بیان کند؛ مانند فراخوانی یک API داخلی با احراز هویت غیر استاندارد.

این راهنما بر Prompt Agents تمرکز دارد، زیرا سریع‌ترین راه برای تأیید صحت تنظیمات .NET شما، پیش از سرمایه‌گذاری روی فایل‌های Docker و ارکستراسیون (orchestration) است.

راه‌اندازی از طریق خط فرمان (Command Line)

استفاده از CLI شما را مجبور می‌کند هر منبع را مشاهده کنید، که دقیقاً همان چیزی است که quickstart پایتون آن را پنهان می‌کند. یک resource group در منطقه East US 2 ایجاد کنید. انتخاب منطقه در اینجا اهمیت دارد. پشتیبانی از ابزارها در Foundry به صورت نامنظم منتشر می‌شود و در حال حاضر East US 2 گسترده‌ترین مجموعه ابزار را دارد. اگر منطقه‌ای را انتخاب کنید که فاقد code interpreter یا ابزارهای جستجوی فایل (file search) باشد، فراخوانی ایجاد agent شما با یک خطای مبهم در مورد قابلیت‌های پشتیبانی‌نشده مواجه خواهد شد.

منبع Foundry را با پرچم --allow-project-management ایجاد کنید. بدون این پرچم، منبع به عنوان یک endpoint مستقل از cognitive services باقی می‌ماند و استقرارهای محدود به پروژه (project-scoped deployments) را که agentها نیاز دارند، نمی‌پذیرد. سپس پروژه را ایجاد کنید، مدل خود را مستقر کنید و به خودتان نقش Foundry User را اختصاص دهید.

به جای نام نمایشی (display name)، از GUID پایدار نقش استفاده کنید:

53ca6127-db72-4b80-b1b0-d745d6d5456d

نام نقش‌ها بسته به tenant با سرعت‌های متفاوتی در Azure Active Directory منتشر می‌شوند. یک سازمان ممکن است امروز نقش Foundry User را در پورتال ببیند؛ سازمان دیگر ممکن است تا چند روز آینده آن را نبیند. GUID مستقیماً به تعریف نقش اشاره می‌کند و در طول فرآیند انتشار با خطا مواجه نخواهد شد. این جزئیات کوچک می‌تواند شما را از یک ساعت عیب‌یابی خطاهای 'permission-denied' نجات دهد؛ خطاهایی که شبیه مشکلات سیاست‌گذاری (policy) به نظر می‌رسند اما در واقع مشکلاتی در تشخیص برچسب‌ها (label-resolution) هستند.

از انتخاب پکیج اشتباه NuGet خودداری کنید

اینجاست که توسعه‌دهندگان .NET اغلب گیر می‌کنند. شما در قطعه‌کدهای قدیمی ارجاعاتی به Azure.AI.Projects.OpenAI خواهید دید. آن پکیج فقط در مرحله preview است و با Azure.AI.Extensions.OpenAI همپوشانی دارد. هر دو پکیج، extension methodها و تایپ‌ها را در namespaceهای مشابه تعریف می‌کنند. اگر آن‌ها را در کنار هم نصب کنید، build شما با خطاهای ارجاع مبهم (ambiguous reference errors) مواجه می‌شود که