ai-agents-for-beginners / ur

# AGENTS.md

## پروجیکٹ کا جائزہ

یہ ریپوزٹری "نئے آنے والوں کے لئے AI ایجنٹس" پر مشتمل ہے — ایک جامع تعلیمی کورس جو AI ایجنٹس بنانے کے لیے درکار تمام معلومات سکھاتا ہے۔ یہ کورس 18 اسباق (نمبر شدہ 00-18) پر مشتمل ہے جن میں بنیادی باتیں، ڈیزائن پیٹرنز، فریم ورکس، پروڈکشن ڈیپلائمنٹ، لوکل/آن ڈیوائس ایجنٹس، اور AI ایجنٹس کی سیکیورٹی شامل ہیں۔

**اہم ٹیکنالوجیز:**
- Python 3.12+
- انٹرایکٹو سیکھنے کے لیے جیوپیٹر نوٹ بکس
- AI فریم ورکس: مائیکروسافٹ ایجنٹ فریم ورک (MAF)
- Azure AI خدمات: مائیکروسافٹ فاؤنڈری، مائیکروسافٹ فاؤنڈری ایجنٹ سروس V2

**معماری:**
- سبق پر مبنی ساخت (00-15+ ڈائریکٹریز)
- ہر سبق میں شامل ہے: README دستاویزات، کوڈ کے نمونے (جیوپیٹر نوٹ بکس)، اور تصاویر
- خودکار ترجمہ نظام کے ذریعے کثیر اللسانی معاونت
- ہر سبق کے لیے ایک Python نوٹ بک جو مائیکروسافٹ ایجنٹ فریم ورک استعمال کرتی ہے

## سیٹ اپ کمانڈز

### ضروریات
- Python 3.12 یا اس سے اوپر
- Azure سبسکرپشن (مائیکروسافٹ فاؤنڈری کے لیے)
- Azure 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. **Python وِرچوئل اینوائرنمنٹ بنائیں اور اس کو فعال کریں:**
   ```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
   # اپنی API کیز اور اینڈ پوائنٹس کے ساتھ .env کو ترمیم کریں
   ```

### مطلوبہ ماحول کے متغیرات

**مائیکروسافٹ فاؤنڈری** کے لیے (ضروری):
- `AZURE_AI_PROJECT_ENDPOINT` - مائیکروسافٹ فاؤنڈری پروجیکٹ اینڈ پوائنٹ
- `AZURE_AI_MODEL_DEPLOYMENT_NAME` - ماڈل کی تعیناتی کا نام (مثلاً gpt-5-mini)

**Azure AI سرچ** کے لیے (سبق 05 - RAG):
- `AZURE_SEARCH_SERVICE_ENDPOINT` - Azure AI سرچ اینڈ پوائنٹ
- `AZURE_SEARCH_API_KEY` - Azure AI سرچ API کلید

تصدیق: نوٹ بکس چلانے سے پہلے `az login` چلائیں (استعمال کرتا ہے `AzureCliCredential`)۔

## ترقیاتی ورک فلو

### جیوپیٹر نوٹ بکس چلانا

ہر سبق میں مختلف فریم ورکس کے لیے متعدد جیوپیٹر نوٹ بکس شامل ہوتے ہیں:

1. **جیوپیٹر شروع کریں:**
   ```bash
   jupyter notebook
   ```

2. **سبق کی ڈائریکٹری میں جائیں** (مثلاً `01-intro-to-ai-agents/code_samples/`)

3. **نوٹ بکس کھولیں اور چلائیں:**
   - `*-python-agent-framework.ipynb` - مائیکروسافٹ ایجنٹ فریم ورک کے ساتھ (Python)
   - `*-dotnet-agent-framework.ipynb` - مائیکروسافٹ ایجنٹ فریم ورک کے ساتھ (.NET)

### مائیکروسافٹ ایجنٹ فریم ورک کے ساتھ کام کرنا

**مائیکروسافٹ ایجنٹ فریم ورک + مائیکروسافٹ فاؤنڈری:**
- Azure سبسکرپشن ضروری ہے
- ایجنٹ سروس V2 کے لیے `FoundryChatClient` استعمال کرتا ہے (ایجنٹس فاؤنڈری پورٹل میں نظر آتے ہیں)
- بلٹ ان آبزرویبیلٹی کے ساتھ پروڈکشن کے لئے تیار
- فائل پیٹرن: `*-python-agent-framework.ipynb`

## جانچ کے ہدایات

