وكلاء الخلفية

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

Important

وكلاء الخلفية تجريبيون.

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

إعداد وكلاء الخلفية يدويا

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

استيراد BackgroundAgentsProvider وإضافته إلى عامل عادي من خلال ChatClientAgentOptions.AIContextProviders:

using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;

var backgroundProvider = new BackgroundAgentsProvider(
    [webSearchAgent, codeAnalysisAgent]);

AIAgent parentAgent = chatClient.AsAIAgent(new ChatClientAgentOptions
{
    Name = "research-coordinator",
    AIContextProviders = [backgroundProvider],
});

AgentSession session = await parentAgent.CreateSessionAsync();

BackgroundAgentsProviderOptions تخصيص إرشادات الموفر وتنسيق قائمة الوكيل.

from agent_framework import Agent, BackgroundAgentsProvider

background_provider = BackgroundAgentsProvider(
    [web_search_agent, code_analysis_agent],
    wait_timeout_seconds=30,
)

parent_agent = Agent(
    client=client,
    name="research-coordinator",
    context_providers=[background_provider],
)
session = parent_agent.create_session()

مرر instructions= لاستبدال BackgroundAgentsProvider التعليمات الخاصة به. قم بتضمين {background_agents} المكان الذي يجب أن تظهر فيه قائمة العامل التابع المنسقة.

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

Note

موفر وكيل الخلفية المجمع الموضح في هذه الصفحة غير متوفر حاليا في Go.

دورة حياة المهام

يضيف الموفر نفس الأدوات المواجهة للنموذج في .NET Python:

الأداة	إجراء دورة الحياة
background_agents_start_task	بدء مهمة غير محظورة على عامل مسمى وإرجاع معرف المهمة الصحيح الخاص به.
background_agents_wait_for_first_completion	انتظر حتى تصل المهمة الأولى في مجموعة تم توفيرها إلى حالة المحطة الطرفية.
background_agents_get_task_results	إرجاع النص المكتمل أو رسالة فشل أو الحالة الحالية.
background_agents_get_all_tasks	معرفات القوائم والحالات وأسماء الوكلاء والأوصاف.
background_agents_continue_task	تشغيل إدخال المتابعة في جلسة العمل الفرعية الموجودة بعد اكتمال المهمة أو فشلها.
background_agents_clear_completed_task	قم بإزالة مهمة طرفية وحرر جلسة العمل التابعة لها.

تسلسل العامل الأصل النموذجي هو:

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

حالة المهمة هي runningأو completedfailedأو أو lost. تصبح المهمة مفقودة عندما تكون معالجة المهمة قيد المعالجة أو جلسة العمل التابعة غير متوفرة، مثل بعد إعادة تشغيل العملية أو استعادة جلسة العمل. يمكن أن تظل بيانات تعريف المهمة القابلة للتسلسل في جلسة العمل الأصل، ولكن العمل أثناء الطيران ومقابض الجلسة الفرعية لا تنجو من هذا الحد.

لا توجد أداة إلغاء في الموفر. اسمح بتشغيل المهام بالوصول إلى حالة طرفية قبل مسحها.

أعد استخدام نفس جلسة العمل الأصل عبر المنعطفات. تتلقى كل مهمة جلسة عمل تابعة مخصصة. الاستمرار في مهمة طرفية يعيد استخدام تلك الجلسة الفرعية؛ يؤدي مسحه إلى إزالة بيانات تعريف المهمة وإصدار مقبض الجلسة الفرعية.

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

تحرير جلسة عمل أصل من المضيف

Note

إصدار جلسة عمل عامل الخلفية من جانب المضيف غير متوفر حاليا في .NET.

عندما يقوم المضيف بإخلاء جلسة عمل أصل أو تجاهلها، حرر مهمة الموفر قيد المعالجة ومقابض الجلسة الفرعية في كتلة finally :

session = parent_agent.create_session()
try:
    await parent_agent.run("Coordinate the research.", session=session)
finally:
    await background_provider.release_session(session)

release_session(session, *, cancel_running=True, timeout=30.0) هي واجهة برمجة تطبيقات دورة حياة من جانب المضيف، وليست أداة مواجهة للنموذج. بشكل افتراضي، فإنه يلغي تشغيل المهام التابعة وينتظر حتى 30 ثانية للإلغاء قبل تحرير كافة حالة وقت التشغيل لجلسة العمل الأصل. تعيين cancel_running=False لرفض الإصدار أثناء تشغيل المهام، أو تعيين timeout=None للانتظار إلى أجل غير مسمى.

