Този урок ще обхване как да стартирате примерите с код от този курс.
Преди да започнете с клонирането на вашето хранилище, присъединете се към AI Agents For Beginners Discord канала, за да получите помощ с настройката, въпроси относно курса или за свързване с други обучаващи се.
За да започнете, моля клонирайте или форкнете GitHub хранилището. Това ще създаде ваша версия на материалите от курса, така че да можете да стартирате, тествате и променяте кода!
Това може да бъде направено като кликнете върху връзката за форкване на хранилището
Сега трябва да имате собствена форкната версия на този курс на следния линк:

Пълното хранилище може да е голямо (~3 GB), ако изтеглите цялата история и всички файлове. Ако посещавате само работилницата или се нуждаете само от няколко папки с уроци, повърхностното клониране (или частично клониране) изтегля много по-малко.
Заменете <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):
# zsh/bash
rm -rf .git
# PowerShell
Remove-Item -Recurse -Force .git
Създайте нов Codespace за това хранилище чрез GitHub UI.
Този курс предлага серия от Jupyter бележници, които можете да стартирате за практически опит с изграждането на AI агенти.
Примерите с код използват Microsoft Agent Framework (MAF) с FoundryChatClient, който се свързва с Microsoft Foundry Agent Service V2 (Responses API) през Microsoft Foundry.
Всички Python бележници са обозначени с *-python-agent-framework.ipynb.
ЗАБЕЛЕЖКА: Ако нямате инсталиран Python3.12, уверете се, че го инсталирате. След това създайте вашата виртуална среда с python3.12, за да се гарантира, че правилните версии ще се инсталират от файла requirements.txt.
Пример
Създаване на директория за Python виртуална среда:
python -m venv 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
gpt-5-mini). Вижте Стъпка 1 по-долу.Включили сме файл requirements.txt в корена на това хранилище, който съдържа всички необходими Python пакети за стартиране на примерите с код.
Можете да ги инсталирате като изпълните следната команда в терминала в корена на хранилището:
pip install -r requirements.txt
Препоръчваме да създадете Python виртуална среда, за да избегнете конфликти и проблеми.
Уверете се, че използвате правилната версия на Python във VSCode.
Необходим ви е Microsoft Foundry проект с внедрен модел, за да стартирате бележниците. Създайте проекта директно в текущото Microsoft Foundry преживяване; hub не е необходим.
gpt-5-mini) от Models + Endpoints → Deploy model.От вашия проект в портала Microsoft Foundry:

gpt-5-mini).az loginПовечето бележници се удостоверяват чрез вашия Azure CLI вход — използвайки AzureCliCredential или DefaultAzureCredential (и двете използват текущата ви az login сесия) от пакета azure-identity — така че не е необходимо API ключове. Някои уроци и опционални интеграции използват API ключове; проверете предварителните изисквания на всеки урок за допълнителни променливи на средата. Това изисква да сте влезли чрез Azure CLI.
Инсталирайте Azure CLI ако още не сте: aka.ms/installazurecli
Влезте като изпълните:
az login
Или ако сте в отдалечена среда/Codespace без браузър:
az login --use-device-code
Изберете своя абонамент ако бъдете подканени — изберете този, който съдържа вашия Foundry проект.
Проверете дали сте влезли:
az account show
Защо
az login? Бележниците се удостоверяват чрезAzureCliCredential(илиDefaultAzureCredential, който също използва Azure CLI входа ви) от пакетаazure-identity. Това означава, че вашата Azure CLI сесия предоставя идентификационните данни — без API ключове или тайни в.envфайла ви. Това е добра практика за сигурност.
.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-5-mini
| Променлива | Къде да я намерите |
|---|---|
AZURE_AI_PROJECT_ENDPOINT |
Портал Foundry → вашият проект → Обзор страница |
AZURE_AI_MODEL_DEPLOYMENT_NAME |
Портал Foundry → Модели + Крайни точки → името на вашия разположен модел |
Това е всичко за повечето уроци! Тефтерите ще се удостоверят автоматично чрез вашата az login сесия.
pip install -r requirements.txt
Препоръчваме да изпълните това във виртуалната среда, която създадохте по-рано.
Тефтерите от Урок 5 (Agentic RAG) и Урок 16 работят веднага с паметна база знания — не са необходими допълнителни Azure ресурси. Ако искате да ги поддържате с реален Azure AI Search индекс, имайте предвид, че тефтерът от Урок 16 в момента използва удостоверяване на база ключ: превключва от търсене в паметта към Azure AI Search само когато и AZURE_SEARCH_SERVICE_ENDPOINT и AZURE_SEARCH_API_KEY са зададени, и в противен случай остава с търсенето в паметта — така че за да го изпълните срещу реален индекс, трябва да зададете и администраторския ключ. Удостоверяването без ключ с Microsoft Entra ID (RBAC) е препоръчителният подход за вашия собствен продукционен код, съвместим с потока az login, използван навсякъде другаде в този курс.
Стъпките с RBAC по-долу се прилагат за примерите от наръчника за настройка и за вашия собствен код. Те не активират удостоверяване без ключ в тефтерът Урок 16; Урок 16 все още изисква както крайната точка, така и администраторския ключ за използване на Azure AI Search.
Активирайте достъп с ролеви права на вашата услуга за търсене:
az search service update --name <service-name> --resource-group <resource-group> --auth-options aadOrApiKey
Присвоете си необходимите роли (създаване/зареждане на индекси и заявки):
az role assignment create --assignee <your-user-or-principal-id> --role "Search Service Contributor" --scope $(az search service show -g <resource-group> -n <service-name> --query id -o tsv)
az role assignment create --assignee <your-user-or-principal-id> --role "Search Index Data Contributor" --scope $(az search service show -g <resource-group> -n <service-name> --query id -o tsv)
Добавете крайната точка във вашия .env файл:
| Променлива | Къде да я намерите |
|---|---|
AZURE_SEARCH_SERVICE_ENDPOINT |
Azure портал → ваш ресурс Azure AI Search → Обзор → URL |
AZURE_SEARCH_API_KEY |
Необходимо (заедно с крайната точка) за активиране на Azure AI Search в тефтерът Урок 16, който използва удостоверяване на база ключ. Azure портал → Настройки → Ключове → основен администраторски ключ |
Защо без ключ? Администраторските ключове дават пълен достъп за запис към вашата услуга за търсене и могат да изтекат чрез
.envфайлове. С RBAC се използва вашатаaz loginидентичност — същият безключов Entra ID модел, който използват тефтерите от курса (чрезAzureCliCredential/DefaultAzureCredential). Вижте Свързване с Azure AI Search чрез роли.
Вижте Наръчника за настройка на Azure AI Search за пълни примери за създаване на индекси на Python и .NET.
Някои тефтери в уроци 6 и 8 извикват Azure OpenAI директно (чрез Responses API) вместо чрез проект Microsoft Foundry. Тези примери преди това използваха GitHub Models, които са оттеглени и не поддържат Responses API. Добавете тези променливи във вашия .env файл:
| Променлива | Къде да я намерите |
|---|---|
AZURE_OPENAI_ENDPOINT |
Azure портал → ваш ресурс Azure OpenAI → Ключове и крайна точка → Крайна точка (напр. https://<your-resource>.openai.azure.com) |
AZURE_OPENAI_DEPLOYMENT |
Името на вашия разположен модел (напр. gpt-5-mini), който поддържа Responses API |
AZURE_OPENAI_API_KEY |
По избор — само ако използвате удостоверяване на база ключ, вместо az login / Entra ID |
Responses API използва стабилната
/openai/v1/крайна точка, така че не е необходимapi-version. Влезте сaz login, за да използвате удостоверяване без ключ с Entra ID.
MiniMax предоставя модели с голям контекст (до 204K токена) чрез API, съвместим с OpenAI. Тъй като OpenAIChatClient на Microsoft Agent Framework работи с всяка крайна точка, съвместима с OpenAI, можете да използвате MiniMax като директна алтернатива за уроци, които използват OpenAIChatClient.
Добавете тези променливи във вашия .env файл:
| Променлива | Къде да я намерите |
|---|---|
MINIMAX_API_KEY |
MiniMax Platform → API Ключове |
MINIMAX_BASE_URL |
Използвайте https://api.minimax.io/v1 (стойност по подразбиране) |
MINIMAX_MODEL_ID |
Име на модела за използване (напр. MiniMax-M3) |
Примерни модели: MiniMax-M3 (препоръчано), MiniMax-M2.7, MiniMax-M2.7-highspeed (по-бързи отговори). Имената на моделите и наличността могат да се променят с течение на времето, а достъпът до даден модел може да зависи от вашия акаунт.
Примерните кодове, които използват OpenAIChatClient (напр. в урок 14 при резервация на хотел), автоматично ще разпознаят и използват вашата конфигурация MiniMax, когато MINIMAX_API_KEY е зададено.
Novita AI предоставя OpenAI-съвместимо API за отворени и новаторски LLM (DeepSeek, Llama, Qwen и др.). Тъй като OpenAIChatClient на Microsoft Agent Framework работи с всяка OpenAI-съвместима крайна точка, можете да използвате Novita AI като заместител на Azure OpenAI или OpenAI.
Добавете тези променливи във вашия .env файл:
| Променлива | Къде да я намерите |
|---|---|
NOVITA_API_KEY |
Табло Novita AI → API ключове |
NOVITA_BASE_URL |
Използвайте https://api.novita.ai/openai/v1 (по подразбиране) |
NOVITA_MODEL_ID |
Име на модела за използване (напр. moonshotai/kimi-k3) |
Примерни модели: moonshotai/kimi-k3, zai-org/glm-5.2, deepseek/deepseek-v4-flash-0731. Novita AI също хоства много други семейства от отворени модели (Llama, Qwen, GLM и други) — вижте библиотеката с модели на Novita AI за текущия списък с налични модели и техните идентификатори.
Текущите примери не използват автоматично NOVITA_* променливи. За да използвате Novita AI, подавайте тези стойности изрично при създаване на OpenAIChatClient в изпълнявания пример.
Foundry Local е лек рантайм, който изтегля, управлява и предоставя езикови модели изцяло на вашата машина чрез OpenAI-съвместимо API — без нужда от облак.
Тъй като OpenAIChatClient на Microsoft Agent Framework работи с всяка OpenAI-съвместима крайна точка, Foundry Local е локална алтернатива на Azure OpenAI.
1. Инсталирайте Foundry Local
# Windows
winget install Microsoft.FoundryLocal
# macOS
brew install foundrylocal
2. Изтеглете и стартирайте модел (това стартира и локалната услуга):
foundry model list # see available models
foundry model run phi-4-mini
3. Инсталирайте Python SDK за откриване на локалната крайна точка:
pip install foundry-local-sdk
4. Насочете Microsoft Agent Framework към вашия локален модел:
from foundry_local import FoundryLocalManager
from agent_framework.openai import OpenAIChatClient
# Downloads (if needed) and serves the model locally, then discovers the endpoint/port.
manager = FoundryLocalManager("phi-4-mini")
chat_client = OpenAIChatClient(
base_url=manager.endpoint, # e.g. http://localhost:<port>/v1
api_key=manager.api_key, # always "not-required" for Foundry Local
model_id=manager.get_model_info("phi-4-mini").id,
)
agent = chat_client.as_agent(
name="LocalAgent",
instructions="You are a helpful assistant running fully on-device.",
)
Забележка: Foundry Local предоставя OpenAI-съвместима крайна точка за Chat Completions. Използвайте я за локална разработка и офлайн сценарии. За пълния набор от функции на Responses API (състояния на разговори и др.) използвайте Azure OpenAI или проект на Microsoft Foundry.
Условният работен процес в урок 8 използва Bing grounding чрез Microsoft Foundry. Ако планирате да изпълнявате този пример, добавете тази променлива във вашия .env файл:
| Променлива | Къде да я намерите |
|---|---|
BING_CONNECTION_ID |
Портал Microsoft 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: Стартирайте Install Certificates скрипта на Python (препоръчително)
# Replace 3.XX with your installed Python version (e.g., 3.12 or 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, # Disable SSL verification if you encounter certificate errors
)
⚠️ Внимание: Изключването на SSL верификация (
connection_verify=False) намалява сигурността, като пропуска проверката на сертификати. Използвайте това само временно в среди за разработка. Никога не го използвайте в продукция.
Опция 3: Инсталирайте и използвайте truststore
pip install truststore
След това добавете следното в началото на тетрадката или скрипта преди всички мрежови заявки:
import truststore
truststore.inject_into_ssl()
Ако имате проблеми с изпълнението на тази настройка, присъединете се към нашия Azure AI Community Discord или създайте проблем.
Вече сте готови да изпълните кода за този курс. Приятно учене за света на AI агентите!
Въведение в AI агенти и случаи на използване на агенти
Отказ от отговорност: Този документ е преведен с помощта на AI преводачески услуга Co-op Translator. Въпреки че се стремим към точност, моля имайте предвид, че автоматизираните преводи могат да съдържат грешки или неточности. Оригиналният документ на неговия роден език трябва да се счита за авторитетен източник. За критична информация се препоръчва професионален човешки превод. Ние не носим отговорност за каквито и да е недоразумения или неправилни тълкувания, произтичащи от използването на този превод.