ai-agents-for-beginners

Подешавање курса

Увод

Овај час ће обухватити како покренути примере кода овог курса.

Придружите се другим ученицима и добијте помоћ

Пре него што почнете са клонирањем вашег репозиторијума, придружите се AI Agents For Beginners Discord каналу да бисте добили помоћ при подешавању, одговоре на питања о курсу или да бисте се повезали са другим ученицима.

Клонирајте или форкујте овај репозиторијум

За почетак, молимо вас да клонирате или форкујете GitHub репозиторијум. Ово ће вам направити вашу верзију материјала курса како бисте могли да покренете, тестирате и мењате код!

Ово можете урадити кликом на линк fork the repo

Сада бисте требали имати своју форковану верзију овог курса на следећем линку:

Forked Repo

Плитко клонирање (препоручено за радионице / Codespaces)

Пуни репозиторијум може бити велики (~3 ГБ) када преузмете целу историју и све фајлове. Ако присуствујете само радионици или вам требају само неке фасцикле лекција, плитко клонирање (или скарачено клонирање) избегава већину тих преузимања тако што скраћује историју и/или прескаче блобове.

Брзо плитко клонирање — минимална историја, сви фајлови

Замените <your-username> у следећим командама са URL-ом вашег форка (или upstream 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

Коришћење GitHub Codespaces (препоручено за избегавање великих локалних преузимања)

Савети

Покретање кода

Овај курс нуди серију Jupyter бележница које можете покренути како бисте стекли практично искуство у изградњи AI агената.

Примери кода користе Microsoft Agent Framework (MAF) са FoundryChatClient, који се повезује са Microsoft Foundry Agent Service V2 (Responses API) преко Microsoft Foundry.

Све Python бележнице су означене са *-python-agent-framework.ipynb.

Захтеви

Укључили смо requirements.txt фајл у корен овог репозиторијума који садржи све потребне Python пакете за покретање примера кода.

Можете их инсталирати покретањем следеће команде у вашем терминалу у корену репозиторијума:

pip install -r requirements.txt

Препоручујемо да направите Python виртуелно окружење да бисте избегли конфликте и проблеме.

Подешавање VSCode

Уверите се да користите праву верзију Python-а у VSCode.

image

Подешавање Microsoft Foundry и Microsoft Foundry Agent Service

Корак 1: Креирајте Microsoft Foundry Пројекат

Потребан вам је Microsoft Foundry hub и проект са распоређеним моделом за покретање бележница.

  1. Идите на ai.azure.com и пријавите се са вашим Azure налогом.
  2. Креирајте hub (или користите постојећи). Погледајте: Pregled Hub ресурса.
  3. Унутар hub-а, креирајте проект.
  4. Распоредите модел (нпр. gpt-4.1-mini) из Models + Endpoints → Deploy model.

Корак 2: Преузмите URL ендпоинта вашег пројекта и име распоређеног модела

Из вашег пројекта у Microsoft Foundry порталу:

Project Connection String

Корак 3: Пријавите се у Azure помоћу az login

Све бележнице користе 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 фајлу. Ово је безбедносна најбоља пракса.

Корак 4: Креирајте ваш .env фајл

Копирајте пример фајл:

# зш/баш
cp .env.example .env

# ПоверШел
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-4.1-mini
Променљива Где је пронаћи
AZURE_AI_PROJECT_ENDPOINT Foundry портал → ваш пројекат → страница Overview
AZURE_AI_MODEL_DEPLOYMENT_NAME Foundry портал → Models + Endpoints → име вашег распоређеног модела

То је све за већину лекција! Бележнице ће аутоматски аутентификовати преко ваше az login сесије.

Корак 5: Инсталирајте Python зависности

pip install -r requirements.txt

Препоручујемо да ово покренете унутар виртуелног окружења које сте раније креирали.

Додатно подешавање за лекцију 5 (Agentic RAG)

Лекција 5 користи Azure AI Search за генерацију уз подршку преузимања. Ако планирате да покренете ту лекцију, додајте ове променљиве у ваш .env фајл:

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

Додатно подешавање за лекције које позивају Azure OpenAI директно (лекције 6 и 8)

Неке бележнице у лекцијама 6 и 8 директно позивају Azure OpenAI (користећи Responses API) уместо да иду кроз Microsoft Foundry пројекат. Ови примери су раније користили GitHub Models, који је застарео (планирани крај у јулу 2026) и не подржава Responses API. Ако планирате покренути те примере, додајте ове променљиве у ваш .env фајл:

Променљива Где је пронаћи
AZURE_OPENAI_ENDPOINT Azure портал → ваш ресурс Azure OpenAI → Keys and Endpoint → Endpoint (нпр. https://<your-resource>.openai.azure.com)
AZURE_OPENAI_DEPLOYMENT Име вашег распоређеног модела (нпр. gpt-4.1-mini) који подржава Responses API
AZURE_OPENAI_API_KEY Опционо — само ако користите аутентификацију на бази кључа уместо az login / Entra ID

Responses API користи стабилан /openai/v1/ енпоинт, тако да није потребан api-version. Пријавите се са az login да бисте користили аутентификацију без кључа преко Entra ID.

Алтернативни провајдер: MiniMax (компатибилан са OpenAI)

MiniMax пружа моделе са великим контекстом (до 204К токена) преко OpenAI-компатибилног API-ја. Пошто Microsoft Agent Framework-ов OpenAIChatClient ради са било којим OpenAI-компатибилним енпоинтом, можете користити MiniMax као замену за Azure OpenAI или OpenAI.

Додајте ове променљиве у ваш .env фајл:

Променљива Где је пронаћи
MINIMAX_API_KEY MiniMax Platform → API Keys
MINIMAX_BASE_URL Користите https://api.minimax.io/v1 (подразумевана вредност)
MINIMAX_MODEL_ID Име модела за коришћење (нпр. MiniMax-M3)

Пример модела: MiniMax-M3 (препоручени), MiniMax-M2.7, MiniMax-M2.7-highspeed (брже одговоре). Имена модела и доступност се могу временом мењати, а приступ одређеном моделу може зависити од вашег налога или региона — проверите MiniMax Platform за тренутну листу. Ако MiniMax-M3 није доступан вашем налогу, подесите MINIMAX_MODEL_ID на модел коме имате приступ (нпр. MiniMax-M2.7).

Примери кода који користе OpenAIChatClient (нпр. Лекција 14, процес резервације хотела) аутоматски ће препознати и користити вашу MiniMax конфигурацију када је подешен MINIMAX_API_KEY.

Алтернативни провајдер: Foundry Local (покретање модела локално)

Foundry Local је лагано окружење које преузима, управља и сервира језичке моделе потпуно на вашем рачунару преко OpenAI-компатибилног API-ја — без облака, без Azure претплате и без API кључева. Одлична је опција за офлајн развој, експериментисање без трошкова облака или за чување података локално.

Пошто Microsoft Agent Framework-ов OpenAIChatClient ради са било којим OpenAI-компатибилним енпоинтом, Foundry Local је локална алтернатива Azure OpenAI-у.

1. Инсталирајте Foundry Local

# Виндоус
winget install Microsoft.FoundryLocal

# мacОС
brew install foundrylocal

2. Преузмите и покрените модел (ово такође стартује локалну услугу):

foundry model list          # видети доступне моделе
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

# Преузима (ако је потребно) и сервира модел локално, затим открива крајњу тачку/порт.
manager = FoundryLocalManager("phi-4-mini")

chat_client = OpenAIChatClient(
    base_url=manager.endpoint,      # нпр. http://localhost:<порт>/v1
    api_key=manager.api_key,        # увек "необавезно" за 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 пројекат као што је показано у лекцијама. Погледајте Foundry Local документацију за тренутни каталог модела и подршку платформе.

Додатна подешавања за Лекцију 8 (Bing Grounding Workflow)

Кондиционални workflow notebook у лекцији 8 користи Bing grounding преко Microsoft Foundry. Ако планирате да покренете тај пример, додајте ову променљиву у ваш .env фајл:

Променљива Где се налази
BING_CONNECTION_ID Microsoft Foundry портал → ваш пројекат → Management → Connected resources → ваша Bing конекција → копирајте connection ID

Решавање проблема

Грешке приликом верификације SSL сертификата на macOS

Ако користите macOS и наиђете на грешку као што је:

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

Ово је познат проблем са Питоном на macOS-у где системски SSL сертификати нису аутоматски поверења вредни. Покушајте следећа решења по редоследу:

Опција 1: Покрените Python скрипту Install Certificates (препоручено)

# Замените 3.XX са вашем инсталираном верзијом Питхона (нпр. 3.12 или 3.13):
/Applications/Python\ 3.XX/Install\ Certificates.command

Опција 2: Користите connection_verify=False у вашем notebook-у (само за GitHub Models notebook-е)

У notebook-у из Лекције 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

Затим додајте следеће на врх вашег notebook-а или скрипте пре него што направите било какве мрежне позиве:

import truststore
truststore.inject_into_ssl()

Запели сте негде?

Ако имате било каквих проблема са покретањем овог подешавања, придружите се нашем Azure AI Community Discord-у или направите issue.

Следећа лекција

Сада сте спремни да покренете код за овај курс. Срећно у даљем учењу о свету AI агената!

Увод у AI агенте и њихове примене

Изјава о одрицању одговорности: Овај документ је преведен коришћењем услуге за аутоматски превод Co-op Translator. Иако тежимо тачности, имајте у виду да аутоматски преводи могу садржати грешке или нетачности. Оригинални документ на његовом изворном језику треба сматрати ауторитативним извором. За критичне информације препоручује се професионални људски превод. Нисмо одговорни за било каква неспоразума или погрешна тумачења која произилазе из коришћења овог превода.

This site is open source. Improve this page.