آموزش Microsoft Agent Framework؛ ساخت ایجنت با ابزار، جلسه و جریان کار

آشنایی با نام یک چارچوب، زمانی به مهارت تبدیل می‌شود که بتوانیم اجزای آن را در یک نمونه‌ی کوچک کنار هم بگذاریم. این آموزش Microsoft Agent Framework دقیقاً همین هدف را دارد. به‌جای فهرست کردن همه‌ی امکانات، اجزای اصلی را یکی‌یکی می‌سازیم و می‌بینیم هر کدام کجای یک دستیار آموزشی می‌نشیند.

پیش‌تر در مجموعه‌ی آموزش هوش مصنوعی تخته سبز معیارهای انتخاب چارچوب را مرور کردیم. حالا وقت کار با یکی از آن‌هاست. در پایان این قسمت ایجنتی دارید که ابزار صدا می‌زند، گفت‌وگو را به خاطر می‌سپارد و هر فراخوانی‌اش قابل مشاهده است.

Microsoft Agent Framework چیست؟

Microsoft Agent Framework یا به اختصار MAF، چارچوب یکپارچه‌ی مایکروسافت برای ساخت ایجنت‌های هوش مصنوعی است. تجربه‌ی دو پروژه‌ی قبلی مایکروسافت، یعنی Semantic Kernel و AutoGen، در آن جمع شده و در پایتون و .NET در دسترس است.

این چارچوب هم ایجنت تکی را پوشش می‌دهد و هم هماهنگی چند ایجنت را. الگوهای هماهنگی آن شامل ترتیبی، هم‌زمان، چت گروهی، واگذاری کار و الگوی «مغناطیسی» است که در آن یک ایجنت مدیر فهرست کارها را می‌سازد و زیرایجنت‌ها را هدایت می‌کند.

امکاناتی که برای محیط واقعی دارد

MAF چهار امکان مهم برای محیط عملیاتی دارد. مشاهده‌پذیری از طریق OpenTelemetry، که هر فراخوانی ابزار و هر قدم هماهنگی را ردیابی می‌کند. امنیت با میزبانی در Microsoft Foundry و کنترل دسترسی مبتنی بر نقش.

دو امکان دیگر دوام و کنترل است. دوام یعنی جلسه‌ها و جریان‌های کار را می‌توان متوقف کرد، ادامه داد و پس از خطا بازیابی کرد. کنترل یعنی جریان‌های کار با تأیید انسانی پشتیبانی می‌شوند و کاری که به تأیید نیاز دارد، منتظر می‌ماند.

وابسته نبودن به ارائه‌دهنده

یکی از نقاط قوت MAF این است که به یک ارائه‌دهنده یا ابر گره نخورده است:

• ابر: ایجنت در کانتینر، سرور محلی یا ابرهای مختلف اجرا می‌شود.
• مدل: OpenAI، Azure OpenAI، Foundry یا هر سرویس سازگار با OpenAI.
• استانداردهای باز: پشتیبانی از MCP و A2A برای ابزارها و ایجنت‌های دیگر.
• اتصال‌دهنده‌ها: ارتباط با ذخیره‌گاه‌هایی مثل Pinecone و Qdrant.

ساخت ایجنت و اجرای آن

ساخت ایجنت سه جزء می‌خواهد: سرویس مدل، دستورالعمل و یک نام. نمونه‌ی زیر ایجنتی می‌سازد که دوره‌ی مناسب پیشنهاد می‌دهد:

from agent_framework.openai import OpenAIChatClient

agent = OpenAIChatClient().create_agent(
    name="CourseAdvisor",
    instructions="You recommend courses that match the student's level. Answer in Persian.",
)

result = await agent.run("من تازه‌کارم؛ برای شروع پایتون چه دوره‌ای خوب است؟")
print(result.text)

کلاینت‌های مختلف مدل

همین ایجنت را می‌توان با کلاینت‌های دیگر ساخت. AzureOpenAIChatClient برای Azure OpenAI، AzureAIAgentClient برای سرویس ایجنت Foundry و OpenAIResponsesClient برای Responses API. حتی می‌توان با تغییر base_url به هر سرویس سازگار با OpenAI وصل شد.