في المقابل، background_agents_clear_completed_task يتيح للنموذج إزالة مهمة طرفية واحدة وجلسة عمل تابعة له أثناء المحادثة. يرفض تشغيل المهام ولا يحل محل تمزق الجلسة الأصل من جانب المضيف.

Note

إصدار جلسة عمل عامل الخلفية من جانب المضيف غير متوفر حاليا في Go.

إضافة انتظار تلقائي يدويا

قم بتضمين الأصل الذي تم تكوينه يدويا باستخدام LoopAgent. BackgroundTaskCompletionLoopEvaluator يستمر فقط أثناء بقاء مهمة في Running الحالة:

AIAgent loopingParent = new LoopAgent(
    parentAgent,
    new BackgroundTaskCompletionLoopEvaluator(),
    new LoopAgentOptions { MaxIterations = 10 });

يتوقف المقيم عن المهام المكتملة والفشلة والمفقودة.

أضف AgentLoopMiddleware إلى الأصل العادي وقم بإقران دالة تقييم مهمة الخلفية مع مساعد الرسالة التالية:

from agent_framework import (
    Agent,
    AgentLoopMiddleware,
    background_tasks_running,
    background_tasks_running_message,
)

parent_agent = Agent(
    client=client,
    context_providers=[background_provider],
    middleware=[
        AgentLoopMiddleware(
            background_tasks_running(),
            next_message=background_tasks_running_message,
            max_iterations=10,
        )
    ],
)

تستمر دالة التقييم فقط بينما لا تزال حالة المهمة المستمرة تبلغ عن مهمة قيد التشغيل.

لا يتوفر تكامل التكرار الحلقي التلقائي للمهمة في الخلفية حاليا في Go.

استخدام وكلاء الخلفية مع Harness Agent

استخدم هذا الإعداد عندما تريد أيضا التخطيط الافتراضي لعامل Harness والذاكرة والموافقة ومسار إمكانية المراقبة.

ضبط HarnessAgentOptions.BackgroundAgents. أضف مقيم الإكمال عندما يجب أن يستمر الأصل في التشغيل حتى لا يكون العمل المفوض قيد التشغيل:

using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;

var options = new HarnessAgentOptions
{
    Name = "research-coordinator",
    BackgroundAgents = [webSearchAgent, codeAnalysisAgent],
    LoopEvaluators = [new BackgroundTaskCompletionLoopEvaluator()],
    LoopAgentOptions = new LoopAgentOptions { MaxIterations = 10 },
};

HarnessAgent parentAgent = chatClient.AsHarnessAgent(options);
// Equivalent construction: new HarnessAgent(chatClient, options)
AgentSession session = await parentAgent.CreateSessionAsync();

يستخدم HarnessAgentOptions.BackgroundAgentsProviderOptions لتخصيص إرشادات الموفر وتنسيق قائمة الوكيل. يحافظ حذف LoopEvaluators التفويض الخلفي على توفره دون إعادة استدعاء تلقائي.

قم بتوفير background_agents إلى create_harness_agent. قم بإقرانه بحلقة محددة عندما يجب على الأصل الانتظار تلقائيا:

from agent_framework import (
    background_tasks_running,
    background_tasks_running_message,
    create_harness_agent,
)

parent_agent = create_harness_agent(
    client=client,
    name="research-coordinator",
    background_agents=[web_search_agent, code_analysis_agent],
    background_agents_wait_timeout_seconds=30,
    loop_should_continue=background_tasks_running(),
    loop_next_message=background_tasks_running_message,
    loop_max_iterations=10,
)
session = parent_agent.create_session()

استخدم background_agents_instructions لاستبدال إرشادات الموفر. background_agents_wait_timeout_seconds تكوين نفس الانتظار المحدد كما في wait_timeout_secondsBackgroundAgentsProvider. يتيح Python harness البرنامج الوسيط للموافقة التلقائية على الأداة بشكل افتراضي، لذا قم بالتمرير session على كل تشغيل.

Note

تفويض خلفية Harness Agent غير متوفر حاليا في Go.

اعتبارات الأمان

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

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

تخطيط العمل وتتبع المهام

التعمق أكثر

• التكرار الحلقي للعامل
• استجابات الخلفية
• جلسات العمل
• عامل Harness