تطبيقات إطار عمل عامل المضيف الذاتي

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

استخدم هذا الخيار عندما تحتاج إلى دمج نقطة نهاية عامل مع البنية الأساسية للتطبيق الحالي. إذا كنت تريد Microsoft Foundry لتشغيل العامل نيابة عنك، فشاهد Foundry Hosted Agents. إذا كنت بحاجة إلى مشغلات دالات Azure أو تنفيذ دائم، فشاهد Durable Extension.

Important

حزم استضافة .NET هي إصدار مسبق. قم بتثبيت الإصدارات التجريبية بشكل صريح ومراجعة ملاحظات الإصدار قبل تحديث نشر الإنتاج.

dotnet add package Microsoft.Agents.AI.Hosting --prerelease

ما يقدمه مساعدو الاستضافة

تدمج Microsoft.Agents.AI.Hosting الحزمة العوامل ومهام سير العمل مع المضيف العام .NET:

• AddAIAgent تسجيل باسم AIAgent مع حقن التبعية.
• AddWorkflow تسجيل سير عمل مسمى. سلسلة AddAsAIAgent لجعل سير العمل متاحا لتكامل البروتوكول من خلال واجهة العامل القياسية.
• IHostedAgentBuilder تكوين خدمات الاستضافة المقترنة بهذا العامل.
• AgentSessionStore يقوم اختياريا بتحميل المثيلات وحفظها AgentSession بواسطة معرف استمرار يوفره التطبيق أو البروتوكول.

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

التكامل مع ASP.NET Core

تستخدم حزمة الاستضافة المشتركة .NET المضيف العام وحقن التبعية. بالنسبة لخادم HTTP، قم بإنشاء تطبيق ASP.NET Core وأضف الحزم الخاصة بالبروتوكول لنقاط النهاية التي تريد كشفها. تقوم هذه الحزم بحل المثيلات المسماة AIAgent من إدخال التبعية وإضافة تعيينات مسار ASP.NET Core.

على سبيل المثال، يمكن أن تعرض حزمة استضافة OpenAI وكيلا مكونا من خلال نقطة نهاية الاستجابات:

dotnet add package Microsoft.Agents.AI.Hosting.OpenAI --prerelease

using Microsoft.Agents.AI.Hosting;

WebApplicationBuilder builder = WebApplication.CreateBuilder(args);

var hostedAgent = builder.AddAIAgent("weather-agent", (_, _) => agent);

WebApplication app = builder.Build();
app.MapOpenAIResponses(hostedAgent);
app.Run();

راجع نقاط النهاية المتوافقة مع OpenAI للتكوين الكامل.

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

إضافة بروتوكولات إلى الخادم الخاص بك

اختر تكاملات البروتوكول التي يحتاجها تطبيقك:

البروتوكول	تكامل
نقاط النهاية المتوافقة مع OpenAI	نقاط نهاية HTTP المتوافقة مع عمليات إكمال الدردشة والاستجابات
A2A	اكتشاف العامل إلى الوكيل والمراسلة ونقاط نهاية المهمة
واجهة مستخدم AG	نقاط نهاية تدفق الأحداث لتطبيقات وكيل الويب

استمرار جلسات العمل المستضافة

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

Important

لا تتضمن MAF مخزن جلسات دائم للأغراض العامة. للإنتاج، قم بتوفير AgentSessionStore تنفيذ مدعوم بالتخزين المناسب للتطبيق الخاص بك.

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

builder.Services.AddSingleton<AgentSessionStore, MyAgentSessionStore>();

var hostedAgent = builder.AddAIAgent("weather-agent", (_, _) => agent);

if (builder.Environment.IsDevelopment())
{
    hostedAgent.WithInMemorySessionStore(withIsolation: false);
}
else
{
    hostedAgent.WithSessionStore((services, _) =>
        services.GetRequiredService<AgentSessionStore>());
}

