ai-agents-for-beginners / bn

# AGENTS.md

## প্রকল্পের সংক্ষিপ্ত বিবরণ

এই রিপোজিটরিতে রয়েছে "শুরুর জন্য AI এজেন্টস" - একটি বিস্তৃত শিক্ষামূলক কোর্স যা AI এজেন্ট তৈরির জন্য প্রয়োজনীয় সবকিছু শেখায়। কোর্সটিতে ১৮টি ধাপ (নম্বর ০০-১৮) রয়েছে যা অন্তর্ভুক্ত করে মৌলিক বিষয়াবলী, ডিজাইন প্যাটার্ন, ফ্রেমওয়ার্ক, উৎপাদন স্থাপনা, স্থানীয়/ডিভাইস-ভিত্তিক এজেন্টস, এবং AI এজেন্টসের নিরাপত্তা।

**মূল প্রযুক্তিগুলি:**
- পাইথন ৩.১২+
- ইন্টারেক্টিভ শেখার জন্য জুপিটার নোটবুক
- AI ফ্রেমওয়ার্ক: মাইক্রোসফট এজেন্ট ফ্রেমওয়ার্ক (MAF)
- আজুর AI সার্ভিস: মাইক্রোসফট ফাউন্ড্রি, মাইক্রোসফট ফাউন্ড্রি এজেন্ট সার্ভিস V2

**স্থাপত্য:**
- পাঠ ভিত্তিক কাঠামো (০০-১৫+ ডিরেক্টরিজ)
- প্রতিটি পাঠে রয়েছে: README ডকুমেন্টেশন, কোড নমুনা (জুপিটার নোটবুক), এবং ছবি
- স্বয়ংক্রিয় অনুবাদ ব্যবস্থা মাধ্যমে বহু-ভাষা সমর্থন
- প্রতিটি পাঠে একক পাইথন নোটবুক মাইক্রোসফট এজেন্ট ফ্রেমওয়ার্ক ব্যবহার করে

## সেটআপ কমান্ডসমূহ

### পূর্বশর্তসমূহ
- পাইথন ৩.১২ অথবা এর উচ্চতর
- আজুর সাবস্ক্রিপশন (মাইক্রোসফট ফাউন্ড্রির জন্য)
- আজুর CLI ইনস্টল ও প্রমাণীকৃত (`az login`)

### প্রাথমিক সেটআপ

১. **রিপোজিটরি ক্লোন বা ফর্ক করুন:**
   ```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
   ```

২. **পাইথন ভার্চুয়াল এনভায়রনমেন্ট তৈরি ও সক্রিয় করুন:**
   ```bash
   python3 -m venv venv
   source venv/bin/activate  # উইন্ডোজে: venv\Scripts\activate
   ```

৩. **ডিপেনডেন্সিস ইনস্টল করুন:**
   ```bash
   pip install -r requirements.txt
   ```

৪. **পরিবেশ ভেরিয়েবলস সেট করুন:**
   ```bash
   cp .env.example .env
   # আপনার API কী এবং এন্ডপয়েন্টসহ .env সম্পাদনা করুন
   ```

### প্রয়োজনীয় পরিবেশ ভেরিয়েবলসমূহ

**মাইক্রোসফট ফাউন্ড্রি** (প্রয়োজনীয়):
- `AZURE_AI_PROJECT_ENDPOINT` - মাইক্রোসফট ফাউন্ড্রি প্রকল্প এন্ডপয়েন্ট
- `AZURE_AI_MODEL_DEPLOYMENT_NAME` - মডেল স্থাপন নাম (যেমন, gpt-5-mini)

**আজুর AI সার্চ** (পাঠ ০৫ - RAG):
- `AZURE_SEARCH_SERVICE_ENDPOINT` - আজুর AI সার্চ এন্ডপয়েন্ট
- `AZURE_SEARCH_API_KEY` - আজুর AI সার্চ API কী

প্রমাণীকরণ: নোটবুক চালানোর আগে `az login` রান করুন (ব্যবহার করে `AzureCliCredential`)।

## উন্নয়ন ওয়ার্কফ্লো