یہ ایک تعلیمی ریپوزٹری ہے جس میں مثال کے کوڈ ہوتے ہیں، نہ کہ پروڈکشن کوڈ یا خودکار ٹیسٹ۔ اپنی ترتیب اور تبدیلیوں کی تصدیق کے لیے:

### دستی جانچ

1. **Python ماحول کی جانچ کریں:**
   ```bash
   python --version  # 3.12+ ہونا چاہیے
   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')"
   ```

### انفرادی نوٹ بکس چلانا

جیوپیٹر میں نوٹ بکس کھولیں اور سیلز کو ترتیب وار چلائیں۔ ہر نوٹ بک خود اپنی جگہ مکمل ہوتا ہے اور شامل ہوتی ہے:
- درآمد کے بیانات
- کنفیگریشن لوڈنگ
- ایجنٹ کی مثالیں
- مارک ڈاون سیلز میں متوقع نتائج

### ڈیپلائے کیے گئے ایجنٹس کی سمک ٹیسٹنگ

ان اسباق کے لیے جہاں ایک ایجنٹ مائیکروسافٹ فاؤنڈری میزبان ایجنٹ کی صورت میں تعینات کیا گیا ہے (01, 04, 05, 16)، ریپوزٹری `tests/` میں سمک ٹیسٹ کیٹیلاگ فراہم کرتی ہے جو `.github/workflows/smoke-test.yml` ورک فلو کے ذریعے [AI سمک ٹیسٹ](https://github.com/marketplace/actions/ai-smoke-test) ایکشن کے ذریعے چلائے جاتے ہیں۔ یہ ایک ہلکا پھلکا پوسٹ-ڈیپلائی گیٹ ہے (کیا ایجنٹ پہنچنے کے قابل ہے اور بنیادی پرامپٹ توقعات پر عمل کر رہا ہے؟)، جو اسسمنٹ پائپ لائن کو سبق 10 اور 16 میں مکمل کرتا ہے۔ کیٹیلاگ کو سبق، اور ایجنٹ کے ساتھ رابطہ کے لیے [tests/README.md](./tests/README.md) دیکھیں۔ سبق 17 لوکل فاؤنڈری کے ساتھ لوکل چلتا ہے اور اس کا کوئی ہوسٹ کیا ہوا اینڈ پوائنٹ نہیں ہوتا، لہذا اس کی توثیق اس کی نوٹ بک کو براہ راست چلانے سے ہوتی ہے۔

## کوڈ اسٹائل

### Python روایات

- **Python ورژن**: 3.12+
- **کوڈ اسٹائل**: معیاری Python 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`) ہٹا دیں

### PR ٹائٹل فارمیٹ

وضاحتی عنوانات استعمال کریں:
- `[Lesson-XX] <concept> کے لیے نیا مثال شامل کریں`
- `[Fix] سبق XX کی README میں ٹائپو درست کریں`
- `[Update] سبق XX میں کوڈ نمونہ بہتر کریں`
- `[Docs] سیٹ اپ ہدایات اپ ڈیٹ کریں`

### مطلوبہ چیکس

- نوٹ بکس بغیر غلطی کے چلنا چاہیے
- README فائلیں واضح اور درست ہونی چاہئیں
- ریپوزٹری میں موجود کوڈ پیٹرنز کی پیروی کریں
- دوسرے اسباق کے ساتھ مطابقت برقرار رکھیں

## اضافی نوٹس

### عام مسائل

1. **Python ورژن کی عدم مطابقت:**
   - یقینی بنائیں کہ Python 3.12+ استعمال ہو رہا ہے
   - کچھ پیکیجز پرانے ورژنز پر کام نہیں کر سکتے
   - Python ورژن واضح کرنے کے لیے `python3 -m venv` استعمال کریں

2. **ماحول کے متغیرات:**
   - ہمیشہ `.env.example` سے `.env` بنائیں
   - `.env` فائل کو کمٹ نہ کریں (یہ `.gitignore` میں ہے)
   - Entra ID کی بغیر کلید کی تصدیق کے لیے `az login` سے سائن ان کریں

3. **پیکیج تنازعات:**
   - تازہ وِرچوئل اینوائرنمنٹ استعمال کریں
   - انفرادی پیکیجز کی بجائے `requirements.txt` سے انسٹال کریں
   - کچھ نوٹ بکس میں اضافی پیکیجز کی ضرورت ہو سکتی ہے جو مارک ڈاون سیلز میں دی گئی ہیں

4. **Azure خدمات:**
   - Azure AI خدمات کے لیے فعال سبسکرپشن ضروری ہے
   - کچھ خصوصیات خطے تک محدود ہوتی ہیں
   - یقینی بنائیں کہ آپ کے Azure OpenAI ماڈل کی تعیناتی Responses API کی حمایت کرتی ہے

### سیکھنے کا راستہ

اسباق میں سفارش کردہ ترقی:
1. **00-course-setup** - ماحول کی ترتیب کے لیے یہاں شروع کریں
2. **01-intro-to-ai-agents** - AI ایجنٹس کی بنیادی باتیں سمجھیں
3. **02-explore-agentic-frameworks** - مختلف فریم ورکس کے بارے میں جانیں
4. **03-agentic-design-patterns** - بنیادی ڈیزائن پیٹرنز
5. نمبر شدہ اسباق کو ترتیب وار جاری رکھیں

### فریم ورک کا انتخاب

اپنے مقاصد کے مطابق فریم ورک منتخب کریں:
- **تمام اسباق**: مائیکروسافٹ ایجنٹ فریم ورک (MAF) `FoundryChatClient` کے ساتھ
- **ایجنٹس سرور سائیڈ پر رجسٹر ہوتے ہیں** مائیکروسافٹ فاؤنڈری ایجنٹ سروس V2 میں اور فاؤنڈری پورٹل میں نظر آتے ہیں

### مدد حاصل کرنا

- [Microsoft Foundry کمیونٹی ڈسکارڈ](https://aka.ms/ai-agents/discord) میں شامل ہوں
- مخصوص رہنمائی کے لیے سبق کی README فائلیں دیکھیں
- کورس کے جائزے کے لیے مرکزی [README.md](./README.md) دیکھیں
- تفصیلی سیٹ اپ ہدایات کے لیے [Course Setup](./00-course-setup/README.md) ملاحظہ کریں

### تعاون کرنا

یہ ایک کھلا تعلیمی پروجیکٹ ہے۔ تعاون خوش آمدید:
- کوڈ کی مثالوں کو بہتر بنائیں
- ٹائپوز یا غلطیوں کو درست کریں
- وضاحتی تبصرے شامل کریں
- نئے سبق کے موضوعات تجویز کریں
- اضافی زبانوں میں ترجمہ کریں

موجودہ ضروریات کے لیے [GitHub Issues](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 Python
- `14-sequential.ipynb` - سبق 14، MAF ایڈوانسڈ پیٹرنز
- `16-python-agent-framework.ipynb` - سبق 16، پروڈکشن صارف معاون ایجنٹ
- `17-local-agent-foundry-local.ipynb` - سبق 17، لوکل ایجنٹ فاؤنڈری لوکل + Qwen کے ساتھ

### خاص ڈائریکٹریز

- `translated_images/` - ترجموں کے لیے مقامی تصاویر
- `images/` - انگریزی مواد کے لیے اصل تصاویر
- `.devcontainer/` - VS Code ترقیاتی کنٹینر کی ترتیب
- `.github/` - GitHub Actions ورک فلو اور ٹیمپلیٹس

### انحصارات

`requirements.txt` سے کلیدی پیکیجز:
- `agent-framework` - مائیکروسافٹ ایجنٹ فریم ورک
- `a2a-sdk` - ایجنٹ سے ایجنٹ پروٹوکول کی معاونت
- `azure-ai-inference`, `azure-ai-projects` - Azure AI خدمات
- `azure-identity` - Azure تصدیق (AzureCliCredential)
- `azure-search-documents` - Azure AI سرچ انضمام
- `mcp[cli]` - ماڈل کانٹیکسٹ پروٹوکول کی معاونت

---

<!-- CO-OP TRANSLATOR DISCLAIMER START -->
**ڈس کلیمر**:
یہ دستاویز AI ترجمہ سروس [Co-op Translator](https://github.com/Azure/co-op-translator) کے ذریعے ترجمہ کی گئی ہے۔ جبکہ ہم درستگی کے لیے کوشاں ہیں، براہ کرم اس بات سے آگاہ رہیں کہ خودکار ترجمے میں غلطیاں یا عدم درستیاں ہو سکتی ہیں۔ اصل دستاویز اپنے مادری زبان میں مستند ماخذ سمجھی جائے گی۔ حساس معلومات کے لیے پیشہ ور انسانی ترجمہ کی سفارش کی جاتی ہے۔ اس ترجمے کے استعمال سے پیدا ہونے والی کسی بھی غلط فہمی یا غلط تشریح کی ذمہ داری ہم قبول نہیں کرتے۔
<!-- CO-OP TRANSLATOR DISCLAIMER END -->