ایجنت‌های راه دور هم با کلاس A2AAgent در دسترس‌اند. یعنی ایجنتی که تیم دیگری ساخته، در کد شما مثل یک ایجنت محلی رفتار می‌کند. پروتکل A2A را در قسمت‌های قبل دیدیم.

اجرای عادی و جریانی

ایجنت با run پاسخ کامل را برمی‌گرداند و با run_stream پاسخ را تکه‌تکه می‌فرستد. اجرای جریانی برای رابط کاربری بهتر است؛ کاربر شروع پاسخ را زودتر می‌بیند و انتظار کوتاه‌تر حس می‌شود.

هر اجرا می‌تواند گزینه‌های خودش را داشته باشد؛ مثل سقف توکن یا ابزارهای مجاز همان اجرا. این وقتی مفید است که یک درخواست خاص به ابزار یا مدل متفاوتی نیاز دارد.

ابزار، جلسه و میان‌افزار

ایجنتی که فقط متن تولید کند، هنوز ایجنت کاملی نیست. سه جزء بعدی آن را به دستیاری واقعی تبدیل می‌کنند.

تعریف ابزار

ابزار در MAF یک تابع معمولی پایتون است با توضیح پارامترها. مدل از روی همین توضیح‌ها تصمیم می‌گیرد کی و چطور آن را صدا بزند:

from typing import Annotated
from pydantic import Field

def get_syllabus(course: Annotated[str, Field(description="Course title")]) -> str:
    """Return the syllabus of a course."""
    return SYLLABI.get(course, "not found")

agent = OpenAIChatClient().create_agent(
    name="CourseAdvisor", instructions="...", tools=[get_syllabus]
)

ابزار را می‌توان هنگام ساخت ایجنت یا فقط برای یک اجرا داد. نکته‌ی کلیدی این است که منطق ابزار جدا از دستور مدل بماند. آن‌وقت می‌توانید get_syllabus را بدون مدل آزمایش کنید.

جلسه‌ی گفت‌وگو

برای گفت‌وگوی چندمرحله‌ای، ایجنت به جلسه نیاز دارد. با get_new_thread یک جلسه ساخته می‌شود و در هر اجرا پاس داده می‌شود. جلسه را می‌توان با serialize ذخیره و بعداً بازیابی کرد؛ یعنی کاربر فردا از همان جایی ادامه می‌دهد که امروز رها کرده است.

اگر جلسه ندهید، یک جلسه‌ی موقت فقط برای همان اجرا ساخته می‌شود. این همان حافظه‌ی کوتاه‌مدتی است که در قسمت قبل دیدیم. برای حافظه‌ی بلندمدت می‌توان ذخیره‌گاه سفارشی یا ابزاری مثل Mem0 را وصل کرد.

میان‌افزار

میان‌افزار کدی است که میان ایجنت و ابزار یا مدل اجرا می‌شود. میان‌افزار تابع، قبل و بعد از هر فراخوانی ابزار اجرا می‌شود؛ جای مناسبی برای لاگ، اندازه‌گیری زمان یا مسدود کردن فراخوانی خطرناک.

میان‌افزار چت هم میان ایجنت و مدل می‌نشیند. چند میان‌افزار را می‌توان زنجیر کرد؛ مثلاً لاگ، احراز هویت و محدودیت نرخ. مزیتش این است که کنترل‌ها بدون تغییر منطق ابزار یا دستور مدل اضافه می‌شوند.

جدول زیر اجزای اصلی را کنار هم می‌گذارد.

نمودار زیر نشان می‌دهد این اجزا چطور لایه‌به‌لایه روی هم قرار می‌گیرند.

جریان کار در MAF

ایجنت خودش تصمیم می‌گیرد چه کاری کند. اما گاهی می‌خواهیم ترتیب قدم‌ها دقیقاً مشخص باشد. جریان کار در MAF برای همین است؛ قدم‌های از پیش تعریف‌شده که ایجنت‌ها بخشی از آن‌ها را اجرا می‌کنند.

مجری، لبه و رویداد

مجری‌ها پیام ورودی را می‌گیرند، کارشان را انجام می‌دهند و پیام خروجی می‌سازند. مجری می‌تواند یک ایجنت باشد یا یک تابع معمولی. لبه‌ها مسیر پیام میان مجری‌ها را تعیین می‌کنند:

from agent_framework import WorkflowBuilder

builder = WorkflowBuilder()
builder.add_edge(check_prerequisites, recommend_course)
builder.set_start_executor(check_prerequisites)
workflow = builder.build()

لبه‌ها انواع مختلفی دارند: مستقیم، شرطی، سوئیچ، پخش به چند مقصد و جمع کردن از چند مبدأ. رویدادهایی مثل شروع جریان، شروع و پایان هر مجری و خطا هم منتشر می‌شوند تا بتوان هر اجرا را دنبال کرد.

میزبانی ایجنت‌های LangGraph

MAF شما را به ایجنت‌های نوشته‌شده با خودش محدود نمی‌کند. اگر ایجنتی با LangChain یا LangGraph دارید، با بسته‌ی langchain-azure-ai[hosting] می‌توانید آن را روی همان پروتکل‌های Foundry میزبانی کنید.

کلاس ResponsesHostServer گراف را روی نقطه‌ی پایانی /responses سازگار با OpenAI ارائه می‌دهد. برای شکل JSON سفارشی یا وب‌هوک هم InvocationsHostServer هست. به این ترتیب کد موجود دور ریخته نمی‌شود.

سناریوی عملی؛ دستیار پیشنهاد دوره

دستیار عنوان یک دوره را می‌گیرد، سرفصل را با ابزار می‌خواند و بر اساس سطح دانشجو توضیح می‌دهد. ورودی آزمون عنوان دوره، سطح دانشجو و ابزار خواندن سرفصل است. یک نمونه‌ی عادی و یک نمونه‌ی ناقص، مثلاً دوره‌ای که سرفصلش نیست، آماده کنید.

معیار پذیرش و نمونه‌ی شکست

اقدام مورد بررسی، تعریف ایجنت و ابزار و اتصال آن‌ها در یک مسیر ساده است. معیار پذیرش، استفاده‌ی واقعی از ابزار و رعایت سطح مخاطب است. با میان‌افزار لاگ بررسی کنید که ابزار واقعاً صدا زده شده؛ نه اینکه مدل سرفصل را از خودش ساخته باشد.

شکستی که باید عمداً دنبالش بگردید، آمیختن منطق ابزار با دستور مدل است؛ به شکلی که جداگانه قابل آزمون نباشند. اگر قاعده‌ی «فقط دوره‌های فعال» در دستور مدل نوشته شده باشد، نه در تابع ابزار، نمی‌توانید مطمئن شوید رعایت می‌شود.

تمرین عملی؛ نمونه‌ی کوچک با مرز روشن

خروجی این تمرین یک نمونه‌ی کوچک با مرز مشخص اجزا و آزمون مسیر اصلی است:

1. ابزار get_syllabus را بنویسید و بدون مدل برایش آزمون واحد بگذارید.
2. ایجنت را با همین ابزار بسازید و یک میان‌افزار لاگ اضافه کنید.
3. گفت‌وگوی دومرحله‌ای را با جلسه اجرا کنید و نمونه‌ی ناقص را هم امتحان کنید.

مشخص کنید کدام بخش را واقعاً اجرا کرده‌اید و کدام هنوز فرض است.

سخن پایانی

این آموزش Microsoft Agent Framework نشان داد یک ایجنت از چند جزء روشن ساخته می‌شود: کلاینت مدل، ایجنت با دستورالعمل، ابزارهای قابل آزمون، جلسه برای حفظ گفت‌وگو، میان‌افزار برای کنترل و جریان کار برای مسیرهای از پیش تعریف‌شده. MAF به ارائه‌دهنده وابسته نیست و حتی ایجنت‌های LangGraph را هم میزبانی می‌کند. مهم‌تر از خود چارچوب، جدا نگه داشتن این اجزاست؛ تا هر کدام جداگانه آزمون شود.

در قسمت بعد ایجنتی می‌سازیم که با مرورگر کار می‌کند.

این آموزش بر پایه‌ی درس Exploring Microsoft Agent Framework از مجموعه‌ی آزاد AI Agents for Beginners مایکروسافت (مجوز MIT) به فارسی بازنویسی و تکمیل شده است.