استجابات خلفية العامل

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

Tip

للحصول على مثال عمل كامل، راجع نموذج استجابات الخلفية.

متى تستخدم استجابات الخلفية

تعد استجابات الخلفية مفيدة بشكل خاص ل:

• مهام المنطق المعقدة التي تتطلب وقتا كبيرا في المعالجة
• العمليات التي قد تتم مقاطعتها بسبب مشكلات في الشبكة أو مهلات العميل
• السيناريوهات التي تريد فيها بدء مهمة طويلة الأمد والتحقق مرة أخرى لاحقا من النتائج

كيفية عمل استجابات الخلفية

تستخدم استجابات الخلفية آلية رمز متابعة للتعامل مع العمليات طويلة الأمد. عند إرسال طلب إلى عامل مع تمكين استجابات الخلفية، يحدث أحد أمرين:

1. الإكمال الفوري: يكمل العامل المهمة بسرعة ويعيد الاستجابة النهائية دون رمز متابعة مميز
2. معالجة الخلفية: يبدأ العامل المعالجة في الخلفية ويعيد رمز متابعة بدلا من النتيجة النهائية

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

تمكين استجابات الخلفية

لتمكين استجابات الخلفية، قم بتعيين الخاصية AllowBackgroundResponses إلى true في AgentRunOptions:

AgentRunOptions options = new()
{
    AllowBackgroundResponses = true
};

Note

حاليا، فقط الوكلاء الذين يستخدمون واجهة برمجة تطبيقات استجابات OpenAI يدعمون استجابات الخلفية: عامل استجابات OpenAIوعامل استجابات OpenAI Azure.

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

الاستجابات الخلفية غير المتدفقة

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

AIAgent agent = new AIProjectClient(
    new Uri("<your-foundry-project-endpoint>"),
    new DefaultAzureCredential())
    .AsAIAgent(model: "<deployment-name>", instructions: "You are a helpful assistant.");

AgentRunOptions options = new()
{
    AllowBackgroundResponses = true
};

AgentSession session = await agent.CreateSessionAsync();

// Get initial response - may return with or without a continuation token
AgentResponse response = await agent.RunAsync("Write a very long novel about otters in space.", session, options);

// Continue to poll until the final response is received
while (response.ContinuationToken is not null)
{
    // Wait before polling again.
    await Task.Delay(TimeSpan.FromSeconds(2));

    options.ContinuationToken = response.ContinuationToken;
    response = await agent.RunAsync(session, options);
}

Console.WriteLine(response.Text);

تحذير

DefaultAzureCredential مناسب للتنمية ولكنه يتطلب دراسة متأنية في الإنتاج. في الإنتاج، ضع في اعتبارك استخدام بيانات اعتماد محددة (على سبيل المثال، ManagedIdentityCredential) لتجنب مشكلات زمن الانتقال، وبحث بيانات الاعتماد غير المقصودة، والمخاطر الأمنية المحتملة من الآليات الاحتياطية.

نقاط رئيسية:

• قد يكتمل الاستدعاء الأولي على الفور (لا يوجد رمز مميز للمتابعة) أو بدء عملية في الخلفية (مع رمز المتابعة المميز)
• إذا لم يتم إرجاع رمز مميز للمتابعة، تكتمل العملية وتحتوي الاستجابة على النتيجة النهائية
• إذا تم إرجاع رمز مميز للمتابعة، فقد بدأ العامل عملية خلفية تتطلب الاستقصاء
• استخدام الرمز المميز للمتابعة من الاستجابة السابقة في مكالمات التحقق اللاحقة
• عندما ContinuationToken يكون null، تكتمل العملية

استجابات الخلفية المتدفقة

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

AIAgent agent = new AIProjectClient(
    new Uri("<your-foundry-project-endpoint>"),
    new DefaultAzureCredential())
    .AsAIAgent(model: "<deployment-name>", instructions: "You are a helpful assistant.");

AgentRunOptions options = new()
{
    AllowBackgroundResponses = true
};

AgentSession session = await agent.CreateSessionAsync();

AgentResponseUpdate? latestReceivedUpdate = null;

await foreach (var update in agent.RunStreamingAsync("Write a very long novel about otters in space.", session, options))
{
    Console.Write(update.Text);

    latestReceivedUpdate = update;

    // Simulate an interruption
    break;
}

// Resume from interruption point captured by the continuation token
options.ContinuationToken = latestReceivedUpdate?.ContinuationToken;
await foreach (var update in agent.RunStreamingAsync(session, options))
{
    Console.Write(update.Text);
}

نقاط رئيسية:

• يحتوي كل AgentResponseUpdate منها على رمز مميز للمتابعة يمكن استخدامه لاستئنافه
• تخزين الرمز المميز للمتابعة من آخر تحديث تم تلقيه قبل الانقطاع
• استخدم رمز المتابعة المخزن لاستئناف الدفق من نقطة الانقطاع

Tip

