ai-agents-for-beginners / el

# AGENTS.md

## Επισκόπηση Έργου

Αυτό το αποθετήριο περιέχει "Πρακτικοί Πράκτορες Τεχνητής Νοημοσύνης για Αρχάριους" - ένα ολοκληρωμένο εκπαιδευτικό μάθημα που διδάσκει όλα όσα χρειάζονται για την κατασκευή Πρακτικών Πρακτόρων Τεχνητής Νοημοσύνης. Το μάθημα αποτελείται από 18 μαθήματα (αριθμημένα 00-18) που καλύπτουν βασικές έννοιες, πρότυπα σχεδίασης, πλαίσια, ανάπτυξη σε παραγωγή, πράκτορες τοπικά ή στη συσκευή, και ασφάλεια των πρακτόρων ΤΝ.

**Κύριες Τεχνολογίες:**
- Python 3.12+
- Jupyter Notebooks για διαδραστική μάθηση
- Πλαίσια Τεχνητής Νοημοσύνης: Microsoft Agent Framework (MAF)
- Υπηρεσίες Azure AI: Microsoft Foundry, Microsoft Foundry Agent Service V2

**Αρχιτεκτονική:**
- Δομημένη ανά μάθημα (00-15+ φάκελοι)
- Κάθε μάθημα περιλαμβάνει: τεκμηρίωση README, δείγματα κώδικα (Jupyter notebooks), και εικόνες
- Υποστήριξη πολλαπλών γλωσσών μέσω αυτοματοποιημένου συστήματος μετάφρασης
- Ένα αρχείο Python notebook ανά μάθημα που χρησιμοποιεί το Microsoft Agent Framework

## Εντολές Εγκατάστασης

### Προαπαιτούμενα
- Python 3.12 ή νεότερο
- Συνδρομή Azure (για Microsoft Foundry)
- Εγκατεστημένο και αυθεντικοποιημένο Azure CLI (`az login`)

### Αρχική Ρύθμιση

1. **Κλωνοποίηση ή fork του αποθετηρίου:**
   ```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  # Στα Windows: venv\Scripts\activate
   ```

3. **Εγκατάσταση εξαρτήσεων:**
   ```bash
   pip install -r requirements.txt
   ```

4. **Ορισμός μεταβλητών περιβάλλοντος:**
   ```bash
   cp .env.example .env
   # Επεξεργαστείτε το .env με τα κλειδιά API και τα endpoints σας
   ```

### Απαιτούμενες Μεταβλητές Περιβάλλοντος

Για **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` πριν την εκτέλεση notebooks (χρησιμοποιεί `AzureCliCredential`).

## Ροή Ανάπτυξης

### Εκτέλεση Jupyter Notebooks

Κάθε μάθημα περιέχει πολλαπλά Jupyter notebooks για διαφορετικά πλαίσια:

1. **Εκκίνηση Jupyter:**
   ```bash
   jupyter notebook
   ```

2. **Πλοήγηση στο φάκελο μαθήματος** (π.χ., `01-intro-to-ai-agents/code_samples/`)

3. **Άνοιγμα και εκτέλεση notebooks:**
   - `*-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
- Χρησιμοποιεί `FoundryChatClient` για Agent Service V2 (πράκτορες ορατοί στο portal Foundry)
- Έτοιμο για παραγωγή με ενσωματωμένη παρατηρησιμότητα
- Πρότυπο αρχείου: `*-python-agent-framework.ipynb`

## Οδηγίες Δοκιμών

Αυτό είναι ένα εκπαιδευτικό αποθετήριο με παραδείγματα κώδικα και όχι παραγωγικό κώδικα με αυτοματοποιημένες δοκιμές. Για να επιβεβαιώσετε τη ρύθμιση και τις αλλαγές σας:

### Χειροκίνητη Δοκιμή

1. **Δοκιμή περιβάλλοντος Python:**
   ```bash
   python --version  # Πρέπει να είναι 3.12+
   pip list | grep -E "(agent-framework|azure-ai|azure-identity)"
   ```

2. **Δοκιμή εκτέλεσης notebook:**
   ```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')"
   ```

### Εκτέλεση Μοναδικών Notebooks

Ανοίξτε notebooks στο Jupyter και εκτελέστε τα κελιά διαδοχικά. Κάθε notebook είναι αυτόνομο και περιλαμβάνει:
- Δηλώσεις εισαγωγής
- Φόρτωση ρυθμίσεων
- Παραδείγματα υλοποίησης πρακτόρων
- Αναμενόμενα αποτελέσματα σε κελιά markdown

