Somo hili litafundisha jinsi ya kuendesha sampuli za msimbo za kozi hii.

Kabla ya kuanza kunakili repo yako, jiunge na AI Agents For Beginners Discord channel ili kupata msaada wowote wa usanidi, maswali kuhusu kozi, au kuungana na wanafunzi wengine.

Ili kuanza, tafadhali nakili au fanya fork ya Hifadhi ya GitHub. Hii itakuwezesha kuwa na toleo lako mwenyewe la nyenzo za kozi ili uweze kuendesha, kujaribu, na kubadilisha msimbo!

This can be done by clicking the link to fatilia repo

You should now have your own forked version of this course in the following link:

Hazina kamili inaweza kuwa kubwa (~3 GB) unapotembelea historia kamili na faili zote. Ikiwa unashiriki tu warsha au unahitaji folda chache za masomo pekee, kukopa mfinyu (au kukopa sparse) kunazuia sehemu kubwa ya upakuaji huo kwa kukata historia na/au kuruka blobs.

Replace <your-username> in the below commands with your fork URL (or the upstream URL if you prefer).

To clone only the latest commit history (small download):

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

To clone a specific branch:

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

Hii inatumia kukopa sehemu na sparse-checkout (inahitaji Git 2.25+ na inashauriwa Git ya kisasa yenye msaada wa partial clone):

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

Traverse into the repo folder:

cd ai-agents-for-beginners

Then specify which folders you want (example below shows two folders):

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

After cloning and verifying the files, if you only need files and want to free space (no git history), please delete the repository metadata (💀irreversible — you will lose all Git functionality: no commits, pulls, pushes, or history access).

# zsh/bash
rm -rf .git

# PowerShell
Remove-Item -Recurse -Force .git

• Tengeneza Codespace mpya kwa repo hii kupitia GitHub UI.

• Katika terminal ya codespace mpya iliyoundwa, run moja ya amri za shallow/sparse clone hapo juu ili kuleta folda za masomo unazohitaji ndani ya eneo la kazi la Codespace.

• Hiari: baada ya kunakili ndani ya Codespaces, ondoa .git ili kurudisha nafasi zaidi (angalia amri za kuondoa hapo juu).

• Kumbuka: Ikiwa unapendelea kufungua repo moja kwa moja katika Codespaces (bila nakili ya ziada), fahamu Codespaces itaunda mazingira ya devcontainer na inaweza bado kuandaa zaidi ya unachohitaji. Kunakili nakili ya mfinyu ndani ya Codespace safi kunakupa udhibiti zaidi juu ya matumizi ya diski.

• Badilisha kila wakati URL ya clone na fork yako ikiwa unataka kuhariri/kujumuisha.
• Ikiwa baadaye utahitaji historia zaidi au faili zaidi, unaweza kuzipata kwa kufetch au kurekebisha sparse-checkout kujumuisha folda za ziada.

Kozi hii inatoa mfululizo wa Jupyter Notebooks ambazo unaweza kuendesha kupata uzoefu wa vitendo wa kujenga Mawakala wa AI.

Sampuli za msimbo zinatumia Microsoft Agent Framework (MAF) na AzureAIProjectAgentProvider, ambayo inajuunga na Azure AI Agent Service V2 (Responses API) kupitia Microsoft Foundry.

Notebooks zote za Python zimewekwa lebo *-python-agent-framework.ipynb.

• Python 3.12+

  • KUMBUKA: Ikiwa huna Python3.12 imewekwa, hakikisha unaisakinisha. Kisha tengeneza venv yako ukitumia python3.12 ili kuhakikisha toleo sahihi linawekwa kutoka kwenye faili requirements.txt.

    Mfano

    Create Python venv directory:

    python -m venv venv
    

    Then activate venv environment for:

    # zsh/bash
    source venv/bin/activate
    

    # Command Prompt for Windows
    venv\Scripts\activate
    

