بنية البنية الأساسية لبرنامج ربط العمليات التجارية للعامل

يستخدم الوكلاء في Microsoft Agent Framework بنية البنية الأساسية لبرنامج ربط العمليات التجارية ذات الطبقات لمعالجة الطلبات. يساعدك فهم هذه البنية على تخصيص سلوك العامل عن طريق إضافة البرامج الوسيطة أو موفري السياق أو التعديلات على مستوى العميل في الطبقة المناسبة.

مسار ChatClientAgent

تبني ChatClientAgent البنية الأساسية لبرنامج ربط العمليات التجارية بثلاث طبقات رئيسية:

1. البرنامج الوسيط للعامل - مصممات اختيارية تقوم بتضمين العامل عبر .Use() للتسجيل أو التحقق من الصحة أو التحويل
2. طبقة السياق - إدارة محفوظات الدردشة (ChatHistoryProvider) وحقن سياق إضافي (AIContextProviders)
3. طبقة عميل الدردشة - مع IChatClient مصممات البرامج الوسيطة الاختيارية التي تتعامل مع اتصال LLM

عند استدعاء RunAsync()، يتدفق طلبك عبر كل طبقة في تسلسل.

البنية الأساسية لبرنامج ربط العمليات التجارية للعامل

تنشئ Agent الفئة البنية الأساسية لبرنامج ربط العمليات التجارية من خلال تكوين الفئة مع مكونين رئيسيين:

العامل (المكون الخارجي):

1. Agent Middleware + Telemetry - AgentMiddlewareLayer تتعامل فئتا و AgentTelemetryLayer مع استدعاء البرامج الوسيطة وOpenTelemetry instrumentation
2. RawAgent - منطق العامل الأساسي الذي يستدعي موفري السياق ويجمع البرامج الوسيطة المضافة من قبل الموفر
3. موفرو السياق - تدير القائمة الموحدة context_providers المحفوظات والسياق الإضافي والبرامج الوسيطة للدردشة/الوظيفة لكل تشغيل

ChatClient (مكون منفصل وقابل للتبديل):

1. FunctionInvocation - يعالج حلقة استدعاء الأداة، استدعاء Function Middleware + Telemetry لكل استدعاء أداة
2. Chat Middleware + Telemetry - سلسلة البرامج الوسيطة الاختيارية وطبقات الأجهزة، بما في ذلك أي برنامج وسيط دردشة تمت إضافته بواسطة موفري السياق، يتم تشغيله لكل مكالمة نموذج
3. RawChatClient - التنفيذ الخاص بالموفر (Azure OpenAI وOpenAI Anthropic وما إلى ذلك) الذي يتصل ب LLM

عند استدعاء run()، يتدفق طلبك عبر طبقات العامل، ثم إلى مسار ChatClient لاتصال LLM.

تقوم إمكانية Agent Hooks الاختيارية بتثبيت مجموعة برامج وسيطة واحدة عبر طبقات العامل والدردشة والدالة. تعمل بوابات الدفق والمثابرة الأساسية على توسيع هذه الحدود بحيث لا يتم تحرير الإخراج أو تخزينه قبل أن يسمح الحكم المعمول به بذلك.

بنية البنية الأساسية لبرنامج ربط العمليات التجارية للعامل

في Go، يستخدم الوكلاء البنية الأساسية لبرنامج ربط العمليات التجارية للبرامج الوسيطة ذات الطبقات. تقوم البرامج الوسيطة بتضمين وظيفة العامل Run ، كل استدعاء next لتمرير عنصر التحكم إلى الطبقة التالية.

عند تشغيل عامل، يتم تطبيق دورة حياته بهذا الترتيب:

1. البرنامج الوسيط للوكيل المخصص - تم تسجيله agent.Config.Middlewares، المطبق بترتيب الإعلان حول دورة حياة العامل بأكملها
2. موفر المحفوظات - تحميل الرسائل السابقة وتخزين رسائل الطلب/الاستجابة لاحقا
3. موفرو السياق - إدخال السياق والخيارات والحالة من المثيلات المسجلة agent.ContextProvider
4. البرنامج الوسيط للموفر - البرامج الوسيطة المسجلة من قبل الموفر مثل الاستدعاء التلقائي للأداة والمخرجات المنظمة وتأليف الاستجابة
5. الموفر - موفر LLM الأساسي، مثل OpenAI أو Anthropic

