ai-agents-for-beginners

کاوش در Microsoft Agent Framework

چارچوب عامل

مقدمه

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

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

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

نمونه کدها

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

درک Microsoft Agent Framework

معرفی چارچوب

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

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

Microsoft Agent Framework همچنین تمرکز زیادی بر وابستگی‌ناپذیری دارد از جمله:

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

مفاهیم کلیدی Microsoft 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، ChatCompletion APIها

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.", )

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

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

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

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

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

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

اجراآکنندگان

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

لبه‌ها

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

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

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 Framework را پوشش می‌دهند. هنگامی که عامل‌های پیچیده‌تری می‌سازید، در نظر گرفتن الگوهای پیشرفته زیر کمک کننده است:

نمونه کدها

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

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

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

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

This site is open source. Improve this page.