ai-agents-for-beginners / ar

# AGENTS.md

## نظرة عامة على المشروع

يحتوي هذا المستودع على "وكلاء الذكاء الاصطناعي للمبتدئين" - دورة تعليمية شاملة تعلم كل ما يلزم لبناء وكلاء الذكاء الاصطناعي. تتألف الدورة من 18 درسًا (مرقمة من 00 إلى 18) تغطي الأساسيات، أنماط التصميم، الأُطر، النشر في الإنتاج، الوكلاء المحليين/على الجهاز، وأمان وكلاء الذكاء الاصطناعي.

**التقنيات الرئيسية:**
- بايثون 3.12+
- دفاتر جوبيتر للتعلم التفاعلي
- أُطر الذكاء الاصطناعي: إطار عمل الوكيل من مايكروسوفت (MAF)
- خدمات الذكاء الاصطناعي في أزور: Microsoft Foundry، خدمة وكلاء Microsoft Foundry V2

**البنية:**
- هيكل قائم على الدروس (مجلدات 00-15+)
- يحتوي كل درس على: مستند README، عينات كود (دفاتر جوبيتر)، وصور
- دعم متعدد اللغات عبر نظام الترجمة الآلي
- دفتر جوبيتر واحد بلغة بايثون لكل درس باستخدام إطار عمل الوكيل من مايكروسوفت

## أوامر الإعداد

### المتطلبات الأساسية
- بايثون 3.12 أو أعلى
- اشتراك في أزور (لـ Microsoft Foundry)
- تثبيت CLI أزور وتسجيل الدخول (`az login`)

### الإعداد الأولي

1. **استنساخ أو تفريع المستودع:**
   ```bash
   gh repo fork microsoft/ai-agents-for-beginners --clone
   # أو
   git clone https://github.com/microsoft/ai-agents-for-beginners.git
   cd ai-agents-for-beginners
   ```

2. **إنشاء وتفعيل بيئة بايثون الافتراضية:**
   ```bash
   python3 -m venv venv
   source venv/bin/activate  # على ويندوز: venv\Scripts\activate
   ```

3. **تثبيت التبعيات:**
   ```bash
   pip install -r requirements.txt
   ```

4. **إعداد متغيرات البيئة:**
   ```bash
   cp .env.example .env
   # عدّل ملف .env بمفاتيح API ونقاط النهاية الخاصة بك
   ```

### متغيرات البيئة المطلوبة

بالنسبة لـ **Microsoft Foundry** (مطلوبة):
- `AZURE_AI_PROJECT_ENDPOINT` - نقطة نهاية مشروع Microsoft Foundry
- `AZURE_AI_MODEL_DEPLOYMENT_NAME` - اسم نشر النموذج (مثل gpt-5-mini)

بالنسبة لـ **Azure AI Search** (الدرس 05 - RAG):
- `AZURE_SEARCH_SERVICE_ENDPOINT` - نقطة نهاية Azure AI Search
- `AZURE_SEARCH_API_KEY` - مفتاح API لـ Azure AI Search

المصادقة: قم بتشغيل `az login` قبل تشغيل دفاتر جوبيتر (يستخدم `AzureCliCredential`).

## سير عمل التطوير

### تشغيل دفاتر جوبيتر

يحتوي كل درس على دفاتر جوبيتر متعددة لأُطر مختلفة:

1. **ابدأ Jupyter:**
   ```bash
   jupyter notebook
   ```

2. **انتقل إلى مجلد الدرس** (مثل `01-intro-to-ai-agents/code_samples/`)

3. **افتح وشغّل الدفاتر:**
   - `*-python-agent-framework.ipynb` - باستخدام إطار عمل الوكيل من مايكروسوفت (بايثون)
   - `*-dotnet-agent-framework.ipynb` - باستخدام إطار عمل الوكيل من مايكروسوفت (.NET)

### العمل مع إطار عمل وكيل مايكروسوفت

**إطار عمل الوكيل من مايكروسوفت + Microsoft Foundry:**
- يتطلب اشتراك أزور
- يستخدم `FoundryChatClient` لخدمة الوكيل V2 (الوكلاء ظاهرون في بوابة Foundry)
- جاهز للإنتاج مع مراقبة مدمجة
- نمط الملفات: `*-python-agent-framework.ipynb`

## تعليمات الاختبار

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

### اختبار يدوي

1. **اختبر بيئة بايثون:**
   ```bash
   python --version  # يجب أن يكون ٣.١٢+
   pip list | grep -E "(agent-framework|azure-ai|azure-identity)"
   ```

2. **اختبر تنفيذ الدفاتر:**
   ```bash
   # تحويل الدفتر إلى نص وتشغيله (اختبار الاستيرادات)
   jupyter nbconvert --to script <lesson-folder>/code_samples/<notebook>.ipynb --stdout | python
   ```

3. **تحقق من متغيرات البيئة:**
   ```bash
   python -c "import os; from dotenv import load_dotenv; load_dotenv(); print('✓ AZURE_AI_PROJECT_ENDPOINT' if os.getenv('AZURE_AI_PROJECT_ENDPOINT') else '✗ AZURE_AI_PROJECT_ENDPOINT missing')"
   ```