### জুপিটার নোটবুক চালানো

প্রতিটি পাঠে বিভিন্ন ফ্রেমওয়ার্কের জন্য একাধিক জুপিটার নোটবুক রয়েছে:

১. **জুপিটার শুরু করুন:**
   ```bash
   jupyter notebook
   ```

২. **একটি পাঠ ডিরেক্টরিতে যান** (যেমন, `01-intro-to-ai-agents/code_samples/`)

৩. **নোটবুক খুলে চালান:**
   - `*-python-agent-framework.ipynb` - মাইক্রোসফট এজেন্ট ফ্রেমওয়ার্ক (পাইথন) ব্যবহার করে
   - `*-dotnet-agent-framework.ipynb` - মাইক্রোসফট এজেন্ট ফ্রেমওয়ার্ক (.NET) ব্যবহার করে

### মাইক্রোসফট এজেন্ট ফ্রেমওয়ার্ক নিয়ে কাজ করা

**মাইক্রোসফট এজেন্ট ফ্রেমওয়ার্ক + মাইক্রোসফট ফাউন্ড্রি:**
- আজুর সাবস্ক্রিপশন প্রয়োজন
- এজেন্ট সার্ভিস V2 এর জন্য `FoundryChatClient` ব্যবহৃত হয় (এজেন্টগুলো ফাউন্ড্রি পোর্টালে দৃশ্যমান)
- উৎপাদন-সক্ষম, বিল্ট-ইন অবজারভেবিলিটি সহ
- ফাইল প্যাটার্ন: `*-python-agent-framework.ipynb`

## পরীক্ষার নির্দেশাবলী

এটি একটি শিক্ষামূলক রিপোজিটরি যেখানে উদাহরণ কোড আছে, স্বয়ংক্রিয় পরীক্ষাসমূহের উৎপাদন কোড নয়। আপনার সেটআপ এবং পরিবর্তন যাচাই করতে:

### ম্যানুয়াল পরীক্ষা

১. **পাইথন পরিবেশ পরীক্ষা করুন:**
   ```bash
   python --version  # হওয়া উচিত ৩.১২+
   pip list | grep -E "(agent-framework|azure-ai|azure-identity)"
   ```

২. **নোটবুক নির্বাহ পরীক্ষা করুন:**
   ```bash
   # নোটবুককে স্ক্রিপ্টে রূপান্তর করুন এবং চালান (টেস্ট ইম্পোর্ট পরীক্ষা করে)
   jupyter nbconvert --to script <lesson-folder>/code_samples/<notebook>.ipynb --stdout | python
   ```

৩. **পরিবেশ ভেরিয়েবলস যাচাই করুন:**
   ```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')"
   ```

### পৃথক নোটবুক চালানো

জুপিটারে নোটবুক খুলে ধারাবাহিকভাবে সেলগুলি চালান। প্রতিটি নোটবুক স্বয়ংসম্পূর্ণ এবং অন্তর্ভুক্ত:
- আমদানি বিবৃতি
- কনফিগারেশন লোডিং
- উদাহরণ এজেন্ট বাস্তবায়ন
- প্রত্যাশিত আউটপুট মারকডাউন সেলে

### স্থাপিত এজেন্ট স্মোক-টেস্টিং

