В этом уроке мы рассмотрим, как запускать примеры кода из этого курса.

Перед тем, как клонировать репозиторий, присоединяйтесь к каналу AI Agents For Beginners Discord, чтобы получить помощь с настройкой, задать вопросы по курсу или пообщаться с другими учащимися.

Для начала клонируйте или форкните репозиторий с GitHub. Это создаст вашу собственную версию материалов курса, чтобы вы могли запускать, тестировать и изменять код!

Это можно сделать, кликнув по ссылке форкнуть репозиторий

Теперь у вас должна быть своя форкнутая версия этого курса по следующей ссылке:

Полный репозиторий может быть большим (~3 ГБ), если загружать всю историю и все файлы. Если вы только посещаете воркшоп или вам нужны только несколько папок с уроками, поверхностное (shallow) или разреженное (sparse) клонирование позволяет избежать большей части загрузки, сокращая историю и/или пропуская бинарные файлы.

Замените <your-username> в командах ниже на URL вашего форка (или URL исходного репозитория, если предпочитаете).

Для клонирования только последней истории коммита (малый объём загрузки):

git clone --depth 1 https://github.com/<your-username>/ai-agents-for-beginners.git

Для клонирования конкретной ветки:

git clone --depth 1 --branch <branch-name> https://github.com/<your-username>/ai-agents-for-beginners.git

Используется частичное клонирование и sparse-checkout (требуется Git 2.25+ и рекомендуется современный Git с поддержкой частичного клонирования):

git clone --depth 1 --filter=blob:none --sparse https://github.com/<your-username>/ai-agents-for-beginners.git

Перейдите в папку репозитория:

cd ai-agents-for-beginners

Затем укажите папки, которые вам нужны (пример ниже показывает две папки):

git sparse-checkout set 00-course-setup 01-intro-to-ai-agents

После клонирования и проверки файлов, если вам нужны только файлы и хотите освободить место (без истории git), удалите файлы метаданных репозитория (💀безвозвратно — вы потеряете всю функциональность Git: коммиты, операции pull/push и доступ к истории).

# zsh/bash
rm -rf .git

# PowerShell
Remove-Item -Recurse -Force .git

• Создайте новый Codespace для этого репозитория через GitHub UI.

• В терминале вновь созданного Codespace выполните одну из команд поверхностного/разреженного клонирования выше, чтобы подтянуть только нужные папки уроков в рабочее пространство Codespace.

• По желанию: после клонирования внутри Codespaces удалите .git для освобождения дополнительного места (см. команды удаления выше).

• Внимание: если вы предпочитаете сразу открыть репозиторий в Codespaces (без дополнительного клонирования), учтите, что Codespaces создаст devcontainer и возможно задействует больше компонентов, чем вам нужно. Клонирование поверхностной копии внутри нового Codespace даёт больше контроля над использованием диска.

• Всегда заменяйте URL клона на ваш форк, если хотите редактировать и коммитить.
• Если позже понадобится больше истории или файлов, вы можете их получить или изменить настройки sparse-checkout для включения дополнительных папок.

Курс включает серию ноутбуков Jupyter, которые вы можете запускать для практического опыта создания AI-агентов.

Примеры кода используют Microsoft Agent Framework (MAF) с провайдером AzureAIProjectAgentProvider, который подключается к Azure AI Agent Service V2 (API ответов) через Microsoft Foundry.

Все Python ноутбуки имеют название в формате *-python-agent-framework.ipynb.

• Python 3.12+

  • ПРИМЕЧАНИЕ: Если у вас не установлен Python 3.12, обязательно установите его. Затем создайте виртуальное окружение с использованием python3.12, чтобы правильно установить версии из файла requirements.txt.

    Пример

    Создание виртуального окружения Python:

    python -m venv venv
    

    Затем активируйте виртуальное окружение для:

    # zsh/bash
    source venv/bin/activate
    

    # Command Prompt for Windows
    venv\Scripts\activate
    

• .NET 10+: Для примеров кода на .NET убедитесь, что установлен .NET 10 SDK или новее. Проверьте версию установленного .NET SDK:

  dotnet --list-sdks
  

• Azure CLI — требуется для аутентификации. Установите с aka.ms/installazurecli.

• Подписка Azure — для доступа к Microsoft Foundry и Azure AI Agent Service.

• Проект Microsoft Foundry — проект с развернутой моделью (например, gpt-4o). См. Шаг 1 ниже.

В корне репозитория есть файл requirements.txt со всеми необходимыми Python пакетами для запуска примеров.

Установите пакеты, выполнив в терминале команду из корня репозитория:

pip install -r requirements.txt

Рекомендуется создавать виртуальное окружение Python, чтобы избежать конфликтов.

Убедитесь, что в VSCode используется нужная версия Python.

Вам нужен центр (hub) и проект в Azure AI Foundry с развернутой моделью для запуска ноутбуков.

1. Перейдите на ai.azure.com и войдите в свою учетную запись Azure.
2. Создайте центр (или используйте существующий). Подробнее: Обзор ресурсов хаба.
3. Внутри хаба создайте проект.
4. Разверните модель (например, gpt-4o) из раздела Models + Endpoints → Deploy model.

В портале Microsoft Foundry в вашем проекте:

• Project Endpoint — перейдите на страницу Overview и скопируйте URL конечной точки.