### تشغيل الدفاتر الفردية

افتح الدفاتر في Jupyter ونفذ الخلايا بالتسلسل. كل دفتر مستقل ويشمل:
- تعليمات الاستيراد
- تحميل الإعدادات
- أمثلة تنفيذ الوكلاء
- المخرجات المتوقعة في خلايا ماركداون

### اختبار سريع للوكلاء المنشورين

بالنسبة للدروس التي يتم فيها نشر وكيل كمستضيف في Microsoft Foundry (01، 04، 05، 16)، يزود المستودع كتالوجات اختبار سريع ضمن `tests/` يتم تشغيلها عبر سير عمل `.github/workflows/smoke-test.yml` بواسطة إجراء [AI Smoke Test](https://github.com/marketplace/actions/ai-smoke-test). هذه بمثابة بوابة خفيفة بعد النشر (هل الوكيل متاح ويتبع التعليمات الأساسية؟)، مكملة لخط تقييم الدروس 10 و 16. انظر [tests/README.md](./tests/README.md) لتطابق الكتالوج-الدرس-الوكيل. الدرس 17 يعمل محلياً مع Foundry Local ولا يمتلك نقطة نهاية مستضافة، لذا يتم التحقق منه بتشغيل دفتره مباشرة.

## نمط كتابة الكود

### اتفاقيات بايثون

- **إصدار بايثون**: 3.12+
- **نمط الكود**: اتبع قواعد PEP 8 القياسية للبايثون
- **الدفاتر**: استخدم خلايا ماركداون واضحة لشرح المفاهيم
- **الاستيرادات**: اجمع حسب المكتبة القياسية، الطرف الثالث، والمحلية

### اتفاقيات دفاتر جوبيتر

- أضف خلايا ماركداون وصفية قبل خلايا الكود
- أضف أمثلة للمخرجات في الدفاتر للمرجعية
- استخدم أسماء متغيرات واضحة تتناسب مع مفاهيم الدرس
- حافظ على تسلسل تنفيذ الدفتر خطياً (خلية 1 → 2 → 3...)

### تنظيم الملفات

```
<lesson-number>-<lesson-name>/
├── README.md                     # Lesson documentation
├── code_samples/
│   ├── <number>-python-agent-framework.ipynb
│   └── <number>-dotnet-agent-framework.ipynb  (optional)
└── images/
    └── *.png
```

## البناء والنشر

### بناء التوثيق

يستخدم هذا المستودع ماركداون للتوثيق:
- ملفات README.md في كل مجلد درس
- ملف README.md الرئيسي في جذر المستودع
- نظام ترجمة آلي عبر GitHub Actions

### خط أنابيب التكامل/التسليم المستمر (CI/CD)

موجود في `.github/workflows/`:

1. **co-op-translator.yml** - ترجمة آلية لأكثر من 50 لغة
2. **welcome-issue.yml** - ترحيب بمُنشئي القضايا الجدد
3. **welcome-pr.yml** - ترحيب بمساهمي طلبات السحب الجديدة

### النشر

هذا مستودع تعليمي - لا يوجد عملية نشر رسمية. يستخدمه الُمستخدمون:
1. استنساخ أو تفريع المستودع
2. تشغيل الدفاتر محليًا أو في GitHub Codespaces
3. التعلم عبر تعديل وتجربة الأمثلة

## إرشادات طلب السحب

### قبل الإرسال

1. **اختبر تغييراتك:**
   - شغّل الدفاتر المتأثرة بالكامل
   - تأكد من تنفيذ جميع الخلايا بدون أخطاء
   - تحقق من أن المخرجات مناسبة

2. **تحديث التوثيق:**
   - حدّث README.md إذا أضفت مفاهيم جديدة
   - أضف تعليقات في الدفاتر للكود المعقد
   - تأكد أن خلايا ماركداون تشرح الهدف

3. **تغييرات الملفات:**
   - تجنب الالتزام بملفات `.env` (استخدم `.env.example`)
   - لا تلزم مجلدات `venv/` أو `__pycache__/`
   - احتفظ بمخرجات الدفاتر عند إيضاحها للمفاهيم
   - احذف الملفات المؤقتة ودفاتر النسخ الاحتياطي (`*-backup.ipynb`)

### صيغة عنوان طلب السحب

استخدم عناوين وصفية:
- `[Lesson-XX] إضافة مثال جديد لـ <concept>`
- `[Fix] تصحيح خطأ مطبعي في README للدرس-XX`
- `[Update] تحسين عينة الكود في الدرس-XX`
- `[Docs] تحديث تعليمات الإعداد`

### الفحوصات المطلوبة

- يجب تنفيذ الدفاتر بدون أخطاء
- يجب أن تكون ملفات README واضحة ودقيقة
- اتبع أنماط الكود الموجودة في المستودع
- حافظ على التناسق مع الدروس الأخرى

## ملاحظات إضافية

### العقبات الشائعة

1. **تفاوت إصدار بايثون:**
   - تأكد من استخدام بايثون 3.12+
   - قد لا تعمل بعض الحزم مع الإصدارات الأقدم
   - استخدم `python3 -m venv` لتحديد إصدار بايثون بوضوح

2. **متغيرات البيئة:**
   - أنشئ دائمًا `.env` من `.env.example`
   - لا تلزم ملف `.env` (موجود في `.gitignore`)
   - سجّل الدخول بـ `az login` للمصادقة بدون مفتاح عبر Entra ID

3. **تعارض الحزم:**
   - استخدم بيئة افتراضية جديدة
   - ثبت من `requirements.txt` بدلاً من حزم فردية
   - قد تتطلب بعض الدفاتر حزم إضافية مذكورة في خلايا ماركداون

4. **خدمات أزور:**
   - تتطلب خدمات أزور للذكاء الاصطناعي اشتراكًا نشطًا
   - بعض الميزات خاصة بالمناطق الجغرافية
   - تأكد من أن نشر نموذج Azure OpenAI يدعم API الردود

### مسار التعلم

التقدم الموصى به عبر الدروس:
1. **00-course-setup** - البداية لإعداد البيئة
2. **01-intro-to-ai-agents** - فهم أساسيات وكلاء الذكاء الاصطناعي
3. **02-explore-agentic-frameworks** - تعرف على الأُطر المختلفة
4. **03-agentic-design-patterns** - أنماط التصميم الأساسية
5. تابع بقية الدروس المرقمة بالتسلسل

### اختيار الإطار

اختر الإطار حسب أهدافك:
- **جميع الدروس**: إطار عمل الوكيل من مايكروسوفت (MAF) مع `FoundryChatClient`
- **الوكلاء يسجلون على الخادم** في خدمة وكلاء Microsoft Foundry V2 ويظهرون في بوابة Foundry

### الحصول على المساعدة

- انضم إلى [مجتمع مايكروسوفت Foundry على ديسكورد](https://aka.ms/ai-agents/discord)
- راجع ملفات README الخاصة بالدروس لتعليمات محددة
- تحقق من [README.md](./README.md) الرئيسي لنظرة عامة على الدورة
- اطلع على [إعداد الدورة](./00-course-setup/README.md) لتعليمات الإعداد التفصيلية

### المساهمة

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

اطلع على [مشكلات جيتهاب](https://github.com/microsoft/ai-agents-for-beginners/issues) للاحتياجات الحالية.

## السياق الخاص بالمشروع

### دعم متعدد اللغات

يستخدم هذا المستودع نظام ترجمة آلي:
- دعم أكثر من 50 لغة
- الترجمات في مجلدات `/translations/<lang-code>/`
- سير عمل GitHub Actions يدير تحديثات الترجمة
- ملفات المصدر بالإنجليزية في جذر المستودع

### هيكل الدرس

يتبع كل درس نمطًا ثابتًا:
1. صورة مصغرة للفيديو مع رابط
2. محتوى الدرس المكتوب (README.md)
3. عينات الكود في أُطر متعددة
4. أهداف التعلم والمتطلبات المسبقة
5. مصادر تعلم إضافية مرتبطة

### تسمية عينات الكود

التنسيق: `<lesson-number>-python-agent-framework.ipynb`
- `01-python-agent-framework.ipynb` - الدرس 1، MAF بايثون
- `14-sequential.ipynb` - الدرس 14، أنماط متقدمة في MAF
- `16-python-agent-framework.ipynb` - الدرس 16، وكيل دعم العملاء للإنتاج
- `17-local-agent-foundry-local.ipynb` - الدرس 17، وكيل محلي مع Foundry Local + Qwen

### مجلدات خاصة

- `translated_images/` - صور مترجمة للغات
- `images/` - الصور الأصلية للمحتوى الإنجليزي
- `.devcontainer/` - إعداد بيئة تطوير VS Code
- `.github/` - سير عمل وقوالب GitHub Actions

### التبعيات

حزم رئيسية من `requirements.txt`:
- `agent-framework` - إطار عمل الوكيل من مايكروسوفت
- `a2a-sdk` - دعم بروتوكول وكيل إلى وكيل
- `azure-ai-inference`, `azure-ai-projects` - خدمات الذكاء الاصطناعي في أزور
- `azure-identity` - المصادقة في أزور (AzureCliCredential)
- `azure-search-documents` - تكامل Azure AI Search
- `mcp[cli]` - دعم بروتوكول سياق النموذج

---

<!-- CO-OP TRANSLATOR DISCLAIMER START -->
**تنويه**:
تمت ترجمة هذا المستند باستخدام خدمة الترجمة بالذكاء الاصطناعي [Co-op Translator](https://github.com/Azure/co-op-translator). بينما نسعى للدقة، يرجى العلم أن الترجمات الآلية قد تحتوي على أخطاء أو عدم دقة. يجب اعتبار المستند الأصلي بلغته الأصلية المصدر الرسمي والمعتمد. للمعلومات الهامة، يُنصح بالاستعانة بترجمة بشرية محترفة. نحن غير مسؤولين عن أي سوء فهم أو تفسير ناتج عن استخدام هذه الترجمة.
<!-- CO-OP TRANSLATOR DISCLAIMER END -->