ai-agents-for-beginners

Konfiguracja kursu

Wprowadzenie

Ta lekcja będzie dotyczyć sposobu uruchamiania przykładów kodu z tego kursu.

Dołącz do innych uczniów i uzyskaj pomoc

Zanim zaczniesz klonować swoje repozytorium, dołącz do kanału Discord AI Agents For Beginners, aby uzyskać pomoc przy konfiguracji, zadać pytania dotyczące kursu lub połączyć się z innymi uczestnikami.

Sklonuj lub utwórz fork tego repozytorium

Aby rozpocząć, proszę sklonuj lub utwórz fork repozytorium GitHub. Spowoduje to utworzenie własnej wersji materiałów kursowych, dzięki czemu będziesz mógł uruchamiać, testować i modyfikować kod!

Można to zrobić, klikając link utwórz fork repozytorium

Powinieneś teraz mieć swoją własną wersję kursu dostępną pod następującym linkiem:

Forked Repo

Płytkie klonowanie (zalecane dla warsztatów / Codespaces)

Pełne repozytorium może być duże (~3 GB) po pobraniu całej historii i wszystkich plików. Jeśli uczestniczysz tylko w warsztacie lub potrzebujesz tylko kilku folderów z lekcjami, płytkie klonowanie (lub klonowanie częściowe) unika pobrania całej historii i/lub pomija niektóre pliki.

Szybkie płytkie klonowanie — minimalna historia, wszystkie pliki

Zastąp <your-username> w poniższych poleceniach adresem URL twojego forka (lub adresu upstream, jeśli wolisz).

Aby sklonować tylko najnowszą historię commitów (małe pobranie):

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

Aby sklonować konkretną gałąź:

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

Częściowe (rzadkie) klonowanie — minimalne pliki + tylko wybrane foldery

To używa częściowego klonowania i sparse-checkout (wymaga Git 2.25+ oraz zaleca się nowoczesne Git z obsługą częściowego klonowania):

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

Przejdź do folderu repozytorium:

cd ai-agents-for-beginners

Następnie określ, które foldery chcesz (przykład poniżej pokazuje dwa foldery):

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

Po sklonowaniu i weryfikacji plików, jeśli potrzebujesz tylko plików i chcesz zwolnić miejsce (bez historii git), usuń metadane repozytorium (💀nieodwracalne — stracisz całą funkcjonalność Git: brak commitów, pullów, pushów, ani dostępu do historii).

# zsh/bash
rm -rf .git

# PowerShell
Remove-Item -Recurse -Force .git

Używanie GitHub Codespaces (zalecane, aby uniknąć dużych lokalnych pobrań)

Utwórz nowy Codespace dla tego repozytorium przez GitHub UI.
W terminalu nowo utworzonego codespace uruchom jedno z powyższych poleceń płytkiego/rzadkiego klonowania, aby pobrać tylko potrzebne foldery z lekcjami do workspace Codespace.
Opcjonalnie: po klonowaniu w Codespaces usuń folder .git, aby odzyskać miejsce (zobacz polecenia usuwania powyżej).
Uwaga: Jeśli wolisz otworzyć repozytorium bezpośrednio w Codespaces (bez dodatkowego klonowania), pamiętaj, że Codespaces zbuduje środowisko devcontainer i może nadal uruchomić więcej zasobów, niż potrzebujesz. Klonowanie płytkiej kopii w świeżym Codespace daje większą kontrolę nad wykorzystaniem dysku.

Wskazówki

Zawsze zastępuj adres URL klonowania swoim forkiem, jeśli chcesz edytować/zatwierdzać zmiany.
Jeśli później potrzebujesz więcej historii lub plików, możesz je pobrać lub dostosować sparse-checkout, aby uwzględnić dodatkowe foldery.

Uruchamianie kodu

Ten kurs oferuje serię notatników Jupyter, które możesz uruchamiać, aby zdobyć praktyczne doświadczenie w budowaniu agentów AI.

Przykłady kodu korzystają z Microsoft Agent Framework (MAF) z AzureAIProjectAgentProvider, który łączy się z Azure AI Agent Service V2 (API odpowiedzi) przez Microsoft Foundry.

Wszystkie notatniki Pythona mają oznaczenie *-python-agent-framework.ipynb.

Wymagania

Python 3.12+
- UWAGA: Jeśli nie masz zainstalowanego Pythona 3.12, upewnij się, że go zainstalujesz. Następnie utwórz swoje środowisko wirtualne za pomocą python3.12, aby zapewnić poprawne wersje pakietów z pliku requirements.txt.
  
  Przykład
  
  Utwórz katalog środowiska wirtualnego Pythona:
```
python -m venv venv
```
  Następnie aktywuj środowisko venv dla:
```
# zsh/bash
source venv/bin/activate
```
```
# Command Prompt for Windows
venv\Scripts\activate
```
.NET 10+: Dla przykładowych kodów używających .NET zainstaluj .NET 10 SDK lub nowszy. Następnie sprawdź zainstalowaną wersję SDK .NET:
```
  dotnet --list-sdks
```
Azure CLI — niezbędne do uwierzytelniania. Zainstaluj ze strony aka.ms/installazurecli.
Subskrypcja Azure — dla dostępu do Microsoft Foundry i Azure AI Agent Service.
Projekt Microsoft Foundry — projekt z wdrożonym modelem (np. gpt-4o). Zobacz Krok 1 poniżej.

W katalogu głównym tego repozytorium znajduje się plik requirements.txt, zawierający wszystkie niezbędne pakiety Pythona do uruchomienia przykładów.

Możesz je zainstalować, uruchamiając poniższe polecenie w terminalu w katalogu głównym repozytorium:

pip install -r requirements.txt

Zalecamy utworzenie wirtualnego środowiska Pythona, aby uniknąć konfliktów i problemów.

Konfiguracja VSCode

Upewnij się, że w VSCode używasz właściwej wersji Pythona.

Konfiguracja Microsoft Foundry i Azure AI Agent Service

Krok 1: Utwórz projekt Microsoft Foundry

Aby uruchomić notatniki, potrzebujesz huba i projektu Microsoft Azure AI Foundry z wdrożonym modelem.

Przejdź do ai.azure.com i zaloguj się na swoje konto Azure.
Utwórz hub (lub użyj już istniejącego). Zobacz: Przegląd zasobów huba.
W hubie utwórz projekt.
Wdróż model (np. gpt-4o) z sekcji Models + Endpoints → Deploy model.

Krok 2: Pobierz punkt końcowy projektu i nazwę wdrożenia modelu

W portalu projektu Microsoft Foundry:

Punkt końcowy projektu — przejdź do strony Overview i skopiuj adres URL endpointu.

Project Connection String

Nazwa wdrożenia modelu — przejdź do Models + Endpoints, wybierz wdrożony model i zanotuj Deployment name (np. gpt-4o).

Krok 3: Zaloguj się do Azure używając `az login`

Wszystkie notatniki używają AzureCliCredential do uwierzytelniania — nie ma potrzeby zarządzania kluczami API. Wymaga to zalogowania za pomocą Azure CLI.

Zainstaluj Azure CLI, jeśli jeszcze tego nie zrobiłeś: aka.ms/installazurecli
Zaloguj się za pomocą polecenia:
```
 az login
```
Lub, jeśli jesteś w środowisku zdalnym/Codespace bez przeglądarki:
```
 az login --use-device-code
```
Wybierz subskrypcję, jeśli zostaniesz o to poproszony — wybierz tę, w której znajduje się twój projekt Foundry.
Sprawdź, czy jesteś zalogowany:
```
 az account show
```

Dlaczego az login? Notatniki uwierzytelniają się za pomocą AzureCliCredential z pakietu azure-identity. Oznacza to, że sesja Azure CLI dostarcza dane uwierzytelniające — nie musisz mieć kluczy API ani sekretów w pliku .env. To jest dobry standard bezpieczeństwa.

Krok 4: Utwórz plik `.env`

Skopiuj plik przykładowy:

# zsh/bash
cp .env.example .env

# PowerShell
Copy-Item .env.example .env

Otwórz .env i uzupełnij te dwie wartości:

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

Zmienna	Gdzie ją znaleźć
`AZURE_AI_PROJECT_ENDPOINT`	Portal Foundry → twój projekt → strona Overview
`AZURE_AI_MODEL_DEPLOYMENT_NAME`	Portal Foundry → Models + Endpoints → nazwa twojego wdrożonego modelu

To wszystko dla większości lekcji! Notatniki uwierzytelniają się automatycznie przez twoją sesję az login.

Krok 5: Zainstaluj zależności Pythona

pip install -r requirements.txt

Zalecamy uruchomienie tego we wcześniej utworzonym środowisku wirtualnym.

Dodatkowa konfiguracja do Lekcji 5 (Agentic RAG)

