الاختبار باستخدام AG-UI Dojo

يوفر تطبيقAG-UI Dojo بيئة تفاعلية لاختبار واستكشاف عوامل إطار عمل عامل Microsoft التي تنفذ بروتوكول AG-UI. يوفر Dojo واجهة مرئية للاتصال بوكلاءك والتفاعل مع جميع ميزات AG-UI السبعة.

المتطلبات الأساسية

قبل أن تبدأ، تأكد من أنك تملك:

• Python 3.10 أو أعلى
• uv لإدارة التبعية
• مفتاح OpenAI API أو نقطة نهاية OpenAI Azure
• Node.js وpnpm (لتشغيل الواجهة الأمامية ل Dojo)

التثبيت

1. استنساخ مستودع AG-UI

أولا، انسخ مستودع AG-UI الذي يحتوي على تطبيق Dojo وأمثلة تكامل إطار عمل العامل Microsoft:

git clone https://github.com/ag-ui-protocol/ag-ui.git
cd ag-ui

2. انتقل إلى دليل الأمثلة

cd integrations/microsoft-agent-framework/python/examples

3. تثبيت تبعيات Python

استخدم uv لتثبيت التبعيات المطلوبة:

uv sync

4. تكوين متغيرات البيئة

.env إنشاء ملف من القالب المتوفر:

cp .env.example .env

تحرير الملف وإضافة .env بيانات اعتماد واجهة برمجة التطبيقات الخاصة بك:

# For OpenAI
OPENAI_API_KEY=your_api_key_here
OPENAI_CHAT_COMPLETION_MODEL="gpt-4.1"

# Or for Azure OpenAI
AZURE_OPENAI_ENDPOINT=your_endpoint_here
AZURE_OPENAI_API_KEY=your_api_key_here
AZURE_OPENAI_CHAT_COMPLETION_MODEL=your_deployment_here

Note

إذا كنت تستخدم DefaultAzureCredential، في مكان للمصادقةapi_key، فتأكد من مصادقتك باستخدام Azure (على سبيل المثال، عبر az login). لمزيد من المعلومات، راجع وثائق الهوية Azure.

تشغيل تطبيق Dojo

1. بدء تشغيل الخادم الخلفي

في دليل الأمثلة، ابدأ تشغيل الخادم الخلفي مع أمثلة العوامل:

cd integrations/microsoft-agent-framework/python/examples
uv run dev

سيبدأ http://localhost:8888 تشغيل الخادم بشكل افتراضي.

2. بدء تشغيل الواجهة الأمامية ل Dojo

افتح نافذة طرفية جديدة، وانتقل إلى جذر مستودع AG-UI، ثم إلى دليل تطبيق Dojo:

cd apps/dojo
pnpm install
pnpm dev

ستكون الواجهة الأمامية ل Dojo متاحة في http://localhost:3000.

3. الاتصال بوكيلك

1. فتح http://localhost:3000 في المستعرض

2. تكوين عنوان URL للخادم إلى http://localhost:8888

3. حدد "Microsoft إطار عمل العامل (Python)" من القائمة المنسدلة

4. ابدأ في استكشاف أمثلة العوامل

عوامل الأمثلة المتوفرة

توضح أمثلة التكامل جميع ميزات AG-UI السبعة من خلال نقاط نهاية الوكيل المختلفة:

نقطة النهاية	الميزة	Description
/agentic_chat	الميزة 1: دردشة وكيلة	وكيل المحادثة الأساسي مع استدعاء الأداة
/backend_tool_rendering	الميزة 2: عرض أداة الواجهة الخلفية	عامل مع عرض واجهة مستخدم أداة مخصصة
/human_in_the_loop	الميزة 3: الإنسان في التكرار الحلقي	عامل مع مهام سير عمل الموافقة
/agentic_generative_ui	الميزة 4: واجهة مستخدم إنشاء عاملية	العامل الذي يقسم المهام إلى خطوات مع تحديثات الدفق
/tool_based_generative_ui	الميزة 5: واجهة المستخدم التوليدية المستندة إلى الأدوات	العامل الذي ينشئ مكونات واجهة مستخدم مخصصة
/shared_state	الميزة 6: الحالة المشتركة	عامل مع مزامنة الحالة ثنائية الاتجاه
/predictive_state_updates	الميزة 7: تحديثات الحالة التنبؤية	عامل مع تحديثات الحالة التنبؤية أثناء تنفيذ الأداة

اختبار عواملك الخاصة

لاختبار وكلائك مع Dojo:

1. إنشاء وكيلك

إنشاء عامل جديد باتباع دليل البدء :

import os
from agent_framework import Agent
from agent_framework.openai import OpenAIChatCompletionClient

