Ši pamoka apims, kaip paleisti šio kurso kodo pavyzdžius.

Prieš pradėdami klonuoti savo saugyklą, prisijunkite prie AI Agents For Beginners Discord channel, kad gautumėte pagalbą dėl sąrankos, turėtumėte klausimų apie kursą arba susisiektumėte su kitais besimokančiaisiais.

Pradėdami, klonuokite arba sukurkite fork GitHub saugyklos. Tai sukurs jūsų pačių versiją kurso medžiagos, kad galėtumėte paleisti, testuoti ir koreguoti kodą!

Tai galite padaryti spustelėdami nuorodą į sukurti forką

Dabar turėtumėte turėti savo forkinę šio kurso versiją šioje nuorodoje:

Pilna saugykla gali būti didelė (~3 GB), kai atsisiunčiate visą istoriją ir visus failus. Jei dalyvaujate tik dirbtuvėse arba jums reikia tik kelių pamokų katalogų, paviršinis klonas (arba sparse klonas) išvengs didesnės dalies atsisiuntimo sumažindamas istoriją ir/ar praleisdamas blob'us.

Pakeiskite <your-username> žemiau esančiuose komandose savo forko URL (arba upstream URL, jei pageidaujate).

Norint klonuoti tik naujausią commit istoriją (mažas atsisiuntimas):

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

Norint klonuoti konkretų šaką:

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

Tai naudoja partial clone ir sparse-checkout (reikalauja Git 2.25+ ir rekomenduojama moderni Git versija su partial clone palaikymu):

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

Pereikite į saugyklos aplanką:

cd ai-agents-for-beginners

Tada nurodykite, kuriuos aplankus norite (žemiau esantis pavyzdys rodo du aplankus):

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