في هذا المثال، MyAgentSessionStore هو التنفيذ الدائم المقدم من التطبيق الخاص بك. يفترض فرع التطوير بيئة محلية مع مستخدم موثوق به وهو المسار الوحيد الذي يعطل العزل. يحتفظ فرع الإنتاج بسلوك العزل الافتراضي؛ تكوين موفر مفتاح العزل كما هو موضح في متابعة جلسة عمل آمنة.

InMemoryAgentSessionStore يفقد جميع جلسات العمل عند إنهاء العملية ولا يشارك الحالة عبر مثيلات التطبيق. تنفيذ التخزين الخاص AgentSessionStore بك مع التخزين المستمر للاحتفاظ بالجلسات.

ينفذ AgentSessionStore عمليات حفظ والحصول على وحذف غير متزامنة. يتلقى هوية المالك AIAgent ومعرف متابعة مبهم تم تحديده بواسطة تكامل استضافة أو مسار مملوك للتطبيق، ويجب أن يرجع مثيلا مستقلا AgentSession من كل عملية الحصول. تعامل مع معرف المتابعة كمفتاح مبهم في المتاجر المخصصة؛ كيفية تفسير المعرف خاص بالبروتوكول.

التنفيذ الدائم له البنية التالية. استبدل كل كعب الروتين بعمليات لنظام التخزين الذي اخترته:

public sealed class MyAgentSessionStore : AgentSessionStore
{
    public override ValueTask SaveSessionAsync(
        AIAgent agent,
        string sessionStoreId,
        AgentSession session,
        CancellationToken cancellationToken = default)
    {
        // Persist the session using your storage system.
        throw new NotImplementedException();
    }

    public override ValueTask<AgentSession> GetSessionAsync(
        AIAgent agent,
        string sessionStoreId,
        CancellationToken cancellationToken = default)
    {
        // Restore an independent session, or create one when no state exists.
        throw new NotImplementedException();
    }

    public override ValueTask DeleteSessionAsync(
        AIAgent agent,
        string sessionStoreId,
        CancellationToken cancellationToken = default)
    {
        // Delete the stored session if it exists.
        throw new NotImplementedException();
    }
}

السجلات الرئيسية لكل من agent.Id و معتمة sessionStoreId. GetSessionAsync يجب أن ترجع مثيل جلسة عمل مستقلة في كل مكالمة؛ استخدم واجهات برمجة تطبيقات تسلسل جلسة عمل العامل المالك عند تخزين الحالة المتسلسلة. يمكن أن تحتوي جلسات العمل المستمرة على بيانات حساسة، لذا قم بحمايتها باستخدام عناصر التحكم والتشفير المناسبة للوصول.

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

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

متابعة الجلسة الآمنة

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

بالنسبة للتطبيقات ASP.NET Core التي تستخدم المصادقة المستندة إلى المطالبات، قم بتثبيت الحزمة التجريبيةMicrosoft.Agents.AI.Hosting.AspNetCore، وسجل موفر العزل المستند إلى المطالبات، وحافظ على تمكين العزل في مخزن الجلسة:

dotnet add package Microsoft.Agents.AI.Hosting.AspNetCore --prerelease

builder.Services.AddHttpContextAccessor();
builder.Services.UseClaimsBasedAgentIsolation();

بشكل افتراضي، UseClaimsBasedAgentIsolation يستخدم المطالبة ClaimTypes.NameIdentifier . قم بتكوين مطالبة أخرى فقط عندما تكون مستقرة وفريدة عبر كل المتصلين الذين يقدمهم المتجر. لا يقوم موفر العزل بمصادقة الطلبات؛ تكوين المصادقة ASP.NET Core والتخويل بشكل منفصل. مع سلوك العزل الصارم الافتراضي، يفشل الوصول إلى جلسة العمل عندما لا يوفر الأساسي الحالي المطالبة المكونة.