• Model Deployment Name — зайдите в Models + Endpoints, выберите развернутую модель и запомните имя развертывания (Deployment name), например gpt-4o.

Все ноутбуки используют AzureCliCredential для аутентификации — ключи API не нужны. Вам просто нужно войти через Azure CLI.

1. Установите Azure CLI, если еще не сделали это: aka.ms/installazurecli

2. Войдите в систему, выполнив:

   az login
   

   Или, если вы работаете в удаленной среде/Codespace без браузера:

   az login --use-device-code
   

3. Выберите подписку, если будет запрос — выберите подписку с вашим проектом Foundry.

4. Проверьте, что вы вошли:

   az account show
   

Почему az login? Ноутбуки аутентифицируются с помощью AzureCliCredential из пакета azure-identity. Это значит, что ваша сессия Azure CLI обеспечивает учетные данные — никаких ключей API или секретов в файле .env. Это лучший подход с точки зрения безопасности.

Скопируйте пример файла:

# zsh/bash
cp .env.example .env

# PowerShell
Copy-Item .env.example .env

Откройте .env и заполните эти два значения:

AZURE_AI_PROJECT_ENDPOINT=https://<your-project>.services.ai.azure.com/api/projects/<your-project-id>
AZURE_AI_MODEL_DEPLOYMENT_NAME=gpt-4o

Переменная	Где найти
AZURE_AI_PROJECT_ENDPOINT	Портал Foundry → ваш проект → страница Overview
AZURE_AI_MODEL_DEPLOYMENT_NAME	Портал Foundry → Models + Endpoints → имя в развернутой модели

Вот и все для большинства уроков! Ноутбуки будут аутентифицироваться автоматически через вашу сессию az login.

pip install -r requirements.txt

Рекомендуется запускать это внутри ранее созданного виртуального окружения.

Урок 5 использует Azure AI Search для retrieval-augmented generation. Если вы собираетесь запускать этот урок, добавьте в свой .env следующие переменные:

Переменная	Где найти
AZURE_SEARCH_SERVICE_ENDPOINT	Портал Azure → ваш ресурс Azure AI Search → Overview → URL
AZURE_SEARCH_API_KEY	Портал Azure → ваш ресурс Azure AI Search → Settings → Keys → основной ключ администратора

Некоторые ноутбуки из уроков 6 и 8 используют GitHub Models вместо Azure AI Foundry. Если планируете запускать эти примеры, добавьте в .env следующие переменные:

Переменная	Где найти
GITHUB_TOKEN	GitHub → Settings → Developer settings → Personal access tokens
GITHUB_ENDPOINT	Используйте https://models.inference.ai.azure.com (значение по умолчанию)
GITHUB_MODEL_ID	Имя модели для использования (например, gpt-4o-mini)

Условный workflow в уроке 8 использует Bing grounding через Azure AI Foundry. Если планируете запускать этот пример, добавьте в .env переменную:

Переменная	Где найти
BING_CONNECTION_ID	Портал Azure AI Foundry → ваш проект → Management → Connected resources → ваше соединение Bing → скопируйте ID соединения

Если вы используете macOS и сталкиваетесь с ошибкой вида:

ssl.SSLCertVerificationError: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: self-signed certificate in certificate chain

Это известная проблема с Python на macOS, где системные SSL сертификаты не автоматически доверяются. Попробуйте следующие решения по порядку:

Вариант 1: Запустите скрипт установки сертификатов Python (рекомендуется)

# Замените 3.XX на установленную версию Python (например, 3.12 или 3.13):
/Applications/Python\ 3.XX/Install\ Certificates.command

Вариант 2: Используйте connection_verify=False в ноутбуках (только для ноутбуков GitHub Models)

В ноутбуке урока 6 (06-building-trustworthy-agents/code_samples/06-system-message-framework.ipynb) уже есть закомментированное решение. Раскомментируйте connection_verify=False при создании клиента:

client = ChatCompletionsClient(
    endpoint=endpoint,
    credential=AzureKeyCredential(token),
    connection_verify=False,  # Отключите проверку SSL, если возникают ошибки сертификата
)

⚠️ Внимание: Отключение проверки SSL (connection_verify=False) снижает безопасность, пропуская проверку сертификатов. Используйте это только как временное решение в процессе разработки, никогда не применяйте в продакшене.

Вариант 3: Установите и используйте truststore

pip install truststore

Затем добавьте следующее в начало вашего ноутбука или скрипта перед сетевыми вызовами:

import truststore
truststore.inject_into_ssl()

Если у вас возникли проблемы с запуском настройки, присоединяйтесь к нашему Azure AI Community Discord или создайте issue.

Теперь вы готовы запускать код этого курса. Желаем успехов в изучении мира AI-агентов!

Введение в AI-агентов и варианты использования агентов

---

Отказ от ответственности:
Этот документ был переведен с помощью службы автоматического перевода Co-op Translator. Несмотря на наши усилия обеспечить точность, просим учитывать, что автоматические переводы могут содержать ошибки или неточности. Оригинальный документ на его исходном языке следует рассматривать как авторитетный источник. Для получения критически важной информации рекомендуется обращаться к профессиональному переводу, выполненному человеком. Мы не несем ответственности за любые недоразумения или неправильные толкования, возникшие в результате использования данного перевода.