راجع نماذج .NET للحصول على أمثلة كاملة قابلة للتشغيل.

Tip

للحصول على مثال عمل كامل، راجع نموذج استجابات الخلفية.

تمكين استجابات الخلفية

لتمكين استجابات الخلفية، مرر background الخيار عند استدعاء agent.run():

session = agent.create_session()
response = await agent.run(
    messages="Your prompt here",
    session=session,
    options={"background": True},
)

Note

حاليا، فقط الوكلاء الذين يستخدمون واجهة برمجة تطبيقات استجابات OpenAI يدعمون استجابات الخلفية: عامل استجابات OpenAIوعامل استجابات OpenAI Azure.

الاستجابات الخلفية غير المتدفقة

بالنسبة للسيناريوهات غير المتدفقة، عند تشغيل عامل في البداية باستخدام background=True، قد يعود على الفور باستخدام continuation_token. إذا كان continuation_token هو None، فقد اكتملت العملية. وإلا، يتم الاستقصاء عن طريق تمرير الرمز المميز مرة أخرى في المكالمات اللاحقة:

import asyncio
from agent_framework import Agent
from agent_framework.openai import OpenAIChatClient

agent = Agent(
    name="researcher",
    instructions="You are a helpful research assistant.",
    client=OpenAIChatClient(model="o3"),
)

session = agent.create_session()

# Start a background run — returns immediately
response = await agent.run(
    messages="Briefly explain the theory of relativity in two sentences.",
    session=session,
    options={"background": True},
)

# Poll until the operation completes
while response.continuation_token is not None:
    await asyncio.sleep(2)
    response = await agent.run(
        session=session,
        options={"continuation_token": response.continuation_token},
    )

# Done — response.text contains the final result
print(response.text)

النقاط الرئيسية

• قد يكتمل الاستدعاء الأولي على الفور (لا يوجد رمز مميز للمتابعة) أو بدء عملية في الخلفية (مع رمز المتابعة المميز)
• continuation_token استخدم من الاستجابة السابقة في مكالمات الاستقصاء اللاحقة
• عندما continuation_token يكون None، تكتمل العملية

استجابات الخلفية المتدفقة

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

session = agent.create_session()

# Start a streaming background run
last_token = None
stream = agent.run(
    messages="Briefly list three benefits of exercise.",
    stream=True,
    session=session,
    options={"background": True},
)

# Read chunks — each update carries a continuation_token
async for update in stream:
    last_token = update.continuation_token
    if update.text:
        print(update.text, end="", flush=True)
    # If interrupted (e.g., network issue), break and resume later

استئناف الدفق المتقطع

إذا تمت مقاطعة الدفق، فاستخدم آخر continuation_token استئناف من حيث توقف:

if last_token is not None:
    stream = agent.run(
        stream=True,
        session=session,
        options={"continuation_token": last_token},
    )
    async for update in stream:
        if update.text:
            print(update.text, end="", flush=True)

النقاط الرئيسية

• يحتوي كل AgentResponseUpdate منها على continuation_token استئناف
• تخزين الرمز المميز من آخر تحديث تم تلقيه قبل المقاطعة
• تمرير الرمز المميز المخزن عبر options={"continuation_token": token} لاستئناف

استجابات الخلفية

يدعم وكلاء Go استجابات الخلفية من agent.AllowBackgroundResponses خلال الخيار . وهذا يمكن العامل من إنتاج استجابات غير متزامنة يمكن استردادها لاحقا.

resp, err := a.RunText(ctx, "Start a long analysis.",
    agent.WithSession(session),
    agent.AllowBackgroundResponses(true),
).Collect()

تتطلب استجابات الخلفية جلسة عمل صريحة عبر agent.WithSession(session) لضمان سلوك متسق بين عمليات التشغيل الأولية والمتابعة.

استخدام استجابات الخلفية مع Harness Agent

يظل عامل Harness عامل إطار عمل عامل قياسي، لذلك تستخدم استجابات خلفية الموفر نفس الخيارات لكل تشغيل الموثقة أعلاه. لا يمكن بناء Harness استجابات خلفية الموفر تلقائيا: يتم تعيينه AllowBackgroundResponses في .NET أو options={"background": True} في Python عند بدء التشغيل، والحفاظ على جلسة العمل، واستمرار رموز المتابعة المميزة عندما يجب أن تنجو العملية من إعادة تشغيل العملية.

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

أفضل الممارسات

عند العمل مع استجابات الخلفية، ضع في اعتبارك أفضل الممارسات التالية:

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

القيود والاعتبارات

• تعتمد استجابات الخلفية على خدمة الذكاء الاصطناعي الأساسية التي تدعم العمليات طويلة الأمد
• لا تدعم كافة أنواع الوكلاء استجابات الخلفية
• قد تتطلب انقطاعات الشبكة أو عمليات إعادة تشغيل العميل معالجة خاصة لاستمرار الرموز المميزة للمتابعة

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

القماش