• .NET 10+: Kwa sampuli za msimbo zinazotumia .NET, hakikisha unasakinisha .NET 10 SDK au baadaye. Kisha, angalia toleo la .NET SDK ulilosakinisha:

  dotnet --list-sdks
  

• Azure CLI — Inahitajika kwa uthibitisho. Sakinisha kutoka aka.ms/installazurecli.

• Azure Subscription — Kwa ufikiaji wa Microsoft Foundry na Azure AI Agent Service.

• Microsoft Foundry Project — Mradi wenye modeli iliyowekwa (k.m., gpt-4o). Tazama Hatua 1 hapa chini.

Tumeganisha faili ya requirements.txt katika mizizi ya hifadhi hii ambayo ina vifurushi vyote vinavyohitajika vya Python ili kuendesha sampuli za msimbo.

Unaweza kuvisakinisha kwa kuendesha amri ifuatayo kwenye terminal yako kwenye mizizi ya hifadhi:

pip install -r requirements.txt

Tunapendekeza kutengeneza mazingira ya virtual ya Python ili kuepuka migongano na matatizo yoyote.

Hakikisha unatumia toleo sahihi la Python katika VSCode.

Unahitaji hub na mradi wa Azure AI Foundry uliyo na modeli iliyotekelezwa ili kuendesha notebooks.

1. Nenda kwenye ai.azure.com na ingia kwa akaunti yako ya Azure.
2. Tengeneza hub (au tumia ile iliyopo). Tazama: Hub resources overview.
3. Ndani ya hub, tengeneza mradi.
4. Tekeleza modeli (k.m., gpt-4o) kutoka Models + Endpoints → Deploy model.

Kutoka kwenye mradi wako kwenye portal ya Microsoft Foundry:

• Endpoint ya Mradi — Nenda kwenye ukurasa wa Muhtasari na nakili URL ya endpoint.

• Model Deployment Name — Nenda kwenye Models + Endpoints, chagua modeli uliyoiweka, na chukulia Deployment name (k.m., gpt-4o).

Notebooks zote zinatumia AzureCliCredential kwa uthibitisho — hakuna funguo za API za kusimamia. Hii inahitaji uwe umeingia kupitia Azure CLI.

1. Sakinisha Azure CLI ikiwa bado hujasakinisha: aka.ms/installazurecli

2. Ingia kwa kuendesha:

   az login
   

   Au kama uko katika mazingira ya mbali/Codespace bila kivinjari:

   az login --use-device-code
   

3. Chagua subscription yako ikiwa itaulizwa — chagua ile yenye mradi wako wa Foundry.

4. Thibitisha umeingia:

   az account show
   

Kwanini az login? Notebooks zinathibitisha kwa kutumia AzureCliCredential kutoka kwa kifurushi azure-identity. Hii ina maana kikao chako cha Azure CLI kinatoa uthibitisho — hakuna funguo za API au siri katika faili yako .env. Hii ni mazoezi bora ya usalama.

Nakili faili la mfano:

# zsh/bash
cp .env.example .env

# PowerShell
Copy-Item .env.example .env

Fungua .env na jaza hizi thamani mbili:

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

Variable	Wapi ya kuipata
AZURE_AI_PROJECT_ENDPOINT	Foundry portal → mradi wako → ukurasa wa Muhtasari
AZURE_AI_MODEL_DEPLOYMENT_NAME	Foundry portal → Models + Endpoints → jina la modeli uliyoitekeleza

Hizo ndiyo kwa masomo mengi! Notebooks zitathibitisha moja kwa moja kupitia kikao chako cha az login.

pip install -r requirements.txt

Tunapendekeza kuendesha hili ndani ya mazingira ya virtual uliyounda hapo awali.

Somo la 5 linatumia Azure AI Search kwa retrieval-augmented generation. Ikiwa unapanga kuendesha somo hilo, ongeza vigezo hivi kwenye faili yako .env:

Variable	Wapi ya kuipata
AZURE_SEARCH_SERVICE_ENDPOINT	Azure portal → rasilimali yako ya Azure AI Search → Overview → URL
AZURE_SEARCH_API_KEY	Azure portal → rasilimali yako ya Azure AI Search → Settings → Keys → funguo kuu ya msimamizi

Baadhi ya notebooks katika masomo 6 na 8 zinatumia GitHub Models badala ya Azure AI Foundry. Ikiwa unapanga kuendesha sampuli hizo, ongeza vigezo hivi kwenye faili yako .env:

Variable	Wapi ya kuipata
GITHUB_TOKEN	GitHub → Settings → Developer settings → Personal access tokens
GITHUB_ENDPOINT	Tumia https://models.inference.ai.azure.com (thamani ya kawaida)
GITHUB_MODEL_ID	Jina la modeli kutumia (k.m. gpt-4o-mini)

Notebook ya workflow inayobadilisha kwa masharti katika somo la 8 inatumia Bing grounding kupitia Azure AI Foundry. Ikiwa unapanga kuendesha sampuli hiyo, ongeza vigezo hivi kwenye faili yako .env:

Variable	Wapi ya kuipata
BING_CONNECTION_ID	Azure AI Foundry portal → mradi wako → Management → Connected resources → muunganisho wako wa Bing → nakili connection ID

Ikiwa uko kwenye macOS na unakutana na kosa kama:

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

Hili ni tatizo linalojulikana na Python kwenye macOS ambapo vyeti vya SSL vya mfumo havithaminiwi moja kwa moja. Jaribu suluhisho zifuatazo kwa mpangilio:

Chaguo 1: Endesha skripti ya Install Certificates ya Python (inayopendekezwa)

# Badilisha 3.XX na toleo lako la Python lililowekwa (kwa mfano, 3.12 au 3.13):
/Applications/Python\ 3.XX/Install\ Certificates.command

Chaguo 2: Tumia connection_verify=False katika notebook yako (kwa notebooks za GitHub Models pekee)

Katika notebook ya Somo 6 (06-building-trustworthy-agents/code_samples/06-system-message-framework.ipynb), suluhisho lililokomentiwa tayari limejumuishwa. Fungua kutoa komenti connection_verify=False unapotengeneza client:

client = ChatCompletionsClient(
    endpoint=endpoint,
    credential=AzureKeyCredential(token),
    connection_verify=False,  # Zima uhakiki wa SSL ikiwa unakutana na makosa ya cheti
)

⚠️ Tahadhari: Kuzima ukaguzi wa SSL (connection_verify=False) kunapunguza usalama kwa kuruka uthibitisho wa cheti. Tumia hili tu kama suluhisho la muda katika mazingira ya maendeleo, wala si katika uzalishaji.

Chaguo 3: Sakinisha na tumia truststore

pip install truststore

Kisha ongeza yafuatayo juu kabisa ya notebook yako au script kabla ya kufanya simu yoyote za mtandao:

import truststore
truststore.inject_into_ssl()

Ikiwa una matatizo yoyote kuendesha usanidi huu, jiunge na Jamii ya Azure AI kwenye Discord au tengeneza issue.

Sasa uko tayari kukimbia msimbo wa kozi hii. Furahia kujifunza zaidi kuhusu ulimwengu wa Mawakala wa AI!

Utangulizi kwa Mawakala wa AI na Matumizi yao

---

Tamko la kutohusika: Nyaraka hii imetafsiriwa kwa kutumia huduma ya utafsiri ya AI Co-op Translator. Ingawa tunajitahidi kufanikisha usahihi, tafadhali fahamu kuwa tafsiri za kiotomatiki zinaweza kuwa na makosa au ukosefu wa usahihi. Nyaraka ya awali katika lugha yake ya asili inapaswa kuchukuliwa kama chanzo cha mamlaka. Kwa taarifa muhimu, utafsiri wa kitaalamu unaofanywa na binadamu unashauriwa. Hatuwajibiki kwa uelewa au tafsiri zisizo sahihi zinazotokana na matumizi ya utafsiri huu.