Po klonavimo ir failų patikrinimo, jei jums reikalingi tik failai ir norite atlaisvinti vietos (be git istorijos), ištrinkite saugyklos metaduomenis (💀negrįžtama — prarasite visą Git funkcionalumą: jokių commit'ų, pull'ų, push'ų ar prieigos prie istorijos).

# zsh/bash
rm -rf .git

# PowerShell
Remove-Item -Recurse -Force .git

• Sukurkite naują Codespace šiai saugyklai per GitHub UI.

• Naujo Codespace terminale vykdykite vieną iš aukščiau pateiktų shallow/sparse klonavimo komandų, kad į Codespace darbinę aplinką atkeltumėte tik reikiamus pamokų katalogus.

• Pasirinktinai: po klonavimo Codespaces viduje pašalinkite .git, kad atgautumėte papildomos vietos (žr. ištrynimo komandas aukščiau).

• Pastaba: jei norite atidaryti saugyklą tiesiogiai Codespaces (be papildomo klonavimo), atkreipkite dėmesį, kad Codespaces sukurs devcontainer aplinką ir gali vis tiek paruošti daugiau nei jums reikia. Klonavimas paviršiniu kopijuotu viduje naujo Codespace suteikia daugiau kontrolės dėl disko naudojimo.

• Visada pakeiskite klono URL į savo forką, jei norite redaguoti/commit'inti.
• Jei vėliau jums reikės daugiau istorijos ar failų, galite juos parsisiųsti arba pakoreguoti sparse-checkout, kad įtrauktumėte papildomus aplankus.

Šis kursas siūlo keletą Jupyter Notebook failų, kuriuos galite paleisti, kad įgytumėte praktinės patirties kuriant AI agentus.

Kodo pavyzdžiai naudoja Microsoft Agent Framework (MAF) su AzureAIProjectAgentProvider, kuris jungiasi prie Azure AI Agent Service V2 (Responses API) per Microsoft Foundry.

Visi Python notebook'ai yra pažymėti *-python-agent-framework.ipynb.

• Python 3.12+

  • PASTABA: Jei neturite įdiegto Python 3.12, įsitikinkite, kad jį įdiegėte. Tada sukurkite savo venv naudodami python3.12, kad būtų įdiegtos teisingos versijos iš requirements.txt failo.

    Pavyzdys

    Sukurkite Python venv katalogą:

    python -m venv venv
    

    Tada suaktyvinkite venv aplinką:

    # zsh/bash
    source venv/bin/activate
    

    # Command Prompt for Windows
    venv\Scripts\activate
    

• .NET 10+: Jei pavyzdžių kodai naudoja .NET, įdiekite .NET 10 SDK arba naujesnę versiją. Tada patikrinkite įdiegtą .NET SDK versiją:

  dotnet --list-sdks
  

• Azure CLI — reikalinga autentifikacijai. Įdiekite iš aka.ms/installazurecli.

• Azure Subscription — prieigai prie Microsoft Foundry ir Azure AI Agent Service.

• Microsoft Foundry Project — projektas su diegimu modeliu (pvz., gpt-4o). Žr. 1 žingsnį žemiau.

Šioje saugykloje šakniniame kataloge yra requirements.txt failas, kuriame pateikti visi reikalingi Python paketai kodo pavyzdžiams paleisti.

Juos galite įdiegti paleidę šią komandą terminale, būdami saugyklos šakniniame kataloge:

pip install -r requirements.txt

Rekomenduojame sukurti Python virtualią aplinką, kad išvengtumėte konfliktų ir problemų.

Įsitikinkite, kad VSCode naudojate tinkamą Python versiją.

Norint paleisti notebook'us, jums reikia Azure AI Foundry hub ir project su įdiegtu modeliu.

1. Eikite į ai.azure.com ir prisijunkite su savo Azure paskyra.
2. Sukurkite hub (arba naudokite esamą). Žr.: Hub resources overview.
3. Hub viduje sukurkite project.
4. Iš Models + Endpoints → Deploy model diegkite modelį (pvz., gpt-4o).

Iš savo projekto Microsoft Foundry portale:

• Project Endpoint — Eikite į Apžvalga puslapį ir nukopijuokite endpoint URL.

• Model Deployment Name — Eikite į Models + Endpoints, pasirinkite savo įdiegtą modelį ir atkreipkite dėmesį į Deployment name (pvz., gpt-4o).

Visi notebook'ai naudoja AzureCliCredential autentifikacijai — nereikia valdyti API raktų. Tam reikalinga prisijungti per Azure CLI.

1. Įdiekite Azure CLI, jei dar to nepadarėte: aka.ms/installazurecli

2. Prisijunkite vykdydami:

   az login
   

   Arba, jei esate nuotolinėje/Codespace aplinkoje be naršyklės:

   az login --use-device-code
   

3. Pasirinkite prenumeratą jei būsite paprašyti — pasirinkite tą, kuriame yra jūsų Foundry projektas.

4. Patikrinkite, ar esate prisijungę:

   az account show
   

Kodėl az login? Notebook'ai autentifikuojasi naudodami AzureCliCredential iš azure-identity paketo. Tai reiškia, kad jūsų Azure CLI sesija suteikia kredencialus — nėra API raktų ar slaptų duomenų jūsų .env faile. Tai yra saugumo geriausia praktika.

Kopijuokite pavyzdinį failą:

# zsh/bash
cp .env.example .env

# PowerShell
Copy-Item .env.example .env

Atidarykite .env ir užpildykite šias dvi reikšmes:

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

Kintamasis	Kur jį rasti
AZURE_AI_PROJECT_ENDPOINT	Foundry portale → jūsų projektas → Apžvalga puslapis
AZURE_AI_MODEL_DEPLOYMENT_NAME	Foundry portale → Models + Endpoints → jūsų įdiegtas modelis → Deployment name

Tai viskas daugumai pamokų! Notebook'ai automatiškai autentifikuosis per jūsų az login sesiją.

pip install -r requirements.txt

Rekomenduojame tai vykdyti virtualioje aplinkoje, kurią sukūrėte anksčiau.

5 pamoka naudoja Azure AI Search retrieval-augmented generation. Jei ketinate paleisti tą pamoką, pridėkite šiuos kintamuosius į savo .env failą:

Kintamasis	Kur jį rasti
AZURE_SEARCH_SERVICE_ENDPOINT	Azure portale → jūsų Azure AI Search išteklius → Overview → URL
AZURE_SEARCH_API_KEY	Azure portale → jūsų Azure AI Search išteklius → Settings → Keys → pagrindinis administratoriaus raktas

Kai kurie 6 ir 8 pamokų notebook'ai naudoja GitHub Models vietoje Azure AI Foundry. Jei ketinate paleisti tuos pavyzdžius, pridėkite šiuos kintamuosius į savo .env failą:

Kintamasis	Kur jį rasti
GITHUB_TOKEN	GitHub → Settings → Developer settings → Personal access tokens
GITHUB_ENDPOINT	Naudokite https://models.inference.ai.azure.com (numatytoji reikšmė)
GITHUB_MODEL_ID	Naudojamo modelio pavadinimas (pvz., gpt-4o-mini)

8 pamokos sąlyginės eigos notebook'as naudoja Bing grounding per Azure AI Foundry. Jei ketinate paleisti tą pavyzdį, pridėkite šį kintamąjį į savo .env failą:

Kintamasis	Kur jį rasti
BING_CONNECTION_ID	Azure AI Foundry portale → jūsų projektas → Management → Connected resources → jūsų Bing ryšys → nukopijuokite connection ID

Jei naudojate macOS ir susiduriate su klaida kaip:

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

Tai yra žinoma problema su Python macOS, kai sistemos SSL sertifikatams automatiškai nėra suteikiamas pasitikėjimas. Išbandykite šiuos sprendimus eilės tvarka:

1 variantas: Paleiskite Python Install Certificates skriptą (rekomenduojama)

# Pakeiskite 3.XX į savo įdiegtą Python versiją (pvz., 3.12 arba 3.13):
/Applications/Python\ 3.XX/Install\ Certificates.command

2 variantas: Naudokite connection_verify=False savo notebook'e (tik GitHub Models notebookams)

Pamokoje 6 esančiame notebook'e (06-building-trustworthy-agents/code_samples/06-system-message-framework.ipynb) jau yra įtrauktas komentaru pažymėtas sprendimas. Atkomentuokite connection_verify=False, kai kuriate klientą:

client = ChatCompletionsClient(
    endpoint=endpoint,
    credential=AzureKeyCredential(token),
    connection_verify=False,  # Išjunkite SSL patikrinimą, jei susiduriate su sertifikato klaidomis
)

⚠️ Įspėjimas: SSL tikrinimo išjungimas (connection_verify=False) sumažina saugumą praleidžiant sertifikatų patikrinimą. Naudokite tai tik kaip laikino pobūdžio sprendimą vystymo aplinkoje, niekada gamyboje.

3 variantas: Įdiekite ir naudokite truststore

pip install truststore

Tada pridėkite šį kodą savo notebook'o arba skripto pradžioje prieš vykdant bet kokius tinklo kvietimus:

import truststore
truststore.inject_into_ssl()

Jei kyla kokių nors problemų vykdant šią sąranką, prisijunkite prie mūsų Azure AI bendruomenės Discord arba pateikite problemos pranešimą.

Dabar esate pasirengę paleisti šio kurso kodą. Sėkmės mokantis apie AI agentų pasaulį!

Įvadas į AI agentus ir naudojimo atvejai

---

Atsakomybės apribojimas: Šis dokumentas buvo išverstas naudojant dirbtinio intelekto vertimo paslaugą Co-op Translator. Nors siekiame tikslumo, atkreipkite dėmesį, kad automatizuoti vertimai gali turėti klaidų ar netikslumų. Originalus dokumentas gimtąja kalba turėtų būti laikomas pagrindiniu šaltiniu. Kritinei informacijai rekomenduojamas profesionalus, žmogaus atliktas vertimas. Mes neatsakome už bet kokius nesusipratimus ar neteisingus aiškinimus, kilusius dėl šio vertimo naudojimo.