ai-agents-for-beginners

کاوش در چارچوب مامور مایکروسافت

Agent Framework

مقدمه

این درس موارد زیر را پوشش خواهد داد:

اهداف یادگیری

پس از پایان این درس، شما خواهید دانست چگونه:

نمونه‌های کد

نمونه‌های کد برای Microsoft Agent Framework (MAF) در این مخزن، زیر فایل‌های xx-python-agent-framework و xx-dotnet-agent-framework یافت می‌شوند.

درک چارچوب مامور مایکروسافت

Framework Intro

Microsoft Agent Framework (MAF) چارچوب متحد مایکروسافت برای ساخت ماموران هوش مصنوعی است. این چارچوب انعطاف‌پذیری لازم برای پاسخ به انواع مختلف موارد استفاده ماموری را که در هر دو محیط تولید و تحقیق دیده می‌شوند ارائه می‌دهد از جمله:

برای ارائه ماموران هوش مصنوعی در تولید، MAF همچنین ویژگی‌هایی برای:

چارچوب مامور مایکروسافت همچنین بر قابلیت همکاری متمرکز است از طریق:

بیایید ببینیم چگونه این ویژگی‌ها در برخی از مفاهیم کلیدی چارچوب مامور مایکروسافت به کار گرفته شده‌اند.

مفاهیم کلیدی چارچوب مامور مایکروسافت

مامورها

Agent Framework

ایجاد نمایندگان

ایجاد نماینده با تعریف سرویس استنتاج (ارائه‌دهنده LLM)، مجموعه‌ای از دستورالعمل‌ها برای دنبال کردن توسط نماینده هوش مصنوعی و انتساب یک نام انجام می‌شود:

agent = AzureOpenAIChatClient(credential=AzureCliCredential()).create_agent( instructions="You are good at recommending trips to customers based on their preferences.", name="TripRecommender" )

مثال بالا از Azure OpenAI استفاده می‌کند اما نمایندگان را می‌توان با استفاده از انواع سرویس‌ها از جمله Microsoft Foundry Agent Service ایجاد کرد:

AzureAIAgentClient(async_credential=credential).create_agent( name="HelperAgent", instructions="You are a helpful assistant." ) as agent

APIهای OpenAI Responses، ChatCompletion

agent = OpenAIResponsesClient().create_agent( name="WeatherBot", instructions="You are a helpful weather assistant.", )

agent = OpenAIChatClient().create_agent( name="HelpfulAssistant", instructions="You are a helpful assistant.", )

یا MiniMax که API سازگار با OpenAI با پنجره‌های متن بزرگ (تا ۲۰۴ هزار توکن) فراهم می‌کند:

agent = OpenAIChatClient(base_url="https://api.minimax.io/v1", api_key=os.environ["MINIMAX_API_KEY"], model_id="MiniMax-M3").create_agent( name="HelpfulAssistant", instructions="You are a helpful assistant.", )

یا نمایندگان راه دور با استفاده از پروتکل A2A:

agent = A2AAgent( name=agent_card.name, description=agent_card.description, agent_card=agent_card, url="https://your-a2a-agent-host" )

اجرای نمایندگان

نمایندگان با استفاده از متدهای .run یا .run_stream برای پاسخ‌های غیرجریان یا جریان اجرا می‌شوند.

result = await agent.run("What are good places to visit in Amsterdam?")
print(result.text)

async for update in agent.run_stream("What are the good places to visit in Amsterdam?"):
    if update.text:
        print(update.text, end="", flush=True)

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

این در مواردی مفید است که مدل‌ها یا ابزارهای خاصی برای تکمیل وظیفه کاربران لازم باشد.

ابزارها

ابزارها می‌توانند هم هنگام تعریف نماینده تعیین شوند:

def get_attractions( location: Annotated[str, Field(description="The location to get the top tourist attractions for")], ) -> str: """Get the top tourist attractions for a given location.""" return f"The top attractions for {location} are." 


# هنگام ایجاد مستقیم یک ChatAgent

