See õppetund käsitleb, kuidas käivitada selle kursuse koodi näited.
Enne oma repo kloonimist liitu AI Agents For Beginners Discord kanaliga, et saada abi seadistamisel, esitada kursuse kohta küsimusi või suhelda teiste õppijatega.
Alustamiseks palun klooni või loo fork GitHubi repositooriumist. See loob sulle kursusmaterjalist omaenda versiooni, mida saad käivitada, testida ja kohandada!
Seda saab teha, klõpsates lingil forki repo
Nüüd peaks sul olema oma forkitud versioon sellest kursusest järgmisel lingil:

Täielik repositoorium võib olla suur (~3 GB), kui laadid alla kogu ajaloo ja kõik failid. Kui osaled ainult töökojas või vajad ainult mõnda õppetunni kausta, laadib madala sügavusega kloon (või hõre kloon) palju vähem alla.
Asenda allpool käskudes <your-username> oma fork’i URL-iga (või upstream URL-iga, kui eelistad).
Klooni ainult uusim commit’i ajalugu (väike allalaadimine):
git clone --depth 1 https://github.com/<your-username>/ai-agents-for-beginners.git
Klooni konkreetne haru:
git clone --depth 1 --branch <branch-name> https://github.com/<your-username>/ai-agents-for-beginners.git
Kasutab osalist kloonimist ja sparse-checkout’i (nõuab Git 2.25+ ning soovitatav on kaasaegne Git osalise kloonimise toetusega):
git clone --depth 1 --filter=blob:none --sparse https://github.com/<your-username>/ai-agents-for-beginners.git
Liigu repositooriumi kausta:
cd ai-agents-for-beginners
Seejärel määra, milliseid kaustu soovid (näites kaks kausta):
git sparse-checkout set 00-course-setup 01-intro-to-ai-agents
Pärast kloonimist ja failide kontrollimist, kui vajad ainult faile ja soovid ruumi vabastada (ilma git-ajaloota), palun kustuta repositooriumi metadata (💀tagasipöördumatu — kaotad kogu Git funktsionaalsuse):
# zsh/bash
rm -rf .git
# PowerShell
Remove-Item -Recurse -Force .git
Loo see repo jaoks uus Codespace GitHub kasutajaliidese kaudu.
See kursus pakub mitut Jupyter Notebooki, mida saad kasutada AI agentide praktiliseks õppimiseks.
Koodi näited kasutavad Microsoft Agent Frameworki (MAF) koos FoundryChatClient, mis ühendub Microsoft Foundry Agent Service V2 (Response API) kaudu Microsoft Foundry’st.
Kõik Python notebookid on märgistatud *-python-agent-framework.ipynb.
MÄRKUS: Kui sul ei ole Python3.12 installitud, palun paigalda see. Seejärel loo oma virtuaalõhkkond python3.12-ga, et tagada nõutud versioonide paigaldamine requirements.txt failist.
Näide
Loo Python virtuaalõhkkonna kataloog:
python -m venv venv
Seejärel aktiveeri virtuaalõhkkond järgnevate jaoks:
# zsh/bash
source venv/bin/activate
# Command Prompt for Windows
venv\Scripts\activate
.NET 10+: Näidiskoodide jaoks, mis kasutavad .NET, veendu, et oled installinud .NET 10 SDK või uuema. Kontrolli installitud .NET SDK versiooni:
dotnet --list-sdks
gpt-5-mini). Vaata allpool olevaid sammu 1.Oleme lisanud selle repositooriumi juurkausta requirements.txt faili, mis sisaldab kõiki vajalikke Python pakette koodi näidete käivitamiseks.
Saad need paigaldada, käivitades oma terminalis repositooriumi juurkaustas järgmise käsu:
pip install -r requirements.txt
Soovitame luua Python virtuaalõhkkonna, et vältida konflikte ja probleeme.
Veendu, et VSCode kasutab õiget Python versiooni.
Selleks, et neid notebooke käivitada, vajad Microsoft Foundry projekti koos juurutatud mudeliga. Loo projekt otse Microsoft Foundry keskkonnas; hubi ei ole vaja.
gpt-5-mini) menüüs Models + Endpoints → Deploy model.Oma projektist Microsoft Foundry portaali kaudu:

gpt-5-mini).az loginEnamik notebooke autentib läbi sinu Azure CLI sisselogimise — kasutades AzureCliCredential või DefaultAzureCredential (mõlemad kasutavad sinu az login sessiooni) paketist azure-identity — seega ei ole vaja API võtmeid. Mõned õppetunnid ja valikulised integratsioonid kasutavad API võtmeid; kontrolli iga õppetunni eeltingimusi võimalike täiendavate keskkonnamuutujate osas. Selleks on vaja olla Azure CLI kaudu sisse loginud.
Paigalda Azure CLI, kui sa pole seda veel teinud: aka.ms/installazurecli
Logi sisse käsuga:
az login
Või kui oled kaug- või Codespace keskkonnas ilma brauserita:
az login --use-device-code
Vali tellimus, kui küsitakse — vali see, kus paikneb sinu Foundry projekt.
Kontrolli, et oled sisse logitud:
az account show
Miks
az login? Notebookid autentivad kasutadesAzureCliCredential(võiDefaultAzureCredential, mis samuti kasutab sinu Azure CLI sisselogimist) paketistazure-identity. See tähendab, et sinu Azure CLI sessioon annab mandaadid — sinu.envfaili ei pea panema API võtmeid ega salasõnu. See on turvalisuse parim tava.
.env failKopeeri näidisfail:
# zsh/bash
cp .env.example .env
# PowerShell
Copy-Item .env.example .env
Ava .env ja täida need kaks väärtust:
AZURE_AI_PROJECT_ENDPOINT=https://<your-project>.services.ai.azure.com/api/projects/<your-project-id>
AZURE_AI_MODEL_DEPLOYMENT_NAME=gpt-5-mini
| Muutuja | Kus leida |
|---|---|
AZURE_AI_PROJECT_ENDPOINT |
Foundry portaali → sinu projekt → Overview leht |
AZURE_AI_MODEL_DEPLOYMENT_NAME |
Foundry portaali → Models + Endpoints → sinu juurutatud mudeli nimi |
Enamiku õppetundide jaoks ongi kõik! Notebookid autentivad automaatselt läbi sinu az login sessiooni.
pip install -r requirements.txt
Soovitame käivitada selle virtuaalõhkkonnas, mille varem lõid.
Õppetunnid 5 (Agentic RAG) ja 16 töötavad kohe välja karbist koos mälu-põhise teadmistebaasiga — lisaks Azure ressursse pole vaja. Kui soovite neid varustada päris Azure AI Search indeksiga, pange tähele, et Õppetunni 16 märkmik kasutab praegu võtmel põhinevat autentimist: see lülitub mälus otsingult Azure AI Searchile ainult siis, kui on määratud nii AZURE_SEARCH_SERVICE_ENDPOINT kui AZURE_SEARCH_API_KEY, muidu jääb mälus otsingule — seega päris indeksi vastu töötamiseks tuleb määrata ka administraatori võti. Võtmeta autentimine Microsoft Entra ID-ga (RBAC) on soovitatav lähenemine teie enda tootmiskoodi jaoks, mis on kooskõlas kogu kursuses mujal kasutatava az login protsessiga.
Alljärgnevad RBAC sammud kehtivad seadistamisjuhendi näidistele ja teie enda koodile. Need ei võimalda võtmeta autentimist Õppetunni 16 märkmikus; Õppetunni 16 jaoks on Azure AI Search kasutamiseks endiselt vajalikud nii lõpp-punkt kui administraatori võti.
Lülitage sisse rollipõhine juurdepääs oma otsinguteenusel:
az search service update --name <service-name> --resource-group <resource-group> --auth-options aadOrApiKey
Määrake endale vajalikud rollid (indekseid loomine/laadimine ja päringute tegemine):
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)
Lisage lõpp-punkt oma .env faili:
| Muutuja | Kus leida |
|---|---|
AZURE_SEARCH_SERVICE_ENDPOINT |
Azure portaal → teie Azure AI Search ressurss → Ülevaade → URL |
AZURE_SEARCH_API_KEY |
Nõutud (lõpp-punktiga koos), et lubada Azure AI Search Õppetunni 16 märkmikus, mis kasutab võtmel põhinevat autentimist. Azure portaal → Seaded → Võtmed → peamine administraatori võti |
Miks võtmeta? Administraatori võtmed annavad täieliku kirjutamisõiguse teie otsinguteenusele ja võivad lekkida kaudu
.envfailid. RBAC kasutamisel kasutatakse teieaz loginidentiteeti — sama võtmeta Entra ID mustrit, mida kursuse märkmikud kasutavad (kõrgemal tasemel kauduAzureCliCredential/DefaultAzureCredential). Vaadake Ühendamine Azure AI Searchiga rollide abil.
Täielike indeksi loomise näidete jaoks Pythonis ja .NETis vt Azure AI Search seadistamisjuhendit.
Mõned õppetunni 6 ja 8 märkmikud kutsuvad Azure OpenAI otse (kasutades Responses API-d) ilma Microsoft Foundry projekti vahenduseta. Need näited kasutasid varem GitHubi mudeleid, mis on aegunud ja ei toeta Responses API-d. Lisage need muutujad oma .env faili:
| Muutuja | Kus leida |
|---|---|
AZURE_OPENAI_ENDPOINT |
Azure portaal → teie Azure OpenAI ressurss → Võtmed ja lõpp-punkt → Lõpp-punkt (nt https://<your-resource>.openai.azure.com) |
AZURE_OPENAI_DEPLOYMENT |
Teie juurutatud mudeli nimi (nt gpt-5-mini), mis toetab Responses API-d |
AZURE_OPENAI_API_KEY |
Valikuline — ainult juhul, kui kasutate võtme-põhist autentimist asemel az login / Entra ID-d |
Responses API kasutab stabiilset
/openai/v1/lõpp-punkti, seega poleapi-versionvajalik. Logige sisseaz loginabil, et kasutada võtmeta Entra ID autentimist.
MiniMax pakub suure kontekstiga mudeleid (kuni 204K tokenit) OpenAI-ga ühilduva API kaudu. Kuna Microsoft Agent Framework’i OpenAIChatClient töötab mis tahes OpenAI-ga ühilduva lõpp-punktiga, saab MiniMaxi kasutada õppetundides, mis kasutavad OpenAIChatClient, kui sisuliseks alternatiiviks.
Lisage need muutujad oma .env faili:
| Muutuja | Kus leida |
|---|---|
MINIMAX_API_KEY |
MiniMax Platform → API võtmed |
MINIMAX_BASE_URL |
Kasutage https://api.minimax.io/v1 (vaikimisi väärtus) |
MINIMAX_MODEL_ID |
Mudeli nimi, mida kasutada (nt MiniMax-M3) |
Näidismudelid: MiniMax-M3 (soovitatav), MiniMax-M2.7, MiniMax-M2.7-highspeed (kiiremad vastused). Mudelitenimed ja kättesaadavus võivad ajas muutuda ning konkreetse mudeli kasutamine võib sõltuda teie kontost.
Koodinäited, mis kasutavad OpenAIChatClient (nt Õppetund 14 hotelli broneerimise töövoog), tuvastavad ja kasutavad automaatselt teie MiniMaxi konfiguratsiooni, kui on määratud MINIMAX_API_KEY.
Novita AI pakub OpenAI-ga ühilduvat API-d avatud lähtekoodiga ja pioneerilikeks LLM-ideks (DeepSeek, Llama, Qwen ja teised). Kuna Microsoft Agent Framework’i OpenAIChatClient töötab mis tahes OpenAI-ga ühilduva otsapunktiga, saate Novita AI-d kasutada Azure OpenAI või OpenAI asemel.
Lisage need muutujad oma .env faili:
| Muutuja | Kus seda leida |
|---|---|
NOVITA_API_KEY |
Novita AI juhtpaneel → API võtmed |
NOVITA_BASE_URL |
Kasutage https://api.novita.ai/openai/v1 (vaikimisi väärtus) |
NOVITA_MODEL_ID |
Kasutatava mudeli nimi (nt moonshotai/kimi-k3) |
Näidismudelid: moonshotai/kimi-k3, zai-org/glm-5.2, deepseek/deepseek-v4-flash-0731. Novita AI majutab ka palju teisi avatud lähtekoodiga mudeliperekondi (Llama, Qwen, GLM ja teised) — vaadake Novita AI mudelite raamatukogu, et näha praegust saadaval olevate mudelite ja nende mudeli-ID-de nimekirja.
Praegused näited ei kasuta automaatselt NOVITA_* muutujaid. Novita AI kasutamiseks edastage need väärtused otseselt sobitamisel OpenAIChatClient näites, mida käitate.
Foundry Local on kergekaaluline käitusaeg, mis laadib alla, haldab ja pakub keelemudeleid täielikult teie enda masinas OpenAI-ga ühilduva API kaudu — pilve pole vaja.
Kuna Microsoft Agent Framework’i OpenAIChatClient töötab mis tahes OpenAI-ga ühilduva otsapunktiga, on Foundry Local mugav lokaalne alternatiiv Azure OpenAI-ile.
1. Installige Foundry Local
# Windows
winget install Microsoft.FoundryLocal
# macOS
brew install foundrylocal
2. Laadige alla ja käivitage mudel (see alustab ka kohaliku teenuse):
foundry model list # see available models
foundry model run phi-4-mini
3. Installige Python SDK, mida kasutatakse kohaliku otsapunkti avastamiseks:
pip install foundry-local-sdk
4. Suunake Microsoft Agent Framework oma kohaliku mudeli poole:
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.",
)
Märkus: Foundry Local pakub OpenAI-ga ühilduvat Chat Completions otsapunkti. Kasutage seda kohaliku arenduse ja võrguühenduseta olukordade jaoks. Täieliku Vastuste API funktsionaalsuse (nt staatuslikud vestlused) jaoks kasutage Azure OpenAI või Microsoft Foundry projekti.
Tingimuslik töövoogude märkmik õppetükis 8 kasutab Bing’i maandamist Microsoft Foundry kaudu. Kui plaanite seda näidet käivitada, lisage see muutuja oma .env faili:
| Muutuja | Kus seda leida |
|---|---|
BING_CONNECTION_ID |
Microsoft Foundry portaali → teie projekt → Halduse → Ühendatud ressursid → teie Bing’i ühendus → kopeerige ühenduse ID |
Kui olete macOS-il ja kohtate sellist viga nagu:
ssl.SSLCertVerificationError: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: self-signed certificate in certificate chain
See on teadaolev probleem Pythoniga macOS-il, kus süsteemi SSL-sertifikaate ei usaldata automaatselt. Proovige järgmisi lahendusi järjest:
Variant 1: Käivitage Pythoni Install Certificates skript (soovitatav)
# Replace 3.XX with your installed Python version (e.g., 3.12 or 3.13):
/Applications/Python\ 3.XX/Install\ Certificates.command
Variant 2: Kasutage connection_verify=False oma märkmikus (ainult GitHub Models märkmikud)
Õppetüki 6 märkmikus (06-building-trustworthy-agents/code_samples/06-system-message-framework.ipynb) on kommenteeritud lahendus juba olemas. Eemaldage kommentaar connection_verify=False, kui ilmnevad sertifikaadivead:
client = ChatCompletionsClient(
endpoint=endpoint,
credential=AzureKeyCredential(token),
connection_verify=False, # Disable SSL verification if you encounter certificate errors
)
⚠️ Hoiduge: SSL kontrolli keelamine (
connection_verify=False) vähendab turvalisust, jättes vahele sertifikaadi valideerimise. Kasutage seda ainult ajutise lahendusena arenduskeskkondades. Ärge kasutage seda tootmises.
Variant 3: Installige ja kasutage truststore
pip install truststore
Seejärel lisage oma märkmiku või skripti algusesse enne mingeid võrgukõnesid järgnev:
import truststore
truststore.inject_into_ssl()
Kui teil on selle seadistusega probleeme, liituge meie Azure AI kogukonna Discordi või loodage probleem.
Olete nüüd valmis jooksutama selle kursuse koodi. Head AI-agendite maailma uurimist!
Sissejuhatus AI agentidesse ja agentide kasutusjuhtumitesse
Lahtiütlus: See dokument on tõlgitud kasutades AI tõlketeenust Co-op Translator. Kuigi me püüdleme täpsuse poole, palun pange tähele, et automatiseeritud tõlgetes võib esineda vigu või ebatäpsusi. Originaaldokument selle emakeeles tuleks pidada autoriteetseks allikaks. Olulise teabe puhul soovitatakse kasutada professionaalset inimtõlget. Me ei vastuta selle tõlkega seotud eksimustest või valesti mõistmistest.