ai-agents-for-beginners / te

# AGENTS.md

## ప్రాజెక్ట్ అవలోకనం

ఈ రిపాజిటరీ "ఆઈ ఏజెంట్స్ ఫర్ బిగినర్స్" ని కలిగి ఉంది - ఏఐ ఏజెంట్స్ నిర్మించడానికి కావలసిన ప్రతిదీ నేర్పించే సమగ్ర విద్యా కోర్సు. కోర్సు 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లో నోట్బుక్స్ తెరిచి క్రమంగా సెల్స్ అమలు చేయండి. ప్రతి నోట్బుక్ స్వయం-గతమైనది మరియు కలిగి ఉంటుంది:
- దిగుమతి ప్రస్తావనలు
- కాన్ఫిగరేషన్ లోడ్ చేయడం
- ఉదాహరణ ఏజెంట్ అమలు
- Markdown సెల్స్ లో ఆశించిన అవుట్పుట్స్

### అమలు చేసిన ఏజెంట్ల స్మోక్-టెస్టింగ్

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 ఫౌండ్రి లోకల్ తో స్థానికంగా నడుస్తుంది మరియు హోస్టెడ్ ఎండ్‌పాయింట్ లేదు, కాబట్టి దాని నోట్బుక్ నేరుగా నడిపించడం ద్వారా ధృవీకరించబడుతుంది.

## కోడ్ శైలి

### Python సాంప్రదాయాలు

- **Python వెర్షన్**: 3.12+
- **కోడ్ శైలి**: సాధారణ Python PEP 8 సాంప్రదాయాలు అనుసరించండి
- **నోట్‌బుక్స్**: సూత్రాలను వివరించడానికి స్పష్టమైన Markdown సెల్స్ ఉపయోగించండి
- **దిగుమతులు**: స్టాండర్డ్ లైబ్రరీ, మూడవ పక్ష, స్థానిక దిగుమతులు గ్రూప్ చేయండి

### Jupyter నోట్బుక్ సాంప్రదాయాలు

- కోడ్ సెల్స్ ముందు వివరణాత్మక Markdown సెల్స్ చేర్చండి
- సూచన కోసం నోట్బుక్స్‌లో అవుట్పుట్ ఉదాహరణలు జోడించండి
- పాఠం సూత్రాలకు సంబంధించిన స్పష్టమైన వేరియబుల్ పేర్లను వుపయోగించండి
- నోట్బుక్ అమలు క్రమాన్ని క్రమంగా ఉంచండి (సెల్ 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 అప్డేట్ చేయండి
   - సంక్లిష్ట కోడ్ కోసం నోట్బుక్స్ లో వ్యాఖ్యలు చేర్చండి
   - Markdown సెల్స్ ఉద్దేశ్యాన్ని వివరించాలి

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+ వాడటం నిర్ధారించండి
   - కొన్ని ప్యాకేజీలు పాత వెర్షన్లతో పని చేయకపోవచ్చు
   - స్పష్టంగా Python వెర్షన్ సూచించడానికి `python3 -m venv` వాడండి

2. **ఎన్విరాన్మెంట్ వేరియబుల్స్:**
   - ఎప్పుడూ `.env.example` నుండి `.env` సృష్టించండి
   - `.env` ఫైలు కమిట్ చేయవద్దు (దేను `.gitignore` లో ఉంచాలి)
   - కీవిల్లెస్ Entra ID ప్రామాణీకరణ కోసం `az login` తో సైన్ ఇన్ అవ్వండి

3. **ప్యాకేజీ సంకర్షణలు:**
   - కొత్త వర్చువల్ ఎన్విరాన్మెంట్ ఉపయోగించండి
   - వ్యక్తిగత ప్యాకేజీల కంటే `requirements.txt` నుండి ఇన్‌స్టాల్ చేయండి
   - కొన్ని నోట్బుక్స్ తమ markdown సెల్స్‌లో అదనపు ప్యాకేజీలను సూచించవచ్చు

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 Community 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, ఫౌండ్రి లోకల్ + క్వేన్ తో స్థానిక ఏజెంట్

### ప్రత్యేక డైరెక్టరీలు

- `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 -->