agent = ChatAgent( chat_client=OpenAIChatClient(), instructions="You are a helpful assistant", tools=[get_attractions]

و همچنین هنگام اجرای نماینده:


result1 = await agent.run( "What's the best place to visit in Seattle?", tools=[get_attractions] # ابزاری که فقط برای این اجرا ارائه شده است )

رشته‌های نماینده

رشته‌های نماینده برای مدیریت گفتگوهای چند مرحله‌ای استفاده می‌شوند. رشته‌ها می‌توانند به یکی از دو روش ایجاد شوند:

برای ایجاد یک رشته، کد به این شکل است:

# ایجاد یک رشته جدید.
thread = agent.get_new_thread() # اجرای عامل با رشته.
response = await agent.run("Hello, I am here to help you book travel. Where would you like to go?", thread=thread)

سپس می‌توانید رشته را سریال کنید تا بعداً ذخیره شود:

# ایجاد یک نخ جدید.
thread = agent.get_new_thread() 

# اجرای نماینده با نخ.

response = await agent.run("Hello, how are you?", thread=thread) 

# سریال‌سازی نخ برای ذخیره‌سازی.

serialized_thread = await thread.serialize() 

# دی‌سریال‌سازی وضعیت نخ پس از بارگذاری از ذخیره‌سازی.

resumed_thread = await agent.deserialize_thread(serialized_thread)

واسط نماینده

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

واسط توابع

این واسط اجازه می‌دهد عملی بین نماینده و تابع/ابزاری که فراخوانی می‌کند، اجرا شود. مثالی که کاربرد دارد، ثبت وقایع (Logging) بر روی فراخوانی تابع است.

در کد زیر next تعیین می‌کند که آیا باید واسط بعدی اجرا شود یا خود تابع اصلی فراخوانی شود.

async def logging_function_middleware(
    context: FunctionInvocationContext,
    next: Callable[[FunctionInvocationContext], Awaitable[None]],
) -> None:
    """Function middleware that logs function execution."""
    # پیش‌پردازش: ثبت لاگ قبل از اجرای تابع
    print(f"[Function] Calling {context.function.name}")

    # ادامه به میان‌افزار بعدی یا اجرای تابع
    await next(context)

    # پس‌پردازش: ثبت لاگ پس از اجرای تابع
    print(f"[Function] {context.function.name} completed")

واسط چت

این واسط اجازه می‌دهد عملی بین نماینده و درخواست‌های بین LLM اجرا یا ثبت شود.

این شامل اطلاعات مهمی مانند messages است که به سرویس هوش مصنوعی ارسال می‌شوند.

async def logging_chat_middleware(
    context: ChatContext,
    next: Callable[[ChatContext], Awaitable[None]],
) -> None:
    """Chat middleware that logs AI interactions."""
    # پیش‌پردازش: ثبت لاگ قبل از فراخوانی هوش مصنوعی
    print(f"[Chat] Sending {len(context.messages)} messages to AI")

    # ادامه به میان‌افزار یا سرویس هوش مصنوعی بعدی
    await next(context)

    # پس‌پردازش: ثبت لاگ پس از پاسخ هوش مصنوعی
    print("[Chat] AI response received")

حافظه نماینده

همان‌طور که در درس Agentic Memory گفته شد، حافظه عنصر مهمی برای امکان کارکرد نماینده در زمینه‌های مختلف است. MAF چندین نوع حافظه متفاوت ارائه می‌دهد:

ذخیره‌سازی در حافظه

این حافظه در رشته‌ها در طول زمان اجرای برنامه ذخیره می‌شود.

# ایجاد یک رشته جدید.
thread = agent.get_new_thread() # اجرای عامل با استفاده از رشته.
response = await agent.run("Hello, I am here to help you book travel. Where would you like to go?", thread=thread)

پیام‌های پایدار

این حافظه برای ذخیره تاریخچه مکالمه در جلسات مختلف استفاده می‌شود. با استفاده از chat_message_store_factory تعریف می‌شود:

from agent_framework import ChatMessageStore

# ایجاد یک فروشگاه پیام سفارشی
def create_message_store():
    return ChatMessageStore()

agent = ChatAgent(
    chat_client=OpenAIChatClient(),
    instructions="You are a Travel assistant.",
    chat_message_store_factory=create_message_store
)

حافظه پویا

این حافظه قبل از اجرای عامل‌ها به متن اضافه می‌شود. این حافظه‌ها می‌توانند در سرویس‌های خارجی مانند mem0 ذخیره شوند:

from agent_framework.mem0 import Mem0Provider

# استفاده از Mem0 برای قابلیت‌های پیشرفته حافظه
memory_provider = Mem0Provider(
    api_key="your-mem0-api-key",
    user_id="user_123",
    application_id="my_app"
)

agent = ChatAgent(
    chat_client=OpenAIChatClient(),
    instructions="You are a helpful assistant with memory.",
    context_providers=memory_provider
)

قابلیت مشاهده عامل

قابلیت مشاهده برای ساخت سیستم‌های عامل قابل اعتماد و قابل نگهداری اهمیت دارد. MAF با OpenTelemetry ادغام می‌شود تا ردیابی و معیارهایی برای مشاهده بهتر فراهم کند.

from agent_framework.observability import get_tracer, get_meter

tracer = get_tracer()
meter = get_meter()
with tracer.start_as_current_span("my_custom_span"):
    # کاری انجام بده
    pass
counter = meter.create_counter("my_custom_counter")
counter.add(1, {"key": "value"})

جریان‌های کاری

MAF جریان‌های کاری را ارائه می‌دهد که گام‌های از پیش تعریف‌شده‌ای برای تکمیل یک وظیفه هستند و عامل‌های هوش مصنوعی را به عنوان اجزا در آن گام‌ها شامل می‌شوند.

جریان‌های کاری از اجزای متفاوتی تشکیل شده‌اند که امکان کنترل بهتر جریان را می‌دهند. جریان‌های کاری همچنین هماهنگی چندعامله و checkpointing برای ذخیره وضعیت جریان کاری را فعال می‌کنند.

اجزای اصلی یک جریان کاری عبارت‌اند از:

اجراکننده‌ها

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

لبه‌ها

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

لبه‌های مستقیم - اتصالات ساده یک‌به‌یک بین اجراکننده‌ها:

from agent_framework import WorkflowBuilder

builder = WorkflowBuilder()
builder.add_edge(source_executor, target_executor)
builder.set_start_executor(source_executor)
workflow = builder.build()

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

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

لبه‌های انشعاب - ارسال یک پیام به چندین مقصد.

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

رویدادها

برای ارائه قابلیت مشاهده بهتر در جریان‌های کاری، MAF رویدادهای ساخته‌شده برای اجرا را ارائه می‌دهد که شامل:

الگوهای پیشرفته MAF

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

میزبانی عامل‌های LangChain / LangGraph روی Microsoft Foundry

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

این کار با بسته langchain_azure_ai.agents.hosting انجام می‌شود که یک گراف کامپایل‌شده LangGraph را از طریق همان پروتکل‌هایی که عوامل میزبانی شده Foundry استفاده می‌کنند، در دسترس قرار می‌دهد.

1. افزودن ماژول میزبانی:

pip install -U "langchain-azure-ai[hosting]>=1.2.4" azure-identity

ماژول hosting کتابخانه‌های پروتکل Foundry را نصب می‌کند: azure-ai-agentserver-responses (نقطه پایانی /responses سازگار با OpenAI) و azure-ai-agentserver-invocations (نقطه پایانی عمومی /invocations).

2. انتخاب پروتکل میزبانی:

پروتکل کلاس میزبان نقطه پایانی استفاده زمانی که
Responses ResponsesHostServer /responses می‌خواهید چت، پخش، تاریخچه پاسخ، و رشته مکالمات سازگار با OpenAI داشته باشید — پیش‌فرض توصیه‌شده برای عامل‌های مکالمه‌ای.
Invocations InvocationsHostServer /invocations به شکل JSON سفارشی، نقطه پایانی به سبک وب‌هوک، یا پردازش غیرمکالمه‌ای نیاز دارید.

چون API Responses، API اصلی برای توسعه عوامل سبک-Agent در Foundry است، برای اکثر عامل‌ها با ResponsesHostServer شروع کنید.

3. پیکربندی متغیرهای محیطی (az login ابتدا برای احراز هویت DefaultAzureCredential):

export FOUNDRY_PROJECT_ENDPOINT="https://<resource>.services.ai.azure.com/api/projects/<project>"
export FOUNDRY_MODEL_NAME="gpt-5-mini"

وقتی عامل بعداً به عنوان عامل میزبانی شده در Foundry اجرا می‌شود، پلتفرم به‌طور خودکار FOUNDRY_PROJECT_ENDPOINT را تزریق می‌کند.

4. عرضه عامل LangGraph از طریق پروتکل Responses:

import os

from azure.ai.projects import AIProjectClient
from azure.identity import DefaultAzureCredential, get_bearer_token_provider
from langchain.agents import create_agent
from langchain_openai import ChatOpenAI
from langchain_azure_ai.agents.hosting import ResponsesHostServer

_AZURE_AI_SCOPE = "https://ai.azure.com/.default"


def build_chat_model() -> ChatOpenAI:
    project_endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"].rstrip("/")
    deployment = os.environ.get("FOUNDRY_MODEL_NAME", "gpt-5-mini")
    credential = DefaultAzureCredential()
    project = AIProjectClient(endpoint=project_endpoint, credential=credential)
    openai_client = project.get_openai_client()
    token_provider = get_bearer_token_provider(credential, _AZURE_AI_SCOPE)

    # اینجا ChatOpenAI به نقطه پایانی سازگار با OpenAI پروژه Foundry (Responses) هدف‌گذاری می‌کند.
    return ChatOpenAI(
        model=deployment,
        base_url=str(openai_client.base_url),
        api_key=token_provider,
    )


def main() -> None:
    graph = create_agent(build_chat_model(), tools=[])
    port = int(os.environ.get("PORT", "8088"))
    ResponsesHostServer(graph).run(port=port)


if __name__ == "__main__":
    main()

آن را به صورت محلی با python main.py اجرا کنید، سپس یک درخواست Responses به http://localhost:8088/responses ارسال کنید.

رفتارهای کلیدی:

نسخه قابل اجرا از این مثال در code-samples/14-langchain-hosted-agent.py موجود است. برای راهنمای کامل (پروتکل Invocations، قالب‌های سفارشی درخواست، و رفع اشکال)، به Host LangGraph agents as Foundry hosted agents مراجعه کنید.

نمونه‌های کد

نمونه‌های کد برای چارچوب عامل مایکروسافت را می‌توان در این مخزن زیر فایل‌های xx-python-agent-framework و xx-dotnet-agent-framework یافت.

سوالات بیشتری درباره چارچوب عامل مایکروسافت دارید؟

به Microsoft Foundry Discord بپیوندید تا با سایر یادگیرندگان ملاقات کنید، در ساعت‌های مشاوره شرکت کنید و سوالات خود درباره عامل‌های هوش مصنوعی را مطرح کنید.

درس قبلی

حافظه برای عامل‌های هوش مصنوعی

درس بعدی

ساخت مأموران استفاده از رایانه (CUA)

سلب مسئولیت: این سند با استفاده از سرویس ترجمه هوش مصنوعی Co-op Translator ترجمه شده است. در حالی که ما در تلاش برای دقت هستیم، لطفاً توجه داشته باشید که ترجمه‌های خودکار ممکن است شامل خطاها یا نادرستی‌هایی باشند. سند اصلی به زبان مادری خود باید به عنوان منبع معتبر در نظر گرفته شود. برای اطلاعات حیاتی، ترجمه حرفه‌ای انسانی توصیه می‌شود. ما در قبال هرگونه سوء تفاهم یا برداشت نادرست ناشی از استفاده از این ترجمه مسئولیتی نداریم.

This site is open source. Improve this page.