ai-agents-for-beginners

بررسی چارچوب Microsoft Agent

Agent Framework

معرفی

این درس شامل موارد زیر است:

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

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

نمونه‌های کد

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

درک چارچوب Microsoft Agent

Framework Intro

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

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

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

بیایید ببینیم چگونه این ویژگی‌ها در برخی از مفاهیم اصلی چارچوب Microsoft Agent اعمال می‌شوند.

مفاهیم کلیدی چارچوب Microsoft Agent

عوامل

Agent Framework

ایجاد عوامل

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

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

OpenAI Responses، APIهای 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 با پنجره‌های زمینه بزرگ (تا 204 هزار توکن) ارائه می‌دهد:

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)

میان‌افزار عامل

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

میان‌افزار تابع

این میان‌افزار امکان اجرای عملی بین عامل و تابع/ابزاری که فراخوانی می‌کند فراهم می‌نماید. مثالی از کاربرد آن وقتی است که می‌خواهید روی فراخوانی تابع لاگ‌برداری انجام دهید.

در کد زیر 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")

میان‌افزار چت

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

این شامل اطلاعات مهمی مانند 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")

حافظه عامل

همانطور که در درس حافظه عاملی پوشش داده شده است، حافظه نقش مهمی در توانمندسازی عامل برای کار در بافت‌های مختلف دارد. 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 جریان‌های کاری را ارائه می‌دهد که گام‌های از پیش تعریف‌شده برای کامل کردن یک وظیفه هستند و عوامل هوش مصنوعی را به عنوان اجزا در آن مراحل شامل می‌شوند.

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

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

مجریان

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

لبه‌ها

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

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

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

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

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

چارچوب Microsoft Agent قابلیت همکاری چارچوبی دارد — شما محدود به عوامل نوشته شده با MAF نیستید. اگر قبلاً عاملی با LangChain یا LangGraph ساخته‌اید، می‌توانید آن را به عنوان عامل میزبانی شده در Microsoft 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 (نقطه پایانی سازگار با OpenAI /responses) و azure-ai-agentserver-invocations (نقطه پایانی عمومی /invocations).

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

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

چون API پاسخ‌ها (Responses) API اصلی برای توسعه به سبک عامل‌ها در 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 در اینجا به نقطه پایانی (Responses) سازگار با OpenAI پروژه Foundry اشاره دارد.
    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، اسکیمای درخواست سفارشی، و رفع خطا) به میزبانی عوامل LangGraph به عنوان عوامل میزبانی شده Foundry مراجعه کنید.

نمونه‌های کد

نمونه‌های کد برای چارچوب Microsoft Agent در این مخزن زیر فایل‌های xx-python-agent-framework و xx-dotnet-agent-framework قرار دارند.

سوالات بیشتری درباره چارچوب Microsoft Agent دارید؟

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

درس قبلی

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

درس بعدی

ساخت عوامل استفاده‌کننده از کامپیوتر (CUA)

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

This site is open source. Improve this page.