### Smoke-Testing Ανεπτυγμένων Πρακτόρων

Για μαθήματα όπου ένας πράκτορας είναι ανεπτυγμένος ως πράκτορας φιλοξενούμενος από Microsoft Foundry (01, 04, 05, 16), το αποθετήριο παρέχει καταλόγους smoke-test κάτω από το `tests/` που τρέχουν μέσω της ροής εργασίας `.github/workflows/smoke-test.yml` με τη δράση [AI Smoke Test](https://github.com/marketplace/actions/ai-smoke-test). Αυτά αποτελούν ελαφρύ έλεγχο μετά την ανάπτυξη (είναι ο πράκτορας προσβάσιμος και ακολουθεί βασικές προσδοκίες prompt;) και συμπληρώνουν την αξιολόγηση στην ροή εργασίας των μαθημάτων 10 και 16. Δείτε [tests/README.md](./tests/README.md) για τη συσχέτιση καταλόγου-μαθήματος-πράκτορα. Το μάθημα 17 τρέχει τοπικά με Foundry Local και δεν έχει φιλοξενούμενο τερματικό, οπότε επικυρώνεται με απευθείας εκτέλεση του notebook του.

## Στυλ Κώδικα

### Συμβάσεις Python

- **Έκδοση Python**: 3.12+
- **Στυλ Κώδικα**: Ακολουθήστε τα τυπικά πρότυπα PEP 8 της Python
- **Notebooks**: Χρησιμοποιήστε καθαρά κελιά markdown για να εξηγήσετε έννοιες
- **Εισαγωγές**: Ομαδοποιήστε ανά βιβλιοθήκη standard, τρίτων, και τοπικά imports

### Συμβάσεις Jupyter Notebook

- Περιλάβετε περιγραφικά κελιά markdown πριν από τα κελιά κώδικα
- Προσθέστε παραδείγματα εξόδου στα notebooks για αναφορά
- Χρησιμοποιήστε σαφή ονόματα μεταβλητών που ταιριάζουν με τις έννοιες του μαθήματος
- Κρατήστε τη γραμμική σειρά εκτέλεσης notebooks (κελί 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 Pipeline

Βρίσκεται σε `.github/workflows/`:

1. **co-op-translator.yml** - Αυτόματη μετάφραση σε 50+ γλώσσες
2. **welcome-issue.yml** - Καλωσορίζει δημιουργούς νέων θεμάτων
3. **welcome-pr.yml** - Καλωσορίζει νέους συνεισφέροντες pull request

### Ανάπτυξη

Αυτό είναι ένα εκπαιδευτικό αποθετήριο - δεν υπάρχει διαδικασία ανάπτυξης. Οι χρήστες:
1. Κλωνοποιούν ή κάνουν fork το αποθετήριο
2. Τρέχουν notebooks τοπικά ή σε GitHub Codespaces
3. Μαθαίνουν τροποποιώντας και πειραματιζόμενοι με παραδείγματα

## Οδηγίες Pull Request

### Πριν Υποβάλετε

1. **Δοκιμάστε τις αλλαγές σας:**
   - Τρέξτε πλήρως τα επηρεαζόμενα notebooks
   - Βεβαιωθείτε ότι όλα τα κελιά εκτελούνται χωρίς σφάλματα
   - Ελέγξτε ότι οι έξοδοι είναι κατάλληλες

2. **Ενημερώσεις τεκμηρίωσης:**
   - Ανανεώστε README.md αν προσθέτετε νέες έννοιες
   - Προσθέστε σχόλια στα notebooks για πολύπλοκο κώδικα
   - Διασφαλίστε ότι τα κελιά markdown εξηγούν τον σκοπό

3. **Αλλαγές αρχείων:**
   - Αποφύγετε την υποβολή αρχείων `.env` (χρησιμοποιήστε `.env.example`)
   - Μην υποβάλετε φακέλους `venv/` ή `__pycache__/`
   - Διατηρήστε τις εξόδους notebooks όταν παρουσιάζουν έννοιες
   - Αφαιρέστε προσωρινά αρχεία και backup notebooks (`*-backup.ipynb`)

### Μορφή Τίτλου PR

Χρησιμοποιήστε περιγραφικούς τίτλους:
- `[Lesson-XX] Προσθήκη νέου παραδείγματος για <concept>`
- `[Fix] Διόρθωση ορθογραφικού λάθους στο lesson-XX README`
- `[Update] Βελτίωση δείγματος κώδικα στο lesson-XX`
- `[Docs] Ενημέρωση οδηγιών εγκατάστασης`

### Απαιτούμενοι Έλεγχοι

- Τα notebooks πρέπει να εκτελούνται χωρίς σφάλματα
- Τα αρχεία README πρέπει να είναι κατανοητά και ακριβή
- Ακολουθήστε υπάρχοντα πρότυπα κώδικα στο αποθετήριο
- Διατηρήστε συνέπεια με τα υπόλοιπα μαθήματα

## Επιπλέον Σημειώσεις

### Συνήθη Προβλήματα

1. **Ασυμφωνία έκδοσης Python:**
   - Βεβαιωθείτε ότι χρησιμοποιείται Python 3.12+
   - Κάποια πακέτα μπορεί να μην λειτουργούν με παλαιότερες εκδόσεις
   - Χρησιμοποιήστε `python3 -m venv` για να προσδιορίσετε ρητά την έκδοση Python

2. **Μεταβλητές περιβάλλοντος:**
   - Πάντα δημιουργήστε `.env` από `.env.example`
   - Μην υποβάλετε το αρχείο `.env` (περιλαμβάνεται στο `.gitignore`)
   - Συνδεθείτε με `az login` για πιστοποίηση Entra ID χωρίς κλειδί

3. **Σύγκρουση πακέτων:**
   - Χρησιμοποιήστε φρέσκο εικονικό περιβάλλον
   - Εγκαταστήστε από το `requirements.txt` αντί για μεμονωμένα πακέτα
   - Ορισμένα notebooks μπορεί να απαιτούν επιπλέον πακέτα που αναφέρονται στα κελιά markdown τους

4. **Υπηρεσίες Azure:**
   - Οι υπηρεσίες Azure AI απαιτούν ενεργή συνδρομή
   - Κάποιες λειτουργίες είναι περιορισμένες ανά περιοχή
   - Βεβαιωθείτε ότι η ανάπτυξη μοντέλου Azure OpenAI υποστηρίζει το Responses API

### Διαδρομή Μάθησης

Συνιστώμενη σειρά μαθημάτων:
1. **00-course-setup** - Ξεκινήστε εδώ για τη ρύθμιση περιβάλλοντος
2. **01-intro-to-ai-agents** - Κατανοήστε τα βασικά των πρακτόρων ΤΝ
3. **02-explore-agentic-frameworks** - Μάθετε για διάφορα πλαίσια
4. **03-agentic-design-patterns** - Κύρια πρότυπα σχεδίασης
5. Συνεχίστε με τα διαδοχικά αριθμημένα μαθήματα

### Επιλογή Πλαισίου

Επιλέξτε πλαίσιο ανάλογα με τους στόχους σας:
- **Όλα τα μαθήματα**: Microsoft Agent Framework (MAF) με `FoundryChatClient`
- **Οι πράκτορες εγγράφονται server-side** στην Microsoft Foundry Agent Service V2 και είναι ορατοί στο portal 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, τοπικός πράκτορας με Foundry Local + Qwen

### Ειδικοί Φάκελοι

- `translated_images/` - Εντοπισμένες εικόνες για μεταφράσεις
- `images/` - Αρχικές εικόνες για αγγλικό περιεχόμενο
- `.devcontainer/` - Ρύθμιση κοντέινερ ανάπτυξης VS Code
- `.github/` - Ροές εργασίας και πρότυπα GitHub Actions

### Εξαρτήσεις

Βασικά πακέτα από `requirements.txt`:
- `agent-framework` - Microsoft Agent Framework
- `a2a-sdk` - Υποστήριξη πρωτοκόλλου Agent-to-Agent
- `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 -->
**Αποποίηση ευθυνών**:
Αυτό το έγγραφο έχει μεταφραστεί χρησιμοποιώντας την υπηρεσία μετάφρασης με τεχνητή νοημοσύνη [Co-op Translator](https://github.com/Azure/co-op-translator). Ενώ επιδιώκουμε την ακρίβεια, παρακαλούμε να έχετε υπόψη ότι οι αυτοματοποιημένες μεταφράσεις ενδέχεται να περιέχουν λάθη ή ανακρίβειες. Το πρωτότυπο έγγραφο στη μητρική του γλώσσα πρέπει να θεωρείται η αυθεντική πηγή. Για κρίσιμες πληροφορίες, συνιστάται επαγγελματική ανθρώπινη μετάφραση. Δεν φέρουμε ευθύνη για τυχόν παρεξηγήσεις ή λανθασμένες ερμηνείες που προκύπτουν από τη χρήση αυτής της μετάφρασης.
<!-- CO-OP TRANSLATOR DISCLAIMER END -->