Tässä oppitunnissa käydään läpi, miten suoritat tämän kurssin koodiesimerkit.
Ennen kuin alat kloonata repositoriotasi, liity AI Agents For Beginners Discord -kanavalle saadaksesi apua asennuksessa, vastauksia kurssin kysymyksiin tai yhteyden muihin oppijoihin.
Aloita kloonaamalla tai haarauttamalla GitHub-repositorio. Tämä luo oman version kurssimateriaalista, jotta voit suorittaa, testata ja muokata koodia!
Tämä onnistuu klikkaamalla linkkiä haaraaksesi repoon
Sinulla tulisi nyt olla oma haarautettu versio tästä kurssista seuraavassa linkissä:

Koko repositorio voi olla suuri (~3 GB), jos lataat koko historian ja kaikki tiedostot. Jos osallistut vain työpajaan tai tarvitset vain muutaman oppituntikansion, shallow-kloonaus (tai sparse-kloonaus) lataa paljon vähemmän.
Korvaa alla komentojen <your-username> omalla haarautus-URL-osoitteellasi (tai upstream URL-osoitteella, jos haluat).
Kloonaa vain uusin commit-historia (pieni lataus):
git clone --depth 1 https://github.com/<your-username>/ai-agents-for-beginners.git
Kloonaa tietty haara:
git clone --depth 1 --branch <branch-name> https://github.com/<your-username>/ai-agents-for-beginners.git
Tämä käyttää osittaista kloonausta ja sparse-checkoutia (vaatii Git 2.25+ ja suositellaan modernia Gitiä osittaisella kloonaustuesta):
git clone --depth 1 --filter=blob:none --sparse https://github.com/<your-username>/ai-agents-for-beginners.git
Siirry repositorion kansioon:
cd ai-agents-for-beginners
Sitten määrittele, mitkä kansiot haluat (alla esimerkissä kaksi kansiota):
git sparse-checkout set 00-course-setup 01-intro-to-ai-agents
Kun kloonaus ja tiedostojen varmistus on valmis, jos tarvitset vain tiedostot ja haluat vapauttaa tilaa (ilman git-historiaa), poista repositorion metatiedot (💀peruuttamaton — menetät kaiken Git-toiminnallisuuden):
# zsh/bash
rm -rf .git
# PowerShell
Remove-Item -Recurse -Force .git
Luo uusi Codespace tälle repolle GitHubin käyttöliittymän kautta.
Tämä kurssi tarjoaa sarjan Jupyter Notebookeja, joita voit suorittaa saadaksesi käytännön kokemusta tekoälyagenttien rakentamisesta.
Esimerkkikoodit käyttävät Microsoft Agent Framework (MAF) -kehyksiä FoundryChatClient kanssa, jotka yhdistävät Microsoft Foundry Agent Service V2 (Responses API) -palveluun Microsoft Foundryn kautta.
Kaikki Python-muistikirjat on merkitty *-python-agent-framework.ipynb.
HUOM: Jos Python 3.12 ei ole asennettuna, varmista sen asentaminen. Luo sitten virtuaaliympäristösi python3.12:lla varmistaaksesi, että vaatimustiedostosta asennetaan oikeat versiot.
Esimerkki
Luo Python virtuaaliympäristön kansio:
python -m venv venv
Aktivoi sitten virtuaaliympäristö seuraavasti:
# zsh/bash
source venv/bin/activate
# Command Prompt for Windows
venv\Scripts\activate
.NET 10+: .NET:ää käyttävissä esimerkkikoodeissa varmista, että sinulla on asennettuna .NET 10 SDK tai uudempi. Tarkista asennettu .NET SDK -versiosi:
dotnet --list-sdks
gpt-5-mini). Katso Vaihe 1 alla.Projektin juuressa on mukana requirements.txt -tiedosto, joka sisältää kaikki tarvittavat Python-paketit koodiesimerkkien suorittamiseen.
Voit asentaa ne suorittamalla seuraavan komennon terminaalissasi projektin juuressa:
pip install -r requirements.txt
Suosittelemme luomaan Python-virtuaaliympäristön ristiriitojen ja ongelmien välttämiseksi.
Varmista, että käytät oikeaa Python-versiota VSCodessa.
Sinun on oltava Microsoft Foundry -projekti, jossa on käyttöön otettu malli, jotta voit suorittaa muistikirjat. Luo projekti suoraan nykyisessä Microsoft Foundry -ympäristössä; hubia ei tarvita.
gpt-5-mini) valitsemalla Mallit + Päätepisteet → Ota malli käyttöön.Microsoft Foundry -portaalissa projektissasi:

gpt-5-mini).az login avullaUseimmat muistikirjat todennetaan sinun Azure CLI -kirjautumisesi kautta — käyttämällä AzureCliCredential tai DefaultAzureCredential (molemmat käyttävät sinun az login istuntoasi) paketista azure-identity — joten ne eivät vaadi API-avaimia. Muutama opetus ja valinnaiset integraatiot käyttävät API-avaimia; tarkista kunkin oppitunnin edellytykset mahdollisten lisäympäristömuuttujien varalta. Tämä vaatii, että olet kirjautuneena Azure CLI:llä.
Asenna Azure CLI, jos et ole vielä tehnyt sitä: aka.ms/installazurecli
Kirjaudu sisään suorittamalla:
az login
Tai jos olet etä- tai Codespace-ympäristössä ilman selainta:
az login --use-device-code
Valitse tilauksesi, jos saat kehotteen — valitse se, joka sisältää Foundry-projektisi.
Varmista että olet kirjautuneena sisään:
az account show
Miksi
az login? Muistikirjat todennetaan käyttämälläAzureCliCredential(taiDefaultAzureCredential, joka myös noutaa Azure CLI -kirjautumisesi) paketistaazure-identity. Tämä tarkoittaa, että Azure CLI -istuntosi tarjoaa tunnistetiedot — ei API-avaimia tai salaisuuksia.envtiedostossasi. Tämä on turvallisuuden paras käytäntö.
.env tiedostosiKopioi esimerkkitiedosto:
# zsh/bash
cp .env.example .env
# PowerShell
Copy-Item .env.example .env
Avaa .env ja täytä nämä kaksi arvoa:
AZURE_AI_PROJECT_ENDPOINT=https://<your-project>.services.ai.azure.com/api/projects/<your-project-id>
AZURE_AI_MODEL_DEPLOYMENT_NAME=gpt-5-mini
| Muuttuja | Missä löytää |
|---|---|
AZURE_AI_PROJECT_ENDPOINT |
Foundry-portaali → projektisi → Yhteenveto-sivu |
AZURE_AI_MODEL_DEPLOYMENT_NAME |
Foundry-portaali → Mallit + Päätepisteet → käyttöönotetun mallisi nimi |
Siinä se suurimmaksi osaksi! Muistikirjat todennetaan automaattisesti az login-istuntosi kautta.
pip install -r requirements.txt
Suosittelemme suorittamaan tämän aiemmin luomassasi virtuaaliympäristössä.
Oppitunnin 5 (Agentic RAG) ja Oppitunnin 16 muistikirjat toimivat suoraan muistissa olevan tietopohjan kanssa — eivät vaadi ylimääräisiä Azure-resursseja. Jos haluat käyttää todellista Azure AI Search -hakemistoa, huomaa että Oppitunnin 16 muistikirja käyttää tällä hetkellä avainpohjaista todennusta: se vaihtaa muistissa olevan haun ja Azure AI Searchin välillä vain, kun molemmat AZURE_SEARCH_SERVICE_ENDPOINT ja AZURE_SEARCH_API_KEY on asetettu, ja muuten pysyy muistihauissa — joten todellista hakemistoa vasten ajaaksesi sinun täytyy asettaa myös hallinta-avain. Avaimeton todennus Microsoft Entra ID:llä (RBAC) on suositeltu lähestymistapa omaan tuotantokoodiin, vastaavasti kuin az login -virtausta käytetään muualla kurssilla.
Alla olevat RBAC-vaiheet koskevat asennusoppaan esimerkkejä ja omaa koodiasi. Ne eivät ota käyttöön avaimetonta todennusta Oppitunnin 16 muistikirjassa; Oppitunti 16 vaatii yhä sekä päätepiste- että hallinta-avaimen Azure AI Searchin käyttöön.
Ota roolipohjainen käyttöoikeus käyttöön hakupalvelussasi:
az search service update --name <service-name> --resource-group <resource-group> --auth-options aadOrApiKey
Määritä itsellesi vaaditut roolit (luo/lataa indeksit ja tee kyselyjä):
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)
Lisää päätepiste tiedostoosi .env:
| Muuttuja | Missä se löytyy |
|---|---|
AZURE_SEARCH_SERVICE_ENDPOINT |
Azure-portaali → oma Azure AI Search -resurssisi → Yleiskatsaus → URL |
AZURE_SEARCH_API_KEY |
Tarvitaan (päätepisteen kanssa) Azure AI Searchin käyttämiseen Oppitunti 16:n muistikirjassa, joka käyttää avainpohjaista todennusta. Azure-portaali → Asetukset → Avaimet → ensisijainen ylläpitäjän avain |
Miksi avaimettomuus? Hallintavaimet antavat täydet kirjoitusoikeudet hakupalveluusi ja voivat vuotaa
.env-tiedostojen kautta. RBAC:in avulla sen sijaan käytetäänaz login-tunnustettasi — samaa avaimetonta Entra ID -kuviota, jota kurssimuistikirjat käyttävät (kauttaAzureCliCredential/DefaultAzureCredential). Katso Yhdistä Azure AI Search -hakupalveluun roolien avulla.
Katso Azure AI Search -asennusopas saadaksesi täydelliset esimerkit indeksin luomisesta Pythonilla ja .NETillä.
Joissakin oppituntien 6 ja 8 muistikirjoissa kutsutaan Azure OpenAI:ta suoraan (käyttäen Responses API:a) sen sijaan, että mentäisiin Microsoft Foundryn projektin kautta. Nämä esimerkit käyttivät aiemmin GitHub-malleja, jotka ovat vanhentuneita eivätkä tue Responses API:a. Lisää nämä muuttujat .env tiedostoosi:
| Muuttuja | Mistä se löytyy |
|---|---|
AZURE_OPENAI_ENDPOINT |
Azure-portaali → oma Azure OpenAI -resurssisi → Avain ja päätepiste → Päätepiste (esim. https://<your-resource>.openai.azure.com) |
AZURE_OPENAI_DEPLOYMENT |
Käyttöönotetun mallisi nimi (esim. gpt-5-mini), joka tukee Responses-rajapintaa |
AZURE_OPENAI_API_KEY |
Valinnainen — vain jos käytät avainpohjaista todennusta az login / Entra ID sijaan |
Responses-rajapinta käyttää vakaata
/openai/v1/-päätepistettä, jotenapi-versionei ole tarpeen. Kirjaudu sisäänaz loginkäyttämällä avaintonta Entra ID -todennusta.
MiniMax tarjoaa laajakonemallin (jopa 204K tokenia) OpenAI-yhteensopivan rajapinnan kautta. Koska Microsoft Agent Frameworkin OpenAIChatClient toimii minkä tahansa OpenAI-yhteensopivan päätepisteen kanssa, voit käyttää MiniMaxia suoraan OpenAIChatClient-oppitunneissa vaihtoehtona.
Lisää nämä muuttujat .env-tiedostoosi:
| Muuttuja | Mistä se löytyy |
|---|---|
MINIMAX_API_KEY |
MiniMax-alusta → API-avaimet |
MINIMAX_BASE_URL |
Käytä https://api.minimax.io/v1 (oletusarvo) |
MINIMAX_MODEL_ID |
Käytettävän mallin nimi (esim. MiniMax-M3) |
Esimerkkimallit: MiniMax-M3 (suositeltu), MiniMax-M2.7, MiniMax-M2.7-highspeed (nopeammat vastaukset). Mallien nimet ja saatavuus voivat muuttua ajan myötä, ja pääsy tiettyyn malliin voi riippua tilistäsi.
Koodiesimerkit, jotka käyttävät OpenAIChatClient (esim. Oppitunti 14 hotellivarauksen työnkulku), tunnistavat ja käyttävät automaattisesti MiniMax-konfiguraatiotasi, kun MINIMAX_API_KEY on asetettu.
Novita AI tarjoaa OpenAI-yhteensopivan API:n avoimen lähdekoodin ja uusimpien LLM-mallien (DeepSeek, Llama, Qwen ja muut) käyttöön. Koska Microsoft Agent Frameworkin OpenAIChatClient toimii minkä tahansa OpenAI-yhteensopivan rajapinnan kanssa, voit käyttää Novita AI:ta suoraan Azure OpenAI:n tai OpenAI:n sijaan.
Lisää nämä muuttujat .env tiedostoosi:
| Muuttuja | Missä löytää |
|---|---|
NOVITA_API_KEY |
Novita AI Dashboard → API-avain |
NOVITA_BASE_URL |
Käytä https://api.novita.ai/openai/v1 (oletusarvo) |
NOVITA_MODEL_ID |
Käytettävän mallin nimi (esim. moonshotai/kimi-k3) |
Esimerkkimalleja: moonshotai/kimi-k3, zai-org/glm-5.2, deepseek/deepseek-v4-flash-0731. Novita AI isännöi myös monia muita avoimen lähdekoodin malliperheitä (Llama, Qwen, GLM ja lisää) — katso Novita AI mallikirjasto saadaksesi ajantasaisen listan saatavilla olevista malleista ja niiden mallitunnuksista.
Nykyiset esimerkit eivät automaattisesti käytä NOVITA_* -muuttujia. Jos haluat käyttää Novita AI:ta, anna nämä arvot eksplisiittisesti rakentaessasi OpenAIChatClient ajamassasi esimerkissä.
Foundry Local on kevyt ajonaikainen ympäristö, joka lataa, hallinnoi ja tarjoaa kielimalleja kokonaan omalla koneellasi OpenAI-yhteensopivan API:n kautta — pilveä ei tarvita.
Koska Microsoft Agent Frameworkin OpenAIChatClient toimii minkä tahansa OpenAI-yhteensopivan päätepisteen kanssa, Foundry Local on paikallinen suora vaihtoehto Azure OpenAI:lle.
1. Asenna Foundry Local
# Windows
winget install Microsoft.FoundryLocal
# macOS
brew install foundrylocal
2. Lataa ja suorita malli (tämä myös käynnistää paikallisen palvelun):
foundry model list # see available models
foundry model run phi-4-mini
3. Asenna Python SDK paikallisen päätepisteen löytämiseen:
pip install foundry-local-sdk
4. Ohjaa Microsoft Agent Framework paikalliseen malliisi:
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.",
)
Huom: Foundry Local tarjoaa OpenAI-yhteensopivan Chat Completions -rajapinnan. Käytä sitä paikalliseen kehitykseen ja offline-tilanteisiin. Täydellistä Responses API -ominaisuusarvostelua (tilalliset keskustelut jne.) varten käytä Azure OpenAI:ta tai Microsoft Foundry -projektia.
Oppitunnin 8 ehdollinen työnkulkumuistio käyttää Bing grounding -ominaisuutta Microsoft Foundryn kautta. Jos aiot ajaa tämän esimerkin, lisää tämä muuttuja .env -tiedostoosi:
| Muuttuja | Missä löytää |
|---|---|
BING_CONNECTION_ID |
Microsoft Foundry portaali → projektisi → Management → Connected resources → Bing-yhteytesi → kopioi yhteystunnus |
Jos käytössäsi on macOS ja kohtaat virheilmoituksen kuten:
ssl.SSLCertVerificationError: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: self-signed certificate in certificate chain
Tämä on tunnettu ongelma Pythonissa macOS:llä, jossa järjestelmän SSL-varmenteita ei automaattisesti luoteta. Kokeile seuraavia ratkaisuja tässä järjestyksessä:
Vaihtoehto 1: Suorita Pythonin Install Certificates -skripti (suositeltu)
# Replace 3.XX with your installed Python version (e.g., 3.12 or 3.13):
/Applications/Python\ 3.XX/Install\ Certificates.command
Vaihtoehto 2: Käytä connection_verify=False muistiossasi (vain GitHub-mallien muistioille)
Oppitunnin 6 muistiossa (06-building-trustworthy-agents/code_samples/06-system-message-framework.ipynb) on jo kommentoitu ohitusratkaisu valmiina. Poista kommenttimerkintä connection_verify=False, jos kohtaat varmennevirheitä:
client = ChatCompletionsClient(
endpoint=endpoint,
credential=AzureKeyCredential(token),
connection_verify=False, # Disable SSL verification if you encounter certificate errors
)
⚠️ Varoitus: SSL-varmennuksen pois käytöstä ottaminen (
connection_verify=False) heikentää tietoturvaa ohittamalla varmenteiden tarkistuksen. Käytä tätä vain tilapäisenä ratkaisuna kehitysympäristöissä. Älä koskaan käytä sitä tuotannossa.
Vaihtoehto 3: Asenna ja käytä truststore
pip install truststore
Lisää sitten seuraava rivi muistiosi tai skriptisi alkuun ennen kuin teet verkko- tai API-kutsuja:
import truststore
truststore.inject_into_ssl()
Jos sinulla on ongelmia tämän asennuksen kanssa, liity Azure AI Community Discordiin tai luo issue.
Olet nyt valmis ajamaan tämän kurssin koodin. Iloisia opiskeluhetkiä tekoälyagenttien maailmassa!
Introduction to AI Agents and Agent Use Cases
Vastuuvapauslauseke: Tämä asiakirja on käännetty käyttämällä tekoälypohjaista käännöspalvelua Co-op Translator. Vaikka pyrimme tarkkuuteen, otathan huomioon, että automaattiset käännökset saattavat sisältää virheitä tai epätarkkuuksia. Alkuperäinen asiakirja sen alkuperäiskielellä on virallinen lähde. Tärkeissä asioissa suositellaan ammattimaista ihmiskäännöstä. Emme ole vastuussa tämän käännöksen käytöstä aiheutuvista väärinymmärryksistä tai tulkinnoista.