ai-agents-for-beginners / hi

# AGENTS.md

## परियोजना अवलोकन

यह रिपोजिटरी "शुरुआत करने वालों के लिए AI एजेंट्स" रखता है - एक व्यापक शैक्षिक कोर्स जो AI एजेंट्स बनाने के लिए आवश्यक सब कुछ सिखाता है। कोर्स में 18 पाठ शामिल हैं (क्रमांक 00-18), जो मूल बातें, डिजाइन पैटर्न, फ्रेमवर्क, उत्पादन प्रक्षेपण, स्थानीय/डिवाइस एजेंट्स, और AI एजेंट्स की सुरक्षा को कवर करते हैं।

**मुख्य तकनीकें:**
- Python 3.12+
- इंटरैक्टिव सीखने के लिए Jupyter नोटबुक्स
- AI फ्रेमवर्क: Microsoft Agent Framework (MAF)
- Azure AI सेवाएँ: Microsoft Foundry, Microsoft Foundry Agent Service V2

**आर्किटेक्चर:**
- पाठ आधारित संरचना (00-15+ निर्देशिकाएँ)
- प्रत्येक पाठ में शामिल हैं: README दस्तावेज़, कोड नमूने (Jupyter नोटबुक्स), और चित्र
- स्वचालित अनुवाद प्रणाली द्वारा बहुभाषी समर्थन
- प्रत्येक पाठ में एक Python नोटबुक जो Microsoft Agent Framework का उपयोग करती है

## सेटअप कमांड्स

### आवश्यकताएँ
- Python 3.12 या उच्चतर
- Azure सब्सक्रिप्शन (Microsoft Foundry के लिए)
- 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 संपादित करें
   ```

### आवश्यक पर्यावरण चर

**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` - Azure AI Search API कुंजी

प्रमाणीकरण: नोटबुक्स चलाने से पहले `az login` चलाएँ (यह `AzureCliCredential` का उपयोग करता है)।

## विकास कार्यप्रवाह

### Jupyter नोटबुक्स चलाना

प्रत्येक पाठ में विभिन्न फ्रेमवर्क्स के लिए कई Jupyter नोटबुक्स शामिल हैं:

1. **Jupyter प्रारंभ करें:**
   ```bash
   jupyter notebook
   ```

2. **किसी पाठ निर्देशिका में नेविगेट करें** (जैसे, `01-intro-to-ai-agents/code_samples/`)

3. **नोटबुक्स खोलें और चलाएँ:**
   - `*-python-agent-framework.ipynb` - Microsoft Agent Framework का उपयोग करते हुए (Python)
   - `*-dotnet-agent-framework.ipynb` - Microsoft Agent Framework का उपयोग करते हुए (.NET)

### Microsoft Agent Framework के साथ काम करना

**Microsoft Agent Framework + Microsoft Foundry:**
- Azure सब्सक्रिप्शन आवश्यक है
- Agent Service V2 के लिए `FoundryChatClient` का उपयोग करता है (Foundry पोर्टल में एजेंट दिखाई देते हैं)
- निर्मित ऑब्ज़रवेबिलिटी के साथ उत्पादन के लिए तैयार
- फ़ाइल पैटर्न: `*-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')"
   ```

### व्यक्तिगत नोटबुक्स चलाना

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 के साथ चलता है और इसका कोई होस्टेड एंडपॉइंट नहीं है, इसलिए इसे अपनी नोटबुक सीधे चलाकर सत्यापित किया जाता है।

## कोड स्टाइल

### Python सम्मेलन

- **Python संस्करण**: 3.12+
- **कोड स्टाइल**: मानक Python PEP 8 सम्मेलन का पालन करें
- **नोटबुक्स**: अवधारणाओं को स्पष्ट करने के लिए स्पष्ट मार्कडाउन सेल्स का उपयोग करें
- **आयात**: मानक लाइब्रेरी, तृतीय-पक्ष और स्थानीय आयात समूहित करें

### Jupyter नोटबुक सम्मेलन