طبقة البرنامج الوسيط للعامل

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

إضافة برنامج وسيط باستخدام نمط منشئ العامل:

var middlewareAgent = originalAgent
    .AsBuilder()
    .Use(runFunc: MyAgentMiddleware, runStreamingFunc: MyStreamingMiddleware)
    .Build();

يمكنك أيضا استخدام MessageAIContextProvider كبرنامج وسيط عامل لإدخال رسائل إضافية في الطلب. يعمل هذا مع أي نوع عامل، وليس فقط ChatClientAgent:

var contextAgent = originalAgent
    .AsBuilder()
    .UseAIContextProviders(new MyMessageContextProvider())
    .Build();

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

إضافة برنامج وسيط عند إنشاء العامل:

from agent_framework import Agent

agent = Agent(
    client=my_client,
    instructions="You are helpful.",
    middleware=[my_middleware_func],
)

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

أضف البرامج الوسيطة عن طريق تنفيذ الواجهة Middleware أو استخدام agent.MiddlewareFunc للبرامج الوسيطة الخفيفة:

type Middleware interface {
    Run(next RunFunc, ctx context.Context, messages []*message.Message,
        options ...agent.Option) iter.Seq2[*agent.ResponseUpdate, error]
}

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

timing := agent.MiddlewareFunc(
    func(next agent.RunFunc, ctx context.Context, messages []*message.Message, options ...agent.Option) iter.Seq2[*agent.ResponseUpdate, error] {
        start := time.Now()
        return func(yield func(*agent.ResponseUpdate, error) bool) {
            defer log.Printf("agent run completed in %s", time.Since(start))
            for update, err := range next(ctx, messages, options...) {
                if !yield(update, err) {
                    return
                }
            }
        }
    },
)

a := foundryprovider.NewAgent(endpoint, token, foundryprovider.ModelDeployment(model), foundryprovider.AgentConfig{
    Config: agent.Config{
        Middlewares: []agent.Middleware{timing},
    },
})

للحصول على أنماط البرامج الوسيطة والملاحظة التفصيلية، راجع البرنامج الوسيط للعاملوإمكانية المراقبة.

طبقة السياق

يتم تشغيل طبقة السياق قبل كل استدعاء LLM لإنشاء محفوظات الرسائل الكاملة وحقن سياق إضافي.

ChatClientAgent يحتوي على نوعين متميزين من الموفرين:

• ChatHistoryProvider (مفرد) - إدارة تخزين محفوظات المحادثات واستردادها
• AIContextProviders (قائمة) - إدخال سياق إضافي مثل الذكريات أو المستندات المستردة أو الإرشادات الديناميكية

var agent = new ChatClientAgent(chatClient, new ChatClientAgentOptions
{
    ChatHistoryProvider = new InMemoryChatHistoryProvider(),
    AIContextProviders = [new MyMemoryProvider(), new MyRagProvider()],
});

يستدعي العامل أسلوب كل موفر InvokingAsync() قبل إرسال رسائل إلى عميل الدردشة مع تمرير إخراج كل موفر كمدخل إلى الموفر التالي.

Agent تستخدم الفئة قائمة موحدة context_providers يمكن أن تتضمن كل من موفري المحفوظات وموفري السياق:

from agent_framework import Agent, InMemoryHistoryProvider

agent = Agent(
    client=my_client,
    context_providers=[
        InMemoryHistoryProvider(),
        MyMemoryProvider(),
        MyRagProvider(),
    ],
)

يمكن لموفري السياق أيضا إرفاق الدردشة أو البرامج الوسيطة الوظيفية لاستدعاء واحد عبر SessionContext.extend_middleware(). يقوم العامل بتسطيح هذه الإضافات بترتيب الموفر قبل إدخال مسار ChatClient.

يعمل موفرو السياق داخل دورة حياة العامل بعد أن يدخل البرنامج الوسيط المخصص في التشغيل وقبل أن يستدعي البرنامج الوسيط للموفر النموذج. يمكن لموفري السياق إضافة رسائل أو خيارات قبل استدعاء الموفر واستمرار الحالة بعد التشغيل.

a := foundryprovider.NewAgent(endpoint, token, foundryprovider.ModelDeployment(model), foundryprovider.AgentConfig{
    Config: agent.Config{
        ContextProviders: []agent.ContextProvider{memoryProvider},
    },
})

