ai-agents-for-beginners / bg

# 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  # В Windows: venv\Scripts\activate
   ```

3. **Инсталирайте зависимости:**
   ```bash
   pip install -r requirements.txt
   ```

4. **Настройте променливи на средата:**
   ```bash
   cp .env.example .env
   # Редактирайте .env с вашите API ключове и крайни точки
   ```

### Изисквани променливи на средата

За **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` преди стартиране на тетрадките (използва `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 абонамент
- Използва `FoundryChatClient` за Agent Service V2 (агентите са видими в портала на 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/`, които се изпълняват от workflow `.github/workflows/smoke-test.yml` чрез действието [AI Smoke Test](https://github.com/marketplace/actions/ai-smoke-test). Това са леки проверки след внедряване (достъпен ли е агентът и следва ли основните очаквания за подканване?), допълващи оценъчния pipeline в уроци 10 и 16. Вижте [tests/README.md](./tests/README.md) за съпоставяне между каталог-урок-агент. Урок 17 се изпълнява локално с Foundry Local и няма хоствана крайна точка, затова се валидира с директно изпълнение на неговата тетрадка.

## Стил на кода

### 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 pipeline

Разположен в `.github/workflows/`:

1. **co-op-translator.yml** - Автоматичен превод на 50+ езика
2. **welcome-issue.yml** - Поздравява създателите на нови проблеми (issues)
3. **welcome-pr.yml** - Поздравява допринасящите с pull request-и

### Внедряване

Това е образователно хранилище - няма процес на внедряване. Потребителите:
1. Форкват или клонират хранилището
2. Изпълняват тетрадките локално или в GitHub Codespaces
3. Учят чрез модифициране и експериментиране с примерите

## Насоки за Pull Request-и

### Преди изпращане

1. **Тествайте промените си:**
   - Изпълнете напълно засегнатите тетрадки
   - Потвърдете, че всички клетки се изпълняват без грешки
   - Проверете дали изходите са подходящи

2. **Обновяване на документацията:**
   - Обновете README.md ако добавяте нови концепции
   - Добавете коментари в тетрадките за сложен код
   - Уверете се, че markdown клетките обясняват целта

3. **Промени по файловете:**
   - Избягвайте комитиране на `.env` файлове (ползвайте `.env.example`)
   - Не комитирайте папки `venv/` или `__pycache__/`
   - Запазвайте изходите в тетрадките, когато демонстрират концепции
   - Премахнете временни файлове и резервни копия на тетрадки (`*-backup.ipynb`)

### Формат на заглавието на PR

Използвайте описателни заглавия:
- `[Lesson-XX] Добавяне на нов пример за <concept>`
- `[Fix] Корекция на правописна грешка в README на урок-XX`
- `[Update] Подобряване на примерен код в урок-XX`
- `[Docs] Обновяване на инструкции за настройка`

### Задължителни проверки

- Тетрадките трябва да се изпълняват без грешки
- README файловете трябва да са ясни и точни
- Спазвайте съществуващите кодови шаблони в хранилището
- Поддържайте последователност с други уроци

## Допълнителни бележки

### Често срещани пропуски

1. **Несъответствие на версията на Python:**
   - Уверете се, че използвате Python 3.12+
   - Някои пакети може да не работят с по-стари версии
   - Използвайте `python3 -m venv`, за да посочите ясно версията на Python

2. **Променливи на средата:**
   - Винаги създавайте `.env` от `.env.example`
   - Не комитирайте `.env` файла (той е в `.gitignore`)
   - Влезте с `az login` за удостоверяване без ключ с Entra ID

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 workflow управлява актуализации на преводите
- Изходните файлове са на английски в корена на хранилището

### Структура на урока

Всеки урок следва последователен модел:
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 workflows и шаблони

### Зависимости

Ключови пакети от `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]` - Поддръжка на Model Context Protocol

---

<!-- CO-OP TRANSLATOR DISCLAIMER START -->
**Отказ от отговорност**:
Този документ е преведен с помощта на AI преводачески услуга [Co-op Translator](https://github.com/Azure/co-op-translator). Въпреки че се стремим към точност, моля имайте предвид, че автоматизираните преводи могат да съдържат грешки или неточности. Оригиналният документ на неговия роден език трябва да се счита за авторитетен източник. За критична информация се препоръчва професионален човешки превод. Ние не носим отговорност за каквито и да е недоразумения или неправилни тълкувания, произтичащи от използването на този превод.
<!-- CO-OP TRANSLATOR DISCLAIMER END -->