# Create your agent
chat_client = OpenAIChatCompletionClient(
    model=os.getenv("AZURE_OPENAI_CHAT_COMPLETION_MODEL"),
    azure_endpoint=os.getenv("AZURE_OPENAI_ENDPOINT"),
    api_version=os.getenv("AZURE_OPENAI_API_VERSION"),
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),
)

agent = Agent(
    name="my_test_agent",
    client=chat_client,
    instructions="You are a helpful assistant.",
)

2. إضافة العامل إلى الخادم الخاص بك

في تطبيق FastAPI الخاص بك، قم بتسجيل نقطة نهاية العامل:

from fastapi import FastAPI
from agent_framework_ag_ui import add_agent_framework_fastapi_endpoint
import uvicorn

app = FastAPI()

# Register your agent
add_agent_framework_fastapi_endpoint(
    app=app,
    path="/my_agent",
    agent=agent,
)

if __name__ == "__main__":
    uvicorn.run(app, host="127.0.0.1", port=8888)

3. اختبار في دوجو

1. بدء تشغيل الخادم
2. فتح Dojo في http://localhost:3000
3. تعيين عنوان URL للخادم إلى http://localhost:8888
4. سيظهر العامل في القائمة المنسدلة لنقطة النهاية ك "my_agent"
5. حدده وابدأ الاختبار

هيكل المشروع

تتبع أمثلة تكامل مستودع AG-UI هذه البنية:

integrations/microsoft-agent-framework/python/examples/
├── agents/
│   ├── agentic_chat/                  # Feature 1: Basic chat agent
│   ├── backend_tool_rendering/        # Feature 2: Backend tool rendering
│   ├── human_in_the_loop/             # Feature 3: Human-in-the-loop
│   ├── agentic_generative_ui/         # Feature 4: Streaming state updates
│   ├── tool_based_generative_ui/      # Feature 5: Custom UI components
│   ├── shared_state/                  # Feature 6: Bidirectional state sync
│   ├── predictive_state_updates/      # Feature 7: Predictive state updates
│   └── dojo.py                        # FastAPI application setup
├── pyproject.toml                     # Dependencies and scripts
├── .env.example                       # Environment variable template
└── README.md                          # Integration examples documentation

Troubleshooting

مشكلات اتصال الخادم

إذا تعذر على Dojo الاتصال بالخادم الخاص بك:

• تحقق من تشغيل الخادم على المنفذ الصحيح (الافتراضي: 8888)
• تحقق من أن عنوان URL للخادم في Dojo يطابق عنوان الخادم الخاص بك
• تأكد من عدم وجود جدار حماية يمنع الاتصال
• ابحث عن أخطاء CORS في وحدة تحكم المستعرض

عامل لا يظهر

إذا لم يظهر وكيلك في القائمة المنسدلة Dojo:

• تحقق من تسجيل نقطة نهاية العامل بشكل صحيح
• التحقق من سجلات الخادم بحثا عن أي أخطاء في بدء التشغيل
• تأكد من add_agent_framework_fastapi_endpoint اكتمال المكالمة بنجاح

مشكلات متغير البيئة

إذا رأيت أخطاء المصادقة:

• .env تحقق من أن الملف موجود في الدليل الصحيح
• تحقق من تعيين كافة متغيرات البيئة المطلوبة
• تأكد من صلاحية مفاتيح واجهة برمجة التطبيقات ونقاط النهاية
• إعادة تشغيل الخادم بعد تغيير متغيرات البيئة

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

• استكشاف أمثلة العوامل لمشاهدة أنماط التنفيذ
• تعرف على عرض أداة الواجهة الخلفية لتخصيص واجهات المستخدم للأداة

موارد إضافية

• وثائقAG-UI

• مستودعAG-UI GitHub

• Microsoft إطار عمل العامل (Python) Dojo

• أمثلة تكامل إطار عمل العامل Microsoft

انتقل AG-UI تعرض الخوادم نقطة نهاية HTTP يمكن للعملاء المتوافقين مع Dojo الاتصال بها. قم باستضافة العامل مع aguiprovider.NewJSONHTTPHandler، ثم أشر إلى Dojo في عنوان URL للخادم.

mux := http.NewServeMux()
mux.Handle("/", aguiprovider.NewJSONHTTPHandler(myAgent, aguiprovider.HandlerConfig{}))

if err := http.ListenAndServe(":8888", mux); err != nil {
    log.Fatal(err)
}

Tip

راجع نموذج خادم بدءAG-UI لخادم كامل قابل للتشغيل.

Dojo هي أداة AG-UI للتشغيل التفاعلي ولا تتطلب تكوين .NET خاص ب MAF. اكشف السيناريو من خلال MapAGUIServer، ثم اتبع وثائق Dojo لتوصيل نقطة نهاية AG-UI.

مثال على إطار عمل العامل / Dojo

المتطلبات الأساسية