بالنسبة لمضيف غير HTTP أو نموذج إيجار آخر، قم بتسجيل مخصص AgentIsolationKeyProvider. تقوم التحميلات الافتراضية WithInMemorySessionStore() والفوقية WithSessionStore(...) بتضمين المخزن المكون في IsolationKeyScopedAgentSessionStore.

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

إضافة نقطة نهاية متوافقة مع OpenAI

انتقل إلى أبعد من ذلك:

• وكلاء المضيف مع A2A
• إنشاء تطبيقات وكيل الويب باستخدام AG-UI
• وكلاء مستضافون في Foundry

Note

لا يتوفر مساعدو بروتوكول الاستضافة الذاتية حاليا ل Go.

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

استخدم هذا الخيار عندما تحتاج إلى دمج نقطة نهاية عامل مع البنية الأساسية للتطبيق الحالي. إذا كنت تريد Microsoft Foundry لتشغيل العامل نيابة عنك، فشاهد Foundry Hosted Agents. إذا كنت بحاجة إلى مشغلات دالات Azure أو تنفيذ دائم، فشاهد Durable Extension.

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

Important

agent-framework-hosting agent-framework-hosting-mcp agent-framework-hosting-a2a agent-framework-a2a agent-framework-hosting-telegramو agent-framework-hosting-responsesهي حزم Python التجريبية. قم بتثبيت الإصدارات التجريبية بشكل صريح ومراجعة ملاحظات الإصدار قبل تحديث نشر الإنتاج.

pip install --pre agent-framework-hosting

ما يقدمه مساعدو الاستضافة

توفر حزمة الاستضافة العامة حالة تنفيذ مشتركة لخادم مملوك للتطبيق:

• AgentState يقوم بإقران هدف عامل ب SessionStore وينشئ جلسات عمل عندما يحدد التطبيق مفتاحا جديدا.
• SessionStore يخزن جلسات العمل ويستردها ويحذفها بواسطة معرف محدد من قبل التطبيق. المخزن الافتراضي الخاص به محلي للعملية ولا يحتوي على نهج إخلاء.
• WorkflowState يحل هدف سير العمل. يمتلك التطبيق الخاص بك تخزين نقطة التحقق وأي تعيين من معرف متابعة العميل إلى نقطة تحقق.

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

تخصيص تخزين الجلسة

SessionStoreهي فئة تخزين صغيرة غير متزامنة مع getsetأساليب و وdelete. يحافظ التنفيذ الافتراضي على جلسات العمل في ذاكرة المعالجة. قم بتقسيمه الفرعي وتجاوز هذه الطرق لتخزين AgentSession العناصر في Redis أو قاعدة بيانات أو تخزين كائن ثنائي كبير الحجم أو مخزن آخر مملوك للتطبيق، ثم قم بتمرير المثيل إلى AgentState(session_store=...).

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

Note

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

إحضار إطار العمل الخاص بك أو مكتبة العميل

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

• بالنسبة لنقاط نهاية HTTP، استخدم واجهات برمجة التطبيقات للتوجيه والطلب/الاستجابة لإطار عمل التطبيق الخاص بك، مثل FastAPI أو Starlette أو Django أو Flask أو دالات Azure أو إطار عمل آخر.
• بالنسبة لعملاء البروتوكول مثل Telegram، استخدم أي مكتبة عميل يمكنها توفير تحديث بروتوكول وتنفيذ العمليات التي ينتجها المساعد.

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

إضافة بروتوكولات إلى الخادم الخاص بك

اختر واحدا أو أكثر من عمليات تكامل البروتوكول:

البروتوكول	الحزمة والتكامل
استجابات OpenAI	agent-framework-hosting-responses
برقيه	agent-framework-hosting-telegram
A2A	agent-framework-a2a او agent-framework-hosting-a2a
MCP	agent-framework-hosting-mcp

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

متابعة الجلسة الآمنة

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

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

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

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

إضافة بروتوكول استجابات OpenAI

انتقل إلى أبعد من ذلك:

• برقيه
• A2A
• MCP
• وكلاء مستضافون في Foundry