إشعار
يتطلب الوصول إلى هذه الصفحة تخويلاً. يمكنك محاولة تسجيل الدخول أو تغيير الدلائل.
يتطلب الوصول إلى هذه الصفحة تخويلاً. يمكنك محاولة تغيير الدلائل.
AG-UI هو بروتوكول يمكنك من إنشاء تطبيقات عامل الذكاء الاصطناعي المستندة إلى الويب مع ميزات متقدمة مثل الدفق في الوقت الحقيقي وإدارة الحالة ومكونات واجهة المستخدم التفاعلية. يوفر تكامل إطار عمل العامل AG-UI اتصالا سلسا بين وكلائك وعملاء الويب.
ما هو AG-UI؟
AG-UI هو بروتوكول موحد لبناء واجهات عامل الذكاء الاصطناعي التي توفر:
- استضافة الوكيل البعيد: نشر عوامل الذكاء الاصطناعي كخدمات ويب يمكن لعدة عملاء الوصول إليها
- الدفق في الوقت الحقيقي: استجابات عامل الدفق باستخدام أحداث Server-Sent (SSE) للحصول على ملاحظات فورية
- الاتصالات الموحدة: تنسيق رسالة متسق لتفاعلات الوكيل الموثوق بها
- إدارة الجلسة: الحفاظ على سياق المحادثة عبر طلبات متعددة
- الميزات المتقدمة: الموافقات البشرية في التكرار الحلقي ومزامنة الحالة وعرض واجهة المستخدم المخصصة
متى تستخدم AG-UI
ضع في اعتبارك استخدام AG-UI عندما تحتاج إلى:
- إنشاء تطبيقات الويب أو الأجهزة المحمولة التي تتفاعل مع وكلاء الذكاء الاصطناعي
- نشر العوامل كخدمات يمكن الوصول إليها من قبل عدة مستخدمين متزامنين
- استجابات عامل الدفق في الوقت الفعلي لتقديم ملاحظات المستخدم الفورية
- تنفيذ مهام سير عمل الموافقة حيث يؤكد المستخدمون الإجراءات قبل التنفيذ
- مزامنة الحالة بين العميل والخادم للحصول على تجارب تفاعلية
- عرض مكونات واجهة المستخدم المخصصة استنادا إلى استدعاءات أداة العامل
سيناريوهات AG-UI
يحدد AG-UI سبعة سيناريوهات للعرض. يختلف دعم MAF حسب SDK؛ استخدم القسم الخاص باللغة في هذه الصفحة للحصول على مستوى الدعم الحالي وإرشادات التنفيذ.
- دردشة عاملية: دردشة دفق أساسية مع استدعاء أداة تلقائية
- عرض أداة الواجهة الخلفية: الأدوات المنفذة على الخلفية مع تدفق النتائج إلى العميل
- Human in the Loop: طلبات الموافقة على الدالة لتأكيد المستخدم
- Agentic Generative UI: أدوات غير متزامنة للعمليات طويلة الأمد مع تحديثات التقدم
- واجهة المستخدم التوليدية المستندة إلى الأدوات: مكونات واجهة المستخدم المخصصة المقدمة استنادا إلى استدعاءات الأدوات
- الحالة المشتركة: مزامنة الحالة ثنائية الاتجاه بين العميل والخادم
- تحديثات الحالة التنبؤية: دفق وسيطات الأدوات كتحديثات حالة متفائلة
إنشاء واجهات المستخدم للعامل باستخدام CopilotKit
يوفر CopilotKit مكونات واجهة مستخدم غنية لبناء واجهات مستخدم عامل استنادا إلى بروتوكول AG-UI القياسي. يدعم CopilotKit دفق واجهات الدردشة، واستدعاء أداة الواجهة الأمامية والخلفية، والتفاعلات البشرية في الحلقة، وواجهة المستخدم التوليدية، والحالة المشتركة، وأكثر من ذلك بكثير. يمكنك مشاهدة أمثلة على سيناريوهات واجهة مستخدم العامل المختلفة التي يدعمها CopilotKit في نموذج تطبيق AG-UI Dojo .
لتوصيل واجهة CopilotKit React الأمامية ب Agent Framework AG-UI الخلفية، قم بتسجيل نقطة النهاية الخاصة بك ك HttpAgent في وقت تشغيل CopilotKit. يسمح هذا لأدوات الواجهة الأمامية ل CopilotKit بالتدفق من خلال أدوات العميل AG-UI، وجميع ميزات AG-UI (الدفق والموافقات ومزامنة الحالة) تعمل تلقائيا.
يساعدك CopilotKit على التركيز على قدرات وكيلك مع تقديم تجربة مستخدم مصقولة دون إعادة اختراع العجلة. لمعرفة المزيد حول البدء في Microsoft Agent Framework و CopilotKit، راجع تكامل Microsoft Agent Framework لوثائق CopilotKit.
تكامل .NET
يعرض تكامل .NET MAF AIAgent كنقطة نهاية HTTP AG-UI. يحول محول الاستضافة دفق استجابة العامل إلى أحداث AG-UI؛ يظل سلوك العامل الأساسي مثل تنفيذ الأداة والموافقة جزءا من MAF.
استخدم تكامل .NET من أجل:
- دفق نص عامل عبر أحداث Server-Sent (SSE).
- Surface استدعاءات أداة الواجهة الخلفيةوالواجهة الأمامية كأحداث AG-UI.
- إرسال طلبات الموافقة على أداة MAF إلى العميل وإرجاع القرار.
- Exchange حالة العميل ولقطات الحالة والدلتات والخصائص التي تمت إعادة توجيهها.
-
استئناف جلسات العمل المستضافة المستمرة باستخدام AG-UI
threadId. - عرض مهام سير العمل المحولة إلى عوامل من خلال نفس نقطة النهاية.
AG-UI يقرر العملاء كيفية عرض النص والأدوات والموافقة وأحداث الحالة.
Architecture
تضيف حزمة استضافة C# نقطة نهاية ASP.NET Core حول عامل MAF عادي:
AG-UI client -- HTTP POST / SSE --> MapAGUIServer --> AIAgent
MapAGUIServer يتكيف مع طلب AG-UI لرسائل MAF وخيارات التشغيل. ثم يحول استجابة دفق العامل إلى أحداث AG-UI باستخدام AG-UI .NET SDK.
التثبيت
dotnet add package Microsoft.Agents.AI.Hosting.AGUI.AspNetCore --prerelease
الخطوات التالية
الموارد ذات الصلة
AG-UI مقابل استخدام العامل المباشر
بينما يمكنك تشغيل العوامل مباشرة في التطبيق الخاص بك باستخدام أساليب إطار عمل run العامل وأساليبه run(..., stream=True) ، يوفر AG-UI قدرات إضافية:
| الميزة | استخدام العامل المباشر | تكامل AG-UI |
|---|---|---|
| النشر | مضمن في التطبيق | الخدمة عن بعد عبر HTTP |
| وصول العميل | تطبيق واحد | عملاء متعددون (ويب، هاتف محمول) |
| البث المباشر | التكرار غير المتزامن قيد المعالجة | Server-Sent الأحداث (SSE) |
| إدارة الحالة | مدار من قبل التطبيق | مزامنة ثنائية الاتجاه على مستوى البروتوكول |
| سياق مؤشر الترابط | مدار من قبل التطبيق | معرفات مؤشر الترابط المدار بواسطة البروتوكول |
| مهام سير عمل الموافقة | التنفيذ المخصص | دعم البروتوكول المضمن |
نظرة عامة على الهندسة المعمارية
يستخدم تكامل AG-UI بنية نظيفة ونمطية:
┌─────────────────┐
│ Web Client │
│ (Browser/App) │
└────────┬────────┘
│ HTTP POST + SSE
▼
┌─────────────────────────┐
│ FastAPI Endpoint │
│ (add_agent_framework_ │
│ fastapi_endpoint) │
└────────┬────────────────┘
│
▼
┌─────────────────────────┐
│ AgentFrameworkAgent │
│ (Protocol Wrapper) │
└────────┬────────────────┘
│
▼
┌─────────────────────────┐
│ Orchestrators │
│ (Execution Flow Logic) │
└────────┬────────────────┘
│
▼
┌─────────────────────────┐
│ Agent │
│ (Agent Framework) │
└────────┬────────────────┘
│
▼
┌─────────────────────────┐
│ Chat Client │
│ (Azure OpenAI, etc.) │
└─────────────────────────┘
المكونات الرئيسية
- نقطة نهاية FastAPI: نقطة نهاية HTTP التي تتعامل مع تدفق SSE والتعليقات الاستمرارية القابلة للتكوين وتوجيه الطلب
- AgentFrameworkAgent: برنامج تضمين خفيف الوزن يقوم بتكييف عوامل إطار عمل العامل مع بروتوكول AG-UI
- المنسقون: التعامل مع تدفقات التنفيذ المختلفة (الافتراضي، الإنسان في الحلقة، إدارة الحالة)
- جسر الأحداث: تحويل أحداث إطار عمل العامل إلى أحداث بروتوكول AG-UI
- محولات الرسائل: التحويل ثنائي الاتجاه بين تنسيقات رسائل AG-UI و Agent Framework
- استراتيجيات التأكيد: استراتيجيات قابلة للتوسيع لرسائل التأكيد الخاصة بالمجال
كيف يترجم إطار عمل العامل إلى AG-UI
يساعدك فهم كيفية تعيين مفاهيم إطار عمل العامل إلى AG-UI على بناء عمليات تكامل فعالة:
| مفهوم إطار عمل العامل | مكافئ AG-UI | Description |
|---|---|---|
Agent |
نقطة نهاية العامل | يصبح كل عامل نقطة نهاية HTTP |
agent.run() |
طلب HTTP POST | يرسل العميل رسائل عبر HTTP |
agent.run(..., stream=True) |
أحداث Server-Sent | الاستجابات المتدفقة عبر SSE |
| تحديثات استجابة العامل | أحداث AG-UI |
TEXT_MESSAGE_CONTENT، TOOL_CALL_START، إلخ. |
أدوات الدالة (@tool) |
أدوات الواجهة الخلفية | يتم تنفيذها على الخادم، يتم دفق النتائج إلى العميل |
| وضع الموافقة على الأداة | Human-in-the-Loop | طلبات الموافقة/الاستجابات عبر البروتوكول |
| محفوظات المحادثات | إدارة الخيوط |
threadId يحافظ على السياق عبر الطلبات |
التثبيت
تثبيت حزمة تكامل AG-UI:
pip install agent-framework-ag-ui --pre
يؤدي هذا إلى تثبيت كل من إطار عمل العامل الأساسي ومكونات التكامل AG-UI.
الخطوات التالية
للبدء في تكامل AG-UI:
- الشروع في العمل: إنشاء أول خادم AG-UI وعميل
- عرض أداة الواجهة الخلفية: إضافة أدوات الدالة إلى وكلائك
- مهام سير العمل: كشف مهام سير العمل متعددة العوامل من خلال AG-UI
- Human-in-the-Loop: تنفيذ مهام سير عمل الموافقة
- توافق تطبيقات MCP: استخدم تطبيقات MCP مع نقطة النهاية AG-UI
- إدارة الحالة: مزامنة الحالة بين العميل والخادم
موارد إضافية
- وثائق إطار عمل العامل
- وثائق بروتوكولAG-UI
- AG-UI تطبيق Dojo - مثال تطبيق يوضح تكامل إطار عمل العامل
- تكامل CopilotKit MAF - توصيل واجهات CopilotKit React الأمامية AG-UI الخلفية
- مستودع GitHub إطار العامل
يدعم Go AG-UI لكل provider/aguiprovider من الخوادم والعملاء.
import "github.com/microsoft/agent-framework-go/provider/aguiprovider"
mux := http.NewServeMux()
mux.Handle("/", aguiprovider.NewJSONHTTPHandler(myAgent, aguiprovider.HandlerConfig{}))
if err := http.ListenAndServe(":8888", mux); err != nil {
log.Fatal(err)
}
Tip
راجع أمثلةAG-UI Go للحصول على عينات كاملة من الخادم والعميل.