যেখানে এজেন্ট মাইক্রোসফট ফাউন্ড্রি হোস্টেড এজেন্ট হিসেবে স্থাপিত (০১, ০৪, ০৫, ১৬), সেই সেক্ষেত্রে রিপোতে `tests/` এর অধীনে স্মোক-টেস্ট ক্যাটালগ থাকে যা `.github/workflows/smoke-test.yml` ওয়ার্কফ্লোর মাধ্যমে [AI স্মোক টেস্ট](https://github.com/marketplace/actions/ai-smoke-test) অ্যাকশন দ্বারা চালানো হয়। এগুলো হালকা পোস্ট-ডিপ্লয় গেট (এজেন্ট পৌঁছনো যায় কিনা এবং মৌলিক প্রম্পট প্রত্যাশা পূরণ হচ্ছে কিনা?), যা পাঠ ১০ ও ১৬ এর ইভ্যালুয়েশন পাইপলাইনের পরিপূরক। ক্যাটালগ-থেকে-পাঠ-থেকে-এজেন্ট ম্যাপিংয়ের জন্য [tests/README.md](./tests/README.md) দেখুন। পাঠ ১৭ লোকালি ফাউন্ড্রি লোকাল দিয়ে চালিত হয় এবং এর কোনো হোস্টেড এন্ডপয়েন্ট নেই, তাই এটি সরাসরি তার নোটবুক চালিয়ে যাচাই করা হয়।

## কোড স্টাইল

### পাইথন রীতিনীতি

- **পাইথন ভার্সন**: ৩.১২+
- **কোড স্টাইল**: স্ট্যান্ডার্ড পাইথন PEP 8 রীতিনীতি অনুসরণ করুন
- **নোটবুক**: ধারণাগুলি ব্যাখ্যার জন্য স্পষ্ট মারকডাউন সেল ব্যবহার করুন
- **ইমপোর্টস**: স্ট্যান্ডার্ড লাইব্রেরি, থার্ড-পার্টি, লোকাল ইমপোর্টস আলাদা গ্রুপে রাখুন

### জুপিটার নোটবুক রীতিনীতি

- কোড সেলগুলোর আগে বর্ণনামূলক মারকডাউন সেল অন্তর্ভুক্ত করুন
- রেফারেন্স হিসেবে নোটবুকে আউটপুট উদাহরণ যোগ করুন
- পাঠের ধারণার সঙ্গে মেলানো স্পষ্ট ভেরিয়েবল নাম ব্যবহার করুন
- নোটবুক নির্বাহ ক্রম লিনিয়ার রাখুন (সেল ১ → ২ → ৩...)

### ফাইল সংগঠন

```
<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
- গিটহাব অ্যাকশনস মাধ্যমে স্বয়ংক্রিয় অনুবাদ ব্যবস্থা

### CI/CD পাইপলাইন

অবস্থান `.github/workflows/` এ:

১. **co-op-translator.yml** - ৫০+ ভাষায় স্বয়ংক্রিয় অনুবাদ
২. **welcome-issue.yml** - নতুন ইস্যু ক্রিয়েটরকে স্বাগত জানায়
৩. **welcome-pr.yml** - নতুন পুল রিকোয়েস্ট কন্ট্রিবিউটরকে স্বাগত জানায়

### স্থাপন

এটি একটি শিক্ষামূলক রিপোজিটরি - কোন স্থাপনা প্রক্রিয়া নেই। ব্যবহারকারীরা:
১. রিপোজিটরি ফর্ক বা ক্লোন করুন
২. স্থানীয় বা গিটহাব কোডস্পেসে নোটবুক চালান
৩. উদাহরণ সংশোধন ও পরীক্ষার মাধ্যমে শিখুন

## পুল রিকোয়েস্ট গাইডলাইন

### জমা দেওয়ার পূর্বে

১. **আপনার পরিবর্তনগুলো পরীক্ষা করুন:**
   - প্রভাবিত নোটবুক সম্পূর্ণ চালান
   - সব সেল ত্রুটিমুক্ত কাজ করে কিনা যাচাই করুন
   - আউটপুটগুলি উপযুক্ত কিনা দেখুন

২. **ডকুমেন্টেশন আপডেট:**
   - নতুন ধারণা যোগ করলে README.md আপডেট করুন
   - জটিল কোডের জন্য নোটবুকের মধ্যে মন্তব্য যোগ করুন
   - মারকডাউন সেলগুলিতে উদ্দেশ্য ব্যাখ্যা নিশ্চিত করুন

৩. **ফাইল পরিবর্তন:**
   - `.env` ফাইল কমিট করা এড়ান (`.env.example` ব্যবহার করুন)
   - `venv/` অথবা `__pycache__/` ডিরেক্টরি কমিট করবেন না
   - ধারণা প্রদর্শনের জন্য নোটবুক আউটপুট রাখুন
   - অস্থায়ী ফাইল ও ব্যাকআপ নোটবুক (`*-backup.ipynb`) মুছে ফেলুন

### পিআর শিরোনামের ফরম্যাট

বর্ণনামূলক শিরোনাম ব্যবহার করুন:
- `[Lesson-XX] <ধারণা> জন্য নতুন উদাহরণ যোগ করুন`
- `[Fix] পাঠ-XX README তে টাইপো সংশোধন`
- `[Update] পাঠ-XX এ কোড নমুনা উন্নত করুন`
- `[Docs] সেটআপ নির্দেশাবলী আপডেট করুন`

### প্রয়োজনীয় পরীক্ষা

- নোটবুকসমূহ ত্রুটিমুক্ত চালাতে হবে
- README ফাইল স্পষ্ট ও সঠিক হতে হবে
- রিপোজিটরির বিদ্যমান কোড প্যাটার্ন অনুসরণ করতে হবে
- অন্যান্য পাঠের সঙ্গে সামঞ্জস্য বজায় রাখতে হবে

## অতিরিক্ত নোট

### সাধারণ সমস্যাসমূহ

১. **পাইথন সংস্করণ মিল না পাওয়া:**
   - নিশ্চিত করুন পাইথন ৩.১২+ ব্যবহার হচ্ছে
   - কিছু প্যাকেজ পুরোনো সংস্করণে কাজ নাও করতে পারে
   - স্পষ্টভাবে পাইথন সংস্করণ নির্ধারণে `python3 -m venv` ব্যবহার করুন

২. **পরিবেশ ভেরিয়েবলস:**
   - সর্বদা `.env.example` থেকে `.env` তৈরি করুন
   - `.env` ফাইল কমিট করবেন না (এটি `.gitignore` এ আছে)
   - কীহীন Entra ID প্রমাণীকরণের জন্য `az login` ব্যবহার করে সাইন ইন করুন

৩. **প্যাকেজ সংঘাত:**
   - একটি নতুন ভার্চুয়াল এনভায়রনমেন্ট ব্যবহার করুন
   - পৃথক প্যাকেজের পরিবর্তে `requirements.txt` থেকে ইনস্টল করুন
   - কিছু নোটবুকের মারকডাউন সেলে অতিরিক্ত প্যাকেজ উল্লেখ থাকতে পারে

৪. **আজুর সার্ভিসসমূহ:**
   - আজুর AI সার্ভিসের জন্য সক্রিয় সাবস্ক্রিপশন প্রয়োজন
   - কিছু ফিচার অঞ্চল-নির্দিষ্ট
   - নিশ্চিত করুন আজুর ওপেনএআই মডেল ডিপ্লয়মেন্ট রেসপন্সেস API সমর্থন করে

### শেখার পথ

পাঠক্রমের সুপারিশকৃত অগ্রগতি:
১. **০০-course-setup** - পরিবেশ সেটআপ শুরু এখান থেকে
২. **০১-intro-to-ai-agents** - AI এজেন্টসের মৌলিক বিষয়বলী বুঝুন
৩. **০২-explore-agentic-frameworks** - বিভিন্ন ফ্রেমওয়ার্ক জানুন
৪. **০৩-agentic-design-patterns** - মূল ডিজাইন প্যাটার্ন
৫. ধারাবাহিকভাবে নম্বরযুক্ত পাঠগুলো চালিয়ে যান

### ফ্রেমওয়ার্ক নির্বাচন

লক্ষ্য অনুযায়ী ফ্রেমওয়ার্ক নির্বাচন করুন:
- **সব পাঠ**: মাইক্রোসফট এজেন্ট ফ্রেমওয়ার্ক (MAF) `FoundryChatClient` সহ
- **এজেন্টসমূহ সার্ভার-সাইডে নিবন্ধিত** মাইক্রোসফট ফাউন্ড্রি এজেন্ট সার্ভিস V2 তে এবং ফাউন্ড্রি পোর্টালে দৃশ্যমান

### সাহায্য পাওয়া

- যোগ দিন [মাইক্রোসফট ফাউন্ড্রি কমিউনিটি ডিসকর্ডে](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)।

## প্রকল্প-নির্দিষ্ট প্রেক্ষাপট

### বহু-ভাষা সমর্থন

এই রিপোজিটরি একটি স্বয়ংক্রিয় অনুবাদ ব্যবস্থা ব্যবহার করে:
- ৫০+ ভাষার সমর্থন
- অনুবাদগুলি `/translations/<lang-code>/` ডিরেক্টরিতে
- গিটহাব অ্যাকশনস ওয়ার্কফ্লো অনুবাদ আপডেটগুলি হ্যান্ডেল করে
- ইংরেজিতে মূল ফাইলসমূহ রিপোজিটরি রুটে আছে

### পাঠ কাঠামো

প্রতিটি পাঠ ধারাবাহিক প্যাটার্ন অনুসরণ করে:
১. ভিডিও থাম্বনেইল সহ লিঙ্ক
২. লিখিত পাঠ বিষয়বস্তু (README.md)
৩. বিভিন্ন ফ্রেমওয়ার্কে কোড নমুনা
৪. শেখার উদ্দেশ্য এবং পূর্বশর্ত
৫. অতিরিক্ত শেখার সম্পদসহ লিঙ্ক

### কোড নমুনা নামকরণ

ফরম্যাট: `<lesson-number>-python-agent-framework.ipynb`
- `01-python-agent-framework.ipynb` - পাঠ ১, MAF পাইথন
- `14-sequential.ipynb` - পাঠ ১৪, MAF উন্নত প্যাটার্নসমূহ
- `16-python-agent-framework.ipynb` - পাঠ ১৬, উৎপাদন গ্রাহক-সাপোর্ট এজেন্ট
- `17-local-agent-foundry-local.ipynb` - পাঠ ১৭, ফাউন্ড্রি লোকাল + কুয়েন সহ স্থানীয় এজেন্ট

### বিশেষ ডিরেক্টরিসমূহ

- `translated_images/` - অনুবাদের জন্য স্থানীয়কৃত ছবি
- `images/` - ইংরেজি বিষয়বস্তুর জন্য মূল ছবি
- `.devcontainer/` - VS কোড ডেভেলপমেন্ট কন্টেইনার কনফিগারেশন
- `.github/` - গিটহাব অ্যাকশনস ওয়ার্কফ্লো ও টেমপ্লেট

### ডিপেনডেন্সিস

`requirements.txt` থেকে মূল প্যাকেজসমূহ:
- `agent-framework` - মাইক্রোসফট এজেন্ট ফ্রেমওয়ার্ক
- `a2a-sdk` - এজেন্ট-টু-এজেন্ট প্রটোকল সমর্থন
- `azure-ai-inference`, `azure-ai-projects` - আজুর AI সার্ভিসসমূহ
- `azure-identity` - আজুর প্রমাণীকরণ (AzureCliCredential)
- `azure-search-documents` - আজুর AI সার্চ ইন্টিগ্রেশন
- `mcp[cli]` - মডেল কনটেক্সট প্রটোকল সমর্থন

---

<!-- CO-OP TRANSLATOR DISCLAIMER START -->
**অস্বীকৃতি**:
এই নথিটি AI অনুবাদ পরিষেবা [Co-op Translator](https://github.com/Azure/co-op-translator) ব্যবহার করে অনূদিত হয়েছে। যদিও আমরা শুদ্ধতার জন্য চেষ্টা করি, অনুগ্রহ করে মনে রাখবেন যে স্বয়ংক্রিয় অনুবাদে ত্রুটি বা অসঙ্গতি থাকতে পারে। মূল নথিটি তার স্বভাষায় কর্তৃত্বপূর্ণ উৎস হিসেবে বিবেচিত হওয়া উচিত। গুরুত্বপূর্ণ তথ্যের জন্য পেশাদার মানব অনুবাদ সুপারিশ করা হয়। এই অনুবাদের ব্যবহারে প্রয়োজনীয় ভুল বোঝাবুঝি বা ভুল ব্যাখ্যার জন্য আমরা দায়বদ্ধ নই।
<!-- CO-OP TRANSLATOR DISCLAIMER END -->