ai-agents-for-beginners / ru

# AGENTS.md

## Обзор проекта

В этом репозитории содержится курс "AI Agents for Beginners" — комплексный образовательный курс, который обучает всему необходимому для создания AI агентов. Курс состоит из 18 уроков (пронумерованных 00-18), охватывающих основы, шаблоны проектирования, фреймворки, производственное развертывание, локальных/устройственных агентов и безопасность AI агентов.

**Ключевые технологии:**
- Python 3.12+
- Jupyter Notebooks для интерактивного обучения
- AI фреймворки: 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. **Склонируйте или форкните репозиторий:**
   ```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` перед запуском 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 (агенты видны в портале 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 ячейках

### Облегченное тестирование развернутых агентов

Для уроков, где агент развернут как хостинг Microsoft Foundry (01, 04, 05, 16), в репозитории есть каталоги smoke-тестов в `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 и не имеет хостинговой конечной точки, поэтому проверяется запуском своего notebook напрямую.

## Стиль кода

### Конвенции для Python

- **Версия Python**: 3.12+
- **Стиль кода**: следуйте стандартным Python конвенциям PEP 8
- **Notebooks**: используйте понятные markdown ячейки для объяснения концепций
- **Импорты**: группируйте по стандартной библиотеке, внешним пакетам, локальным импортам

### Конвенции для Jupyter Notebook

- Включайте описательные markdown ячейки перед кодовыми ячейками
- Добавляйте примеры вывода в 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** — приветствие создателей новых issue
3. **welcome-pr.yml** — приветствие новых участников pull request

### Развертывание

Это образовательный репозиторий — нет процесса развертывания. Пользователи:
1. Форкают или клонируют репозиторий
2. Запускают notebooks локально или в GitHub Codespaces
3. Обучаются, модифицируя и экспериментируя с примерами

## Руководство по Pull Request

### Перед отправкой

1. **Протестируйте ваши изменения:**
   - Полностью запустите затронутые notebooks
   - Убедитесь, что все ячейки выполняются без ошибок
   - Проверьте, что вывод корректен

2. **Обновления документации:**
   - Обновите README.md при добавлении новых концепций
   - Добавьте комментарии в notebooks для сложного кода
   - Убедитесь, что markdown ячейки объясняют цель

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

### Формат названия PR

Используйте описательные заголовки:
- `[Lesson-XX] Добавить новый пример для <концепция>`
- `[Fix] Исправить опечатку в README урока XX`
- `[Update] Улучшить пример кода в уроке 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 поддерживает API Ответов (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>/`
- Workflow GitHub Actions управляет обновлениями переводов
- Исходные файлы на английском в корне репозитория

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

Каждый урок следует единообразному шаблону:
1. Миниатюра видео с ссылкой
2. Текстовый контент урока (README.md)
3. Примеры кода в нескольких фреймворках
4. Цели обучения и предварительные требования
5. Ссылки на дополнительные обучающие ресурсы

### Именование примеров кода

Формат: `<номер-урока>-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/` — workflows и шаблоны 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]` — поддержка Model Context Protocol

---

<!-- CO-OP TRANSLATOR DISCLAIMER START -->
**Отказ от ответственности**:
Этот документ был переведен с использованием сервиса машинного перевода [Co-op Translator](https://github.com/Azure/co-op-translator). Несмотря на наши усилия по обеспечению точности, имейте в виду, что автоматический перевод может содержать ошибки или неточности. Оригинальный документ на его исходном языке следует считать авторитетным источником. Для получения критически важной информации рекомендуется обратиться к профессиональному человеческому переводу. Мы не несем ответственности за любые недоразумения или неправильные толкования, возникшие в результате использования этого перевода.
<!-- CO-OP TRANSLATOR DISCLAIMER END -->