للحصول على أنماط موفر سياق مفصلة، راجع موفري السياق.

طبقة عميل الدردشة

تعالج طبقة عميل الدردشة الاتصال الفعلي مع خدمة LLM.

ChatClientAgent يستخدم مثيلا IChatClient ، والذي يمكن تزيينه ببرمجيات وسيطة إضافية:

var chatClient = new AIProjectClient(endpoint, credential)
    .GetProjectOpenAIClient()
    .GetProjectResponsesClient()
    .AsIChatClient(deploymentName)
    .AsBuilder()
    .Use(CustomChatClientMiddleware)
    .Build();

var agent = new ChatClientAgent(chatClient, instructions: "You are helpful.");

يمكنك أيضا استخدام AIContextProvider كبرنامج وسيط لعميل الدردشة لإثراء الرسائل والأدوات والإرشادات على مستوى العميل. يجب استخدام هذا في سياق تشغيل AIAgent:

var chatClient = new AIProjectClient(endpoint, credential)
    .GetProjectOpenAIClient()
    .GetProjectResponsesClient()
    .AsIChatClient(deploymentName)
    .AsBuilder()
    .UseAIContextProviders(new MyContextProvider())
    .Build();

var agent = new ChatClientAgent(chatClient, instructions: "You are helpful.");

بشكل افتراضي، ChatClientAgent يلتف عميل الدردشة المتوفر مع دعم استدعاء الوظيفة. تعيين UseProvidedChatClientAsIs = true خيارات لتخطي هذا الالتفاف الافتراضي.

Agent تقبل الفئة أي عميل ينفذ SupportsChatGetResponse. يعالج مسار ChatClient البرامج الوسيطة وبيانات تتبع الاستخدام واستدعاء الوظيفة والاتصال الخاص بالموفر:

from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient

client = FoundryChatClient(
    credential=credential,
    project_endpoint=endpoint,
    model=model,
)

agent = Agent(client=client, instructions="You are helpful.")

داخل RawChatClient ChatClient ينفذ المنطق الخاص بالموفر للتواصل مع خدمات LLM المختلفة.

يعمل البرنامج الوسيط للموفر بعد موفري المحفوظات والسياق، مباشرة قبل موفر LLM الأساسي. يتم تسجيل المساعدين على مستوى العامل مثل OpenTelemetry وتسجيل التشغيل كبرنامج وسيط مخصص للعامل والتفاف خطوات دورة الحياة السابقة.

المكون	التسجيل	الطبقة	الغرض
مكالمة تلقائية	agent/harness/toolautocall	البرامج الوسيطة لموفر الخدمة	استدعاء أدوات الدالة تلقائيا
الإنتاج المنظم	agent.WithStructuredOutput	البرامج الوسيطة لموفر الخدمة	يعالج تحليل الإخراج المنظم
التتبع المفتوح	provider/otelprovider	البرنامج الوسيط للعامل	تتبع استدعاءات العامل
تشغيل المسجل	agent.Config.Logger	البرنامج الوسيط للعامل	تفاعلات عامل السجلات

agent.ContextProvider القيم هي مكونات دورة الحياة بدلا من agent.Middleware عمليات التنفيذ. يتم تشغيلها بين البرامج الوسيطة المخصصة للعامل والبرامج الوسيطة لموفر الخدمة.

تدفق التنفيذ.

عند استدعاء عامل، يتدفق الطلب عبر البنية الأساسية لبرنامج ربط العمليات التجارية:

1. يتم تنفيذ البرنامج الوسيط للعامل (إذا تم تكوينه)
2. يقوم ChatHistoryProvider بتحميل محفوظات المحادثات في قائمة رسائل الطلب
3. يضيف AIContextProviders رسائل أو أدوات أو إرشادات إلى الطلب
4. يتم تنفيذ البرامج الوسيطة IChatClient (إذا تم تزيينها)
5. يرسل IChatClient الطلب إلى LLM
6. تتدفق الاستجابة مرة أخرى عبر الطبقات نفسها
7. يتم إعلام ChatHistoryProviderوIContextProviders بالرسائل الجديدة

البنية الأساسية لبرنامج ربط العمليات التجارية للعامل:

