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)، مجموعة التعليمات التي يجب على وكيل الذكاء الاصطناعي اتباعها، والاسم المعين:

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

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


# عند إنشاء 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")

برنامج وسيط الدردشة

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

يحتوي هذا على معلومات مهمة مثل الرسائل التي يتم إرسالها إلى خدمة الذكاء الاصطناعي.

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 سير عمل هي خطوات محددة مسبقًا لإكمال مهمة وتتضمن وكلاء الذكاء الاصطناعي كمكونات في تلك الخطوات.

يتألف سير العمل من مكونات مختلفة تسمح بتحكم أفضل في التدفق. كما يتيح سير العمل تنسيق عدة وكلاء وحفظ نقاط التفتيش لحفظ حالات سير العمل.

المكونات الأساسية لسير العمل هي:

المنفذون (Executors)

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

الحواف (Edges)

تُستخدم الحواف لتعريف تدفق الرسائل في سير العمل. يمكن أن تكون:

حواف مباشرة - اتصالات بسيطة واحد إلى واحد بين المنفذين:

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. مع بناء وكلاء أكثر تعقيدًا، إليك بعض الأنماط المتقدمة للنظر فيها:

عينات الشفرة

عينات الشفرة لإطار عمل Microsoft Agent يمكن العثور عليها في هذا المستودع تحت ملفات xx-python-agent-framework وxx-dotnet-agent-framework.

هل لديك المزيد من الأسئلة حول إطار عمل Microsoft Agent؟

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

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

This site is open source. Improve this page.