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) يعتمد على الخبرة والدروس المستفادة من Semantic Kernel و AutoGen. يوفر المرونة لمعالجة مجموعة واسعة من حالات الاستخدام الوكالية في بيئات الإنتاج والبحث، بما في ذلك:

لتقديم وكلاء ذكاء اصطناعي في الإنتاج، يتضمن MAF ميزات مثل:

يركز إطار عمل Microsoft Agent Framework أيضًا على التوافق من خلال:

لنلقِ نظرة على كيفية تطبيق هذه الميزات على بعض المفاهيم الأساسية لإطار عمل Microsoft Agent Framework.

المفاهيم الأساسية لإطار عمل Microsoft 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 أعلاه، ولكن يمكن إنشاء الوكلاء باستخدام مجموعة متنوعة من الخدمات بما في ذلك Azure AI Foundry Agent Service:

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

واجهات برمجة التطبيقات Responses و ChatCompletion الخاصة بـ OpenAI

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 التي يمكن للوكيل استدعاؤها، وحتى النموذج نفسه المستخدم للوكيل.

هذا مفيد في الحالات التي تتطلب نماذج أو أدوات محددة لإكمال مهمة المستخدم.

الأدوات

يمكن تعريف الأدوات عند تعريف الوكيل:

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


# When creating a ChatAgent directly 

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] # Tool provided for this run only )

سلاسل الوكلاء

تُستخدم سلاسل الوكلاء للتعامل مع المحادثات متعددة الأدوار. يمكن إنشاء السلاسل إما باستخدام:

لإنشاء سلسلة، يبدو الكود كما يلي:

# Create a new thread. 
thread = agent.get_new_thread() # Run the agent with the thread. 
response = await agent.run("Hello, I am here to help you book travel. Where would you like to go?", thread=thread)

يمكنك بعد ذلك تسلسل السلسلة لتخزينها للاستخدام لاحقًا:

# Create a new thread. 
thread = agent.get_new_thread() 

# Run the agent with the thread. 

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

# Serialize the thread for storage. 

serialized_thread = await thread.serialize() 

# Deserialize the thread state after loading from storage. 

resumed_thread = await agent.deserialize_thread(serialized_thread)

وسيط الوكلاء

يتفاعل الوكلاء مع الأدوات و LLMs لإكمال مهام المستخدم. في بعض السيناريوهات، نريد تنفيذ أو تتبع بين هذه التفاعلات. يتيح لنا وسيط الوكلاء القيام بذلك من خلال:

وسيط الوظيفة

يسمح هذا الوسيط بتنفيذ إجراء بين الوكيل والوظيفة/الأداة التي سيقوم باستدعائها. مثال على ذلك هو عندما ترغب في تسجيل استدعاء الوظيفة.

في الكود أدناه، يحدد next ما إذا كان يجب استدعاء الوسيط التالي أو الوظيفة الفعلية.

async def logging_function_middleware(
    context: FunctionInvocationContext,
    next: Callable[[FunctionInvocationContext], Awaitable[None]],
) -> None:
    """Function middleware that logs function execution."""
    # Pre-processing: Log before function execution
    print(f"[Function] Calling {context.function.name}")

    # Continue to next middleware or function execution
    await next(context)

    # Post-processing: Log after function execution
    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."""
    # Pre-processing: Log before AI call
    print(f"[Chat] Sending {len(context.messages)} messages to AI")

    # Continue to next middleware or AI service
    await next(context)

    # Post-processing: Log after AI response
    print("[Chat] AI response received")

ذاكرة الوكلاء

كما تم تغطيته في درس Agentic Memory، تعد الذاكرة عنصرًا مهمًا لتمكين الوكيل من العمل عبر سياقات مختلفة. يوفر MAF عدة أنواع مختلفة من الذكريات:

التخزين في الذاكرة

هذه هي الذاكرة المخزنة في السلاسل أثناء وقت تشغيل التطبيق.

# Create a new thread. 
thread = agent.get_new_thread() # Run the agent with the 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

# Create a custom message store
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

# Using Mem0 for advanced memory capabilities
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"):
    # do something
    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 أحداثًا مدمجة للتنفيذ بما في ذلك:

الانتقال من أطر أخرى (Semantic Kernel و AutoGen)

الفروقات بين MAF و Semantic Kernel

إنشاء الوكلاء المبسط

يعتمد Semantic Kernel على إنشاء مثيل Kernel لكل وكيل. يستخدم MAF نهجًا مبسطًا باستخدام الامتدادات للمزودين الرئيسيين.

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

إنشاء سلاسل الوكلاء

يتطلب Semantic Kernel إنشاء السلاسل يدويًا. في MAF، يتم تعيين السلسلة مباشرة للوكيل.

thread = agent.get_new_thread() # Run the agent with the thread.

تسجيل الأدوات

في Semantic Kernel، يتم تسجيل الأدوات في Kernel ثم يتم تمرير Kernel إلى الوكيل. في MAF، يتم تسجيل الأدوات مباشرة أثناء عملية إنشاء الوكيل.

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

الفروقات بين MAF و AutoGen

الفرق بين الفرق وسير العمل

Teams هي هيكل الأحداث للنشاط المدفوع بالأحداث مع الوكلاء في AutoGen. يستخدم MAF Workflows التي توجه البيانات إلى المنفذين من خلال بنية تعتمد على الرسوم البيانية.

إنشاء الأدوات

يستخدم AutoGen FunctionTool لتغليف الوظائف التي يمكن للوكلاء استدعاؤها. يستخدم MAF @ai_function الذي يعمل بشكل مشابه ولكنه يستنتج المخططات تلقائيًا لكل وظيفة.

سلوك الوكلاء

الوكلاء في AutoGen هم وكلاء ذو دورة واحدة افتراضيًا ما لم يتم تعيين max_tool_iterations إلى قيمة أعلى. في MAF، يكون ChatAgent متعدد الأدوار افتراضيًا مما يعني أنه سيستمر في استدعاء الأدوات حتى يتم إكمال مهمة المستخدم.

عينات الكود

يمكن العثور على عينات الكود الخاصة بـ Microsoft Agent Framework في هذا المستودع تحت ملفات xx-python-agent-framework و xx-dotnet-agent-framework.

هل لديك المزيد من الأسئلة حول Microsoft Agent Framework؟

انضم إلى Azure AI Foundry Discord للتواصل مع متعلمين آخرين، حضور ساعات المكتب والحصول على إجابات لأسئلتك حول وكلاء الذكاء الاصطناعي.

إخلاء المسؤولية:
تم ترجمة هذا المستند باستخدام خدمة الترجمة بالذكاء الاصطناعي Co-op Translator. بينما نسعى لتحقيق الدقة، يرجى العلم أن الترجمات الآلية قد تحتوي على أخطاء أو عدم دقة. يجب اعتبار المستند الأصلي بلغته الأصلية المصدر الرسمي. للحصول على معلومات حاسمة، يُوصى بالترجمة البشرية الاحترافية. نحن غير مسؤولين عن أي سوء فهم أو تفسيرات خاطئة ناتجة عن استخدام هذه الترجمة.

This site is open source. Improve this page.