قبل أن تبدأ، تأكد من أنك تملك:

• .NET SDK 10.0 (LTS) أو أحدث
• نقطة نهاية Azure OpenAI مع نشر نموذج دردشة
• Azure بيانات الاعتماد القابلة للاستخدام من خلال DefaultAzureCredential (على سبيل المثال، تسجيل الدخول باستخدام az login)
• Node.js وpnpm (لتشغيل الواجهة الأمامية ل Dojo)

التثبيت

1. استنساخ مستودع AG-UI

أولا، انسخ مستودع AG-UI الذي يحتوي على تطبيق Dojo وأمثلة تكامل إطار عمل العامل Microsoft:

git clone https://github.com/ag-ui-protocol/ag-ui.git
cd ag-ui

2. انتقل إلى دليل الأمثلة

cd integrations/microsoft-agent-framework/dotnet/examples

3. تكوين متغيرات البيئة

تعيين نقطة النهاية Azure OpenAI واسم نشر الدردشة المستخدمة من قبل خادم العينة:

export AZURE_OPENAI_ENDPOINT="https://your-resource.openai.azure.com/"
export AZURE_OPENAI_CHAT_DEPLOYMENT_NAME="gpt-4o-mini"

Note

يصادق النموذج باستخدام DefaultAzureCredential، لذا تأكد من مصادقتك مع Azure (على سبيل المثال، عبر az login) قبل تشغيل الخادم. لمزيد من المعلومات، راجع وثائق الهوية Azure.

تشغيل تطبيق Dojo

1. بدء تشغيل الخادم الخلفي

في دليل الأمثلة، قم باستعادة وتشغيل خادم العينة باستخدام أمثلة العوامل:

dotnet restore AGUIDojoServer/AGUIDojoServer.csproj
dotnet run --project AGUIDojoServer/AGUIDojoServer.csproj --urls "http://localhost:8889"

سيبدأ الخادم في http://localhost:8889.

2. بدء تشغيل الواجهة الأمامية ل Dojo

افتح نافذة محطة طرفية جديدة، وانتقل إلى جذر مستودع AG-UI، ثم إلى دليل تطبيق Dojo. قم بتعيين AGENT_FRAMEWORK_DOTNET_URL حتى يتمكن Dojo من اكتشاف خادم .NET الخاص بك، ثم بدء تشغيله:

cd apps/dojo
pnpm install
export AGENT_FRAMEWORK_DOTNET_URL="http://localhost:8889"
pnpm dev

ستكون الواجهة الأمامية ل Dojo متاحة في http://localhost:3000.

Note

تعيين AGENT_FRAMEWORK_DOTNET_URL قبل تشغيل pnpm dev. متغير البيئة هذا هو ما يجعل إدخال "Microsoft Agent Framework (.NET)" يظهر في Dojo.

3. الاتصال بوكيلك

1. فتح http://localhost:3000 في المستعرض
2. حدد "Microsoft Agent Framework (.NET)" من القائمة المنسدلة
3. ابدأ في استكشاف أمثلة العوامل

عوامل الأمثلة المتوفرة

توضح أمثلة التكامل جميع ميزات AG-UI السبعة من خلال نقاط نهاية الوكيل المختلفة:

نقطة النهاية	الميزة	Description
/agentic_chat	الميزة 1: دردشة وكيلة	وكيل المحادثة الأساسي مع استدعاء الأداة
/backend_tool_rendering	الميزة 2: عرض أداة الواجهة الخلفية	عامل مع عرض واجهة مستخدم أداة مخصصة
/human_in_the_loop	الميزة 3: الإنسان في التكرار الحلقي	عامل مع مهام سير عمل الموافقة
/agentic_generative_ui	الميزة 4: واجهة مستخدم إنشاء عاملية	العامل الذي يقسم المهام إلى خطوات مع تحديثات الدفق
/tool_based_generative_ui	الميزة 5: واجهة المستخدم التوليدية المستندة إلى الأدوات	العامل الذي ينشئ مكونات واجهة مستخدم مخصصة
/shared_state	الميزة 6: الحالة المشتركة	عامل مع مزامنة الحالة ثنائية الاتجاه
/predictive_state_updates	الميزة 7: تحديثات الحالة التنبؤية	عامل مع تحديثات الحالة التنبؤية أثناء تنفيذ الأداة

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

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

موارد إضافية

• وثائقAG-UI
• مستودعAG-UI GitHub
• Microsoft إطار عمل العامل (.NET) Dojo
• أمثلة تكامل إطار عمل العامل Microsoft

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

للحصول على إرشادات تنفيذ MAF، استخدم مقالات السيناريو في هذا القسم:

• أدوات الواجهة الخلفية
• أدوات الواجهة الأمامية
• الموافقة البشرية
• إدارة الحالة