Lekcja 5 używa Azure AI Search do generowania wspomaganego wyszukiwaniem. Jeśli planujesz uruchomić tę lekcję, dodaj te zmienne do pliku .env:

Zmienna	Gdzie ją znaleźć
`AZURE_SEARCH_SERVICE_ENDPOINT`	Portal Azure → twoje zasoby Azure AI Search → Overview → URL
`AZURE_SEARCH_API_KEY`	Portal Azure → twoje zasoby Azure AI Search → Settings → Keys → klucz administracyjny podstawowy

Dodatkowa konfiguracja do Lekcji 6 i Lekcji 8 (Modele GitHub)

Niektóre notatniki w lekcjach 6 i 8 używają GitHub Models zamiast Azure AI Foundry. Jeśli planujesz uruchomić te przykłady, dodaj te zmienne do pliku .env:

Zmienna	Gdzie ją znaleźć
`GITHUB_TOKEN`	GitHub → Settings → Developer settings → Personal access tokens
`GITHUB_ENDPOINT`	Użyj `https://models.inference.ai.azure.com` (wartość domyślna)
`GITHUB_MODEL_ID`	Nazwa modelu do użycia (np. `gpt-4o-mini`)

Dodatkowa konfiguracja do Lekcji 8 (Bing Grounding Workflow)

Warunkowy notatnik przepływu pracy z lekcji 8 używa Bing grounding przez Azure AI Foundry. Jeśli planujesz uruchomić ten przykład, dodaj tę zmienną do pliku .env:

Zmienna	Gdzie ją znaleźć
`BING_CONNECTION_ID`	Portal Azure AI Foundry → twój projekt → Management → Connected resources → twoje połączenie Bing → skopiuj ID połączenia

Rozwiązywanie problemów

Błędy weryfikacji certyfikatu SSL na macOS

Jeśli korzystasz z macOS i napotkasz błąd podobny do:

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

To znany problem z Pythonem na macOS, gdzie systemowe certyfikaty SSL nie są automatycznie zaufane. Spróbuj poniższych rozwiązań w kolejności:

Opcja 1: Uruchom skrypt instalacji certyfikatów Pythona (zalecane)

# Zastąp 3.XX zainstalowaną wersją Pythona (np. 3.12 lub 3.13):
/Applications/Python\ 3.XX/Install\ Certificates.command

Opcja 2: Użyj connection_verify=False w notatniku (tylko dla notatników GitHub Models)

W notatniku Lekcji 6 (06-building-trustworthy-agents/code_samples/06-system-message-framework.ipynb) jest już zawarte zakomentowane rozwiązanie. Odkomentuj connection_verify=False podczas tworzenia klienta:

client = ChatCompletionsClient(
    endpoint=endpoint,
    credential=AzureKeyCredential(token),
    connection_verify=False,  # Wyłącz weryfikację SSL, jeśli napotkasz błędy certyfikatu
)

⚠️ Ostrzeżenie: Wyłączenie weryfikacji SSL (connection_verify=False) zmniejsza bezpieczeństwo, pomijając sprawdzanie certyfikatów. Używaj tego tylko jako tymczasowe rozwiązanie w środowiskach deweloperskich, nigdy w produkcji.

Opcja 3: Zainstaluj i użyj truststore

pip install truststore

Następnie dodaj poniższe na początku swojego notatnika lub skryptu, przed jakimikolwiek wywołaniami sieciowymi:

import truststore
truststore.inject_into_ssl()

Utknąłeś gdzieś?

Jeśli masz jakiekolwiek problemy z uruchomieniem tego setupu, dołącz do naszej Społeczności Azure AI na Discord lub zglos problem.

Następna lekcja

Jesteś teraz gotowy do uruchomienia kodu dla tego kursu. Powodzenia w dalszej nauce o świecie agentów AI!

Wprowadzenie do Agentów AI i przypadków użycia agentów

Zastrzeżenie: Ten dokument został przetłumaczony przy użyciu usługi tłumaczeń AI Co-op Translator. Chociaż dążymy do dokładności, prosimy pamiętać, że automatyczne tłumaczenia mogą zawierać błędy lub nieścisłości. Oryginalny dokument w języku źródłowym należy traktować jako źródło ostateczne. W przypadku informacji krytycznych zalecane jest skorzystanie z profesjonalnego tłumaczenia wykonanego przez człowieka. Nie ponosimy odpowiedzialności za jakiekolwiek nieporozumienia lub błędne interpretacje wynikające z użycia tego tłumaczenia.

This site is open source. Improve this page.