- कोड सेल्स से पहले वर्णनात्मक मार्कडाउन सेल्स शामिल करें
- संदर्भ के लिए नोटबुक्स में आउटपुट उदाहरण जोड़ें
- पाठ अवधारणाओं से मेल खाते स्पष्ट वेरिएबल नामों का उपयोग करें
- नोटबुक निष्पादन क्रम को रैखिक रखें (सेल 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
```

## निर्माण और तैनाती

### दस्तावेज़ निर्माण

यह रिपोजिटरी दस्तावेज़ीकरण के लिए Markdown का उपयोग करती है:
- प्रत्येक पाठ फ़ोल्डर में 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] lesson-XX README में टाइपो सही करें`
- `[Update] lesson-XX में कोड उदाहरण सुधारें`
- `[Docs] सेटअप निर्देश अपडेट करें`

### आवश्यक परीक्षण

- नोटबुक बिना त्रुटि के चलनी चाहिए
- README फाइलें स्पष्ट और सटीक होनी चाहिए
- रिपोजिटरी में मौजूद मौजूदा कोड पैटर्न का पालन करें
- अन्य पाठों के साथ संगति बनाए रखें

## अतिरिक्त नोट्स

### सामान्य समस्याएँ

1. **Python संस्करण असंगति:**
   - सुनिश्चित करें कि Python 3.12+ उपयोग हो रहा है
   - कुछ पैकेज पुराने संस्करणों पर काम नहीं कर सकते
   - `python3 -m venv` का उपयोग करके Python संस्करण स्पष्ट रूप से निर्दिष्ट करें

2. **पर्यावरण चर:**
   - हमेशा `.env.example` से `.env` बनाएँ
   - `.env` फ़ाइल कमिट न करें (यह `.gitignore` में है)
   - keyless 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. अनुक्रमबद्ध रूप से नंबरबद्ध पाठों के माध्यम से जारी रखें

### फ्रेमवर्क चयन

अपने लक्ष्यों के आधार पर फ्रेमवर्क चुनें:
- **सभी पाठ**: Microsoft Agent Framework (MAF) के साथ `FoundryChatClient`
- **एजेंट्स सर्वर-साइड पंजीकृत** Microsoft Foundry Agent Service V2 में और Foundry पोर्टल में दिखाई देते हैं

### सहायता प्राप्त करना

- [Microsoft Foundry समुदाय Discord](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, Foundry Local + Qwen के साथ स्थानीय एजेंट

### विशेष निर्देशिकाएँ

- `translated_images/` - अनुवादों के लिए स्थानीयकृत छवियाँ
- `images/` - अंग्रेजी सामग्री के लिए मूल चित्र
- `.devcontainer/` - VS Code विकास कंटेनर विन्यास
- `.github/` - GitHub Actions वर्कफ़्लो और टेम्पलेट्स

### निर्भरताएँ

`requirements.txt` से प्रमुख पैकेज:
- `agent-framework` - Microsoft Agent Framework
- `a2a-sdk` - एजेंट-टू-एजेंट प्रोटोकॉल सपोर्ट
- `azure-ai-inference`, `azure-ai-projects` - Azure AI सेवाएँ
- `azure-identity` - Azure प्रमाणीकरण (AzureCliCredential)
- `azure-search-documents` - Azure AI Search एकीकरण
- `mcp[cli]` - मॉडल संदर्भ प्रोटोकॉल सपोर्ट

---

<!-- CO-OP TRANSLATOR DISCLAIMER START -->
**अस्वीकरण**:
इस दस्तावेज़ का अनुवाद AI अनुवाद सेवा [Co-op Translator](https://github.com/Azure/co-op-translator) का उपयोग करके किया गया है। जबकि हम सटीकता के लिए प्रयास करते हैं, कृपया ध्यान दें कि स्वचालित अनुवादों में त्रुटियाँ या अशुद्धियाँ हो सकती हैं। मूल दस्तावेज़ अपनी मूल भाषा में ही प्रामाणिक स्रोत माना जाना चाहिए। महत्वपूर्ण जानकारी के लिए, पेशेवर मानव अनुवाद की सिफारिश की जाती है। इस अनुवाद के उपयोग से उत्पन्न किसी भी गलतफहमी या गलत व्याख्या के लिए हम उत्तरदायी नहीं हैं।
<!-- CO-OP TRANSLATOR DISCLAIMER END -->