1. يقوم الوكيل Middleware + Telemetry بتنفيذ البرامج الوسيطة (إذا تم تكوينها) وتمتد السجلات
2. يستدعي RawAgent موفري السياق لتحميل المحفوظات وإضافة السياق وجمع الدردشة/البرامج الوسيطة للدالة المضافة من قبل الموفر
3. يتم تمرير الطلب إلى ChatClient

مسار ChatClient:

4. يقوم FunctionInvocation بإدارة حلقة استدعاء الأداة
   • لكل استدعاء أداة، يتم تنفيذ Function Middleware + Telemetry ، بما في ذلك أي برنامج وسيط دالة تمت إضافته بواسطة موفري السياق
5. يتم تنفيذ برنامج الدردشة الوسيط + القياس عن بعد لكل مكالمة نموذج (إذا تم تكوينها)، بما في ذلك أي برنامج وسيط دردشة تمت إضافته بواسطة موفري السياق
6. يعالج RawChatClient اتصال LLM الخاص بموفر الخدمة
7. تتدفق الاستجابة مرة أخرى عبر الطبقات نفسها
8. يتم إعلام موفري السياق بالرسائل الجديدة للتخزين

Note

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

1. ينفذ البرنامج الوسيط للعامل المخصص أولا ويغلف دورة حياة العامل الكاملة.
2. يقوم موفر المحفوظات بتحميل محفوظات المحادثات لجلسة العمل الحالية عندما تكون المحفوظات المحلية نشطة.
3. يضيف موفرو السياق رسائل أو خيارات أو حالة قبل استدعاء الموفر.
4. ينفذ برنامج وسيط الموفر، بما في ذلك أداة الاتصال التلقائي بالبرنامج الوسيط ومعالجة الإخراج المنظم عند التمكين.
5. يرسل الموفر الطلب إلى النموذج.
6. تتدفق تحديثات الاستجابة مرة أخرى من خلال برنامج وسيط موفر البرامج الوسيطة والبرامج الوسيطة المخصصة للعامل.
7. يخزن موفرو المحفوظاتوموفرو السياق حالة الاستجابة بعد نجاح التشغيل.

أنواع عوامل أخرى

لا يستخدم جميع العوامل البنية الأساسية لبرنامج ربط العمليات التجارية الكاملة ChatClientAgent . وكلاء مثل A2AAgentأو GitHubCopilotAgentأو CopilotStudioAgent يتواصلون مع الخدمات البعيدة بدلا من استخدام محلي IChatClient. ومع ذلك، فإنها لا تزال تدعم البرامج الوسيطة على مستوى العامل.

نظرا لأن هذه العوامل مشتقة من AIAgent، يمكنك استخدام نفس أنماط البرنامج الوسيط للعامل:

// Agent middleware works with any AIAgent
var a2aAgent = originalA2AAgent
    .AsBuilder()
    .Use(runFunc: LoggingMiddleware)
    .UseAIContextProviders(new MyMessageContextProvider())
    .Build();

// Same pattern works for GitHubCopilotAgent
var copilotAgent = originalCopilotAgent
    .AsBuilder()
    .Use(runFunc: AuditMiddleware)
    .Build();

Note

لا يمكنك إضافة برنامج وسيط لعميل الدردشة إلى هؤلاء الوكلاء لأنهم لا يستخدمون IChatClient.

أنواع عوامل أخرى

لا يستخدم كل عامل Python البنية الأساسية لبرنامج ربط العمليات التجارية الكاملةAgent + ChatClient. GitHubCopilotAgent، على سبيل المثال، يرسل طلبات من خلال GitHub Copilot CLI بدلا من عميل دردشة محلي.

ومع ذلك، لا يزال Python GitHubCopilotAgent يدعم البرامج الوسيطة للعامل ويعمل الآن context_providers حول كل استدعاء. يتم تضمين الرسائل والإرشادات التي أضافها الموفر في المطالبة المرسلة إلى Copilot، ويتلقى الموفرون رد الاتصال المطابق after_run بمجرد توفر استجابة.

Note

نظرا لعدم GitHubCopilotAgent استخدام عميل دردشة محلي، لا يزال البرنامج الوسيط لعميل الدردشة لا ينطبق.

الخطوات التالية

فهم توجيه نموذج وقت التشغيل

المحتوى ذو الصلة

• برنامج وسيط - إضافة سلوك شامل إلى وكلائك
• موفرو السياق - أنماط مفصلة لحقن المحفوظات والسياق
• عوامل التشغيل - كيفية استدعاء العوامل